Command-line Arguments

Maps command-line arguments to a configuration object.

Installation

$ npm install argv-to-object

Usage

var argv = require( 'argv-to-object' );

argv( map[, options] )

Maps command-line arguments to a configuration object.

var map = {
	'env': {
		'keypath': 'argv',
		'type': 'string',
		'default': 'dev'
	},
	'port': {
		'keypath': 'server.port',
		'type': 'integer',
		'default': 8080,
		'alias': [
			'p'
		],
		'radix': 10
	},
	'ssl': {
		'keypath': 'server.ssl',
		'type': 'boolean'
	},
	'loglevel': {
		'keypath': 'logger.level',
		'type': 'string',
		'default': 'info'
	}
};

// --env=test --port 7331 --ssl --loglevel debug
var out = argv( map );
/*
	{
		'env': 'test',
		'server': {
			'port': 7331,
			'ssl': true
		},
		'logger': {
			'level': 'debug'
		}
	}
*/

A command-line argument mapping must include a keypath, which is a dot-delimited object path. By default, this module parses a command-line argument value as a string. The following types are supported:

• string
• number
• integer
• boolean
• object
• date
• regexp

The function accepts the following options:

• parsers: an object containing command-line argument parsers. Each key should correspond to a defined type, and each value should be a function which accepts a command-line argument value and any associated options.

  var map = {
  	'custom_type': {
  		'keypath': 'custom',
  		'type': 'custom',
  		... // => options
  	}
  };
  
  var parsers = {
  	'custom_type': custom
  };
  
  function custom( str, opts ) {
  	var v = parseInt( str, 10 );
  	if ( v !== v ) {
  		return new TypeError( 'invalid value. Value must be an integer. Value: `' + str + '`.' );
  	}
  	return v * 6;
  }
  
  // --custom_type=5
  var out = argv( map, parsers );
  /*
  	{
  		'custom': 30
  	}
  */

Types

All command-line argument value types support the following options:

• default: default value.
• alias: array of command-line argument aliases.

Except for boolean, all command-line argument value types support the following options:

• multiple: boolean indicating whether a command-line argument can be provided multiple times. If true, the command-line argument value is always an array containing values of a specified type. Default: false.

===

string

Coerce a command-line argument value to a string.

var map = {
	'str': {
		'keypath': 'str',
		'type': 'string'
	}
};

// --str=beep
var out = argv( map );
/*
	{
		'str': 'beep'
	}
*/

// --str=1234
var out = argv( map );
/*
	{
		'str': '1234'
	}
*/

===

number

Coerce a command-line argument value to a number.

var map = {
	'num': {
		'keypath': 'num',
		'type': 'number'
	}
};

// --num='3.14'
var out = argv( map );
/*
	{
		'num': 3.14
	}
*/

// --num=bop
var out = argv( map );
// => throws

===

integer

Coerce a command-line argument value to an integer.

var map = {
	'int': {
		'keypath': 'int',
		'type': 'integer'
	}
};

// --int=2
var out = argv( map );
/*
	{
		'int': 2
	}
*/

// --int=beep
var out = argv( map );
// => throws

The integer type supports the following options:

• radix: an integer on the interval [2,36]. Default: 10.

  var map = {
  	'int': {
  		'keypath': 'int',
  		'type': 'integer',
  		'radix': 2
  	}
  };
  
  // --int=1
  var out = argv( map );
  /*
  	{
  		'int': 1
  	}
  */
  
  // --int=2
  var out = argv( map );
  // => throws

===

boolean

Coerce a command-line argument value to a boolean.

var map = {
	'bool': {
		'keypath': 'bool',
		'type': 'boolean'
	}
};

// --bool
var out = argv( map );
/*
	{
		'bool': true
	}
*/

Prefixing --no-* to a boolean command-line argument will override a default value.

var map = {
	'bool': {
		'keypath': 'bool',
		'type': 'boolean',
		'default': true
	}
};

// --no-bool
var out = argv( map );
/*
	{
		'bool': false
	}
*/

If a boolean command-line argument does not have a default value, using the --no-* prefix is equivalent to not specifying the command-line argument.

