CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-yargs-parser

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

yargs-parser

yargs-parser is the mighty option parser used by yargs for parsing command-line arguments. It provides comprehensive argument parsing capabilities with extensive configuration options, supporting various data types, complex option configurations, and advanced parsing features like dot-notation, camel-case expansion, and configurable parsing behaviors.

Package Information

  • Package Name: yargs-parser
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install yargs-parser

Core Imports

Node.js

ESM (ES Modules):

import parser from "yargs-parser";

// Individual utilities (separate import paths)
import { camelCase, decamelize, looksLikeNumber } from "yargs-parser";
import { tokenizeArgString } from "yargs-parser/build/lib/tokenize-arg-string.js";

CommonJS:

const parser = require("yargs-parser");

// Access utilities via parser object
const { camelCase, decamelize, looksLikeNumber } = parser;

Browser (ESM)

<script type="module">
  import parser from "https://unpkg.com/yargs-parser@22.0.0/browser.js";
  
  // Utilities are available on the parser object
  const { camelCase, decamelize, looksLikeNumber } = parser;
  
  // Note: tokenizeArgString and config file loading not supported in browser
</script>

Deno

import parser from "https://deno.land/x/yargs_parser/deno.ts";
// or from specific version:
// import parser from "https://deno.land/x/yargs_parser@v22.0.0/deno.ts";

// Utilities available on parser object
const { camelCase, decamelize, looksLikeNumber } = parser;

// Note: Only .json config files supported in Deno

Basic Usage

import parser from "yargs-parser";

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

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

// Parse with options
const parsed = parser(['--name', 'Alice', '--age', '25', '--verbose'], {
  string: ['name'],
  number: ['age'],
  boolean: ['verbose']
});
console.log(parsed);
// Output: { _: [], name: 'Alice', age: 25, verbose: true }

Architecture

yargs-parser is built around several key components:

  • Core Parser: Main parsing function that handles argument tokenization and processing
  • Type System: Complete TypeScript integration with detailed type definitions for all options and return values
  • Configuration Engine: Extensive configuration system with 18+ behavioral options (camel-case expansion, dot-notation, etc.)
  • Platform Support: Cross-platform compatibility with Node.js, browser, and Deno environments
  • String Utilities: Built-in utility functions for camelCase conversion, number detection, and string manipulation

Capabilities

Core Parsing

Main argument parsing functionality that converts command-line arguments into structured JavaScript objects with extensive configuration options.

function parser(args: string | any[], opts?: Partial<Options>): Arguments;

interface Arguments {
  _: (string | number)[];
  '--'?: (string | number)[];
  [argName: string]: any;
}

Core Parsing

Detailed Parsing

Advanced parsing mode that returns comprehensive information including error details, alias mappings, and parsing metadata.

function parser.detailed(args: string | any[], opts?: Partial<Options>): DetailedArguments;

interface DetailedArguments {
  argv: Arguments;
  error: Error | null;
  aliases: Dictionary<string[]>;
  newAliases: Dictionary<boolean>;
  defaulted: Dictionary<boolean>;
  configuration: Configuration;
}

Detailed Parsing

Configuration Options

Comprehensive parsing behavior configuration with 18+ options controlling how arguments are interpreted and processed.

interface Configuration {
  'boolean-negation': boolean;
  'camel-case-expansion': boolean;
  'combine-arrays': boolean;
  'dot-notation': boolean;
  'duplicate-arguments-array': boolean;
  'flatten-duplicate-arrays': boolean;
  'greedy-arrays': boolean;
  'halt-at-non-option': boolean;
  'nargs-eats-options': boolean;
  'negation-prefix': string;
  'parse-positional-numbers': boolean;
  'parse-numbers': boolean;
  'populate--': boolean;
  'set-placeholder-key': boolean;
  'short-option-groups': boolean;
  'strip-aliased': boolean;
  'strip-dashed': boolean;
  'unknown-options-as-args': boolean;
}

Configuration Options

Parser Options

Parsing hints and type specifications that control how individual arguments are processed and coerced.

