{"id":12826,"library":"args-tokens","title":"args-tokens: Command-line Argument Token Parser","description":"`args-tokens` is a high-performance, type-safe library designed for parsing command-line arguments, offering a compatible token representation with Node.js `util.parseArgs`. It differentiates itself by providing a decoupled, more performant approach to argument parsing and tokenization compared to the built-in Node.js utility. The library is optimized for universal runtimes, ships with comprehensive TypeScript types, and maintains zero external dependencies, making it a lightweight and efficient choice for CLI application development. Currently at version 0.24.3, `args-tokens` demonstrates an active release cadence, frequently delivering bug fixes, performance improvements, and new features. Its key differentiators include significantly faster parsing benchmarks, explicit control over argument resolution, and a strong focus on generating `util.parseArgs`-compatible tokens.","status":"active","version":"0.24.3","language":"javascript","source_language":"en","source_url":"https://github.com/kazupon/args-tokens","tags":["javascript","args","args-parser","cli","parseargs","tokens","typescript"],"install":[{"cmd":"npm install args-tokens","lang":"bash","label":"npm"},{"cmd":"yarn add args-tokens","lang":"bash","label":"yarn"},{"cmd":"pnpm add args-tokens","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ES Module only. Use named imports for core parsing functionality.","wrong":"const { parse } = require('args-tokens')","symbol":"parse","correct":"import { parse } from 'args-tokens'"},{"note":"Used for resolving parsed tokens into `values` and `positionals` based on a schema. Ensure named import.","wrong":"import resolveArgs from 'args-tokens/resolveArgs'","symbol":"resolveArgs","correct":"import { resolveArgs } from 'args-tokens'"},{"note":"The parser combinator API was introduced in v0.24.0 as an experimental feature. Its usage path is typically from a sub-path.","symbol":"createParser","correct":"import { createParser } from 'args-tokens/combinator'"}],"quickstart":{"code":"import { parse, resolveArgs } from 'args-tokens';\n\n// Example 1: Basic token parsing\nconst rawArgs1 = ['--name', 'Alice', '-a', '10', '--', 'file1.txt', 'file2.txt'];\nconst tokens1 = parse(rawArgs1);\nconsole.log('Tokens (Example 1):', JSON.stringify(tokens1, null, 2));\n/*\nTokens (Example 1): [\n  { \"kind\": \"option\", \"name\": \"name\", \"rawValue\": \"Alice\", \"index\": 0, \"trailing\": [] },\n  { \"kind\": \"option\", \"name\": \"a\", \"rawValue\": \"10\", \"index\": 2, \"trailing\": [] },\n  { \"kind\": \"dash\", \"index\": 4, \"trailing\": [] },\n  { \"kind\": \"positional\", \"value\": \"file1.txt\", \"index\": 5, \"trailing\": [] },\n  { \"kind\": \"positional\", \"value\": \"file2.txt\", \"index\": 6, \"trailing\": [] }\n]\n*/\n\n// Example 2: Resolving arguments with options schema\nconst rawArgs2 = ['--user=Bob', '-p', '8080', 'config.json'];\nconst { values, positionals } = resolveArgs(rawArgs2, {\n  options: {\n    user: { type: 'string' },\n    port: { type: 'string', short: 'p' },\n    debug: { type: 'boolean', short: 'd' }\n  },\n  strict: true\n});\n\nconsole.log('Resolved Values (Example 2):', values); // { user: 'Bob', port: '8080', debug: false }\nconsole.log('Resolved Positionals (Example 2):', positionals); // ['config.json']\n\n// Example 3: Handling complex short options\nconst rawArgs3 = ['-abc', 'valueC', 'remainder'];\nconst { values: complexValues, positionals: complexPositionals } = resolveArgs(rawArgs3, {\n  options: {\n    a: { type: 'boolean' },\n    b: { type: 'boolean' },\n    c: { type: 'string' }\n  }\n});\nconsole.log('Complex Values (Example 3):', complexValues); // { a: true, b: true, c: 'valueC' }\nconsole.log('Complex Positionals (Example 3):', complexPositionals); // ['remainder']","lang":"typescript","description":"Demonstrates basic argument tokenization with `parse` and resolution with `resolveArgs` using an options schema, mirroring `util.parseArgs` functionality."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 20 or newer (e.g., using nvm, fnm, or volta).","message":"Node.js version 20 or higher is required to use this package.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Thoroughly test argument parsing behavior with various short option combinations if exact parity with `util.parseArgs` is critical for your application.","message":"While aiming for `util.parseArgs` token compatibility, `args-tokens` may handle short options differently than the built-in Node.js utility due to different design philosophies, especially with bundled short options (e.g., `-abc`).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use experimental features with caution. Consider pinning to a specific patch version if you rely on the experimental combinators or postpone adoption until the API stabilizes.","message":"The parser combinator API, introduced in v0.24.0, is explicitly marked as experimental. It may be subject to breaking changes in future minor or patch releases.","severity":"gotcha","affected_versions":">=0.24.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use ES Module `import` syntax: `import { parse } from 'args-tokens';`. Ensure your project's `package.json` includes `\"type\": \"module\"` or your file uses the `.mjs` extension.","cause":"This package is distributed as an ES Module. Attempting to load it with CommonJS `require()` in a script that is not configured for ES Modules.","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using named imports: `import { parse, resolveArgs } from 'args-tokens';`.","cause":"Attempting to use a named export (like `parse` or `resolveArgs`) as a default export or incorrectly destructuring imports.","error":"TypeError: args_tokens.parse is not a function"},{"fix":"Upgrade your Node.js runtime to version 20 or newer to meet the package's engine requirements.","cause":"The package explicitly requires Node.js version 20 or higher, as declared in its `engines` field, but you are running an older version.","error":"Error: The current Node.js version (vX.Y.Z) does not satisfy the '>=20' requirement."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}