tessl/npm-yargs-parser

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

Overview

Eval results

Files

Core Parsing

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

The main parsing function that converts command-line arguments into structured JavaScript objects. This is the primary interface for yargs-parser.

Import

import parser from "yargs-parser";

API

function parser(args: ArgsInput, opts?: Partial<Options>): Arguments;

type ArgsInput = string | any[];

interface Arguments {
  /** Non-option arguments */
  _: (string | number)[];
  /** Arguments after the end-of-options flag `--` */
  '--'?: (string | number)[];
  /** All remaining options */
  [argName: string]: any;
}

Basic Usage

Parse Array of Arguments

import parser from "yargs-parser";

// Parse process arguments
const argv = parser(process.argv.slice(2));

// Parse custom array
const result = parser(['--foo', 'bar', '--number', '42', 'positional']);
console.log(result);
// Output: { _: ['positional'], foo: 'bar', number: 42 }

Parse String Arguments

// Parse argument string
const result = parser("--foo=99 --bar hello -x 33");
console.log(result);
// Output: { _: [], foo: 99, bar: 'hello', x: 33 }

// Parse complex string with positional args
const complex = parser("command --verbose --file input.txt output.txt");
console.log(complex);
// Output: { _: ['command', 'output.txt'], verbose: true, file: 'input.txt' }

Option Processing

Boolean Options

// Short and long boolean flags
const booleans = parser(['-v', '--debug', '--no-color']);
console.log(booleans);
// Output: { _: [], v: true, debug: true, color: false }

String and Number Options

// Automatic type inference
const mixed = parser(['--name', 'Alice', '--port', '3000', '--ratio', '0.75']);
console.log(mixed);
// Output: { _: [], name: 'Alice', port: 3000, ratio: 0.75 }

Array Options

// Multiple values create arrays
const arrays = parser(['--file', 'a.txt', '--file', 'b.txt', '--tag', 'dev', '--tag', 'test']);
console.log(arrays);
// Output: { _: [], file: ['a.txt', 'b.txt'], tag: ['dev', 'test'] }

Short Option Groups

// Combined short options
const grouped = parser(['-abc', 'value']);
console.log(grouped);
// Output: { _: [], a: true, b: true, c: 'value' }

Camel Case Expansion

// Hyphenated options become camelCase
const camelCase = parser(['--foo-bar', 'value', '--multi-word-option']);
console.log(camelCase);
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value', 'multi-word-option': true, multiWordOption: true }

Dot Notation

// Nested object creation
const nested = parser(['--db.host', 'localhost', '--db.port', '5432', '--server.name', 'api']);
console.log(nested);
// Output: { _: [], db: { host: 'localhost', port: 5432 }, server: { name: 'api' } }

End-of-Options Handling

// Arguments after -- are treated as positional
const endOfOptions = parser(['--verbose', '--', '--not-an-option', 'file.txt']);
console.log(endOfOptions);
// Output: { _: [], verbose: true, '--': ['--not-an-option', 'file.txt'] }

Advanced Usage

Type Coercion with Options

// Explicit type specification
const typed = parser(['--count', '5', '--name', 'test', '--debug'], {
  number: ['count'],
  string: ['name'],
  boolean: ['debug']
});
console.log(typed);
// Output: { _: [], count: 5, name: 'test', debug: true }

Aliases

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

Default Values

// Provide default values
const withDefaults = parser(['--name', 'Bob'], {
  default: {
    port: 3000,
    debug: false,
    name: 'Anonymous'
  }
});
console.log(withDefaults);
// Output: { _: [], name: 'Bob', port: 3000, debug: false }

Error Handling

The main parser function does not throw errors for invalid input but may return unexpected results. For error handling, use the detailed parsing mode.

// Basic parsing continues with invalid input
const result = parser(['--invalid-number', 'not-a-number']);
console.log(result);
// Output: { _: [], 'invalid-number': 'not-a-number' }

Install with Tessl CLI