reloquent

Reloquent allows to ask users a question, a confirmation (y/n), or a series of questions via the read-line interface.

yarn add reloquent
npm i reloquent

Table Of Contents
API
Question Type
async askSingle(question: (string|!Question), timeout=: number): string
async askQuestions(questions: !Questions, timeout=: number): !Object<string, string>
- Questions
async confirm(question: (string|!Question), options=: !ConfirmOptions): boolean
- ConfirmOptions
Copyright

API

There are 4 types of calls to the API:

ask a single question as a string;
ask a single question as an object;
ask multiple questions.
ask for a confirmation;

Their respective methods can be accessed via the import statement:

import ask, { askSingle, confirm } from 'reloquent'

`Question` Type

When asking a question which is not a string, the question object should have the following structure:

Property	Type	Description	Example
*`text`**	string	Display text. Required.	`const q = { text: 'What is your name', }`
`validation`	(async) function	A function which needs to throw an error if validation does not pass.	`const q = { text: 'What is your name', validate(v) { if (!v.length) { throw new Error('Name required.') } }, }`
`postProcess`	(async) function	A function to transform the answer.	const q = { text: 'What is your name', postProcess(v) { return `${v.toLowerCase()}` }, }
`defaultValue`	string	Default answer (shown to users in `[default]` brackets).	`const q = { text: 'What is your name', defaultValue: 'Visitor', }`
`getDefault`	(async) function	A function to execute to obtain the default value.	`const q = { text: 'What is your name', async getDefault() { await git('config', 'user.name') }, }`
`password`	boolean	Hide the inputs behind `*` when typing the answer.	`const q = { text: 'Please enter the password', password: true, }`

If both defaultValue and getDefault are provided, the result of the getDefault takes precedence:

const q = {
  defaultValue: 'I desire it much',
  getDefault() {
    return 'I desire it much so'
  },
}

getDefault will get precedence

When the password property is set to true, the answer will be hidden behind the * symbols.

import { askSingle  } from 'reloquent'

const Password = async () => {
  const res = await askSingle({
    text: 'Please enter the password',
    password: true,
  })
  return res
}

Please enter the password: ********

<summary>Question extends readline.ReadLineOptions: A question.</summary>

Name	Type	Description	Default
text*	string	The text to show to the user.	-
defaultValue	string	The default answer to the question.	-
password	boolean	Hide the inputs behind `*` when typing the answer.	`false`
getDefault	() => (string \| !Promise<string>)	The function which will get the default value, possibly asynchronously.	-
validation	(answer: string) => void	The validation function which should throw on error.	-
postProcess	(answer: string) => (string \| !Promise<string>)	The transformation function for the answer.	-

`async askSingle(`_{question: (string|!Question),
timeout=: number,}`): string`

Ask user a question via the CLI. Returns the answer to the question. If a timeout is passed, the promise will expire after the specified number of milliseconds if the answer was not given.

<kbd>question*</kbd> (string | !Question): The question to present to the user.
<kbd>timeout</kbd> number (optional): How long to wait before rejecting the promise. Waits forever by default.

Questions can be asked as a simple string.

import { askSingle } from 'reloquent'

(async () => {
  try {
    const answer = await askSingle('What brought you her', 10000)
    console.log(`You've answered: ${answer}`)
  } catch (err) {
    console.log()
    console.log(err)
    console.log('Nevermind...')
  }
})()

What brought you her: I guess Art is the cause.

You've answered: I guess Art is the cause.

Alternatively, Reloquent can ask a question which is passed as an object of the Question type, and return a string.

import { askSingle } from 'reloquent'

(async () => {
  const answer = await askSingle({
    text: 'Do you wish me to stay so long?',
    validation(a) {
      if (a.length < 5) {
        throw new Error('The answer is too short')
      }
    },
    defaultValue: 'I desire it much',
    postProcess(a) {
      return `${a}!`
    },
    async getDefault() {
      return 'I desire it much so'
    },
  })
  console.log(answer)
})()

Do you wish me to stay so long? [I desire it much]

I desire it much!

`async askQuestions(`_{questions: !Questions,
timeout=: number,}`): !Object<string, string>`

Ask user a series of questions via CLI and transform them into answers. Returns an object with keys as questions' texts and values as answers.

<kbd>questions*</kbd> !Questions: A set of questions.
<kbd>timeout</kbd> number (optional): How long to wait before rejecting the promise. Waits forever by default.

!Object<string, (string | !Question)> Questions: A set of questions.

import ask from 'reloquent'

const Ask = async () => {
  const questions = {
    title: {
      text: 'Title',
      validation(a) {
        if (!a) throw new Error('Please enter the title.')
      },
    },
    description: {
      text: 'Description',
      postProcess: s => s.trim(),
      defaultValue: 'A test default value',
    },
    date: {
      text: 'Date',
      async getDefault() {
        await new Promise(r => setTimeout(r, 200))
        return new Date().toLocaleString()
      },
    },
  }
  const res = await ask(questions)
  return res
}

If when provided with the following answers (leaving Date as it is), the result will be returned as an object:

Title: hello
Description: [A test default value] world
Date: [2/22/2020, 21:37:04] 

Result: {
  "title": "hello",
  "description": "world",
  "date": "2/22/2020, 21:37:04"
}

`async confirm(`_{question: (string|!Question),
options=: !ConfirmOptions,}`): boolean`

Ask a yes/no question. Returns true when answer was y and false otherwise.

<kbd>question*</kbd> (string | !Question): The question, such as "Add default options", or "Continue to delete?". The question mark can added automatically.
<kbd>options</kbd> !ConfirmOptions (optional): Options for the confirmation question.

ConfirmOptions: Options for the confirmation question.

Name	Type	Description	Default
defaultYes	boolean	Whether the default value is yes.	`true`
timeout	number	How long to wait before rejecting the promise. Waits forever by default.	-

import { confirm } from 'reloquent'

const Confirm = async (question) => {
  const res = await confirm(question, {
    defaultYes: false,
  })
  return res
}

Do you wish to continue (y/n): [n] y

Result: true

Copyright

	© Art Deco™ 2020

Current Tags

1.4.1 ... latest (6 years ago)

reloquent

Table Of Contents

API

Question Type

async askSingle( question: (string|!Question), timeout=: number,): string

async askQuestions( questions: !Questions, timeout=: number,): !Object<string, string>