args-json
Version:
Zero-dependency descriptively typed command-line argument parser
204 lines (140 loc) • 5.81 kB
Markdown
# args-json
Zero-dependency descriptively typed command-line argument parser
Contents: [parseArgs](#parseargs) · [Args](#args) · [isOn / isOff / isExplicitlyOff](#ison--isoff--isexplicitlyoff)
## parseArgs
### String input
```js
import { parseArgs } from "args-json";
const args = parseArgs(
"--config=./config.json -v 1.0.0 -d \"lorem ipsum\" -i -n=0 --test-value abc --debug",
{
v: "version",
d: "description",
}
);
// args = {
// config: "./config.json",
// version: "1.0.0",
// description: "lorem ipsum",
// i: true,
// n: 0,
// testValue: "abc",
// debug: true,
// };
```
Note that keys and values can be separated from each other either with a space or an equals sign, and the value can be either quoted or not. These variants are equivalent. Also, keys are converted to *camelCase* (like `--test-value` → `testValue` in the example above).
The second parameter is optional. It is a way to rename argument keys in the output. In the example above, `-d` and `-v` in the input string are renamed to `description` and `version` in the output object.
Other examples:
```js
const args = parseArgs("--config ./configs/default.json --debug");
// { config: "./configs/default.json", debug: true }
if (args.debug) console.log(args.config);
```
The first line is also equivalent to:
```js
const args = parseArgs("--config \"./configs/default.json\" --debug");
```
or
```js
const args = parseArgs("--config=./configs/default.json --debug");
```
or
```js
const args = parseArgs("--config=\"./configs/default.json\" --debug");
```
### String array input
```js
const args = parseArgs(["--config", "./configs/default.json", "--debug"]);
// { config: "./configs/default.json", debug: true }
if (args.debug) console.log(args.config);
```
### Node process arguments
In a Node environment, `parseArgs()` without parameters parses the node process arguments.
```js
const args = parseArgs();
```
is equivalent to
```js
const args = parseArgs(process.argv);
```
If the `process` object is unavailable in the current environment, `parseArgs()` is equivalent to `parseArgs([])`.
### Key mapping
```js
const args = parseArgs("-c ./configs/default.json --debug", { c: "config" });
// { config: "./configs/default.json", debug: true }
if (args.debug) console.log(args.config);
```
As specified with the second parameter of `parseArgs()`, `-c` is mapped to `config` in the output.
### Value parsing
Values are `JSON.parse`d if they are parsable.
```js
const args = parseArgs("-d \"{\"x\":10}\" -i 0 -n=3 -c ./config.json");
// { d: { x: 10 }, i: 0, n: 3, c: "./config.json" }
```
### Unkeyed values
Values that aren't preceded by a dashed key (like `-x` or `--xxx`) are collected in an array under an empty key entry.
```js
const args = parseArgs("unkeyed args --debug -x 0 -y 1");
// { "": ["unkeyed", "args"], debug: true, x: 0, y: 1 }
```
### Descriptive typing
The output type can be descriptively specified, without validation, by providing a generic type to `parseArgs<T>()`.
```ts
type CustomShape = {
level?: number;
debug?: boolean;
};
const args = parseArgs<CustomShape>("--level=0 --debug");
if (args.debug) console.log(`Level: ${args.level}`);
```
## Args
Use an `Args` class instance to facilitate access to named command line arguments:
```js
import { Args } from "args-json";
const args = new Args(["--key", "value", "--paths", "./x", "./y"]);
args.hasKey("--key") // true
args.hasKey("--arg") // false
args.getValue("--key") // "value"
args.getValues("--paths") // ["./x", "./y"]
```
Without an argument array, `new Args()` is equivalent to `new Args(process.argv)` (or `new Args([])` if the `process` object is unavailable in the current environment). An `Args` object initialized without arguments can also be directly imported with `import { args } from "args-json";`.
## isOn / isOff / isExplicitlyOff
Use `isOn(x)` and `isOff(x)` to check whether a parameter value is `true`, `1`, `"on"` or `false`, `0`, `"off"`, `null`, `undefined`.
```js
import { parseArgs, isOn, isOff } from "args-json";
// isOn
isOn(parseArgs("--debug").debug) // true
isOn(parseArgs("--debug=1").debug) // true
isOn(parseArgs("--debug=on").debug) // true
isOn(parseArgs("").debug) // false
isOn(parseArgs("--debug=0").debug) // false
isOn(parseArgs("--debug=off").debug) // false
new Args(["--debug"]).isOn("--debug") // true
new Args(["--debug", "1"]).isOn("--debug") // true
new Args(["--debug", "on"]).isOn("--debug") // true
// isOff
isOff(parseArgs("").debug) // true
isOff(parseArgs("--debug=0").debug) // true
isOff(parseArgs("--debug=off").debug) // true
new Args([""]).isOff("--debug") // true
new Args(["--debug", "0"]).isOff("--debug") // true
new Args(["--debug", "off"]).isOff("--debug") // true
```
Note the difference between `isOff(x)` and `isExplicitlyOff(x)`: `isExplicitlyOff(x)` results in `true` if `x` is present and it's explicitly a turn-off value, while `isOff(x)` returns `true` if `x` is omitted, too.
```js
import { parseArgs, isOff, isExplicitlyOff } from "args-json";
isOff(parseArgs("--debug=off").debug) // true
isOff(parseArgs("--debug=0").debug) // true
isOff(parseArgs("").debug) // true
isExplicitlyOff(parseArgs("--debug=off").debug) // true
isExplicitlyOff(parseArgs("--debug=0").debug) // true
isExplicitlyOff(parseArgs("").debug) // false
```
Use the utility types `On` and `Off` (or `ExplicitlyOff`) to define a switch parameter type:
```ts
import { parseArgs, type On, type Off } from "args-json";
type Params = {
debug?: On | Off;
};
const args = parseArgs<Params>("--debug=on");
```