dargs

What is dargs?

The dargs npm package is used to convert an object of options into an array of command-line arguments. This is particularly useful when you need to pass configuration options to a command-line tool in a programmatic way.

What are dargs's main functionalities?

Basic Conversion

Converts an object of options into an array of command-line arguments. In this example, the object { foo: 'bar', baz: true, qux: false } is converted to ['--foo', 'bar', '--baz'].

const dargs = require('dargs');
const options = { foo: 'bar', baz: true, qux: false };
const args = dargs(options);
console.log(args); // ['--foo', 'bar', '--baz']

Excluding Keys

Allows you to exclude specific keys from the conversion. In this example, the key 'qux' is excluded from the resulting array.

const dargs = require('dargs');
const options = { foo: 'bar', baz: true, qux: false };
const args = dargs(options, { excludes: ['qux'] });
console.log(args); // ['--foo', 'bar', '--baz']

Including Only Specific Keys

Allows you to include only specific keys in the conversion. In this example, only the keys 'foo' and 'baz' are included in the resulting array.

const dargs = require('dargs');
const options = { foo: 'bar', baz: true, qux: false };
const args = dargs(options, { includes: ['foo', 'baz'] });
console.log(args); // ['--foo', 'bar', '--baz']

Using Short Flags

Converts long flags to short flags if specified. In this example, the long flags are converted to short flags.

const dargs = require('dargs');
const options = { foo: 'bar', baz: true, qux: false };
const args = dargs(options, { shortFlag: true });
console.log(args); // ['-f', 'bar', '-b']

Other packages similar to dargs

minimist

Minimist is a package for parsing command-line arguments. Unlike dargs, which converts an object to command-line arguments, minimist is used to parse command-line arguments into an object. It is often used for the opposite purpose of dargs.

yargs

Yargs is a more feature-rich package for parsing command-line arguments and generating an elegant user interface. It provides more advanced features like command handling, middleware, and more, making it more comprehensive compared to dargs.

commander

Commander is a package for building command-line interfaces. It provides a way to define commands, options, and arguments, and it also parses command-line arguments. While dargs focuses on converting objects to arguments, Commander is more about building complete CLI applications.

README

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

import dargs from 'dargs';

const object = {
	_: ['some', 'option'],          // Values in '_' will be appended to the end of the generated argument list
	'--': ['separated', 'option'],  // Values in '--' will be put at the very end of the argument list after the escape option (`--`)
	foo: 'bar',
	hello: true,                    // Results in only the key being used
	cake: false,                    // Prepends `no-` before the key
	camelCase: 5,                   // CamelCase is slugged to `camel-case`
	multiple: ['value', 'value2'],  // Converted to multiple arguments
	pieKind: 'cherry',
	sad: ':('
};

const excludes = ['sad', /.*Kind$/];  // Excludes and includes accept regular expressions
const includes = ['camelCase', 'multiple', 'sad', /^pie.*/];
const aliases = {file: 'f'};

console.log(dargs(object, {excludes}));
/*
[
	'--foo=bar',
	'--hello',
	'--no-cake',
	'--camel-case=5',
	'--multiple=value',
	'--multiple=value2',
	'some',
	'option',
	'--',
	'separated',
	'option'
]
*/

console.log(dargs(object, {excludes, includes}));
/*
[
	'--camel-case=5',
	'--multiple=value',
	'--multiple=value2'
]
*/


console.log(dargs(object, {includes}));
/*
[
	'--camel-case=5',
	'--multiple=value',
	'--multiple=value2',
	'--pie-kind=cherry',
	'--sad=:('
]
*/


console.log(dargs({
	foo: 'bar',
	hello: true,
	file: 'baz'
}, {aliases}));
/*
[
	'--foo=bar',
	'--hello',
	'-f', 'baz'
]
*/

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.

import dargs from 'dargs';

console.log(dargs({foo: 'bar'}, {useEquals: false}));
/*
[
	'--foo', 'bar'
]
*/

shortFlag

Type: boolean
Default: true

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

import dargs from 'dargs';

console.log(dargs({a: true}));
//=> ['-a']

console.log(dargs({a: true}, {shortFlag: false}));
//=> ['--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.

import dargs from 'dargs';

console.log(dargs({fooBar: 'baz'}));
//=> ['--foo-bar', 'baz']

console.log(dargs({fooBar: 'baz'}, {allowCamelCase: true}));
//=> ['--fooBar', 'baz']

---

Get professional support for this package with a Tidelift subscription
_{Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.}