aspargvs v0.7.0

April 27, 2026 · View on GitHub

aspargvs v0.7.0

aspargvs v0.7.0

Type Aliases

JsonArray

type JsonArray = JsonValue[];

JsonObject

type JsonObject = object;

Index Signature

[key: string]: JsonValue

JsonPrimitive

type JsonPrimitive = string | number | boolean | null;

JsonValue

type JsonValue = 
  | JsonPrimitive
  | JsonArray
  | JsonObject;

Options

type Options = object;

Options object.

Properties

Property	Type	Description
`allowSpacedValue?`	`boolean`	Allow `--key value` syntax (without `=`).
`handlers?`	`object`	Handlers for various actions.
`handlers.bin?`	() => `string`	Function to return the CLI binary name. Used in the help text. Can query it from package.json for example.
`handlers.help?`	`true` \| ((`help`: `string`) => `string` \| `void`)	Set to `true` to enable built-in `help` command - `aspargvs` will print it's own help text. Provide a function to customize the help output - add app-specific information. `help` argument is the help text generated by `aspargvs`. If function returns a string then it will be sent to console. Otherwise it is considered handled by client code.
`handlers.inspect?`	\| `InspectOptions` \| ((`json`: `JsonObject`) => `string` \| `void`)	Provide InspectOptions object to enable built-in inspect command. `aspargvs` will log to console the output of `util.inspect` applied to the parsed JSON object with the specified options. `{ depth: 4 }` would be a simple practical example. Provide a function to customize the command - to use a custom serializer or to send the output elsewhere. If function returns a string then it will be sent to console. Otherwise it is considered handled by client code.
`handlers.json?`	(`json`: `JsonObject`) => `string` \| `void`	Function to handle the parsed JSON object. This is the main handler, business logic of the client package is supposed to be called from it. If function returns a string then it will be sent to console. Otherwise it is considered handled by client code.
`handlers.key?`	(`key`: `string`) => `string`	Function to convert CLI keys to JSON keys. If you need to convert from kebab-case to camelCase for example.
`handlers.merge?`	(`acc`: `JsonObject`, `next`: `JsonObject`) => `JsonObject`	Function to merge JSON objects that come from `preset` and `json` commands. Bring your own deep merger in case you need these commands.
`handlers.unkey?`	(`key`: `string`) => `string`	Function to convert JSON keys to CLI keys. If you need to convert from camelCase to kebab-case for example.
`handlers.unparse?`	`true` \| ((`args`: `string`[]) => `string` \| `void`)	Set to `true` to enable built-in unparse command - `aspargvs` will convert the parsed JSON object back into a list of argument strings and log it to console. Provide a function to customize the command. `args` array contains argument strings. If function returns a string then it will be sent to console. Otherwise it is considered handled by client code.
`handlers.version?`	() => `string` \| `void`	Specify this function to enable the version command. Can query the version from package.json for example. If function returns a string then it will be sent to console. Otherwise it is considered handled by client code.
`presets?`	`object`	Presets are pre-filled JSON objects. If supplied, this will enable `preset` command. Requires Options.handlers.merge to work.

Functions

handleArgs()

function handleArgs(args: string[], options?: Options): void;

Parse arguments-only array into JSON object, run required actions as defined in options object.

Use handleArgv instead in case you don't need any special pre-processing of process.argv.

Parameters

Parameter	Type	Description
`args`	`string`[]	arguments array (for example `process.argv.slice(2)`).
`options`	`Options`	Options object.

Returns

void

handleArgv()

function handleArgv(options?: Options): void;

Parse process.argv into JSON object, run required actions as defined in options object.

This function automatically slices process.argv to remove paths to node executable and script file. Only actual arguments are parsed.

Use handleArgs instead in case you need to pass custom arguments array.

Parameters

Parameter	Type	Description
`options`	`Options`	Options object.

Returns

void

unparseArgs()

function unparseArgs(json: JsonObject, unkey?: (key: string) => string): string[];

Convert a JSON object into an equivalent array of arguments.

Parameters

Parameter	Type	Description
`json`	`JsonObject`	JSON object to break down into arguments.
`unkey?`	(`key`: `string`) => `string`	A function to transform keys (for example change camel case of JSON keys to kebab case of CLI arguments).

Returns

string[]

An array of argument strings (unescaped, may require escaping specific to a shell).