Prask

Lightweight prompting library for terminal apps.

Install

npm install --save prask

Prompts

| Input | Selection | Others | | ----------------------- | --------------------------- | ------------------- | | string | multiselect | log | | invisible | select | prompt | | password | boolean | spinner | | number | toggle | | | | rating | |

string

This prompt can be used to ask the user for a string value.

import {string} from 'prask';
import color from 'tiny-colors';

const result = await string ({
  /* REQUIRED OPTIONS */
  message: 'What is your name?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: 'John Doe', // Optional default value, to allow the user to quickly press Enter for it
  required: true, // Whether a non-empty value for this prompt is required or not
  format: ( value, settled ) => value.length >= 2 ? colors.green ( value ) : colors.red ( value ), // Optional formatting function, the visual length of the output string must remain the same
  validate: value => value.length >= 2 // Optional validation function
});

Interactions:

| Trigger | Description | | ------- | -------------------------------------------------------------------------------- | | Esc | Quit the prompt, which will resolve to undefined. | | Enter | Submit the value, or the initial value if visible, checking if it's valid first. | | Tab | Edit the initial value, if visible. |

invisible

This prompt can be used to ask the user for a password, without visually leaking even the length of the password to the console.

import {invisible} from 'prask';

const result = await invisible ({
  /* REQUIRED OPTIONS */
  message: 'What is your password?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: 'P@assword!', // Optional default value, to allow the user to quickly press Enter for it, better not to use it since it will be visible
  required: true, // Whether a non-empty value for this prompt is required or not
  validate: value => value.length >= 8 // Optional validation function
});

It can be interacted with exactly like a string prompt, the only difference is that the value is invisible.

password

This prompt can be used to ask the user for a password, without visually leaking the characters that make it up to the console.

import {password} from 'prask';

const result = await password ({
  /* REQUIRED OPTIONS */
  message: 'What is your password?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: 'P@assword!', // Optional default value, to allow the user to quickly press Enter for it, better not to use it since it will be visible
  required: true, // Whether a non-empty value for this prompt is required or not
  validate: value => value.length >= 8 // Optional validation function
});

It can be interacted with exactly like a string prompt, the only difference is that every character in the value will be replaced with an asterisk.

number

This prompt can be used to ask the user for a numeric value.

import {number} from 'prask';
import colors from 'tiny-colors';

const result = await number ({
  /* REQUIRED OPTIONS */
  message: 'What is your favorite even number?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: 42, // Optional default value, to allow the user to quickly press Enter for it
  format: ( value, settled ) => ( value % 2 ) ? colors.red ( value ) : colors.green ( value ), // Optional formatting function, the visual length of the output string must remain the same
  validate: value => ( value % 2 ) ? 'The number must be even' : true // Optional validation function
});

It can be interacted with exactly like a string prompt, the main difference is that the value of the input is also automatically validated to be a number, plus the following extra interactions are supported:

| Trigger | Description | | ------------- | --------------------------------- | | Up/Right | Increment the current value by 1. | | Down/Left | Decrement the current value by 1. |

multiselect

This prompt can be used to ask the user to pick from zero to many options between the provided ones.

import {multiselect} from 'prask';

const result = await multiselect ({
  /* REQUIRED OPTIONS */
  message: 'Which countries would you like to visit?', // The message that the user will read
  options: [
    { title: 'Italy', value: 'it' },
    { title: 'Turkey', value: 'tr' },
    { title: 'United Kingdom', value: 'uk' }
  ],
  /* OPTIONAL OPTIONS */
  limit: 10, // Limit to this number the maximum number of options visible at one time
  min: 1, // Require at least this number of options to be selected
  max: 10, // Require at most this number of options to be selected
  searchable: false, // Turn off support for filtering the list of options
  validate: values => ( values.length % 2 ) // Optional validation function
});

Each option must have the following shape:

