# yargs-promise

> Use the headless yargs parser with promises

Latest version **1.1.0** (published 2017-04-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install yargs-promise
pnpm add yargs-promise
yarn add yargs-promise
bun add yargs-promise
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2017-04-30 |
| First published | 2017-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Eddy Hernandez |
| Maintainers | eddywashere |
| Keywords | yargs, parser, yargs-parser, promise, promises |

## Links

- npm: https://www.npmjs.com/package/yargs-promise
- Repository: https://github.com/eddywashere/yargs-promise
- Homepage: https://github.com/eddywashere/yargs-promise#readme
- Issues: https://github.com/eddywashere/yargs-promise/issues
- npm.io page: https://npm.io/package/yargs-promise

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2017-04-30
- 1.0.0 — 2017-04-25

## README

# 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.

---
_Source: https://npm.io/package/yargs-promise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._