Display text in the terminal with temporal effects like a typewriter ✍️, pauses ⏸️, and erasures ⌫ — built for expressive and dynamic CLI experiences.
Caution
The erase feature is not fully stable and may result in unexpected behavior. Use with caution.
- Node.js v22 or higher
This package is available in the Node Package Repository and can be easily installed with npm or yarn.
$ npm i @topcli/timedtext
# or
$ yarn add @topcli/timedtextExecute one synchronously
import TimedText from "@topcli/timedtext";
import kleur from "kleur";
new TimedText()
.write("Hello world!\n", {
interval: 40
})
.write(kleur.yellow(`Coding a ${kleur.green("cool")} new ${kleur.blue("package")} for ${kleur.white("CLI")} 😲`), {
interval: 50
})
.pause(250)
.erase({ steps: 1 })
.pause(100)
.write(kleur.magenta("Get the party started!"), {
interval: 150,
segmenter: {
granularity: "word"
}
})
.execute({ jumpLineBeforeExecution: true });class TimedText {
constructor(options?: TimedTextOptions);
jumpCursorToTheEnd(): void;
write(input: string, options?: WriteTextOptions): this;
pause(duration: number): this;
erase(options?: EraseTextOptions): this;
execute(options?: ExecuteOptions): void;
executeAsync(options?: ExecuteOptions): Promise<void>;
static DefaultLocal: Intl.LocalesArgument;
static DefaultSegmenterGranularity: Intl.SegmenterOptions["granularity"];
}Add a timed write action to the sequence.
interface WriteTextOptions {
interval?: number;
segmenter?: SegmenterOptions;
}Pause the sequence for duration milliseconds.
Erase one or multiple previous write() calls.
type EraseTextOptions = {
length?: number;
steps?: number;
};If no options are provided, all previous writes are erased.
Warning
Calling erase() before any write() or after a full erase will throw an error.
Execute the sequence synchronously (using Atomics.wait under the hood).
type ExecuteOptions = {
/**
* @description
* Default to `true` for Synchronous execution and `false` for Asynchronous
*/
jumpToCursorAfterExecution?: boolean;
};Same as execute(), but supports asynchronous delays (useful for orchestrating multiple instances).
Example
console.log("");
const tt1 = new TimedText();
console.log("\n\n");
const tt2 = new TimedText();
await Promise.all([
tt1.executeAsync(),
tt2.executeAsync()
]);
tt2.jumpCursorToTheEnd();
Thanks goes to these wonderful people (emoji key):