Requirements

- Node.js v20 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

``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;
}
``

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Open an issue if you want to provide feedback such as bug reports or enchancements.

Contributors

PierreDemailly 💻 ⚠️	Gentilhomme 👀 💻 📖	Tony Gorez 👀	Yefis 💻 📖	Ben 📖 🚧	Takeshi Kondo 🚧	FredGuiou 💻 ⚠️ 📖
Marcus Reinhardt 💻 ⚠️ 📖	Harper Andrews 📖