tessl/npm-yargs-parser

The mighty option parser used by yargs for parsing command-line arguments with extensive configuration options.

Overview

Eval results

Files

Configuration Options

Name: tessl/npm-yargs-parser
Author: tessl

yargs-parser provides extensive configuration options to control parsing behavior. These options can be set via the configuration property in parser options.

Import

import parser from "yargs-parser";

API

interface Configuration {
  /** Should variables prefixed with --no be treated as negations? Default is `true` */
  'boolean-negation': boolean;
  /** Should hyphenated arguments be expanded into camel-case aliases? Default is `true` */
  'camel-case-expansion': boolean;
  /** Should arrays be combined when provided by both command line arguments and a configuration file? Default is `false` */
  'combine-arrays': boolean;
  /** Should keys that contain `.` be treated as objects? Default is `true` */
  'dot-notation': boolean;
  /** Should arguments be coerced into an array when duplicated? Default is `true` */
  'duplicate-arguments-array': boolean;
  /** Should array arguments be coerced into a single array when duplicated? Default is `true` */
  'flatten-duplicate-arrays': boolean;
  /** Should arrays consume more than one positional argument following their flag? Default is `true` */
  'greedy-arrays': boolean;
  /** Should parsing stop at the first text argument? This is similar to how e.g. ssh parses its command line. Default is `false` */
  'halt-at-non-option': boolean;
  /** Should nargs consume dash options as well as positional arguments? Default is `false` */
  'nargs-eats-options': boolean;
  /** The prefix to use for negated boolean variables. Default is `'no-'` */
  'negation-prefix': string;
  /** Should positional values that look like numbers be parsed? Default is `true` */
  'parse-positional-numbers': boolean;
  /** Should keys that look like numbers be treated as such? Default is `true` */
  'parse-numbers': boolean;
  /** Should unparsed flags be stored in -- or _? Default is `false` */
  'populate--': boolean;
  /** Should a placeholder be added for keys not set via the corresponding CLI argument? Default is `false` */
  'set-placeholder-key': boolean;
  /** Should a group of short-options be treated as boolean flags? Default is `true` */
  'short-option-groups': boolean;
  /** Should aliases be removed before returning results? Default is `false` */
  'strip-aliased': boolean;
  /** Should dashed keys be removed before returning results? This option has no effect if camel-case-expansion is disabled. Default is `false` */
  'strip-dashed': boolean;
  /** Should unknown options be treated like regular arguments? An unknown option is one that is not configured in opts. Default is `false` */
  'unknown-options-as-args': boolean;
}

Basic Usage

const result = parser(['--foo-bar', 'value'], {
  configuration: {
    'camel-case-expansion': false,
    'dot-notation': true
  }
});

Configuration Options Detail

Boolean Negation

Control how --no- prefixed options are handled.

// Default behavior (boolean-negation: true)
const withNegation = parser(['--no-debug']);
console.log(withNegation);
// Output: { _: [], debug: false }

// Disabled boolean negation
const withoutNegation = parser(['--no-debug'], {
  configuration: { 'boolean-negation': false }
});
console.log(withoutNegation);
// Output: { _: [], 'no-debug': true }

Camel Case Expansion

Control automatic camelCase alias creation for hyphenated options.

// Default behavior (camel-case-expansion: true)
const withCamelCase = parser(['--foo-bar', 'value']);
console.log(withCamelCase);
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }

// Disabled camel case expansion
const withoutCamelCase = parser(['--foo-bar', 'value'], {
  configuration: { 'camel-case-expansion': false }
});
console.log(withoutCamelCase);
// Output: { _: [], 'foo-bar': 'value' }

Dot Notation

Control parsing of dotted keys as nested objects.

// Default behavior (dot-notation: true)
const withDotNotation = parser(['--db.host', 'localhost', '--db.port', '5432']);
console.log(withDotNotation);
// Output: { _: [], db: { host: 'localhost', port: 5432 } }

// Disabled dot notation
const withoutDotNotation = parser(['--db.host', 'localhost'], {
  configuration: { 'dot-notation': false }
});
console.log(withoutDotNotation);
// Output: { _: [], 'db.host': 'localhost' }

Parse Numbers

Control automatic number parsing for option values.

