reloquent

1.2.4 • Public • Published

reloquent

npm version

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

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

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-2-3 11:16:06] 

Result: {
  "title": "hello",
  "description": "world",
  "date": "2019-2-3 11:16:06"
}

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

Ask a yes or no 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 © Art Deco 2019 Tech Nation Visa Tech Nation Visa Sucks

Package Sidebar

Install

npm i reloquent@1.2.4

Version

1.2.4

License

MIT

Unpacked Size

25.4 kB

Total Files

15

Last publish

Collaborators

  • zvr