@clerc/parser


A powerful, lightweight, and flexible command-line arguments parser.

Installation

``bash
$ npm install @clerc/parser
$ yarn add @clerc/parser
$ pnpm add @clerc/parser
`

Usage

The core of this package is the parse function. It takes an array of arguments and a configuration object, and returns a structured object containing the parsed flags, parameters, and other useful information.

`typescript
import { parse } from "@clerc/parser";

const { flags, parameters, unknown } = parse(process.argv.slice(2), {
flags: {
// Define your flags here
port: {
type: Number,
alias: "p",
default: 8080,
},
help: {
type: Boolean,
alias: "h",
},
},
});

console.log("Flags:", flags);
console.log("Parameters:", parameters);
console.log("Unknown args:", unknown);
`

API

$3

#### args

- Type: string[]
- The array of command-line arguments to parse (e.g., process.argv.slice(2)).

#### options

- Type: ParseOptions

An object to configure the parser.

- flags: An object defining the flags to parse.
- Key: The name of the flag (in camelCase).
- Value: The flag's configuration, which can be a type constructor (String, Number, Boolean) or a custom function that takes a string and returns a parsed value or an object with the following properties:
- type: The type of the flag. Can be a constructor like String, Number, Boolean, Object, an array of a constructor (e.g., [String]), or a custom function that takes a string and returns a parsed value.
- alias: A string or an array of strings for alternative names (e.g., short flags).
- default: A default value for the flag if it's not provided in the arguments. Can be a value or a function that returns a value.
- negatable: (For Booleans) Whether to support --no- syntax. Defaults to true.
- ignore: A function to conditionally stop parsing. It receives the type (flag or parameter) and the arg string, and should return true to stop parsing from that point.

#### Returns

An object with the following properties:

- flags: An object containing the parsed flags.
- parameters: An array of positional arguments.
- unknown: An object containing flags that were not defined in the schema.
- doubleDash: An array of arguments that appear after a --.
- ignored: An array of arguments that were ignored due to the ignore function.

Features

$3

Supports Boolean, String, and Number.

`typescript
const { flags } = parse(["--bool", "--str", "hello", "--num", "42"], {
flags: {
bool: { type: Boolean },
str: { type: String },
num: { type: Number },
},
});
// flags: { bool: true, str: "hello", num: 42 }
`

$3

Use alias to define short or alternative names for flags.

`typescript
const { flags } = parse(["-b", "-s", "hello"], {
flags: {
bool: { type: Boolean, alias: "b" },
str: { type: String, alias: "s" },
},
});
// flags: { bool: true, str: "hello" }
`

$3

- To collect multiple values for a flag, use an array type like [String].
- To count the occurrences of a boolean flag, use [Boolean].

`typescript
// Array of strings
const { flags: arrayFlags } = parse(["--arr", "a", "--arr", "b"], {
flags: {
arr: { type: [String] },
},
});
// arrayFlags: { arr: ["a", "b"] }

// Counter
const { flags: counterFlags } = parse(["-vvv"], {
flags: {
verbose: { type: [Boolean], alias: "v" },
},
});
// counterFlags: { verbose: 3 }
`

$3

Multiple boolean short flags can be combined. The last flag in the group can take a value.

`typescript
// -abc => a=true, b=true, c=true
const { flags: merged } = parse(["-abc"], {
flags: {
a: Boolean,
b: Boolean,
c: Boolean,
},
});
// merged: { a: true, b: true, c: true }

