@topcli/prompts 2.1.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +13 -13
- package/README.md +274 -274
- package/dist/index.cjs +74 -75
- package/dist/index.d.cts +10 -10
- package/dist/index.d.ts +10 -10
- package/dist/index.js +44 -45
- package/package.json +50 -54
package/LICENSE
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
Copyright 2023-2025 TopCli
|
|
2
|
-
|
|
3
|
-
Permission to use, copy, modify, and/or distribute this software for any purpose
|
|
4
|
-
with or without fee is hereby granted, provided that the above copyright notice
|
|
5
|
-
and this permission notice appear in all copies.
|
|
6
|
-
|
|
7
|
-
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
8
|
-
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
9
|
-
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
10
|
-
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
|
|
11
|
-
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
|
12
|
-
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
|
|
13
|
-
THIS SOFTWARE.
|
|
1
|
+
Copyright 2023-2025 TopCli
|
|
2
|
+
|
|
3
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose
|
|
4
|
+
with or without fee is hereby granted, provided that the above copyright notice
|
|
5
|
+
and this permission notice appear in all copies.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
8
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
9
|
+
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
10
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
|
|
11
|
+
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
|
12
|
+
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
|
|
13
|
+
THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,274 +1,274 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
<img src="./public/banner.png" alt="@topcli/prompts">
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://github.com/TopCli/prompts/commit-activity)
|
|
6
|
-
[](https://github.com/TopCli/prompts/blob/main/LICENSE)
|
|
7
|
-
[](https://ossf.github.io/scorecard-visualizer/#/projects/github.com/TopCli/prompts)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
<img src="./public/topcli.gif" alt="demo">
|
|
11
|
-
</div>
|
|
12
|
-
|
|
13
|
-
## Requirements
|
|
14
|
-
- [Node.js](https://nodejs.org/en/) v20 or higher
|
|
15
|
-
|
|
16
|
-
## Getting Started
|
|
17
|
-
|
|
18
|
-
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
$ npm i @topcli/prompts
|
|
22
|
-
# or
|
|
23
|
-
$ yarn add @topcli/prompts
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Usage exemple
|
|
27
|
-
|
|
28
|
-
You can locally run `node ./demo.js`
|
|
29
|
-
|
|
30
|
-
```js
|
|
31
|
-
import { question, confirm, select, multiselect } from "@topcli/prompts";
|
|
32
|
-
|
|
33
|
-
const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
|
|
34
|
-
|
|
35
|
-
const name = await question("Project name ?", { defaultValue: "foo" });
|
|
36
|
-
const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
|
|
37
|
-
const isCLI = await confirm("Your project is a CLI ?", { initial: true });
|
|
38
|
-
const os = await multiselect("Choose OS", {
|
|
39
|
-
choices: ["linux", "mac", "windows"],
|
|
40
|
-
preSelectedChoices: ["linux"]
|
|
41
|
-
});
|
|
42
|
-
|
|
43
|
-
console.log(name, runner, isCLI, os);
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
## API
|
|
47
|
-
|
|
48
|
-
### `question()`
|
|
49
|
-
|
|
50
|
-
```ts
|
|
51
|
-
question(message: string, options?: PromptOptions): Promise<string>
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Simple prompt, similar to `rl.question()` with an improved UI.
|
|
55
|
-
|
|
56
|
-
Use `options.defaultValue` to set a default value.
|
|
57
|
-
|
|
58
|
-
Use `options.secure` if you need to hide both input and answer.
|
|
59
|
-
|
|
60
|
-
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
61
|
-
|
|
62
|
-
Use `options.validators` to handle user input.
|
|
63
|
-
|
|
64
|
-
Use `options.skip` to skip prompt. It will return `options.defaultValue` if given, `""` otherwise.
|
|
65
|
-
|
|
66
|
-
**Example**
|
|
67
|
-
|
|
68
|
-
```js
|
|
69
|
-
const packageName = await question('Package name', {
|
|
70
|
-
validators: [
|
|
71
|
-
{
|
|
72
|
-
validate: (value) => {
|
|
73
|
-
if (
|
|
74
|
-
return `Folder ${value} already exists
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
}
|
|
78
|
-
]
|
|
79
|
-
});
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
**This package provide some validators for common usage**
|
|
83
|
-
|
|
84
|
-
- required
|
|
85
|
-
|
|
86
|
-
```js
|
|
87
|
-
import { prompt, required } from "@topcli/prompts";
|
|
88
|
-
|
|
89
|
-
const name = await prompt("What's your name ?", {
|
|
90
|
-
validators: [required()]
|
|
91
|
-
});
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### `select()`
|
|
95
|
-
|
|
96
|
-
```ts
|
|
97
|
-
select(message: string, options: SelectOptions): Promise<string>
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Scrollable select depending `maxVisible` (default `8`).
|
|
101
|
-
|
|
102
|
-
Use `options.ignoreValues` to skip result render & clear lines after a selected one.
|
|
103
|
-
|
|
104
|
-
Use `options.validators` to handle user input.
|
|
105
|
-
|
|
106
|
-
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
|
|
107
|
-
|
|
108
|
-
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`
|
|
109
|
-
|
|
110
|
-
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
111
|
-
|
|
112
|
-
Use `options.skip` to skip prompt. It will return the first choice.
|
|
113
|
-
|
|
114
|
-
### `multiselect()`
|
|
115
|
-
|
|
116
|
-
```ts
|
|
117
|
-
multiselect(message: string, options: MultiselectOptions): Promise<[string]>
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
Scrollable multiselect depending `options.maxVisible` (default `8`).<br>
|
|
121
|
-
Use `options.preSelectedChoices` to pre-select choices.
|
|
122
|
-
|
|
123
|
-
Use `options.validators` to handle user input.
|
|
124
|
-
|
|
125
|
-
Use `options.showHint: false` to disable hint (this option is truthy by default).
|
|
126
|
-
|
|
127
|
-
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
|
|
128
|
-
|
|
129
|
-
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`.
|
|
130
|
-
|
|
131
|
-
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
132
|
-
|
|
133
|
-
Use `options.skip` to skip prompt. It will return `options.preSelectedChoices` if given, `[]` otherwise.
|
|
134
|
-
|
|
135
|
-
### `confirm()`
|
|
136
|
-
|
|
137
|
-
```ts
|
|
138
|
-
confirm(message: string, options?: ConfirmOptions): Promise<boolean>
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
Boolean prompt, default to `options.initial` (`false`).
|
|
142
|
-
|
|
143
|
-
> [!TIP]
|
|
144
|
-
> You can answer pressing <kbd>Y</kbd> or <kbd>N</kbd>
|
|
145
|
-
|
|
146
|
-
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
147
|
-
|
|
148
|
-
Use `options.skip` to skip prompt. It will return `options.initial` (`false` by default)
|
|
149
|
-
|
|
150
|
-
### `PromptAgent`
|
|
151
|
-
|
|
152
|
-
The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
|
|
153
|
-
|
|
154
|
-
```ts
|
|
155
|
-
const agent = PromptAgent.agent();
|
|
156
|
-
agent.nextAnswer("John");
|
|
157
|
-
|
|
158
|
-
const input = await question("What's your name?");
|
|
159
|
-
assert.equal(input, "John");
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
> [!WARNING]
|
|
163
|
-
> Answers set with `PromptAgent` will **bypass** any logical & validation rules.
|
|
164
|
-
> Examples:
|
|
165
|
-
> - When using `question()`, `validators` functions will not be executed.
|
|
166
|
-
> - When using `select()`, the answer can be different from the available choices.
|
|
167
|
-
> - When using `confirm()`, the answer can be any type other than boolean.
|
|
168
|
-
> - etc<br>
|
|
169
|
-
> **Use with caution**
|
|
170
|
-
|
|
171
|
-
## Errors
|
|
172
|
-
|
|
173
|
-
### `AbortError`
|
|
174
|
-
|
|
175
|
-
```ts
|
|
176
|
-
export class AbortError extends Error {
|
|
177
|
-
constructor(message: string) {
|
|
178
|
-
super(message);
|
|
179
|
-
this.name = "AbortError";
|
|
180
|
-
}
|
|
181
|
-
}
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
## Interfaces
|
|
185
|
-
|
|
186
|
-
```ts
|
|
187
|
-
type Stdin = NodeJS.ReadStream & {
|
|
188
|
-
fd: 0;
|
|
189
|
-
};
|
|
190
|
-
|
|
191
|
-
type Stdout = NodeJS.WriteStream & {
|
|
192
|
-
fd: 1;
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
export interface AbstractPromptOptions {
|
|
196
|
-
stdin?: Stdin;
|
|
197
|
-
stdout?: Stdout;
|
|
198
|
-
message: string;
|
|
199
|
-
sginal?: AbortSignal;
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
export interface PromptValidator<T = string | string[] | boolean> {
|
|
203
|
-
validate: (input: T) => boolean;
|
|
204
|
-
error: (input: T) => string;
|
|
205
|
-
}
|
|
206
|
-
|
|
207
|
-
export interface QuestionOptions extends SharedOptions {
|
|
208
|
-
defaultValue?: string;
|
|
209
|
-
validators?: Validator[];
|
|
210
|
-
secure?: boolean;
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
export interface Choice {
|
|
214
|
-
value: any;
|
|
215
|
-
label: string;
|
|
216
|
-
description?: string;
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
export interface SelectOptions extends SharedOptions {
|
|
220
|
-
choices: (Choice | string)[];
|
|
221
|
-
maxVisible?: number;
|
|
222
|
-
ignoreValues?: (string | number | boolean)[];
|
|
223
|
-
validators?: Validator[];
|
|
224
|
-
autocomplete?: boolean;
|
|
225
|
-
caseSensitive?: boolean;
|
|
226
|
-
}
|
|
227
|
-
|
|
228
|
-
export interface MultiselectOptions extends SharedOptions {
|
|
229
|
-
choices: (Choice | string)[];
|
|
230
|
-
maxVisible?: number;
|
|
231
|
-
preSelectedChoices?: (Choice | string)[];
|
|
232
|
-
validators?: Validator[];
|
|
233
|
-
autocomplete?: boolean;
|
|
234
|
-
caseSensitive?: boolean;
|
|
235
|
-
showHint?: boolean;
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
export interface ConfirmOptions extends SharedOptions {
|
|
239
|
-
initial?: boolean;
|
|
240
|
-
}
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
## Contributing
|
|
244
|
-
|
|
245
|
-
Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
|
|
246
|
-
|
|
247
|
-
Open an issue if you want to provide feedback such as bug reports or enchancements.
|
|
248
|
-
|
|
249
|
-
## Contributors
|
|
250
|
-
|
|
251
|
-
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
|
|
252
|
-
<!-- prettier-ignore-start -->
|
|
253
|
-
<!-- markdownlint-disable -->
|
|
254
|
-
<table>
|
|
255
|
-
<tbody>
|
|
256
|
-
<tr>
|
|
257
|
-
<td align="center" valign="top" width="14.28%"><a href="https://github.com/PierreDemailly"><img src="https://avatars.githubusercontent.com/u/39910767?v=4?s=100" width="100px;" alt="PierreDemailly"/><br /><sub><b>PierreDemailly</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=PierreDemailly" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=PierreDemailly" title="Tests">⚠️</a></td>
|
|
258
|
-
<td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/thomas-gentilhomme/"><img src="https://avatars.githubusercontent.com/u/4438263?v=4?s=100" width="100px;" alt="Gentilhomme"/><br /><sub><b>Gentilhomme</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Afraxken" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/TopCli/prompts/commits?author=fraxken" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=fraxken" title="Documentation">📖</a></td>
|
|
259
|
-
<td align="center" valign="top" width="14.28%"><a href="http://tonygo.dev"><img src="https://avatars0.githubusercontent.com/u/22824417?v=4?s=100" width="100px;" alt="Tony Gorez"/><br /><sub><b>Tony Gorez</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Atony-go" title="Reviewed Pull Requests">👀</a></td>
|
|
260
|
-
<td align="center" valign="top" width="14.28%"><a href="http://sofiand.github.io/portfolio-client/"><img src="https://avatars.githubusercontent.com/u/39944043?v=4?s=100" width="100px;" alt="Yefis"/><br /><sub><b>Yefis</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Documentation">📖</a></td>
|
|
261
|
-
<td align="center" valign="top" width="14.28%"><a href="http://justie.dev"><img src="https://avatars.githubusercontent.com/u/7118300?v=4?s=100" width="100px;" alt="Ben"/><br /><sub><b>Ben</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=JUSTIVE" title="Documentation">📖</a> <a href="#maintenance-JUSTIVE" title="Maintenance">🚧</a></td>
|
|
262
|
-
<td align="center" valign="top" width="14.28%"><a href="https://github.com/ncukondo"><img src="https://avatars.githubusercontent.com/u/17022138?v=4?s=100" width="100px;" alt="Takeshi Kondo"/><br /><sub><b>Takeshi Kondo</b></sub></a><br /><a href="#maintenance-ncukondo" title="Maintenance">🚧</a></td>
|
|
263
|
-
<td align="center" valign="top" width="14.28%"><a href="https://github.com/FredGuiou"><img src="https://avatars.githubusercontent.com/u/99122562?v=4?s=100" width="100px;" alt="FredGuiou"/><br /><sub><b>FredGuiou</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Tests">⚠️</a> <a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Documentation">📖</a></td>
|
|
264
|
-
</tr>
|
|
265
|
-
<tr>
|
|
266
|
-
<td align="center" valign="top" width="14.28%"><a href="https://github.com/noxify"><img src="https://avatars.githubusercontent.com/u/521777?v=4?s=100" width="100px;" alt="Marcus Reinhardt"/><br /><sub><b>Marcus Reinhardt</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Tests">⚠️</a> <a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Documentation">📖</a></td>
|
|
267
|
-
</tr>
|
|
268
|
-
</tbody>
|
|
269
|
-
</table>
|
|
270
|
-
|
|
271
|
-
<!-- markdownlint-restore -->
|
|
272
|
-
<!-- prettier-ignore-end -->
|
|
273
|
-
|
|
274
|
-
<!-- ALL-CONTRIBUTORS-LIST:END -->
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="./public/banner.png" alt="@topcli/prompts">
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
[](https://github.com/TopCli/prompts/commit-activity)
|
|
6
|
+
[](https://github.com/TopCli/prompts/blob/main/LICENSE)
|
|
7
|
+
[](https://ossf.github.io/scorecard-visualizer/#/projects/github.com/TopCli/prompts)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
<img src="./public/topcli.gif" alt="demo">
|
|
11
|
+
</div>
|
|
12
|
+
|
|
13
|
+
## Requirements
|
|
14
|
+
- [Node.js](https://nodejs.org/en/) v20 or higher
|
|
15
|
+
|
|
16
|
+
## Getting Started
|
|
17
|
+
|
|
18
|
+
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
$ npm i @topcli/prompts
|
|
22
|
+
# or
|
|
23
|
+
$ yarn add @topcli/prompts
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Usage exemple
|
|
27
|
+
|
|
28
|
+
You can locally run `node ./demo.js`
|
|
29
|
+
|
|
30
|
+
```js
|
|
31
|
+
import { question, confirm, select, multiselect } from "@topcli/prompts";
|
|
32
|
+
|
|
33
|
+
const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
|
|
34
|
+
|
|
35
|
+
const name = await question("Project name ?", { defaultValue: "foo" });
|
|
36
|
+
const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
|
|
37
|
+
const isCLI = await confirm("Your project is a CLI ?", { initial: true });
|
|
38
|
+
const os = await multiselect("Choose OS", {
|
|
39
|
+
choices: ["linux", "mac", "windows"],
|
|
40
|
+
preSelectedChoices: ["linux"]
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
console.log(name, runner, isCLI, os);
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## API
|
|
47
|
+
|
|
48
|
+
### `question()`
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
question(message: string, options?: PromptOptions): Promise<string>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Simple prompt, similar to `rl.question()` with an improved UI.
|
|
55
|
+
|
|
56
|
+
Use `options.defaultValue` to set a default value.
|
|
57
|
+
|
|
58
|
+
Use `options.secure` if you need to hide both input and answer.
|
|
59
|
+
|
|
60
|
+
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
61
|
+
|
|
62
|
+
Use `options.validators` to handle user input.
|
|
63
|
+
|
|
64
|
+
Use `options.skip` to skip prompt. It will return `options.defaultValue` if given, `""` otherwise.
|
|
65
|
+
|
|
66
|
+
**Example**
|
|
67
|
+
|
|
68
|
+
```js
|
|
69
|
+
const packageName = await question('Package name', {
|
|
70
|
+
validators: [
|
|
71
|
+
{
|
|
72
|
+
validate: (value) => {
|
|
73
|
+
if (fs.existsSync(path.join(process.cwd(), value))) {
|
|
74
|
+
return `Folder ${value} already exists`;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
]
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**This package provide some validators for common usage**
|
|
83
|
+
|
|
84
|
+
- required
|
|
85
|
+
|
|
86
|
+
```js
|
|
87
|
+
import { prompt, required } from "@topcli/prompts";
|
|
88
|
+
|
|
89
|
+
const name = await prompt("What's your name ?", {
|
|
90
|
+
validators: [required()]
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### `select()`
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
select(message: string, options: SelectOptions): Promise<string>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Scrollable select depending `maxVisible` (default `8`).
|
|
101
|
+
|
|
102
|
+
Use `options.ignoreValues` to skip result render & clear lines after a selected one.
|
|
103
|
+
|
|
104
|
+
Use `options.validators` to handle user input.
|
|
105
|
+
|
|
106
|
+
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
|
|
107
|
+
|
|
108
|
+
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`
|
|
109
|
+
|
|
110
|
+
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
111
|
+
|
|
112
|
+
Use `options.skip` to skip prompt. It will return the first choice.
|
|
113
|
+
|
|
114
|
+
### `multiselect()`
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
multiselect(message: string, options: MultiselectOptions): Promise<[string]>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Scrollable multiselect depending `options.maxVisible` (default `8`).<br>
|
|
121
|
+
Use `options.preSelectedChoices` to pre-select choices.
|
|
122
|
+
|
|
123
|
+
Use `options.validators` to handle user input.
|
|
124
|
+
|
|
125
|
+
Use `options.showHint: false` to disable hint (this option is truthy by default).
|
|
126
|
+
|
|
127
|
+
Use `options.autocomplete` to allow filtered choices. This can be useful for a large list of choices.
|
|
128
|
+
|
|
129
|
+
Use `options.caseSensitive` to make autocomplete filters case sensitive. Default `false`.
|
|
130
|
+
|
|
131
|
+
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
132
|
+
|
|
133
|
+
Use `options.skip` to skip prompt. It will return `options.preSelectedChoices` if given, `[]` otherwise.
|
|
134
|
+
|
|
135
|
+
### `confirm()`
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
confirm(message: string, options?: ConfirmOptions): Promise<boolean>
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Boolean prompt, default to `options.initial` (`false`).
|
|
142
|
+
|
|
143
|
+
> [!TIP]
|
|
144
|
+
> You can answer pressing <kbd>Y</kbd> or <kbd>N</kbd>
|
|
145
|
+
|
|
146
|
+
Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
|
|
147
|
+
|
|
148
|
+
Use `options.skip` to skip prompt. It will return `options.initial` (`false` by default)
|
|
149
|
+
|
|
150
|
+
### `PromptAgent`
|
|
151
|
+
|
|
152
|
+
The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
const agent = PromptAgent.agent();
|
|
156
|
+
agent.nextAnswer("John");
|
|
157
|
+
|
|
158
|
+
const input = await question("What's your name?");
|
|
159
|
+
assert.equal(input, "John");
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
> [!WARNING]
|
|
163
|
+
> Answers set with `PromptAgent` will **bypass** any logical & validation rules.
|
|
164
|
+
> Examples:
|
|
165
|
+
> - When using `question()`, `validators` functions will not be executed.
|
|
166
|
+
> - When using `select()`, the answer can be different from the available choices.
|
|
167
|
+
> - When using `confirm()`, the answer can be any type other than boolean.
|
|
168
|
+
> - etc<br>
|
|
169
|
+
> **Use with caution**
|
|
170
|
+
|
|
171
|
+
## Errors
|
|
172
|
+
|
|
173
|
+
### `AbortError`
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
export class AbortError extends Error {
|
|
177
|
+
constructor(message: string) {
|
|
178
|
+
super(message);
|
|
179
|
+
this.name = "AbortError";
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Interfaces
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
type Stdin = NodeJS.ReadStream & {
|
|
188
|
+
fd: 0;
|
|
189
|
+
};
|
|
190
|
+
|
|
191
|
+
type Stdout = NodeJS.WriteStream & {
|
|
192
|
+
fd: 1;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
export interface AbstractPromptOptions {
|
|
196
|
+
stdin?: Stdin;
|
|
197
|
+
stdout?: Stdout;
|
|
198
|
+
message: string;
|
|
199
|
+
sginal?: AbortSignal;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export interface PromptValidator<T = string | string[] | boolean> {
|
|
203
|
+
validate: (input: T) => boolean;
|
|
204
|
+
error: (input: T) => string;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
export interface QuestionOptions extends SharedOptions {
|
|
208
|
+
defaultValue?: string;
|
|
209
|
+
validators?: Validator[];
|
|
210
|
+
secure?: boolean;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
export interface Choice {
|
|
214
|
+
value: any;
|
|
215
|
+
label: string;
|
|
216
|
+
description?: string;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
export interface SelectOptions extends SharedOptions {
|
|
220
|
+
choices: (Choice | string)[];
|
|
221
|
+
maxVisible?: number;
|
|
222
|
+
ignoreValues?: (string | number | boolean)[];
|
|
223
|
+
validators?: Validator[];
|
|
224
|
+
autocomplete?: boolean;
|
|
225
|
+
caseSensitive?: boolean;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
export interface MultiselectOptions extends SharedOptions {
|
|
229
|
+
choices: (Choice | string)[];
|
|
230
|
+
maxVisible?: number;
|
|
231
|
+
preSelectedChoices?: (Choice | string)[];
|
|
232
|
+
validators?: Validator[];
|
|
233
|
+
autocomplete?: boolean;
|
|
234
|
+
caseSensitive?: boolean;
|
|
235
|
+
showHint?: boolean;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
export interface ConfirmOptions extends SharedOptions {
|
|
239
|
+
initial?: boolean;
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## Contributing
|
|
244
|
+
|
|
245
|
+
Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
|
|
246
|
+
|
|
247
|
+
Open an issue if you want to provide feedback such as bug reports or enchancements.
|
|
248
|
+
|
|
249
|
+
## Contributors
|
|
250
|
+
|
|
251
|
+
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
|
|
252
|
+
<!-- prettier-ignore-start -->
|
|
253
|
+
<!-- markdownlint-disable -->
|
|
254
|
+
<table>
|
|
255
|
+
<tbody>
|
|
256
|
+
<tr>
|
|
257
|
+
<td align="center" valign="top" width="14.28%"><a href="https://github.com/PierreDemailly"><img src="https://avatars.githubusercontent.com/u/39910767?v=4?s=100" width="100px;" alt="PierreDemailly"/><br /><sub><b>PierreDemailly</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=PierreDemailly" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=PierreDemailly" title="Tests">⚠️</a></td>
|
|
258
|
+
<td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/thomas-gentilhomme/"><img src="https://avatars.githubusercontent.com/u/4438263?v=4?s=100" width="100px;" alt="Gentilhomme"/><br /><sub><b>Gentilhomme</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Afraxken" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/TopCli/prompts/commits?author=fraxken" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=fraxken" title="Documentation">📖</a></td>
|
|
259
|
+
<td align="center" valign="top" width="14.28%"><a href="http://tonygo.dev"><img src="https://avatars0.githubusercontent.com/u/22824417?v=4?s=100" width="100px;" alt="Tony Gorez"/><br /><sub><b>Tony Gorez</b></sub></a><br /><a href="https://github.com/TopCli/prompts/pulls?q=is%3Apr+reviewed-by%3Atony-go" title="Reviewed Pull Requests">👀</a></td>
|
|
260
|
+
<td align="center" valign="top" width="14.28%"><a href="http://sofiand.github.io/portfolio-client/"><img src="https://avatars.githubusercontent.com/u/39944043?v=4?s=100" width="100px;" alt="Yefis"/><br /><sub><b>Yefis</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=SofianD" title="Documentation">📖</a></td>
|
|
261
|
+
<td align="center" valign="top" width="14.28%"><a href="http://justie.dev"><img src="https://avatars.githubusercontent.com/u/7118300?v=4?s=100" width="100px;" alt="Ben"/><br /><sub><b>Ben</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=JUSTIVE" title="Documentation">📖</a> <a href="#maintenance-JUSTIVE" title="Maintenance">🚧</a></td>
|
|
262
|
+
<td align="center" valign="top" width="14.28%"><a href="https://github.com/ncukondo"><img src="https://avatars.githubusercontent.com/u/17022138?v=4?s=100" width="100px;" alt="Takeshi Kondo"/><br /><sub><b>Takeshi Kondo</b></sub></a><br /><a href="#maintenance-ncukondo" title="Maintenance">🚧</a></td>
|
|
263
|
+
<td align="center" valign="top" width="14.28%"><a href="https://github.com/FredGuiou"><img src="https://avatars.githubusercontent.com/u/99122562?v=4?s=100" width="100px;" alt="FredGuiou"/><br /><sub><b>FredGuiou</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Tests">⚠️</a> <a href="https://github.com/TopCli/prompts/commits?author=FredGuiou" title="Documentation">📖</a></td>
|
|
264
|
+
</tr>
|
|
265
|
+
<tr>
|
|
266
|
+
<td align="center" valign="top" width="14.28%"><a href="https://github.com/noxify"><img src="https://avatars.githubusercontent.com/u/521777?v=4?s=100" width="100px;" alt="Marcus Reinhardt"/><br /><sub><b>Marcus Reinhardt</b></sub></a><br /><a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Code">💻</a> <a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Tests">⚠️</a> <a href="https://github.com/TopCli/prompts/commits?author=noxify" title="Documentation">📖</a></td>
|
|
267
|
+
</tr>
|
|
268
|
+
</tbody>
|
|
269
|
+
</table>
|
|
270
|
+
|
|
271
|
+
<!-- markdownlint-restore -->
|
|
272
|
+
<!-- prettier-ignore-end -->
|
|
273
|
+
|
|
274
|
+
<!-- ALL-CONTRIBUTORS-LIST:END -->
|