prompts

Node.js user prompt library for command-line interfaces.

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.

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 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

`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).

Example

const os = await multiselect('Choose OS', {
  choices: ["linux", "mac", "windows"]
  validators: [required()]
});

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

`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).

`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

Interfaces

export interface SharedOptions {
  stdin?: NodeJS.ReadStream & {
    fd: 0;
  };
  stdout?: NodeJS.WriteStream & {
    fd: 1;
  };
}

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)[];
  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;
}