// -ab val => a=true, b="val"
const { flags: withValue } = parse(["-ab", "val"], {
flags: {
a: Boolean,
b: String,
},
});
// or -abval, b is not boolean
const { flags: withValue } = parse(["-abval"], {
flags: {
a: Boolean,
b: String,
},
});
// withValue: { a: true, b: "val" }
`

$3

Provide a default value for flags that are not present.

`typescript
const { flags } = parse([], {
flags: {
str: { type: String, default: "default" },
num: { type: Number, default: 123 },
fn: { type: String, default: () => "computed" },
},
});
// flags: { str: "default", num: 123, fn: "computed" }
`

By default, booleans, counters, arrays and objects have implicit defaults when default is not provided:

- Boolean: false
- Counter: 0
- Array: []
- Object: {}

$3

Boolean flags are negatable by default using the --no- prefix.

If you want to disable this behavior, set negatable: false in the flag configuration. Passing --no- will then be treated as an unknown flag.

`typescript
const { flags, unknown } = parse(
["--no-cache", "--no-ssl=false", "--no-disable-negate"],
{
flags: {
cache: { type: Boolean, default: true },
ssl: { type: Boolean, default: true },
disableNegate: { type: Boolean, negatable: false, default: true },
},
},
);
// flags: { cache: false, ssl: true, disableNegate: true }
// unknown: { noDisableNegate: true }
`

$3

You can provide a custom function to the type property for advanced parsing logic. The function receives the string value and should return the parsed value.

`typescript
// Let's limit port between 1 and 65535
const { flags } = parse(["--port", "8080"], {
flags: {
port: {
type: (value: string) => {
const parsed = Number.parseInt(value, 10);
if (Number.isNaN(parsed)) {
throw new TypeError("Port must be a number!");
}
if (parsed < 1 || parsed > 65_535) {
throw new Error("Port must be between 1 and 65535!");
}

return parsed;
},
},
},
});
// flags: { port: 8080 }
`

$3

Define flags with Object type to parse dot-notation arguments into a nested object.

`typescript
const { flags } = parse(
["--config.port", "8080", "--config.host", "localhost"],
{
flags: {
config: { type: Object },
},
},
);
// flags: { config: { port: "8080", host: "localhost" } }
`

Multi-level nesting is also supported.

`typescript
const { flags } = parse(
[
"--db.host",
"localhost",
"--db.port",
"5432",
"--db.credentials.user",
"admin",
"--db.credentials.password",
"secret",
],
{
flags: {
db: { type: Object },
},
},
);
// flags: { db: { host: "localhost", port: "5432", credentials: { user: "admin", password: "secret" } } }
`

$3

Flags that are not defined in the schema are collected in the unknown object. If possible, they will be converted to boolean true.

`typescript
const { flags, unknown } = parse([
"--unknown1",
"--unknown2=foo",
"--unknown3",
"bar",
"--unknown.foo",
]);

// unknown: { unknown1: true, unknown2: "foo", unknown3: "bar", "unknown.foo": true }
`

$3

Use the ignore function to stop parsing when a certain condition is met. Subsequent arguments will be added to the ignored array.

`typescript
const { flags, ignored } = parse(["--a", "--b", "stop", "--c"], {
flags: {
a: Boolean,
b: Boolean,
c: Boolean,
},
ignore: (type, arg) => arg === "stop",
});
// flags: { a: true, b: true, c: false }
// ignored: ["stop", "--c"]
`

You can ignore everything after the first positional parameter by checking the type.

`typescript
const { flags, parameters, ignored } = parse(
["--allow-all", "./deno.ts", "--param"],
{
flags: {
allowAll: Boolean,
},
ignore: (type) => type === "parameter",
},
);

// flags: { allowAll: true }
// parameters: []
// ignored: ["./deno.ts", "--param"]
`

$3

Arguments after -- are not parsed as flags and are collected in the doubleDash array.

`typescript
const { flags, doubleDash } = parse(["--foo", "--", "--bar"], {
flags: {
foo: Boolean,
bar: Boolean,
},
});
// flags: { foo: true, bar: false }
// doubleDash: ["--bar"]
`

Benchmark

Benchmarked with vitest.

`
✓ packages/parser/bench/bench.bench.ts > bench 6267ms
name hz min max mean p75 p99 p995 p999 rme samples
· minimist 684,422.77 0.0012 3.5582 0.0015 0.0013 0.0031 0.0040 0.0222 ±1.50% 342212
· mri 2,451,855.02 0.0003 0.2422 0.0004 0.0004 0.0007 0.0009 0.0021 ±0.33% 1225928
· yargs-parser 90,437.66 0.0092 3.1595 0.0111 0.0103 0.0346 0.0602 0.1311 ±1.42% 45219
· nopt 636,086.73 0.0014 0.3214 0.0016 0.0015 0.0027 0.0031 0.0056 ±0.38% 318044
· type-flag 715,908.28 0.0012 0.3783 0.0014 0.0013 0.0022 0.0027 0.0282 ±0.61% 357955
· node:util parseArgs 1,204,359.72 0.0007 0.3827 0.0008 0.0008 0.0016 0.0017 0.0047 ±0.56% 602196
· args-tokens 2,379,934.00 0.0002 0.2923 0.0004 0.0004 0.0010 0.0015 0.0051 ±0.49% 1189967
· @clerc/parser 2,119,030.30 0.0003 0.2482 0.0005 0.0005 0.0009 0.0011 0.0017 ±0.49% 1059516

BENCH Summary

mri - packages/parser/bench/bench.bench.ts > bench
1.03x faster than args-tokens
1.16x faster than @clerc/parser
2.04x faster than node:util parseArgs
3.42x faster than type-flag
3.58x faster than minimist
3.85x faster than nopt
27.11x faster than yargs-parser
``

📝 License

MIT. Made with ❤️ by Ray