{"id":15470,"library":"parameter-reducers","title":"CLI Parameter Reducers","description":"parameter-reducers is a JavaScript/TypeScript library designed for building robust and type-safe command-line interface (CLI) parameter parsers. Its current stable version is 2.1.0, and it appears to follow an active development cadence with recent feature additions and a significant breaking change in version 2.0.0. A key differentiator is its immutable, reducer-based chain API, which allows for flexible composition and reuse of parameter definitions. This approach facilitates highly customizable parsing logic while leveraging TypeScript to provide strong type guarantees for parsed arguments, reducing runtime errors associated with CLI argument processing. It focuses on core parsing capabilities, intentionally leaving documentation generation to user-defined template literals.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/ForbesLindesay/parameter-reducers","tags":["javascript","typescript"],"install":[{"cmd":"npm install parameter-reducers","lang":"bash","label":"npm"},{"cmd":"yarn add parameter-reducers","lang":"bash","label":"yarn"},{"cmd":"pnpm add parameter-reducers","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Preferred modern ESM import. CommonJS `require` might work if your environment is correctly configured, but ESM is recommended and shown in examples.","wrong":"const { startChain } = require('parameter-reducers');","symbol":"startChain","correct":"import { startChain } from 'parameter-reducers';"},{"note":"`param` is a named export containing utility methods (e.g., `param.string`, `param.flag`), not a default export.","wrong":"import param from 'parameter-reducers';","symbol":"param","correct":"import { param } from 'parameter-reducers';"},{"note":"`parse` is a named export for initiating the parsing process against a parameter chain.","wrong":"import parse from 'parameter-reducers';","symbol":"parse","correct":"import { parse } from 'parameter-reducers';"}],"quickstart":{"code":"import {startChain, param, parse} from 'parameter-reducers';\n\nconst params = startChain()\n  .addParam(param.flag(['-h', '--help'], 'help'))\n  .addParam(param.string(['-m', '--message'], 'message'))\n  .addParam(param.integer(['-c', '--count'], 'count'));\n\nconst {help = false, message = 'hello world', count = 1} = parse(\n  params,\n  process.argv.slice(2),\n).extract();\n\nif (help) {\n  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`);\n}\n\nfor (let i = 0; i < count; i++) {\n  console.log(message);\n}\n\n// Example execution: node your-script.ts -m \"Hello CLI\" -c 3","lang":"typescript","description":"Demonstrates basic CLI argument parsing for help flags, strings, and integers, including default values and help text output for a simple 'repeat' command."},"warnings":[{"fix":"Review and reorder parameter definitions in `startChain().addParam(...)` calls to ensure the desired precedence. The parameter added last in the chain now wins.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When destructuring the parsed object, provide default values like `const { help = false, message = 'hello world' } = parsedResult.extract();`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"🚨 Unrecognized option --some-unexpected-flag."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'message')"}],"ecosystem":"npm"}