// Default behavior (parse-numbers: true)
const withNumberParsing = parser(['--port', '3000', '--ratio', '0.75']);
console.log(withNumberParsing);
// Output: { _: [], port: 3000, ratio: 0.75 }

// Disabled number parsing
const withoutNumberParsing = parser(['--port', '3000'], {
  configuration: { 'parse-numbers': false }
});
console.log(withoutNumberParsing);
// Output: { _: [], port: '3000' }

Parse Positional Numbers

Control automatic number parsing for positional arguments.

// Default behavior (parse-positional-numbers: true)
const withPositionalNumbers = parser(['command', '42', '3.14']);
console.log(withPositionalNumbers);
// Output: { _: ['command', 42, 3.14] }

// Disabled positional number parsing
const withoutPositionalNumbers = parser(['command', '42'], {
  configuration: { 'parse-positional-numbers': false }
});
console.log(withoutPositionalNumbers);
// Output: { _: ['command', '42'] }

Short Option Groups

Control parsing of combined short options like -abc.

// Default behavior (short-option-groups: true)
const withGroups = parser(['-abc']);
console.log(withGroups);
// Output: { _: [], a: true, b: true, c: true }

// Disabled short option groups
const withoutGroups = parser(['-abc'], {
  configuration: { 'short-option-groups': false }
});
console.log(withoutGroups);
// Output: { _: [], abc: true }

Duplicate Arguments Array

Control how duplicate arguments are handled.

// Default behavior (duplicate-arguments-array: true)
const withArrays = parser(['--file', 'a.txt', '--file', 'b.txt']);
console.log(withArrays);
// Output: { _: [], file: ['a.txt', 'b.txt'] }

// Disabled duplicate arguments array
const withoutArrays = parser(['--file', 'a.txt', '--file', 'b.txt'], {
  configuration: { 'duplicate-arguments-array': false }
});
console.log(withoutArrays);
// Output: { _: [], file: 'b.txt' } (last value wins)

Halt at Non-Option

Control whether parsing stops at first non-option argument.

// Default behavior (halt-at-non-option: false)
const normal = parser(['--debug', 'command', '--verbose']);
console.log(normal);
// Output: { _: ['command'], debug: true, verbose: true }

// Halt at non-option enabled
const halting = parser(['--debug', 'command', '--verbose'], {
  configuration: { 'halt-at-non-option': true }
});
console.log(halting);
// Output: { _: ['command', '--verbose'], debug: true }

Strip Aliased

Control whether alias keys are removed from results.

const withAliases = parser(['-v'], {
  alias: { verbose: ['v'] }
});
console.log(withAliases);
// Output: { _: [], v: true, verbose: true }

const strippedAliases = parser(['-v'], {
  alias: { verbose: ['v'] },
  configuration: { 'strip-aliased': true }
});
console.log(strippedAliases);
// Output: { _: [], verbose: true } (alias 'v' removed)

Strip Dashed

Control whether dashed keys are removed when camelCase versions exist.

const withDashed = parser(['--foo-bar', 'value']);
console.log(withDashed);
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }

const strippedDashed = parser(['--foo-bar', 'value'], {
  configuration: { 'strip-dashed': true }
});
console.log(strippedDashed);
// Output: { _: [], fooBar: 'value' } (dashed key removed)

Unknown Options as Args

Control whether unknown options are treated as positional arguments.

// Default behavior (unknown-options-as-args: false)
const normal = parser(['--known', '--unknown', 'value'], {
  boolean: ['known']
});
console.log(normal);
// Output: { _: [], known: true, unknown: 'value' }

// Unknown options as args
const asArgs = parser(['--known', '--unknown', 'value'], {
  boolean: ['known'],
  configuration: { 'unknown-options-as-args': true }
});
console.log(asArgs);
// Output: { _: ['--unknown', 'value'], known: true }

Negation Prefix

Customize the prefix used for boolean negation.

// Default negation prefix ('no-')
const defaultPrefix = parser(['--no-debug']);
console.log(defaultPrefix);
// Output: { _: [], debug: false }

// Custom negation prefix
const customPrefix = parser(['--disable-debug'], {
  configuration: { 'negation-prefix': 'disable-' }
});
console.log(customPrefix);
// Output: { _: [], debug: false }

Combine Arrays

Control whether arrays are combined when provided by both command line and configuration files.

