reloquent

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

• Table Of Contents
• API
• Question Type
  • text*
  • validation
  • postProcess
  • defaultValue
  • getDefault
  • password
  • Question
• 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'
  },
}

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: ********

Question extends readline.ReadLineOptions: A question.

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.

• question* (string | !Question): The question to present to the user.
• timeout 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.

• questions* !Questions: A set of questions.
• timeout 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.

• question* (string | !Question): The question, such as "Add default options", or "Continue to delete?". The question mark can added automatically.
• options !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

Changelog

1.4.1

• [doc] Appveyor badge.