CLI Parameter Reducers

Common errors

• 🚨 Unrecognized option --some-unexpected-flag.

  cause The CLI was invoked with an option or argument that was not defined in the parameter chain, and the `parseResult.rest` array was not properly handled or `extract()` was not used.
  fix Ensure all possible CLI arguments are covered by `addParam` calls in your chain. If unexpected arguments are acceptable, explicitly check `parseResult.rest.length` after parsing and decide how to handle them. Using `parseResult.extract()` will automatically detect and report unrecognized options.

• TypeError: Cannot read properties of undefined (reading 'message')

  cause Attempting to access a parsed parameter (e.g., `message`) that was not provided on the command line, and no default value was assigned during destructuring.
  fix Provide a default value when destructuring the parsed parameters, e.g., `const { message = 'default value' } = parse(...).extract();`. Alternatively, ensure the parameter is always present in CLI invocations or add validation checks.

Warnings

• breaking In version 2.0.0, the order of precedence for parameters was reversed. If you previously defined a parameter twice (e.g., a string and then a flag with the same name), the last defined parameter now takes precedence, whereas previously it was the first. This can change the effective type and value of parameters.
  Fix: Review and reorder parameter definitions in `startChain().addParam(...)` calls to ensure the desired precedence. The parameter added last in the chain now wins.
• gotcha The `parse()` function returns an object that can represent either a valid parsing result or an error. Users must explicitly check `parseResult.valid` and `parseResult.rest.length` to ensure all arguments were parsed successfully and without errors. Failing to do so can lead to silent errors or incorrect processing of unhandled arguments.
  Fix: Always check `if (!parseResult.valid)` and `if (parseResult.rest.length)` manually. Alternatively, use `parseResult.extract()` which handles these checks, logs errors, and exits the process if parsing fails or unrecognized options are present.
• gotcha Default values for parameters are not set within the `param` definition itself. Instead, they are applied through JavaScript's object destructuring assignment when extracting the parsed results.
  Fix: When destructuring the parsed object, provide default values like `const { help = false, message = 'hello world' } = parsedResult.extract();`.
• gotcha The library explicitly does not provide built-in functionality for generating help documentation for your CLI. Developers are expected to manage and render help text manually.
  Fix: Utilize template literals or other string formatting methods within your application logic (e.g., when a `--help` flag is present) to construct and display usage information and parameter descriptions.

Install

• npm install parameter-reducers npm
• yarn add parameter-reducers yarn
• pnpm add parameter-reducers pnpm

Imports

• startChain
  wrong:

  const { startChain } = require('parameter-reducers');

  correct:

  import { startChain } from 'parameter-reducers';

  Preferred modern ESM import. CommonJS `require` might work if your environment is correctly configured, but ESM is recommended and shown in examples.
• param
  wrong:

  import param from 'parameter-reducers';

  correct:

  import { param } from 'parameter-reducers';

  `param` is a named export containing utility methods (e.g., `param.string`, `param.flag`), not a default export.
• parse
  wrong:

  import parse from 'parameter-reducers';

  correct:

  import { parse } from 'parameter-reducers';

  `parse` is a named export for initiating the parsing process against a parameter chain.

Quickstart

Demonstrates basic CLI argument parsing for help flags, strings, and integers, including default values and help text output for a simple 'repeat' command.

import {startChain, param, parse} from 'parameter-reducers';

const params = startChain()
  .addParam(param.flag(['-h', '--help'], 'help'))
  .addParam(param.string(['-m', '--message'], 'message'))
  .addParam(param.integer(['-c', '--count'], 'count'));

const {help = false, message = 'hello world', count = 1} = parse(
  params,
  process.argv.slice(2),
).extract();

if (help) {
  console.log(`Usage: repeat -m "My Message" -c 10\n\nparameters:\n\n-h --help    Print this help\n-m --message The message to print\n-c --count   How many times to print the message`);
}

for (let i = 0; i < count; i++) {
  console.log(message);
}

// Example execution: node your-script.ts -m "Hello CLI" -c 3