dargs

Reverse minimist. Convert an object of options into an array of command-line arguments.

Useful when spawning command-line tools.

Install

$ npm install dargs

Usage

1import dargs from 'dargs';
2
3const object = {
4	_: ['some', 'option'],          // Values in '_' will be appended to the end of the generated argument list
5	'--': ['separated', 'option'],  // Values in '--' will be put at the very end of the argument list after the escape option (`--`)
6	foo: 'bar',
7	hello: true,                    // Results in only the key being used
8	cake: false,                    // Prepends `no-` before the key
9	camelCase: 5,                   // CamelCase is slugged to `camel-case`
10	multiple: ['value', 'value2'],  // Converted to multiple arguments
11	pieKind: 'cherry',
12	sad: ':('
13};
14
15const excludes = ['sad', /.*Kind$/];  // Excludes and includes accept regular expressions
16const includes = ['camelCase', 'multiple', 'sad', /^pie.*/];
17const aliases = {file: 'f'};
18
19console.log(dargs(object, {excludes}));
20/*
21[
22	'--foo=bar',
23	'--hello',
24	'--no-cake',
25	'--camel-case=5',
26	'--multiple=value',
27	'--multiple=value2',
28	'some',
29	'option',
30	'--',
31	'separated',
32	'option'
33]
34*/
35
36console.log(dargs(object, {excludes, includes}));
37/*
38[
39	'--camel-case=5',
40	'--multiple=value',
41	'--multiple=value2'
42]
43*/
44
45
46console.log(dargs(object, {includes}));
47/*
48[
49	'--camel-case=5',
50	'--multiple=value',
51	'--multiple=value2',
52	'--pie-kind=cherry',
53	'--sad=:('
54]
55*/
56
57
58console.log(dargs({
59	foo: 'bar',
60	hello: true,
61	file: 'baz'
62}, {aliases}));
63/*
64[
65	'--foo=bar',
66	'--hello',
67	'-f', 'baz'
68]
69*/

API

dargs(object, options?)

object

Type: object

Object to convert to command-line arguments.

options

Type: object

excludes

Type: Array<string | RegExp>

Keys or regex of keys to exclude. Takes precedence over includes.

includes

Type: Array<string | RegExp>

Keys or regex of keys to include.

aliases

Type: object

Maps keys in object to an aliased name. Matching keys are converted to arguments with a single dash (-) in front of the aliased key and the value in a separate array item. Keys are still affected by includes and excludes.

useEquals

Type: boolean
Default: true

Setting this to false makes it return the key and value as separate array items instead of using a = separator in one item. This can be useful for tools that doesn't support --foo=bar style flags.

1import dargs from 'dargs';
2
3console.log(dargs({foo: 'bar'}, {useEquals: false}));
4/*
5[
6	'--foo', 'bar'
7]
8*/

shortFlag

Type: boolean
Default: true

Make a single character option key {a: true} become a short flag -a instead of --a.

1import dargs from 'dargs';
2
3console.log(dargs({a: true}));
4//=> ['-a']
5
6console.log(dargs({a: true}, {shortFlag: false}));
7//=> ['--a']

ignoreTrue

Type: boolean
Default: false

Exclude true values. Can be useful when dealing with argument parsers that only expect negated arguments like --no-foo.

ignoreFalse

Type: boolean
Default: false

Exclude false values. Can be useful when dealing with strict argument parsers that throw on unknown arguments like --no-foo.

allowCamelCase

Type: boolean
Default: false

By default, camel-cased keys will be hyphenated. Enabling this will bypass the conversion process.

1import dargs from 'dargs';
2
3console.log(dargs({fooBar: 'baz'}));
4//=> ['--foo-bar', 'baz']
5
6console.log(dargs({fooBar: 'baz'}, {allowCamelCase: true}));
7//=> ['--fooBar', 'baz']

---