Wargs - Wrong Args Parser

Common errors

• TypeError: (0 , wargs__WEBPACK_IMPORTED_MODULE_0__.wargs) is not a function

  cause Attempting to use `wargs` with named import syntax (`import { wargs } from 'wargs'`) when it is a default export.
  fix Use a default import: `import wargs from 'wargs';`

• TypeError: wargs is not a function

  cause Attempting to destructure `wargs` from `require()` in CommonJS (`const { wargs } = require('wargs')`) when it is a default export.
  fix Use the direct `require()` assignment: `const wargs = require('wargs');`

• Arguments not parsed as expected (e.g., 'key=value' in 'params' instead of 'data')

  cause Misunderstanding the distinction between `data` (for `key=value` syntax) and `params` (for `key:value` syntax) in `wargs`'s output structure.
  fix Refer to the `wargs` documentation carefully. `data` collects `key=value` pairs, while `params` collects `key:value` pairs. Adjust your input or access the correct output property accordingly.

Warnings

• gotcha Wargs is explicitly designed as a 'wrong args parser' and deviates significantly from common CLI parsing libraries like `minimist` or `yargs`. Its regex-based approach and unique categorization of arguments (`data` for `key=value` vs. `params` for `key:value`) requires careful understanding of its output structure.
  Fix: Thoroughly review the documentation and examples to understand how `wargs` processes arguments and maps them to its distinct output properties.
• deprecated The `wargs` package appears to be abandoned. The last commit to its GitHub repository was in September 2020, and the latest version (0.10.0) was published 5 years ago on npm. This means there is no active development, bug fixes, or security patches, making it unsuitable for new projects or critical applications.
  Fix: Consider migrating to an actively maintained argument parsing library for new or critical projects. If usage is essential, be aware of potential unpatched vulnerabilities or incompatibilities with newer Node.js versions.
• gotcha Wargs does not ship with TypeScript type definitions. Developers using TypeScript will need to create their own declaration files (`.d.ts`) or use `declare module 'wargs';` to avoid type errors, losing the benefits of strong typing.
  Fix: Create a `wargs.d.ts` file with appropriate type declarations (e.g., `declare module 'wargs' { function wargs(input: string | string[], options?: any): { _: string[]; raw: string[]; data: { [key: string]: string }; flags: { [key: string]: boolean }; params: { [key: string]: string } }; export default wargs; }`) or cast the return value to `any`.

Install

• npm install wargs npm
• yarn add wargs yarn
• pnpm add wargs pnpm

Imports

• wargs
  wrong:

  import { wargs } from 'wargs';

  correct:

  import wargs from 'wargs';

  Wargs is a default export. Named imports will result in a TypeError.
• wargs
  wrong:

  const { wargs } = require('wargs');

  correct:

  const wargs = require('wargs');

  CommonJS usage for the default export. Destructuring is incorrect.

Quickstart

Demonstrates parsing both string and array inputs, and accessing the different argument categories (`_`, `raw`, `data`, `flags`, `params`) along with options like `camelCase` and `format`.

import wargs from 'wargs';

const strInput = '/ _csrf=`token` --json accept:"text/plain; charset=utf8" -- x foo:bar';
const arrayInput = ['/', '_csrf=`token`', '--json', 'accept:text/plain; charset=utf8', '--', 'x', 'foo:bar'];

console.log('--- Parsing String Input ---');
const parsedFromString = wargs(strInput, { camelCase: true });
console.log('Parsed Object:', parsedFromString);
console.log('Positional arguments (_):', parsedFromString._);
console.log('Raw arguments (raw):', parsedFromString.raw);
console.log('Data (key=value):', parsedFromString.data);
console.log('Flags (--flag, -f):', parsedFromString.flags);
console.log('Parameters (key:value):', parsedFromString.params);

console.log('\n--- Parsing Array Input ---');
const parsedFromArray = wargs(arrayInput, { format: v => String(v).toUpperCase() });
console.log('Parsed Object:', parsedFromArray);
console.log('Positional arguments (_):', parsedFromArray._);
console.log('Raw arguments (raw):', parsedFromArray.raw);
console.log('Data (key=value):', parsedFromArray.data);
console.log('Flags (--flag, -f):', parsedFromArray.flags);
console.log('Parameters (key:value):', parsedFromArray.params);