yargs-promise

yargs-promise

Use the headless yargs parser with promises!

Install

npm

npm install --save yargs-promise

yarn

yarn add --save yargs-promise

Usage

Instead of using a callback with yargs.parse, use a promise chain: parser.parse(text).then().catch().

Examples:

const yargs = require('yargs');
const YargsPromise = require('yargs-promise');

// create the customized yargs parser
const parser = new YargsPromise(yargs);

// setup command & command handler
parser
  .command('hello <name>', 'hello world parser' , ()=>{}, (argv) => {

    // resolve a promise or other value
    argv.resolve(doSomething);

    // reject stuff
    argv.reject(yourErrorData);

    // or do nothing and reject/resolve will be handled internally
    console.log('testing argv');
  })
  .help();

// parse text input and use the returned promise
parser.parse('hello world')
  .then(({data, argv}) => {
    // data is what your code resolved or what an internal command resolved
  })
  .catch(({error, argv}) => {
    // `error` is what your code rejected or an internal error from yargs
  });

Customizing context example

const yargs = require('yargs');
const YargsPromise = require('yargs-promise');

const parser = new YargsPromise(
  yargs,
  // customize context
  {
    customContextMethod: () => {},
    foo: 'bar'
  }
);

parser
  .command('hello <name>', 'hello world parser' , ()=>{}, (argv) => {
    // argv now contains
    argv.customContextMethod();
    console.log(argv.foo);
  })
  .help();

Need access to yargs object? Work with the direct yargs object prior to passing it into the yargs-promise constructor. For convenience, it is also available at parser.yargs.

How it works

This library does three things:

• wraps the yargs.parse in a new Promise
  • no more callbacks
• attaches that Promises resolve & reject methods on the context passed to yargs.parse
  • this enables you to call argv.resolve or argv.reject in command handler function
• handles default behavior
  • from Error validation
  • output from internal commands like .help()
  • unhandled output from custom handler

Checkout the source code or tests for more information.

Why

Building chatbots requires parsing and handling text input. This wraps up the most common needs I've come across for handling errors, simple commands, and commands with handlers.