klaudiosinani/qoa

Minimal interactive command-line prompts

Qoa

Minimal interactive command-line prompts

Description

Lightweight and without any external dependencies qoa enables you to receive various types of user input through a set of intuitive, interactive & verbose command-line prompts. The library utilizes a simple & minimal usage syntax and contains 7 configurable console interfaces, such as plain text, confirmation & password/secret prompts as well as single keypress, quiz & multiple-choice navigable menus.

You can now support the development process through GitHub Sponsors.

Visit the contributing guidelines to learn more on how to translate this document into more languages.

Come over to Gitter or Twitter to share your thoughts on the project.

Highlights

• 7 out-of-the-box interactive prompts
• Zero dependencies
• Lightweight & fast 8.8kB / 71ms
• Clean & concise output
• Simple & minimal usage syntax
• Navigation, quiz & keypress menus
• Secure & hidden input interfaces
• Utilizes async/await expressions
• Configurable & customizable

Contents

• Description
• Highlights
• Install
• Usage
• Prompts
• Configuration
• API
• Development
• Related
• Team
• License

Install

Yarn

yarn add qoa

NPM

npm install qoa

Usage

Import qoa and start using any of the available prompts:

• confirm
• hidden
• input
• interactive
• keypress
• quiz
• secure

In order to sequentially create & display a series of prompts, the asynchronous unary qoa.prompt function can be used. The function accepts as input an array of objects, where each object contains the configuration of its corresponding prompt. The display order of the prompts is based on the order in which the configuration objects are defined inside the array. A new object containing the user's response to each prompt is finally returned by the function.

const qoa = require('qoa');

const {log} = console;

const ps = [
  {
    type: 'input',
    query: 'Type your username:',
    handle: 'username'
  },
  {
    type: 'secure',
    query: 'Type your password:',
    handle: 'password'
  }
];

qoa.prompt(ps).then(log);
//=> { username: 'klaussinani', password: 'token' }

Alternatively, for non sequential use-cases, each prompt can be individually initialized through its respective asynchronous unary function, where each function accepts as input an object containing the prompt's properties/configuration.

const qoa = require('qoa');

const {log} = console;

const login = async () => {
  const username = await qoa.input({
    query: 'Type your username:',
    handle: 'username'
  });

  const password = await qoa.secure({
    query: 'Type your password:',
    handle: 'password'
  });

  return Object.assign({}, username, password);
}

login().then(log);
//=> { username: 'klaussinani', password: 'token' }

Prompts

Confirm Prompt

Initializes a text based input prompt with two accept & deny options. Based on the input provided by the user, the query displayed by the prompt is confirmed or rejected. In order for the query to be confirmed, thus return true, the user must provide exactly the indicated accept string (strict equality). On any other input the query is rejected & false is returned. The return value is a new object with the prompt result stored under the specified handle property.

const qoa = require('qoa');

const {log} = console;

const confirm = {
  type: 'confirm',
  query: 'Update Qoa to latest version?',
  handle: 'update',
  accept: 'Y',
  deny: 'n'
};

// using the `prompt` async method
qoa.prompt([confirm]).then(log);
//=> { update: true }

// using the `confirm` async method
qoa.confirm(confirm).then(log);
//=> { update: true }

Hidden Prompt

Initializes a text based prompt, where each character typed by the user is automatically hidden. The return value is a new object with the prompt result stored under the specified handle property.

const qoa = require('qoa');

const {log} = console;

const hidden = {
  type: 'hidden',
  query: '[sudo] password for admin:',
  handle: 'sudo'
};

// using the `prompt` async method
qoa.prompt([hidden]).then(log);
//=> { sudo: 'admin' }

// using the `hidden` async method
qoa.hidden(hidden).then(log);
//=> { sudo: 'admin' }

Input Prompt

Initializes a text based prompt, where input can be freely provided by the user. The return value is a new object with the prompt result stored under the specified handle property.

const qoa = require('qoa');

const {log} = console;

const input = {
  type: 'input',
  query: 'Select your username:',
  handle: 'username'
};

