README

Args

Parse arguments from argv, env variables, and locals

Features:

Easy to use
Parse arguments from argv, env variables, and locals
Coerce to native and/or specified type (class or factory function)
Supports defaults and aliases
Supports multiple key formats (snake, camel, kebab)
Error handling options
Supports positional and sub process (--) arguments
Supports enums

About

I needed a better way to parse application arguments across a variety of interfaces. It's simple enough if you build only a node api, but what if you want to expose a cli component as well? Now you have to worry about parsing argv options and types from multiple formats. What if you wanted to expose configuration for the same options via env variables? It starts to become a complicated mess of parsing values and remembering order, precidence, and types.

This package aims to take care of all that for you. Simply define your arguments in a declarative way whether you want env variables, argv variables, or local variables and it will resolve all the options and return a single object. You can request specific types by providing classes or factory functions, you can set defaults, and you can specify required-ness and how to handle errors.

Usage

Add args as a dependency for your app and install via npm

npm install @danmasta/args --save

Require the package in your app

const args = require('@danmasta/args');

Options

name	type	description
`pos`	`boolean`	If true any positional arguments from argv will be added to output at `_`. Default is `true`
`sub`	`boolean`	If true any sub-process arguments from argv will be added to output at `--`. Default is `true`
`defaults`	`object`	Default option values to set for all arguments. Default is `null`

Methods

name	description
`resolve(locals)`	Resolve argument values with optionanl local overrides

Arguments

Arguments can be configured with the following options: name | type | description -----|------|------------ id | string | This is used for initial value lookup from argv. It is also used as the output key in resolved options. Default is undefined description | string | Description for the argument. Default is undefined alias | string | Which alias key to use for argv arguments. Default is undefined argv | boolean | Whether or not to parse argument values from process.argv. Default is true env | boolean | Which env variable key to use for value lookup. Default is undefined camel | boolean | If true will also support camelCase keys for id in argv arguments. Default is false snake | boolean | If true will also support snake_case keys for id in argv arguments. Default is false kebab | boolean | If true will also support kebab-case keys for id in argv arguments. Default is true type | constructor\|function | If set, after the value has been resolved it will attempt to coerce to arg.type. If a constructor it will use new type(val) otherwise just type(val). Default is undefined enum | array\|any | If set, will attempt to validate against this value. Can be an array of possible values or a single value. Default is undefined. required | boolean | If true will create an error if value is undefined. Default is false value | any | Value of the argument. Default is undefined default | any | Which value to use as the default for specified argument. Default is undefined parseUndefined | boolean | If false will ignore undefined values when attempting to parse to native and/or custom types. Default is true warn | boolean | If true will write errors to stderr for missing required fields and invalid enum values. Default is false throw | boolean | If true will throw errors on missing required fields and invalid enum values. Default is false nativeType | boolean | If true will attempt to coerce values to native types if possible. Default is true nullable | boolean | If true will allow undefined for required fields or enums. Default is false

Examples

const Args = require('@danmasta/args');

process.env.PROJECT='APP';
process.env.HOST='app.net';
process.env.PORT=8080;

let args = [
    {
        id: 'project',
        type: String,
        env: 'PROJECT'
    },
    {
        id: 'host',
        alias: 'h',
        type: String,
        env: 'HOST'
    },
    {
        id: 'port',
        alias: 'p',
        type: Number,
        env: 'PORT'
    }
];

let opts = Args(args).resolve();

// {
//     project: 'APP',
//     host: 'app.net',
//     port: 8080
// }

Testing

Testing is currently run using mocha and chai. To execute tests just run npm run test. To generate unit test coverage reports just run npm run coverage

Contact

If you have any questions feel free to get in touch

Usage no npm install needed!