var map = {
	'bool': {
		'keypath': 'bool',
		'type': 'boolean'
	}
};

// --no-bool
var out = argv( map );
/*
	{}
*/

===

object

Parse a command-line argument value as a JSON object. Note that a value must be valid JSON.

var map = {
	'obj': {
		'keypath': 'obj',
		'type': 'object'
	}
};

// --obj='{"beep":"boop"}'
var out = argv( map );
/*
	{
		'obj': {
			'beep': 'boop'
		}
	}
*/

// --obj='[1,2,3,"4",null]'
var out = argv( map );
/*
	{
		'obj': [ 1, 2, 3, '4', null ]
	}
*/

// --obj='{"beep:"boop"}'
var out = argv( map );
// => throws

===

date

Coerce a command-line argument to a Date object.

var map = {
	'date': {
		'keypath': 'date',
		'type': 'date'
	}
};

// --date='2015-10-17'
var out = argv( map );
/*
	{
		'date': <Date>
	}
*/

// --date=beep
var out = argv( map );
// => throws

===

regexp

Parse a command-line argument as a RegExp.

var map = {
	'regexp': {
		'keypath': 're',
		'type': 'regexp'
	}
};

// --regexp='/\\w+/'
var out = argv( map );
/*
	{
		're': /\w+/
	}
*/

// --regexp=beep
var out = argv( map );
// => throws

Notes

• If a command-line argument does not exist and no default value is specified, the corresponding configuration keypath will not exist in the output object.

  var map = {
  	'unset_argv': {
  		'keypath': 'a.b.c'
  	}
  };
  
  var out = argv( map );
  // returns {}

Examples

var argv = require( 'argv-to-object' );

var map = {
	'env': {
		'keypath': 'env',
		'default': 'dev'
	},
	'port': {
		'keypath': 'server.port',
		'type': 'integer',
		'default': 8080,
		'alias': [
			'p'
		],
		'radix': 10
	},
	'ssl': {
		'keypath': 'server.ssl',
		'type': 'boolean'
	},
	'loglevel': {
		'keypath': 'logger.level',
		'type': 'string',
		'default': 'info'
	},
	'num': {
		'keypath': 'num',
		'type': 'number'
	},
	'obj': {
		'keypath': 'obj',
		'type': 'object'
	},
	'arr': {
		'keypath': 'arr',
		'type': 'object'
	},
	'bool': {
		'keypath': 'bool',
		'type': 'boolean'
	},
	'nested': {
		'keypath': 'a.b.c.d',
		'type': 'object'
	},
	'date': {
		'keypath': 'date',
		'type': 'date'
	},
	'regex': {
		'keypath': 're',
		'type': 'regexp'
	},
	'mnum': {
		'keypath': 'mnum',
		'type': 'integer',
		'multiple': true
	}
};

// --env=test --ssl --p 7331 --num='3.14' --obj='{"hello":"world"}' --arr='[1,2,3,4]' --nested='{"beep":"boop"}' --date="2015-10-17" --regex '/\\w+/' --no-bool --mnum 1 --mnum=2 --mnum=3 --mnum 4
var out = argv( map );
/*
	{
		'env': 'test',
		'server': {
			'ssl': true,
			'port': 7331
		},
		'logger': {
			'level': 'info'
		},
		'num': 3.14,
		'obj': {
			'hello': 'world'
		},
		'arr': [ 1, 2, 3, 4 ],
		'nested': {
			'a': {
				'b': {
					'c': {
						'd': {
							'beep': 'boop'
						}
					}
				}
			}
		},
		'date': <Date>,
		're': /\w+/,
		'mnum': [ 1, 2, 3, 4 ]
	}
*/

To run the example code from the top-level application directory,

$ node ./examples/index.js --env=test --ssl --p 7331 --num='3.14' --obj='{"hello":"world"}' --arr='[1,2,3,4]' --nested='{"beep":"boop"}' --date="2015-10-17" --regex '/\\w+/' --no-bool --mnum 1 --mnum=2 --mnum=3 --mnum 4

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2015. Athan Reines.