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

Contributors