228 lines
6.6 KiB
Markdown
228 lines
6.6 KiB
Markdown
# promptly
|
|
|
|
[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url]
|
|
|
|
[npm-url]:https://npmjs.org/package/promptly
|
|
[downloads-image]:https://img.shields.io/npm/dm/promptly.svg
|
|
[npm-image]:https://img.shields.io/npm/v/promptly.svg
|
|
[travis-url]:https://travis-ci.org/moxystudio/node-promptly
|
|
[travis-image]:https://img.shields.io/travis/moxystudio/node-promptly/master.svg
|
|
[codecov-url]:https://codecov.io/gh/moxystudio/node-promptly
|
|
[codecov-image]:https://img.shields.io/codecov/c/github/moxystudio/node-promptly/master.svg
|
|
[david-dm-url]:https://david-dm.org/moxystudio/node-promptly
|
|
[david-dm-image]:https://img.shields.io/david/moxystudio/node-promptly.svg
|
|
[david-dm-dev-url]:https://david-dm.org/moxystudio/node-promptly?type=dev
|
|
[david-dm-dev-image]:https://img.shields.io/david/dev/moxystudio/node-promptly.svg
|
|
|
|
> Simple command line prompting utility.
|
|
|
|
|
|
## Installation
|
|
|
|
`$ npm install promptly`
|
|
|
|
|
|
## API
|
|
|
|
### .prompt(message, [options])
|
|
|
|
Prompts for a value, printing the `message` and waiting for the input.
|
|
Returns a promise that resolves with the input.
|
|
|
|
Available options:
|
|
|
|
| Name | Description | Type | Default |
|
|
| ------ | ------------- | -------- | ------- |
|
|
| default | The default value to use if the user provided an empty input | string | undefined |
|
|
| trim | Trims the user input | boolean | true |
|
|
| validator | A validator or an array of validators | function/array | undefined |
|
|
| retry | Retry if any of the validators fail | boolean | true |
|
|
| silent | Do not print what the user types | boolean | false |
|
|
| replace | Replace each character with the specified string when `silent` is true | string | '' |
|
|
| input | Input stream to read from | [Stream](https://nodejs.org/api/process.html#process_process_stdin) | process.stdin |
|
|
| output | Output stream to write to | [Stream](https://nodejs.org/api/process.html#process_process_stdout) | process.stdout |
|
|
| timeout | Timeout in ms | number | 0 |
|
|
| useDefaultOnTimeout | Return default value if timed out | boolean | false |
|
|
|
|
The same **options** are available to **all functions** but with different default values.
|
|
|
|
#### Examples
|
|
|
|
- Ask for a name:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const name = await promptly.prompt('Name: ');
|
|
console.log(name);
|
|
})();
|
|
```
|
|
|
|
- Ask for a name with a constraint (non-empty value and length > 2):
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
const validator = function (value) {
|
|
if (value.length < 2) {
|
|
throw new Error('Min length of 2');
|
|
}
|
|
|
|
return value;
|
|
};
|
|
|
|
(async () => {
|
|
const name = await promptly.prompt('Name: ', { validator });
|
|
// Since retry is true by default, promptly will keep asking for a name until it is valid
|
|
// Between each prompt, the error message from the validator will be printed
|
|
console.log('Name is:', name);
|
|
})();
|
|
|
|
```
|
|
|
|
- Same as above but do not retry automatically:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
const validator = function (value) {
|
|
if (value.length < 2) {
|
|
throw new Error('Min length of 2');
|
|
}
|
|
|
|
return value;
|
|
};
|
|
|
|
(async () => {
|
|
try {
|
|
const name = await promptly.prompt('Name: ', { validator, retry: false });
|
|
console.log('Name is:', name);
|
|
} catch (err) {
|
|
console.error('Invalid name:')
|
|
console.error(`- ${err.message}`);
|
|
}
|
|
})();
|
|
```
|
|
|
|
- Ask for a name with timeout:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const name = await promptly.prompt('Name: ', { timeout: 3000 });
|
|
console.log(name);
|
|
})();
|
|
```
|
|
|
|
It throws an `Error("timed out")` if timeout is reached and no default value is provided
|
|
|
|
#### Validators
|
|
|
|
The validators have two purposes: to check and transform input. They can be asynchronous or synchronous
|
|
|
|
```js
|
|
const validator = (value) => {
|
|
// Validation example, throwing an error when invalid
|
|
if (value.length !== 2) {
|
|
throw new Error('Length must be 2');
|
|
}
|
|
|
|
// Parse the value, modifying it
|
|
return value.replace('aa', 'bb');
|
|
}
|
|
|
|
const asyncValidator = async (value) => {
|
|
await myfunc();
|
|
return value;
|
|
}
|
|
```
|
|
|
|
### .confirm(message, [options])
|
|
|
|
Ask the user for confirmation, printing the `message` and waiting for the input.
|
|
Returns a promise that resolves with the answer.
|
|
|
|
Truthy values are: `y`, `yes` and `1`. Falsy values are `n`, `no`, and `0`.
|
|
Comparison is made in a case insensitive way.
|
|
|
|
The options are the same as [prompt](#promptmessage-options), except that `trim` defaults to `false`.
|
|
|
|
#### Examples
|
|
|
|
- Ask to confirm something important:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const answer = await promptly.confirm('Are you really sure? ');
|
|
|
|
console.log('Answer:', answer);
|
|
})();
|
|
```
|
|
|
|
### .choose(message, choices, [options])
|
|
|
|
Ask the user to choose between multiple `choices` (array of choices), printing the `message` and waiting for the input.
|
|
Returns a promise that resolves with the choice.
|
|
|
|
The options are the same as [prompt](#promptmessage-options), except that `trim` defaults to `false`.
|
|
|
|
#### Examples
|
|
|
|
- Ask to choose between:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const choice = await promptly.choose('Do you want an apple or an orange? ', ['apple', 'orange']);
|
|
|
|
console.log('Choice:', choice);
|
|
})();
|
|
```
|
|
|
|
### .password(message, [options])
|
|
|
|
Prompts for a password, printing the `message` and waiting for the input.
|
|
Returns a promise that resolves with the password.
|
|
|
|
The options are the same as [prompt](#promptmessage-options), except that `trim` and `silent` default to `false` and `default` is an empty string (to allow empty passwords).
|
|
|
|
#### Examples
|
|
|
|
- Ask for a password:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const password = await promptly.password('Type a password: ');
|
|
|
|
console.log('Password:', password);
|
|
})();
|
|
```
|
|
|
|
- Ask for a password but mask the input with `*`:
|
|
|
|
```js
|
|
const promptly = require('promptly');
|
|
|
|
(async () => {
|
|
const password = await promptly.password('Type a password: ', { replace: '*' });
|
|
|
|
console.log('Password:', password);
|
|
})();
|
|
```
|
|
|
|
## Tests
|
|
|
|
`$ npm test`
|
|
`$ npm test -- --watch` during development
|
|
|
|
|
|
## License
|
|
|
|
Released under the [MIT License](https://www.opensource.org/licenses/mit-license.php).
|