interface Options {
  alias: Dictionary<string | string[]>;
  array: ArrayOption | ArrayOption[];
  boolean: string | string[];
  config: string | string[] | Dictionary<boolean | ConfigCallback>;
  configObjects: Dictionary<any>[];
  configuration: Partial<Configuration>;
  coerce: Dictionary<CoerceCallback>;
  count: string | string[];
  default: Dictionary<any>;
  envPrefix?: string;
  narg: Dictionary<number>;
  normalize: string | string[];
  string: string | string[];
  number: string | string[];
  __: (format: any, ...param: any[]) => string;
  key: Dictionary<any>;
}

Parser Options

String Utilities

Built-in utility functions for string manipulation and number detection that are also exposed as part of the public API.

function parser.camelCase(str: string): string;
function parser.decamelize(str: string, joinString?: string): string;
function parser.looksLikeNumber(x: null | undefined | number | string): boolean;

String Utilities

Argument String Tokenization

Low-level utility for tokenizing argument strings into arrays, handling quoted strings and escape sequences.

function tokenizeArgString(argString: string | any[]): string[];

Argument String Tokenization

Types

Core Types

type ArgsInput = string | any[];
type ArgsOutput = (string | number)[];

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

Parser Types

interface Parser {
  (args: ArgsInput, opts?: Partial<Options>): Arguments;
  detailed(args: ArgsInput, opts?: Partial<Options>): DetailedArguments;
  camelCase(str: string): string;
  decamelize(str: string, joinString?: string): string;
  looksLikeNumber(x: null | undefined | number | string): boolean;
}

Configuration Types

type ArrayOption = string | { 
  key: string; 
  boolean?: boolean; 
  string?: boolean; 
  number?: boolean; 
  integer?: boolean; 
};

type CoerceCallback = (arg: any) => any;
type ConfigCallback = (configPath: string) => { [key: string]: any } | Error;

Advanced Types

// Utility types for working with keys and values
type KeyOf<T> = {
  [K in keyof T]: string extends K ? never : number extends K ? never : K
} extends { [_ in keyof T]: infer U } ? U : never;

type ValueOf<T> = T extends (infer U)[] ? U : T[keyof T];

// Internal flag management types
type StringFlag = Dictionary<string[]>;
type BooleanFlag = Dictionary<boolean>;
type NumberFlag = Dictionary<number>;
type ConfigsFlag = Dictionary<string | string[] | boolean | ConfigCallback>;
type CoercionsFlag = Dictionary<CoerceCallback>;
type KeysFlag = string[];

interface Flags {
  aliases: StringFlag;
  arrays: BooleanFlag;
  bools: BooleanFlag;
  strings: BooleanFlag;
  numbers: BooleanFlag;
  counts: BooleanFlag;
  normalize: BooleanFlag;
  configs: ConfigsFlag;
  nargs: NumberFlag;
  coercions: CoercionsFlag;
  keys: KeysFlag;
}

type Flag = ValueOf<Omit<Flags, 'keys'>>;
type FlagValue = ValueOf<Flag>;
type FlagsKey = KeyOf<Omit<Flags, 'keys'>>;
type ArrayFlagsKey = Extract<FlagsKey, 'bools' | 'strings' | 'numbers'>;

// Parser mixin interface for platform-specific implementations
interface YargsParserMixin {
  cwd: Function;
  format: Function;
  normalize: Function;
  require: Function;
  resolve: Function;
  env: Function;
}

// Default values configuration
enum DefaultValuesForTypeKey {
  BOOLEAN = 'boolean',
  STRING = 'string',
  NUMBER = 'number',
  ARRAY = 'array',
}

interface DefaultValuesForType {
  [DefaultValuesForTypeKey.BOOLEAN]: boolean;
  [DefaultValuesForTypeKey.STRING]: string;
  [DefaultValuesForTypeKey.NUMBER]: undefined;
  [DefaultValuesForTypeKey.ARRAY]: any[];
}

type OptionsDefault = ValueOf<Pick<Required<Options>, 'default'>>;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/yargs-parser@22.0.x
Publish Source
CLI
Badge
tessl/npm-yargs-parser badge