Registry / args-tokens

args-tokens

JSON →
library0.24.3jsnpmunverified

`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.

npm install args-tokens
github ↗package ↗
INSTALL
IMPORT
SIG · ARGS-TOKENS
A
args-tokens
javascriptv0.24.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
✓ import { parse } from 'args-tokens'
✗ const { parse } = require('args-tokens')
This package is ES Module only. Use named imports for core parsing functionality.
resolveArgs
✓ import { resolveArgs } from 'args-tokens'
✗ import resolveArgs from 'args-tokens/resolveArgs'
Used for resolving parsed tokens into `values` and `positionals` based on a schema. Ensure named import.
createParser
✓ import { createParser } from 'args-tokens/combinator'
The parser combinator API was introduced in v0.24.0 as an experimental feature. Its usage path is typically from a sub-path.

Demonstrates basic argument tokenization with `parse` and resolution with `resolveArgs` using an options schema, mirroring `util.parseArgs` functionality.

import { parse, resolveArgs } from 'args-tokens'; // Example 1: Basic token parsing const rawArgs1 = ['--name', 'Alice', '-a', '10', '--', 'file1.txt', 'file2.txt']; const tokens1 = parse(rawArgs1); console.log('Tokens (Example 1):', JSON.stringify(tokens1, null, 2)); /* Tokens (Example 1): [ { "kind": "option", "name": "name", "rawValue": "Alice", "index": 0, "trailing": [] }, { "kind": "option", "name": "a", "rawValue": "10", "index": 2, "trailing": [] }, { "kind": "dash", "index": 4, "trailing": [] }, { "kind": "positional", "value": "file1.txt", "index": 5, "trailing": [] }, { "kind": "positional", "value": "file2.txt", "index": 6, "trailing": [] } ] */ // Example 2: Resolving arguments with options schema const rawArgs2 = ['--user=Bob', '-p', '8080', 'config.json']; const { values, positionals } = resolveArgs(rawArgs2, { options: { user: { type: 'string' }, port: { type: 'string', short: 'p' }, debug: { type: 'boolean', short: 'd' } }, strict: true }); console.log('Resolved Values (Example 2):', values); // { user: 'Bob', port: '8080', debug: false } console.log('Resolved Positionals (Example 2):', positionals); // ['config.json'] // Example 3: Handling complex short options const rawArgs3 = ['-abc', 'valueC', 'remainder']; const { values: complexValues, positionals: complexPositionals } = resolveArgs(rawArgs3, { options: { a: { type: 'boolean' }, b: { type: 'boolean' }, c: { type: 'string' } } }); console.log('Complex Values (Example 3):', complexValues); // { a: true, b: true, c: 'valueC' } console.log('Complex Positionals (Example 3):', complexPositionals); // ['remainder']
Debug
Known issues
breakingNode.js version 20 or higher is required to use this package.
fix
Upgrade your Node.js runtime environment to version 20 or newer (e.g., using nvm, fnm, or volta).
affects: >=0.1.0
gotchaWhile 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`).
fix
Thoroughly test argument parsing behavior with various short option combinations if exact parity with `util.parseArgs` is critical for your application.
affects: >=0.1.0
gotchaThe 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.
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.
affects: >=0.24.0
Errors
Common errors & fixes
ReferenceError: require is not defined
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.
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.
TypeError: args_tokens.parse is not a function
Attempting to use a named export (like `parse` or `resolveArgs`) as a default export or incorrectly destructuring imports.
fix
Ensure you are using named imports: `import { parse, resolveArgs } from 'args-tokens';`.
Error: The current Node.js version (vX.Y.Z) does not satisfy the '>=20' requirement.
The package explicitly requires Node.js version 20 or higher, as declared in its `engines` field, but you are running an older version.
fix
Upgrade your Node.js runtime to version 20 or newer to meet the package's engine requirements.
Upgrade
Version history
0.24.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/kazupon/args-tokens ↗
packagehttps://www.npmjs.com/package/args-tokens ↗
args-tokens — npm install args-tokens · libregistry