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 -E reloquent

• API
• Question Type
  • text*
  • validation
  • postProcess
  • defaultValue
  • getDefault
  • password
• async askSingle(question: string, timeout?: number): string
• async askSingle(question: Question, timeout?: number): string
• async ask(questions: <string, Question>, timeout?: number): object
• async confirm(question: string, options: confirmOptions): boolean
  • _reloquent.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: ********

async askSingle(
  question: string,
  timeout?: number,
): string

Ask a question as a string and wait for the answer. If a timeout is passed, the promise will expire after the specified number of milliseconds if the answer was not given.

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.

async askSingle(
  question: Question,
  timeout?: number,
): string

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 ask(
  questions: <string, Question>,
  timeout?: number,
): object

Ask a series of questions and transform them into answers.

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: [2019-5-1 19:57:40] 

Result: {
  "title": "hello",
  "description": "world",
  "date": "2019-5-1 19:57:40"
}

async confirm(
  question: string,
  options: confirmOptions,
): boolean

Ask a yes or no question.

_reloquent.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 2019		Tech Nation Visa Sucks

Changelog

1.3.1

• [fix] Quote the promise property.

30 April 2019