// using the `prompt` async method
qoa.prompt([input]).then(log);
//=> { username: 'klaussinani' }
  
// using the `input` async method
qoa.input(input).then(log);
//=> { username: 'klaussinani' }

Interactive Prompt

Initializes an interactive navigable menu based prompt, where the user can navigate within a set of options and select only one of them. The options can be defined in the menu array while the navigation indicator can be customized through the symbol option and if omitted the default string '>' will be used. The return value is new object with the selected option stored under the specified handle property. The interactive menu can be navigated through the up arrow/k & down arrow/j keys.

const qoa = require('qoa');

const {log} = console;

const interactive = {
  type: 'interactive',
  query: 'What is your favorite treat?',
  handle: 'treat',
  symbol: '>',
  menu: [
    'Chocolate',
    'Cupcakes',
    'Ice-Cream'
  ]
};

// using the `prompt` async method
qoa.prompt([interactive]).then(log);
//=> { treat: 'Cupcakes' }

// using the `interactive` async method
qoa.interactive(interactive).then(log);
//=> { treat: 'Cupcakes' }

Keypress Prompt

Initializes an non-navigable menu based prompt, where the user can select one of the options defined in the menu array, by pressing the unique key corresponding to it. The options can be up to 9, and the keys are integers x where 1 <= x <= 9. The return value is new object with the selected option stored under the specified handle property.

const qoa = require('qoa');

const {log} = console;

const keypress = {
  type: 'keypress',
  query: 'How useful are the new features?',
  handle: 'features',
  menu: [
    'Meh',
    'Averagely',
    'Very',
    'Super'
  ]
};

// using the `prompt` async method
qoa.prompt([keypress]).then(log);
//=> { features: 'Very' }

// using the `keypress` async method
qoa.keypress(keypress).then(log);
//=> { features: 'Very' }

Quiz Prompt

Initializes an interactive navigable menu based prompt, where the user can navigate within a set options and select only one of them. The displayed menu is consisted of a number amount of options, of which the value of answer is by default one of them, corresponding to the correct answer to the query, and the rest amount - 1 are randomly selected from the choices array. The navigation indicator can be customized through the symbol option and if omitted the default string '>' is used. The return value is new object containing the selected option, stored under the specified handle property, and a boolean isCorrect attribute, indicating whether the choice made by the user was the answer one. The quiz menu can be navigated through the up arrow/k & down arrow/j keys.

const qoa = require('qoa');

const {log} = console;

const quiz = {
  type: 'quiz',
  query: 'How far is the moon from Earth?',
  handle: 'distance',
  answer: '333400 km',
  symbol: '>',
  amount: 4,
  choices: [
    '190000 km',
    '280500 km',
    '333400 km',
    '560000 km',
    '890500 km'
  ]
};

// using the `prompt` async method
qoa.prompt([quiz]).then(log);
//=> { distance: { answer: '333400 km', isCorrect: true } }

// using the `quiz` async method
qoa.quiz(quiz).then(log);
//=> { distance: { answer: '333400 km', isCorrect: true } }

Secure Prompt

Initializes a text based prompt, where each character typed by the user is automatically replaced with the * symbol. The return value is an object with the prompt result stored under the specified handle property.

const qoa = require('qoa');

const {log} = console;

const secure = {
  type: 'secure',
  query: 'What\'s your password:',
  handle: 'password'
};

// using the `prompt` async method
qoa.prompt([secure]).then(log);
//=> { password: 'password' }

// using the `secure` async method
qoa.secure(secure).then(log);
//=> { password: 'password' }

Configuration

Qoa can be collectively configured through the unary qoa.config() function, which accepts an object containing the following two attributes: prefix & underlineQuery. The configuration is applied to all prompts belonging to the targeted qoa instance.

prefix

• Type: String
• Default: ''

A string to be included as prefix to the query of each prompt.

underlineQuery

• Type: Boolean
• Default: false

Underline the query of each prompt.

const qoa = require('qoa');

