Node.js user input library for command-line interfaces.
bash
$ npm i @topcli/prompts
or
$ yarn add @topcli/prompts
`
Usage exemple
You can locally run node ./demo.js
`js
import { question, confirm, select, multiselect } from "@topcli/prompts";
const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
const name = await question("Project name ?", { defaultValue: "foo" });
const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
const isCLI = await confirm("Your project is a CLI ?", { initial: true });
const os = await multiselect("Choose OS", {
choices: ["linux", "mac", "windows"],
preSelectedChoices: ["linux"]
});
console.log(name, runner, isCLI, os);
`
API
$3
`ts
question(message: string, options?: PromptOptions): Promise
`
Simple prompt, similar to rl.question() with an improved UI.
Use options.defaultValue to set a default value.
Use options.secure if you need to hide both input and answer. You can provide either a boolean or an object which allows to configure a placeholder such as *.
Use options.signal to set an AbortSignal (throws a AbortError).
Use options.validators to handle user input.
Use options.skip to skip prompt. It will return options.defaultValue if given, "" otherwise.
Example
`js
const packageName = await question('Package name', {
validators: [
{
validate: (value) => {
if (fs.existsSync(path.join(process.cwd(), value))) {
return Folder ${value} already exists;
}
}
}
]
});
`
This package provide some validators for common usage
- required
`js
import { question, required } from "@topcli/prompts";
const name = await question("What's your name ?", {
validators: [required()]
});
`
$3
`ts
select(message: string, options: SelectOptions): Promise
`
Scrollable select depending maxVisible (default 8).
Use options.ignoreValues to skip result render & clear lines after a selected one.
Use options.validators to handle user input.
Use options.autocomplete to allow filtered choices. This can be useful for a large list of choices.
Use options.caseSensitive to make autocomplete filters case sensitive. Default false
Use options.signal to set an AbortSignal (throws a AbortError).
Use options.skip to skip prompt. It will return the first choice.
$3
`ts
multiselect(message: string, options: MultiselectOptions): Promise
`
Scrollable multiselect depending options.maxVisible (default 8).
Use options.preSelectedChoices to pre-select choices.
Use options.validators to handle user input.
Use options.showHint: false to disable hint (this option is truthy by default).
Use options.autocomplete to allow filtered choices. This can be useful for a large list of choices.
Use options.caseSensitive to make autocomplete filters case sensitive. Default false.
Use options.signal to set an AbortSignal (throws a AbortError).
Use options.skip to skip prompt. It will return options.preSelectedChoices if given, [] otherwise.
$3
`ts
confirm(message: string, options?: ConfirmOptions): Promise
`
Boolean prompt, default to options.initial (false).
> [!TIP]
> You can answer pressing Y or N
Use options.signal to set an AbortSignal (throws a AbortError).
Use options.skip to skip prompt. It will return options.initial (false by default)
$3
The PromptAgent class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
`ts
const agent = PromptAgent.agent();
agent.nextAnswer("John");
const input = await question("What's your name?");
assert.equal(input, "John");
`
> [!WARNING]
> Answers set with PromptAgent will bypass any logical & validation rules.
> Examples:
> - When using question(), validators functions will not be executed.
> - When using select(), the answer can be different from the available choices.
> - When using confirm(), the answer can be any type other than boolean.
> - etc
> Use with caution
Errors
$3
`ts
export class AbortError extends Error {
constructor(message: string) {
super(message);
this.name = "AbortError";
}
}
`
Interfaces
`ts
type Stdin = NodeJS.ReadStream & {
fd: 0;
};
type Stdout = NodeJS.WriteStream & {
fd: 1;
}
export interface AbstractPromptOptions {
stdin?: Stdin;
stdout?: Stdout;
message: string;
skip?: boolean;
signal?: AbortSignal;
}
export interface PromptValidator {
validate: (input: T) => boolean;
}
export interface QuestionOptions extends SharedOptions {
defaultValue?: string;
validators?: PromptValidator[];
secure?: boolean;
}
export interface Choice {
value: T;
label: string;
description?: string;
}
export interface SelectOptions extends AbstractPromptOptions {
choices: (Choice | T)[];
maxVisible?: number;
ignoreValues?: (T | number | boolean)[];
validators?: PromptValidator[];
autocomplete?: boolean;
caseSensitive?: boolean;
}
export interface MultiselectOptions extends AbstractPromptOptions {
choices: (Choice | T)[];
maxVisible?: number;
preSelectedChoices?: (Choice | T)[];
validators?: PromptValidator[];
autocomplete?: boolean;
caseSensitive?: boolean;
showHint?: boolean;
}
export interface ConfirmOptions extends AbstractPromptOptions {
initial?: boolean;
}
``
PierreDemailly 💻 ⚠️ |
Gentilhomme 👀 💻 📖 |
Tony Gorez 👀 |
Yefis 💻 📖 |
Ben 📖 🚧 |
Takeshi Kondo 🚧 |
FredGuiou 💻 ⚠️ 📖 |
Marcus Reinhardt 💻 ⚠️ 📖 |
Harper Andrews 📖 |