type Option<T> = {
  /* REQUIRED VALUES */
  title: string, // The name of the option that will be showed to the user
  value: T, // The value of the option that the prompt will return you when this option is selected
  /* OPTIONAL VALUES */
  disabled?: boolean, // Whether this option can be toggled or not
  description?: string, // The description that will be showed next to the title
  heading?: boolean, // Whether this option is an unselectable heading or not
  hint?: string, // The description that will be showed next to the title, only when the item is focused
  selected?: boolean // Whether this option is pre-selected or not
};

Options can be provided dynamically also, with a function that returns an array of options depending on the current query. That can also be used to customize how results are searched and ranked.

Interactions:

| Trigger | Description | | ------- | -------------------------------------------------------------------------------------- | | Esc | Quit the prompt, which will resolve to undefined. | | Enter | Submit the selected values, checking if the selection is valid first. | | Space | Toggle the focused option. | | Up | Move the focus to the previous item, and potentially scroll to the previous page. | | Down | Move the focus to the next item, and potentially scroll to the next page. | | * | All other keys will be used to edit the search query, which will filter down the list. |

select

This prompt can be used to ask the user to pick one option between the provided ones.

import {select} from 'prask';

const result = await select ({
  /* REQUIRED OPTIONS */
  message: 'Which country would you like to visit first?', // The message that the user will read
  options: [
    { title: 'Italy', value: 'it' },
    { title: 'Turkey', value: 'tr' },
    { title: 'United Kingdom', value: 'uk' }
  ],
  /* OPTIONAL OPTIONS */
  limit: 10, // Limit to this number the maximum number of options visible at one time
  searchable: false, // Turn off support for filtering the list of options
  validate: value => value !== 'Foo' // Optional validation function
});

It can be interacted with exactly like a multiselect prompt.

boolean

This prompt can be used to ask the user to pick between yes and no.

import {boolean} from 'prask';

const result = await boolean ({
  /* REQUIRED OPTIONS */
  message: 'Do you like this library?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: true // Select this option by default
});

It can be interacted with exactly like a select prompt, except that search is turned off for it.

toggle

This prompt can be used to ask the user to pick between yes and no, using a single line of output, rather than the three that boolean needs.

import {toggle} from 'prask';

const result = await toggle ({
  /* REQUIRED OPTIONS */
  message: 'Do you like this library?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: true // Select this option by default
});

Interactions:

| Trigger | Description | | -------------------------------- | --------------------------------------------------- | | Esc | Quit the prompt, which will resolve to undefined. | | Enter | Submit the selected option. | | Left/Right/Up/Down/Tab | Select the other option. |

rating

This prompt can be used to ask the user for a numeric rating between 1 and 5.

import {rating} from 'prask';

const result = await rating ({
  /* REQUIRED OPTIONS */
  message: 'How would you rate this library?', // The message that the user will read
  /* OPTIONAL OPTIONS */
  initial: 5 // Select this option by default
});

Interactions:

| Trigger | Description | | ------------- | --------------------------------------------------- | | Esc | Quit the prompt, which will resolve to undefined. | | Enter | Submit the selected rating. | | Right/Up | Increment the selected rating. | | Left/Down | Decrement the selected rating. |

log

This utility provides functions for logging a line of text to the console, with the same style that the built-in prompts use.

import {log} from 'prask';

log.success ( 'Success message' );
log.error ( 'Error message' );
log.warning ( 'Warning message' );
log.question ( 'Question message' );
log.info ( 'Info message' );

prompt

This is a low-level general prompt, which is used internally to implement the other higher-level prompts, and which you can use to implement your own custom prompts.

import {prompt} from 'prask';
import color from 'tiny-colors';

// Let's define the "rating" prompt, it returns a number between 1 and 5, which is the rating the user picked
// This is the actual internal implementation for that component, so you can see exactly how it works

type Rating = 1 | 2 | 3 | 4 | 5;

type Options = {
  message: string,
  initial?: Rating
};