qoa.config({
  prefix: '>', // Use the `>` string as prefix to all queries
  underlineQuery: false // Do not underline queries
})

qoa.secure({
  type: 'secure',
  query: 'Type your password:',
  handle: 'password'
});
//=> > Type your password: ******

Additionally, for individual customization the unary prefix & underlineQuery functions are available.

const qoa = require('qoa');

// Use the `>` string as prefix to all queries
qoa.prefix('>');

// Do not underline queries
qoa.underlineQuery(false);

qoa.secure({
  type: 'secure',
  query: 'Type your password:',
  handle: 'password'
});
//=> > Type your password: ******

API

qoa.prompt([, configObj])

• Type: Function
• Async: True
• Returns: Object

Sequentially create & display a series of prompts.

configObj

• Type: Object

Object containing the configuration of a prompt. Can hold any of the documented options.

qoa.confirm({ type, query, handle, accept, deny })

• Type: Function
• Async: True
• Returns: Object

Create and display a confirm prompt.

type

• Type: String
• Default: 'confirm'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.confirm() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

accept

• Type: String
• Default: 'Y'

The string to be typed in order for the prompt to be confirmed.

deny

• Type: String
• Default: 'n'

The string to be typed in order for the prompt to be rejected.

qoa.hidden({ type, query, handle })

• Type: Function
• Async: True
• Returns: Object

Create and display a hidden prompt.

type

• Type: String
• Default: 'hidden'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.hidden() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

qoa.input({ type, query, handle })

• Type: Function
• Async: True
• Returns: Object

Create and display an input prompt.

type

• Type: String
• Default: 'input'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.input() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

qoa.interactive({ type, query, handle, symbol, menu })

• Type: Function
• Async: True
• Returns: Object

Create and display an interactive prompt.

type

• Type: String
• Default: 'interactive'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.interactive() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

symbol

• Type: String
• Default: '>'

The string to be used as the navigation indicator for the menu. can be customized through the symbol option and if omitted the default string '>' will be used.

menu

• Type: String[]

The array containing the menu options.

qoa.keypress({ type, query, handle, menu })

• Type: Function
• Async: True
• Returns: Object

Create and display a keypress prompt.

type

• Type: String
• Default: 'keypress'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.keypress() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

menu

• Type: String[]

The array containing the menu options.

qoa.quiz({ type, query, handle, answer, symbol, amount, choices })

• Type: Function
• Async: True
• Returns: Object

Create and display a quiz prompt.

type

• Type: String
• Default: 'quiz'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.quiz() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

answer

• Type: String

The correct answer to the quiz.

symbol

• Type: String
• Default: '>'

The string to be used as the navigation indicator for the menu.

amount

• Type: Number
• Default: 3

The number of options to be included to the menu.

choices

• Type: String[]

The array containing the candidate menu options.

qoa.secure({ type, query, handle })

• Type: Function
• Async: True
• Returns: Object

Create and display a secure prompt.

type

• Type: String
• Default: 'secure'

Indicates the type of the prompt. The option is mandatory when it is part of the configuration object inside the array passed to qoa.prompt() function. Can be considered optional when it is part of the object passed to the qoa.secure() function.

query

• Type: String

The query to be displayed by the prompt.

handle

• Type: String

The name of the attribute under which the prompt result will be saved, inside the returned object.

qoa.config({ prefix, underlineQuery })

• Type: Function
• Async: False

Collectively configure a qoa instance.

prefix

• Type: String
• Default: ''

A string to be included as prefix to the query of each prompt.

underlineQuery

• Type: Boolean
• Default: false

Underline the query of each prompt.

qoa.prefix(str)

• Type: Function
• Async: False

Add a string as prefix to the query of each prompt belonging to the targeted qoa instance.

str

• Type: String

A string to be included as prefix to the query of each prompt.

qoa.underlineQuery(status)

• Type: Function
• Async: False

Underline the query of each prompt belonging to the targeted qoa instance.

status

• Type: Boolean

Underline the query of each prompt.

qoa.clearScreen()

