Requirements

• Node.js v18 or higher

Getting Started

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

$ npm i @topcli/prompts
# or
$ yarn add @topcli/prompts

Usage exemple

You can locally run node ./demo.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

question()

question(message: string, options?: PromptOptions): Promise<string>

Simple prompt, similar to rl.question() with an improved UI.

Use options.secure if you need to hide both input and answer.

Use options.validators to handle user input.

Use options.signal to set an AbortSignal (throws a AbortError).

Example

const packageName = await question('Package name', {
  validators: [
    {
      validate: (value) => !existsSync(join(process.cwd(), value)),
      error: (value) => `Folder ${value} already exists`
    }
  ]
});

This package provide some validators for common usage

• required

import { prompt, required } from "@topcli/prompts";

const name = await prompt("What's your name ?", {
  validators: [required()]
});

select()

select(message: string, options: SelectOptions): Promise<string>

Scrollable select depending maxVisible (default 8).

Use ignoreValues to skip result render & clear lines after a selected one.

Use validators to handle user input.

Use autocomplete to allow filtered choices. This can be useful for a large list of choices.

Use caseSensitive to make autocomplete filters case sensitive. Default false

Use options.signal to set an AbortSignal (throws a AbortError).

multiselect()

multiselect(message: string, options: MultiselectOptions): Promise<[string]>

Scrollable multiselect depending maxVisible (default 8).
Use preSelectedChoices to pre-select choices.

Use validators to handle user input.

Use showHint: false to disable hint (this option is truthy by default).

Use autocomplete to allow filtered choices. This can be useful for a large list of choices.

Use caseSensitive to make autocomplete filters case sensitive. Default false.

Use options.signal to set an AbortSignal (throws a AbortError).

confirm()

confirm(message: string, options?: ConfirmOptions): Promise<boolean>

Boolean prompt, return options.initial if user input is different from y/yes/n/no (case insensitive), (default false).

Use options.signal to set an AbortSignal (throws a AbortError).

PromptAgent

The PromptAgent class allows to programmatically set the next answers for any prompt function, this can be useful for testing.

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

AbortError

export class AbortError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "AbortError";
  }
}

Interfaces

type Stdin = NodeJS.ReadStream & {
  fd: 0;
};

type Stdout = NodeJS.WriteStream & {
  fd: 1;
}

export interface AbstractPromptOptions {
  stdin?: Stdin;
  stdout?: Stdout;
  message: string;
  sginal?: AbortSignal;
}

export interface PromptValidator<T = string | string[] | boolean> {
    validate: (input: T) => boolean;
    error: (input: T) => string;
}

export interface QuestionOptions extends SharedOptions {
  defaultValue?: string;
  validators?: Validator[];
  secure?: boolean;
}

export interface Choice {
  value: any;
  label: string;
  description?: string;
}

export interface SelectOptions extends SharedOptions  {
  choices: (Choice | string)[];
  maxVisible?: number;
  ignoreValues?: (string | number | boolean)[];
  validators?: Validator[];
  autocomplete?: boolean;
  caseSensitive?: boolean;
}

export interface MultiselectOptions extends SharedOptions  {
  choices: (Choice | string)[];
  maxVisible?: number;
  preSelectedChoices?: (Choice | string)[];
  validators?: Validator[];
  autocomplete?: boolean;
  caseSensitive?: boolean;
  showHint?: boolean;
}

export interface ConfirmOptions extends SharedOptions  {
  initial?: boolean;
}

Contributors

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