// Default behavior (combine-arrays: false)
const withoutCombine = parser(['--tags', 'cli1', '--tags', 'cli2'], {
  configObjects: [{ tags: ['config1', 'config2'] }]
});
console.log(withoutCombine);
// Output: { _: [], tags: ['cli1', 'cli2'] } (config values ignored)

// Enabled combine arrays
const withCombine = parser(['--tags', 'cli1'], {
  configObjects: [{ tags: ['config1', 'config2'] }],
  configuration: { 'combine-arrays': true }
});
console.log(withCombine);
// Output: { _: [], tags: ['config1', 'config2', 'cli1'] } (arrays combined)

Flatten Duplicate Arrays

Control whether array arguments are flattened when duplicated.

// Default behavior (flatten-duplicate-arrays: true)
const flattened = parser(['--files', 'a.txt', 'b.txt', '--files', 'c.txt', 'd.txt'], {
  array: ['files']
});
console.log(flattened);
// Output: { _: [], files: ['a.txt', 'b.txt', 'c.txt', 'd.txt'] }

// Disabled flatten duplicate arrays
const notFlattened = parser(['--files', 'a.txt', 'b.txt', '--files', 'c.txt'], {
  array: ['files'],
  configuration: { 'flatten-duplicate-arrays': false }
});
console.log(notFlattened);
// Output: { _: [], files: [['a.txt', 'b.txt'], ['c.txt']] }

Greedy Arrays

Control whether arrays consume multiple positional arguments following their flag.

// Default behavior (greedy-arrays: true)
const greedy = parser(['--files', 'a.txt', 'b.txt', 'c.txt'], {
  array: ['files']
});
console.log(greedy);
// Output: { _: [], files: ['a.txt', 'b.txt', 'c.txt'] }

// Disabled greedy arrays
const notGreedy = parser(['--files', 'a.txt', 'b.txt', 'c.txt'], {
  array: ['files'],
  configuration: { 'greedy-arrays': false }
});
console.log(notGreedy);
// Output: { _: ['b.txt', 'c.txt'], files: ['a.txt'] }

NArgs Eats Options

Control whether nargs consume dash options as well as positional arguments.

// Default behavior (nargs-eats-options: false)
const normal = parser(['--input', 'file1.txt', '--output', 'result.txt'], {
  narg: { input: 2 }
});
console.log(normal);
// Output: { _: [], input: ['file1.txt'], output: 'result.txt' }

// Enabled nargs eats options
const eatsOptions = parser(['--input', 'file1.txt', '--output', 'result.txt'], {
  narg: { input: 2 },
  configuration: { 'nargs-eats-options': true }
});
console.log(eatsOptions);
// Output: { _: [], input: ['file1.txt', '--output'] }

Populate Double Dash

Control whether unparsed flags are stored in -- or _.

// Default behavior (populate--: false)
const inUnderscore = parser(['cmd', '-a', '--', 'x', 'y']);
console.log(inUnderscore);
// Output: { _: ['cmd', 'x', 'y'], a: true }

// Enabled populate--
const inDoubleDash = parser(['cmd', '-a', '--', 'x', 'y'], {
  configuration: { 'populate--': true }
});
console.log(inDoubleDash);
// Output: { _: ['cmd'], '--': ['x', 'y'], a: true }

Set Placeholder Key

Control whether a placeholder is added for keys not set via CLI arguments.

// Default behavior (set-placeholder-key: false)
const normal = parser(['--name', 'Alice'], {
  string: ['name', 'email', 'phone']
});
console.log(normal);
// Output: { _: [], name: 'Alice' }

// Enabled set placeholder key
const withPlaceholders = parser(['--name', 'Alice'], {
  string: ['name', 'email', 'phone'],
  configuration: { 'set-placeholder-key': true }
});
console.log(withPlaceholders);
// Output: { _: [], name: 'Alice', email: undefined, phone: undefined }

Combining Multiple Configuration Options

const result = parser(['--foo-bar', 'value', '-abc', '--no-debug'], {
  configuration: {
    'camel-case-expansion': true,
    'short-option-groups': true,
    'boolean-negation': true,
    'parse-numbers': true,
    'dot-notation': true
  }
});
console.log(result);
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value', a: true, b: true, c: true, debug: false }

Install with Tessl CLI