@exalif/inquirer-prompt-builder NPM

@exalif/inquirer-prompt-builder

@exalif/inquirer-prompt-builder is a TypeScript library that simplifies the creation and management of complex Inquirer.js prompts. This library supports all major Inquirer prompt types and allows for dynamic and conditional prompts based on user responses.

Features

Supports all Inquirer.js prompt types (input, select, confirm, checkbox, password, rawlist, expand, editor).
Allows dynamic and conditional prompts based on previous answers.
Simplifies the creation of CLI applications with robust and flexible user interactions.

Installation

To install the @exalif/inquirer-prompt-builder library, run:

yarn add @exalif/@exalif/inquirer-prompt-builder

Usage

Here's an example of how to use @exalif/@exalif/inquirer-prompt-builder in your project:

import { PromptBuilder } from '@exalif/inquirer-prompt-builder';

async function main() {
  const prompts = [
    {
      type: 'select' as const,
      name: 'appType',
      message: 'What type of application are you working on?',
      choices: [
        { name: 'Node', value: 'Node' },
        { name: 'Angular', value: 'Angular' },
        { name: 'Java', value: 'Java' },
      ]
    },
    {
      type: 'input' as const,
      name: 'nodeVersion',
      message: 'Which Node.js version are you using?',
      when: (answers) => answers.appType === 'Node' || answers.appType === 'Angular',
    },
    {
      type: 'confirm' as const,
      name: 'setupComplete',
      message: 'Is the setup complete?',
    },
  ];

  // a method that returns previously stores answers. You can store it in a file or anywhere you want
  const retrieveAnswers = async () => {
    return {};
  };

  const storeAnswer = async (name: string, value: string | boolean) => {
    // store answer somewhere
  };

  const builder = new PromptBuilder(
    prompts,
    retrieveAnswers,
    storeAnswer,
  );
  const answers = await builder.run();

  console.log('Collected answers:', answers);
}

main();

Value validation

The PromptBuilder class allows you to add validation to any prompt. The validation function is specified using the validate property. This function should return true if the input is valid, or a string containing an error message if the input is invalid. The user will be prompted to provide input again until the validation passes.

import { PromptBuilder } from '@exalif/inquirer-prompt-builder';

async function main() {
  const prompts = [
    {
      type: 'input' as const,
      name: 'username',
      message: 'Enter your username:',
      validate: (input) => {
        const isValid = /^[a-zA-Z0-9_]+$/.test(input);
        return isValid ? true : 'Username can only contain letters, numbers, and underscores.';
      },
    },
    {
      type: 'password' as const,
      name: 'password',
      message: 'Enter your password:',
      validate: (input) => {
        return input.length >= 8 ? true : 'Password must be at least 8 characters long.';
      },
    },
  ];

  const promptBuilder = new PromptBuilder(prompts);
  const answers = await promptBuilder.run();

  console.log('Collected answers:', answers);
}

main();

Conditional Prompts with `when`

The when property allows you to conditionally show prompts based on previous answers. This is useful for creating dynamic question flows where certain prompts are only relevant under specific conditions.

import { PromptBuilder } from '@exalif/inquirer-prompt-builder';

async function main() {
  const prompts = [
    {
      type: 'select' as const,
      name: 'appType',
      message: 'What type of application are you working on?',
      choices: [
        { name: 'Node', value: 'Node' },
        { name: 'Clojure', value: 'Clojure' },
      ],
    },
    {
      type: 'input' as const,
      name: 'nodeVersion',
      message: 'Which Node.js version are you using?',
      when: (answers) => answers.appType === 'Node' || answers.appType === 'Angular',
    },
  ];

  const promptBuilder = new PromptBuilder(prompts);
  const answers = await promptBuilder.run();

  console.log('Collected answers:', answers);
}

main();

`default` and stored values

Key Properties

default: This property specifies the default value to be used if the user does not provide an input. It can be a static value or a function that takes previous answers and choices as arguments while returning the value.
storeValue: A boolean that, if set to true, indicates that the value should be stored after the prompt is completed.
preferStoredValue: A boolean that determines whether to use a stored value over a default value if both are available.

Behavior

Default Value Only:
- If only the default value is provided, it will be used as the fallback value for the prompt.
Stored Value with preferStoredValue set to true:
- The retrieveStoredAnswers method is called to fetch the stored value when instantiating the class
- If a stored value exists (i.e., it’s not null or undefined), it is used as the default value for the prompt, overriding any static or function-based default provided.
Stored Value with preferStoredValue set to false:
- The default value is used if provided.
- If no default value is provided, the retrieveStoredAnswers is called, and its result is used as the fallback value.
Handling Nullish Values:
- If the stored value is null or undefined, the default value (if provided) is used.
- If no default value exists, and the stored value is null or undefined, the prompt does not pre-fill any value.

Example Usage

const prompts = [
  {
    type: 'input' as const,
    name: 'username',
    message: 'What is your username?',
    default: 'DefaultUsername',
    storeValue: true,
    preferStoredValue: true,
  },
];

const promptBuilder = new PromptBuilder(prompts);
const answers = await promptBuilder.run();
console.log(answers);

In this example, the prompt for username will prefer a stored value over the default value if it exists. If not, the default value "DefaultUsername" will be used.

JsonStorage Utility

The library provide an example JsonStorage utility provides a simple way to store and retrieve values in a JSON file. But we encourage developers to write their own storage system.