• Type: Function
• Async: False

Move the cursor to the top-left corner of the console and clear everything below it.

Development

For more info on how to contribute to the project, please read the contributing guidelines.

• Fork the repository and clone it to your machine
• Navigate to your local fork: cd qoa
• Install the project dependencies: npm install or yarn install
• Lint code for errors: npm test or yarn test

Related

• signale - Highly configurable logging utility
• taskbook - Tasks, boards & notes for the command-line habitat
• hyperocean - Deep oceanic blue Hyper terminal theme

Team

• Klaus Sinani (@klaussinani)

License

MIT

qoa's Issues

Add support for TypeScript

Description

Add TypeScript support by declaring types for the exported Qoa API methods.

Separator for interactive

As a user, I would like to see a clear separation between groups of menu points.

Describe the solution you'd like

      {
        type: 'interactive',
        query: 'What would you like to do today?',
        handle: 'action',
        symbol: '>',
        menu: [
           'outside walking', 'outside running',
           '---' // not selectable - special string or a special type like new Seprator();
           'inside cardgame', 'inside talking'
        ],
      },

this._input.setRawMode is not a function

Describe the bug
qoa.interactive({
type: 'interactive',
query: 'which code do you want to sync?',
handle: 'type',
symbol: '>',
menu: [
'react',
'vue'
]
});

TypeError: this._input.setRawMode is not a function

Support for color

It would be nice to print colored/styled questions similar to inquirer.js

Interactive symbol bug when mixed with colors

Describe the bug
When i put a color on a interactive input symbol, non-selected menus are not aligned anymore.

To Reproduce
Just create a qoa.interactive input with a symbol that have color (i use the package Kleur).

const kleur = require("kleur");
const qoa = require("qoa");

async function main() {
    await qoa.interactive({
        query: "query here",
        symbol: kleur.green(">"),
        menu: [
            "v1",
            "v2",
            "v3"
        ],
        handle: "any"
    });
}
main().catch(console.error);

Expected behavior
Menu must be aligned even when we use a color on a symbol.

Technical Info (please complete the following information)

• OS: Windows 10
• Qoa Version: 0.2.0
• Node.js Version: 12.5.0

Note: reproduced on WSL (Ubuntu)

Best Regards,
Thomas

How-to: Translating Documentation

Please visit the contributing guidelines to learn more on how to translate Qoa's documentation into more languages.

Tons of thank you to everyone for your help and support! ❤️

Any plans for a validation hook?

Is your feature request related to a problem? Please describe.
Validation is often necessary, would be nice to offer a hook to keep things clean

Describe the solution you'd like
Perhaps a "validate" option that accepts a regex expression & warning message, or a function that returns true/false and warning message to allow for validation. Better yet "validate" could accept an array of these, such that specific checks could be isolated (less than 8 chars, all lowercase, etc)

Additional context
N/A

Interactive checklist prompt

Description

A prompt which allows users to select multiple options, inquirer already has this kind of prompt https://github.com/SBoudrias/Inquirer.js/#checkbox---type-checkbox

Solution?

const checklist = {
  type: 'checklist',
  query: 'What languages do you know?',
  handle: 'langs',
  menu: [
    'English',
    'French',
    'German',
    'Spanish'
  ]
};

qoa.checklist(checklist).then(log);

Shouldn't switch in prompt warn user if type doesn't exist?

Describe the bug
Not really a bug, just a developer question.
I was developing a tool with Qoa, and I've done a typo in question type, password instead of hidden. I didn't understand why I didn't get prompted for this question.

To Reproduce
Use an non existing type.

Expected behavior
Warning/error about non existing type ?

Thanks for your work on this project 🔥

https://github.com/klaussinani/qoa/blob/master/src/qoa.js#L73

Recommend @klaussinani for GitHub Sponsor Matching Funds

We can use this form link https://forms.gle/6zoiq8jdagoMm9N48 to recommend @klaussinani for GitHub Sponsor Matching Funds

Totaly worth for his work! 🚀

Original idea from klaudiosinani/ao#96