tessl/npm-yargs-parser

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

Overview

Eval results

Files

Detailed Parsing

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

Advanced parsing mode that returns comprehensive information including error details, alias mappings, and parsing metadata. This mode is primarily used by the yargs framework itself but can be useful for debugging and advanced use cases.

Import

import parser from "yargs-parser";

API

function parser.detailed(args: ArgsInput, opts?: Partial<Options>): DetailedArguments;

interface DetailedArguments {
  /** An object representing the parsed value of `args` */
  argv: Arguments;
  /** Populated with an error object if an exception occurred during parsing */
  error: Error | null;
  /** The inferred list of aliases built by combining lists in opts.alias */
  aliases: Dictionary<string[]>;
  /** Any new aliases added via camel-case expansion */
  newAliases: Dictionary<boolean>;
  /** Any new argument created by opts.default, no aliases included */
  defaulted: Dictionary<boolean>;
  /** The configuration loaded from the yargs stanza in package.json */
  configuration: Configuration;
}

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

interface Dictionary<T = any> {
  [key: string]: T;
}

Basic Usage

import parser from "yargs-parser";

const result = parser.detailed(['--foo', 'bar', '--verbose', '-n', 'test'], {
  alias: { name: ['n'] },
  boolean: ['verbose'],
  default: { port: 3000 }
});

console.log(result);

Output:

{
  argv: { _: [], foo: 'bar', verbose: true, n: 'test', name: 'test', port: 3000 },
  error: null,
  aliases: { name: ['n'] },
  newAliases: {},
  defaulted: { port: true },
  configuration: { /* full configuration object */ }
}

Error Handling

The detailed parser captures parsing errors in the error property:

const result = parser.detailed(['--config', 'invalid-file.json'], {
  config: ['config']
});

if (result.error) {
  console.error('Parsing error:', result.error.message);
} else {
  console.log('Parsed successfully:', result.argv);
}

Alias Information

Configured Aliases

The aliases property contains all explicitly configured aliases:

const result = parser.detailed(['-v', '--name', 'Alice'], {
  alias: {
    verbose: ['v'],
    name: ['n', 'user']
  }
});

console.log(result.aliases);
// Output: { verbose: ['v'], name: ['n', 'user'] }

New Aliases from Camel-Case Expansion

The newAliases property tracks aliases created through camel-case expansion:

const result = parser.detailed(['--foo-bar', 'value']);

console.log(result.newAliases);
// Output: { fooBar: true }
console.log(result.argv);
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }

Default Value Tracking

The defaulted property identifies which arguments received default values:

const result = parser.detailed(['--name', 'Alice'], {
  default: {
    port: 3000,
    debug: false,
    name: 'Anonymous'
  }
});

console.log(result.defaulted);
// Output: { port: true, debug: true }
// Note: 'name' is not in defaulted because it was explicitly provided

Configuration Information

The configuration property contains the complete configuration object used for parsing:

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

console.log(result.configuration);
// Output: Complete configuration with custom and default values

Debugging Usage

Detailed parsing is particularly useful for debugging argument parsing issues:

function debugParser(args: string[], options?: any) {
  const result = parser.detailed(args, options);
  
  console.log('Parsed arguments:', result.argv);
  console.log('Configured aliases:', result.aliases);
  console.log('Auto-generated aliases:', result.newAliases);
  console.log('Defaulted values:', result.defaulted);
  
  if (result.error) {
    console.error('Parsing error:', result.error);
  }
  
  return result.argv;
}

debugParser(['--foo-bar', 'value', '--debug'], {
  alias: { debug: ['d'] },
  default: { port: 8080 }
});

Comparison with Basic Parsing

// Basic parsing - returns only the parsed arguments
const basic = parser(['--foo', 'bar']);
console.log(basic);
// Output: { _: [], foo: 'bar' }

// Detailed parsing - returns comprehensive information
const detailed = parser.detailed(['--foo', 'bar']);
console.log(detailed.argv);  // Same as basic result
console.log(detailed.error); // null
console.log(detailed.aliases); // {}
console.log(detailed.newAliases); // {}
console.log(detailed.defaulted); // {}

Advanced Use Cases

Custom Configuration Validation

function validateConfig(args: string[], expectedConfig: Partial<Configuration>) {
  const result = parser.detailed(args, { configuration: expectedConfig });
  
  // Verify configuration was applied correctly
  for (const [key, value] of Object.entries(expectedConfig)) {
    if (result.configuration[key] !== value) {
      console.warn(`Configuration mismatch for ${key}: expected ${value}, got ${result.configuration[key]}`);
    }
  }
  
  return result;
}

Alias Analysis

function analyzeAliases(args: string[], options: any) {
  const result = parser.detailed(args, options);
  
  console.log('Explicit aliases used:');
  Object.entries(result.aliases).forEach(([key, aliases]) => {
    console.log(`  ${key}: ${aliases.join(', ')}`);
  });
  
  console.log('Auto-generated aliases:');
  Object.keys(result.newAliases).forEach(alias => {
    console.log(`  ${alias} (from camel-case expansion)`);
  });
  
  return result.argv;
}

Install with Tessl CLI