Prompts Reference

Coverage License NPM Version Open Issues

⁉️ CLI interactive prompts. Can be used to wrap anything that matches the interface of node:readline/promises.

Usage

📦 Node

Install @lou.codes/prompts as a dependency:

1
pnpm add @lou.codes/prompts
2
# or
3
npm install @lou.codes/prompts
4
# or
5
yarn add @lou.codes/prompts

Import it and use it:

1
import { question } from "@lou.codes/prompts";
2
import { createInterface } from "node:readline/promises";
3

4
const exampleQuestion = question(
5
	createInterface({
6
		input: process.stdin,
7
		output: process.stdout,
8
	}),
9
);
10

11
exampleQuestion({
12
	format: value => parseInt(value, 18),
13
	query: "How old are you?",
14
	validate: value => (value < 18 ? "You must be at least 18 years old." : ""),
15
})
16
	.then(console.log)
17
	.catch(console.error)
18
	.finally(() => readlineInterface.close());

🦕 Deno

Import @lou.codes/prompts using the npm: prefix, and use it directly with the native prompt:

1
import { question } from "npm:@lou.codes/prompts";
2

3
const exampleQuestion = question({
4
	question: query => Promise.resolve(prompt(query)),
5
});
6

7
exampleQuestion({
8
	format: value => parseInt(value, 18),
9
	query: "How old are you?",
10
	validate: value => (value < 18 ? "You must be at least 18 years old." : ""),
11
})
12
	.then(console.log)
13
	.catch(console.error);

🌎 Browser

Import @lou.codes/prompts using esm.sh, and use it directly with the native prompt:

1
import { question } from "https://esm.sh/@lou.codes/prompts";
2

3
const exampleQuestion = question({
4
	question: query => Promise.resolve(prompt(query)),
5
});
6

7
exampleQuestion({
8
	format: value => parseInt(value, 18),
9
	query: "How old are you?",
10
	validate: value => (value < 18 ? "You must be at least 18 years old." : ""),
11
})
12
	.then(console.log)
13
	.catch(console.error);

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Type Aliases

QuestionObject

1
type QuestionObject: object;

Question object.

Remarks

Small abstraction layer on top the question method of Node’s readline module.

Type declaration

Member	Type	Description
`question`	(`query`: `string`) => `Awaitable`<`string`>	Question function.

View source

QuestionOptions<FormattedValue>

1
type QuestionOptions<FormattedValue>: object;

Options object for the question function.

Type parameters

Type parameter	Value
`FormattedValue`	`string`

Type declaration

Member	Type	Description
`format`	`Unary`<`string`, `FormattedValue`>	Function to format the question’s answer given by the user. Example `typescript{ format: value => parseInt(value, 18),}` Param The question’s answer given by the user.
`query`	`string`	Query to show to the user.
`retry`	`boolean`	Whether to retry the question if the answer is invalid.
`validate`	`Unary`<`FormattedValue`, `Maybe`<`string`>>	Function to validate the question’s answer given by the user (after formatting). Returning an string will be used to reject with an error, while an empty string or undefined is considered valid. Example `typescript{ validate: value => value % 2 === 0,}` Param The question’s answer given by the user.

View source

Functions

question()

1
function question(
2
	questionObject: QuestionObject,
3
): <FormattedValue>(
4
	options: QuestionOptions<FormattedValue>,
5
) => Promise<FormattedValue>;

Interactive question.

Parameters

Parameter	Type	Description
`questionObject`	`QuestionObject`	Object with a question function that returns a promise.

Returns

Function

Curried function with questionObject set in context.

Interactive question with questionObject set in context.

Type parameters

Type parameter	Value	Description
`FormattedValue`	`string`	Result of the value after formatting.

Parameters

Parameter	Type	Description
`options`	`QuestionOptions`<`FormattedValue`>	Options object for the question.

Returns

Promise<FormattedValue>

Promise with the question’s answer.

See

question

Remarks

Small abstraction layer on top the question method of Node’s readline module.

Example

1
import { createInterface } from "node:readline/promises";
2

3
const exampleQuestion = question(
4
	createInterface({
5
		input: process.stdin,
6
		output: process.stdout,
7
	}),
8
);
9

10
exampleQuestion({
11
	format: value => parseInt(value, 18),
12
	query: "How old are you?",
13
	validate: value => (value < 18 ? "You must be at least 18 years old." : ""),
14
})
15
	.then(console.log)
16
	.catch(console.error);

View source