reloquent

reloquent

reloquent allows to ask users a question, or a series of questions via the read-line interface.

yarn add -E reloquent

• API
  • Question Type
    • text
    • validation
    • postProcess
    • defaultValue
    • getDefault
  • async askSingle(question: string, timeout?: number): string
  • async askSingle(question: Question, timeout?: number): string
  • async ask(questions: <string, Question>, timeout?: number): object
• Them Questions

API

There are 3 types of calls to the API:

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

Their respective methods can be required with the import statement:

import ask, { askSingle } 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 is 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') }, }

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'
  },
}

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 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 questions = {
  title: {
    text: 'Title',
    validation: (a) => {
      if (!a) {
        throw new Error('Please enter a 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()
    },
  },
}

;(async () => {
  try {
    const answers = await ask(questions)
    console.log(answers)
  } catch (err) {
    console.log()
    console.log(err)
  }
})()

If you provide the following answers (leaving Date as it is):

Title: hello
Description: [A test default value] world
Date: [2018-6-9 07:11:03]

You will get the following object as the result:

{ title: 'hello',
  description: 'world',
  date: '2018-6-9 07:11:03' }

Them Questions

User interaction is important in the modern day applications. reloquent is an eloquent way to do this.

---

(c) Art Deco Code 2018

Changelog

1.0.2

• [fix] Don't display same defaultValue to getDefault value, grey out defaultValue if getDefault takes precedence.
• [doc] Start using documentary, split into files, document the Question type in a table.

11 June 2018