ordinary-arg-parser

A lightweight command-line argument parser for Node.js and browsers. It follows GNU conventions.

Quick Start

Installation

npm install ordinary-arg-parser

Try It

Create a file cli.js with the following code:

// cli.js
const { ordinaryArgParser } = require("ordinary-arg-parser");

const result = ordinaryArgParser(
    process.argv.slice(2),
    [
        { name: 'all', kind: 'flag', alias: 'a' },
        { name: 'message', kind: 'value', alias: 'm', default: '' },
        { name: 'verify', kind: 'flag', default: true },
        { name: 'author', kind: 'value', default: '' }
    ]
);

console.dir(result);

Run it with:

node ./cli.js -am "Initial commit" --author="John" --no-verify file.js

You'll see:

{
  _: [ 'file.js' ],
  all: true,
  message: 'Initial commit',
  author: 'John',
  verify: false
}

For browser or ES module environments, import the module and pass your command string split into an array:

import { ordinaryArgParser } from "ordinary-arg-parser";

const result = ordinaryArgParser(cliInputString.split(" "), config)

Usage

ordinaryArgParser(args, config)

Parameters:

• args: string[] — An array of argument strings to parse. This is typically process.argv.slice(2) in Node.js app.
• config: OptionsConfig — An array of option definitions that describe the expected arguments and their behavior.

Returns:

• ParseResult — An object containing the parsing results. Options are stored by their name (never by alias), and positional arguments are stored in _.

Throws:

• The parser throws UnknownArgumentError or MissingValueError when it encounters invalid arguments.

Option Configuration

interface OptionConfig {
    kind: "flag" | "value";
    name: string; // Canonical long name
    alias?: string; // Single-character short name
    default?: unknown; // Required for 'value' kind
    duplicateHandling?: "accumulate" | "last-wins" | "first-wins";
    transform?: (value: unknown) => unknown; // Applied after parsing
}

Each option in your configuration must specify whether it's a flag (boolean) or expects a value.

Supported Option Formats

The parser recognizes standard GNU-style argument patterns:

| Format | Example | Description | | ---------------- | ------------------- | ---------------------------- | | Short flag | -v | Boolean flag | | Long flag | --verbose | Boolean flag | | Short clustered | -abc | Multiple flags: -a -b -c | | Short with value | -o file.txt | Space-separated | | Short attached | -ofile.txt | Value attached | | Long with equals | --output=file.txt | Equals syntax | | Long with space | --output file.txt | Space-separated | | Negation | --no-verify | Sets flag to false | | Terminator | -- | End options, rest positional |

Numeric Values

Numbers are always treated as values, never as options. This includes negative numbers and floating-point values. For example, --count 10 produces a value of '10', and --offset -5 produces '-5'.

Duplicate Handling

When an option appears multiple times, you can control the behavior through the duplicateHandling property.

• The default strategy is 'last-wins', where --output a.txt --output b.txt results in output: 'b.txt'.
• The 'first-wins' strategy does the opposite, keeping 'a.txt'.
• The 'accumulate' strategy collects all values into an array, so --exclude a --exclude b produces exclude: ['a', 'b'].

Transforms

The transform function is applied to both parsed values and defaults. This allows you to convert strings to numbers, validate inputs, or perform any other post-processing.

Error Handling

The ordinary-arg-parser throws errors with a code property and a toJSON() method for logging.

UnknownArgumentError (code: 'UNKNOWN_ARGUMENT') is thrown when an argument isn't defined in your configuration. The error includes the problematic argument and the full rawArgs array for context.

MissingValueError (code: 'MISSING_VALUE') is thrown when an argument with kind: 'value' doesn't receive a value. Like the unknown argument error, it includes both the argument and rawArgs properties.

try {
    const args = ordinaryArgParser(process.argv.slice(2), config);
    // Use parsed args...
} catch (error) {
    if (error.code === "UNKNOWN_ARGUMENT") {
        console.error(`Error: Unknown option '${error.argument}'`);
        console.error("Run with --help to see available options.");
    }

    if (error.code === "MISSING_VALUE") {
        console.error(`Error: ${error.argument} requires a value`);
        console.error(`Example: mytool ${error.argument} <value>`);
    }

    // Log structured error data to your telemetry system
    logger.error("Argument parsing failed", error.toJSON());
    process.exit(1);
}

Limitations

The parser has intentional constraints that keep it lightweight and focused.

When clustering short options like -abc value, only the last option in the cluster can receive a value, so the value is assigned to c.

The parser also doesn't include built-in validation for required options, value constraints, or relationships between options. You should handle these requirements in your application logic after parsing.

Further Reading

• POSIX defines the core: short options (-v), option arguments, and -- terminator
• GNU extends with: long options (--verbose), equals syntax (--output=file), and negation (--no-verify)

License

MIT