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();
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