// A prompt could always resolve to "undefined", if the user escapes from it
const rating = ( options: Options ): Promise<Rating | undefined> => {

  // Let's define some internal constants we need for rendering

  const STAR_ACTIVE = color.green ( '●' );
  const STAR_INACTIVE = '○';
  const STARS_DIVIDER = '─────';
  const LABELS_DIVIDER = '     ';

  // Let's define some internal state variables
  // The status variable let's us keep track of whether this prompt was escaped (-1), submitted (1), or it's still pending (0)

  let {message, initial = 3} = options;
  let status: -1 | 0 | 1 = 0;
  let current = initial;

  // Let's define some components
  // Basically each prompt re-renders its components in a loop, React-style
  // Each prompt must return something to render, which can be a single component or an array of components
  // A component is just a function that can either return a string, which will be printed to the console, or undefined, which will be ignored
  // The "prompt" function takes care of cleaning up the previous output and replacing it with the new one
  // That's basically how the entire library works, the "prompt" function tells you when a key is pressed, and you just tell it what to render next

  const getStatusSymbol = ( status ): string => {
    if ( status < 0 ) return color.red ( '✖' );
    if ( status > 0 ) return color.green ( '✔' );
    return color.cyan.bold ( '?' );
  };

  const question = (): string => {
    const question = `${getStatusSymbol ()} ${color.bold ( message )}`;
    const result = status === 1 ? color.cyan ( String ( current ) ) : '';
    return [question, result].join ( ' ' );
  };

  const stars = (): string => {
    const star1 = ( current === 1 ) ? STAR_ACTIVE : STAR_INACTIVE;
    const star2 = ( current === 2 ) ? STAR_ACTIVE : STAR_INACTIVE;
    const star3 = ( current === 3 ) ? STAR_ACTIVE : STAR_INACTIVE;
    const star4 = ( current === 4 ) ? STAR_ACTIVE : STAR_INACTIVE;
    const star5 = ( current === 5 ) ? STAR_ACTIVE : STAR_INACTIVE;
    const stars = [star1, star2, star3, star4, star5].join ( STARS_DIVIDER );
    return stars;
  };

  const labels = (): string => {
    return [1, 2, 3, 4, 5].join ( LABELS_DIVIDER );
  };

  // Now let's handle keypresses

  return prompt ( ( resolve, {key} ) => {
    if ( key === '' ) { // Initial render, no key has been pressed yet
      return [question, stars, labels];
    } else if ( key === 'escape' ) { // Escape, let's bail out
      status = -1;
      resolve ( undefined );
      return [question];
    } else if ( key === 'return' ) { // Enter, let's return the current rating
      status = 1;
      resolve ( current );
      return [question];
    } else if ( key === 'left' || key === 'down' ) { // Left or Down, let's decrement the rating, if possible
      current = Math.max ( 1, current - 1 );
      return [question, stars, labels];
    } else if ( key === 'right' || key === 'up' ) { // Right or Up, let's increment the rating, if possible
      current = Math.min ( 5, current + 1 );
      return [question, stars, labels];
    } else { // Something else was pressed, let's just ignore it
      return [question, stars, labels];
    }
  });

};

spinner

The spinner prompt is a convenience wrapper around tiny-spinner, which you could also use directly if you prefer.

It allows to notify the user of in progress operations, and can resolve to a successful or an unsuccessful state.

import {spinner} from 'prompts';

const result = await spinner ( async ({ update, resolve, reject }) => {
  update ( 'Working' );
  await delay ( 750 );
  update ( 'Working hard' );
  await delay ( 750 );
  update ( 'Working harder' );
  await delay ( 750 );
  update ( 'Working real hard' );
  await delay ( 750 );
  let result = true; // Let's say this is the result of the operation
  if ( result ) {
    resolve ( 'Work succeeded' );
  } else {
    reject ( 'Work failed' );
  }
});

License

MIT © Fabio Spampinato