Have ideas to improve npm?Join in the discussion! »

    promptly
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/promptly package

    3.2.0 • Public • Published

    promptly

    NPM version Downloads Build Status Coverage Status Dependency status Dev Dependency status

    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 process.stdin
    output Output stream to write to Stream 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:

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

      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:

      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:

      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

    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, except that trim defaults to false.

    Examples

    • Ask to confirm something important:

      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, except that trim defaults to false.

    Examples

    • Ask to choose between:

      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, except that trim and silent default to false and default is an empty string (to allow empty passwords).

    Examples

    • Ask for a password:

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

      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.

    Install

    npm i promptly

    DownloadsWeekly Downloads

    1,336,874

    Version

    3.2.0

    License

    MIT

    Unpacked Size

    15.5 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar
    • avatar