yargs-promise/README.md

Use the headless yargs parser with promises

# 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](http://yargs.js.org/docs/#methods-parseargs-context-parsecallback), use a promise chain: `parser.parse(text).then().catch()`.

Examples:

```js
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

```js
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.