enquirer

Intuitive, plugin-based prompt system for node.js. Much faster and lighter alternative to Inquirer, with all the same prompt types and more, but without the bloat.

Table of Contents

• Usage
• Prompt types
  • Publishing prompt types
• Plugins
  • Publishing plugins
• Why another prompt module?
• TODO
• About
  • Related projects
  • Contributing
  • Running tests
  • Author
  • License

(TOC generated by verb using markdown-toc)

Usage

Enquirer

Create an instance of Enquirer with the given options.

Params

• options {Object}

Example

var Enquirer = require('enquirer');
var enquirer = new Enquirer();

.register

Register a new prompt type with the given fn.

Params

• type {String}: The name of the prompt type
• fn {Function}: Prompt function that inherits from prompt-base.
• returns {Object}: Returns the Enquirer instance for chaining.

Example

enquirer.register('confirm', require('enquirer-prompt-confirm'));

.use

Invoke a plugin fn

Params

• fn {Function}: Function that takes an instance of Enquirer
• returns {Object}: Returns the instance for chaining.

Example

enquirer.use(require('some-enquirer-plugin'));

.question

Create question name with the given message and options. Uses enquirer-question, visit that library for additional details.

Params

• name {String|Object}: Name or options object
• message {String|Object}: Message or options object
• options {Object}
• returns {Object}: Returns the created question object

Events

• emits: question

Example

enquirer.question('color', 'What is your favorite color?');
enquirer.question('color', 'What is your favorite color?', {
  default: 'blue'
});
enquirer.question('color', {
  message: 'What is your favorite color?',
  default: 'blue'
});
enquirer.question({
  name: 'color',
  message: 'What is your favorite color?',
  default: 'blue'
});
enquirer.question({
  name: 'color',
  type: 'input', // "input" is the default prompt type and doesn't need to be specified
  message: 'What is your favorite color?',
  default: 'blue'
});

.ask

Initialize a prompt session for one or more questions.

• returns {Array|Object} questions: One or more question objects or names of registered questions.

Events

• emits: ask With the array of questions to be asked

Example

var Enquirer = require('enquirer');
var enquirer = new Enquirer();

enquirer.question('first', 'First name?');
enquirer.question('last', 'Last name?');

enquirer.ask('first')
  .then(function(answers) {
    console.log(answers)
  });

// errors
enquirer.ask('first')
  .then(function(answers) {
    console.log(answers)
  })
  .catch(function(err) {
    console.log(err)
  });

.prompt

Initialize a prompt session for a single question. Used by the ask method.

Params

• name {String}

Events

• emits: prompt with the default value, key, question object, and answers object
• emits: answer with the answer value, key, question object, and answers object

Example

var Enquirer = require('enquirer');
var enquirer = new Enquirer();

enquirer.question('first', 'First name?');
enquirer.prompt('first')
  .then(function(answers) {
    console.log(answers)
  });

.separator

Create a new Separator to use in a choices array.

.Separator

Create a new Separator to use in a choices array.

Prompt types

What is a prompt "type"?

Prompt types determine the type of question - or prompt - to initiate. Currently, the only prompt type that ships with enquirer is input.

These following additional prompt types are available as plugins:

• prompt-base: Base prompt module used for creating custom prompt types for Enquirer. | homepage
• prompt-choices: Create an array of multiple choice objects for use in prompts. | homepage
• prompt-question: Question object, used by Enquirer and prompt plugins. | homepage
• readline-utils: Readline utils, for moving the cursor, clearing lines, creating a readline interface, and more. | homepage

Or you can use enquirer-prompts, if you want a bundle with all of the listed prompt types.

Publishing prompt types

Prompt modules are named using the convention enquirer-prompt-*.

TBC

Plugins

TODO

Publishing plugins

Plugin modules are named using the convention enquirer-*.

TBC

Why another prompt module?

We use prompts extensively in our projects, and we wanted to improve the user experience and reduce dependencies associated with other libraries we tried, like Inquirer.

Our main goals were:

• reduce initial load time
• make prompt-types easier to add
• make code footprint smaller

Initial load time

Enquirer takes ~11ms to load. This is about the same amount of time that it takes chalk to load.

By comparison, Inquirer takes ~120ms just to load!!! This is about how long it takes babel, or other massive libraries that you would never include in production code.

Regardless of whether or not a prompt is every actually used, your own application will be 120ms slower from having Inquirer in its dependency tree. This is caused by its own massive dependency tree, code redundancy, monolithic and slow reactive interface (which makes little sense for this use case anyway), poor API design (Inquirer actually executes code, even if you never call the library!), and so on.

120ms might not seem like a lot, but there is a critical threshold where performance of an application begins to feel laggy, and having inquirer in your dependency tree cuts into that threshold significantly, leaving less room for everything else.

Make prompts easier to add

Inquirer uses a reactive interface for flow control. Aside from being overkill and not offering and real code advantages, to work with the code you need to be familiar with microsoft's RX first. This makes it a pain to add new prompt types (e.g. you probably won't).

Regarding the specific "merits" of RX alone, we think it's overkill, makes the application slow, bloated, hard to maintain, hard to contribute to, and difficult to extend. Events are sufficient.

Code footprint

By moving prompt types into separate libraries, we're able to keep the core library small and fast. Moreover, implementors and authors can create their own prompt types without having to require enquirer itself (unlike inquirer). This also makes the individual prompt libraries easier to maintain.

TODO

• support promises
• support callbacks
• support es6 generators
• support async filter, when etc

About

Related projects

• prompt-base: Base prompt module used for creating custom prompt types for Enquirer. | homepage
• prompt-choices: Create an array of multiple choice objects for use in prompts. | homepage
• prompt-question: Question object, used by Enquirer and prompt plugins. | homepage
• readline-utils: Readline utils, for moving the cursor, clearing lines, creating a readline interface, and more. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb-generate-readme, v0.1.30, on October 17, 2016.