API reference

This page lists every export of @bomb.sh/router 0.8.0. Signatures leave out generic parameters, because TypeScript infers them from your definitions.

Definitions

command(name, …elements)

Declares a route that supports help and execute. Returns a route. Same as route(name, executable(), ...elements). See Routes and methods.

route(name, …elements)

Declares a route that supports help only. Returns a route. Child routes are passed directly as elements of route() and command().

name(value)

Returns a Definition with the given name. The first argument of command(), route(), option(), toggle(), argument(), and param().

description(text)

Adds a description to a route or parameter. Shown in help output. See Help, version, and errors.

version(semver)

Adds the version method to a route and sets the version string printVersion() prints. Does not apply to child routes.

executable()

Adds the execute method to a route.

Parameters

option(name, …elements)

Declares a named parameter read from --kebab-name <value> or --kebab-name=<value>. See Parameters.

toggle(name, …elements)

Declares a boolean parameter read from --kebab-name and --no-kebab-name. Defaults to false.

argument(name, …elements)

Declares a positional parameter.

schema(standardSchema)

Validates a parameter with a Standard Schema. Sets the parameter’s type, default, and whether it is required.

multiple()

Turns a parameter into a list. An option collects every occurrence. An argument collects every positional value.

cli(names, options?)

Replaces the flags a parameter reads. With { switch: true }, the parameter takes no value and reads true when present.

env(key)

Replaces the environment variable a parameter reads.

Sources

withValues(sources)

Attaches value sources to a route. Values are addressed from that route. See Value and environment sources.

withEnvs(sources)

Attaches environment sources to a route.

Composition

extend(…elements)

Bundles elements, including child routes, into one reusable element:

import { 
function command<const N extends string, const E extends readonly Input[]>(start: Definition<N>, ...elements: E & Validate<CommandZero<N>, E>): Materialize<Fold<CommandZero<N>, Normalize<E>>>
command, 
function extend<const E extends readonly Input[]>(...elements: E): Extension<Normalize<E>>
extend, 
function name<N extends string>(name: N): Definition<N>
name, 
function route<const N extends string, const E extends readonly Input[]>(start: Definition<N>, ...elements: E & Validate<RouteZero<N>, E>): Materialize<Fold<RouteZero<N>, Normalize<E>>>
route } from "@bomb.sh/router";

const 
const prCommands: Extension<readonly [RoutesElement<readonly [Route<"list", "help" | "execute", [Done<{}, []>]>]>, RoutesElement<readonly [Route<"create", "help" | "execute", [Done<{}, []>]>]>]>
prCommands = 
extend<readonly [Route<"list", "help" | "execute", [Done<{}, []>]>, Route<"create", "help" | "execute", [Done<{}, []>]>]>(elements_0: Route<"list", "help" | "execute", [...]>, elements_1: Route<...>): Extension<...>
extend(
  
command<"list", readonly []>(start: Definition<"list">): Route<"list", "help" | "execute", [Done<{}, []>]>
command(
name<"list">(name: "list"): Definition<"list">
name("list")),
  
command<"create", readonly []>(start: Definition<"create">): Route<"create", "help" | "execute", [Done<{}, []>]>
command(
name<"create">(name: "create"): Definition<"create">
name("create")),
);

const 
const app: Route<"gh", "help" | "execute", readonly [Done<{}, readonly [Route<"pr", "help", readonly [Done<{}, readonly [Route<"list", "help" | "execute", [Done<{}, []>]>, Route<"create", "help" | "execute", [...]>]>]>]>]>
app = 
command<"gh", readonly [Route<"pr", "help", readonly [Done<{}, readonly [Route<"list", "help" | "execute", [Done<{}, []>]>, Route<"create", "help" | "execute", [Done<{}, []>]>]>]>]>(start: Definition<...>, elements_0: Route<...>): Route<...>
command(
name<"gh">(name: "gh"): Definition<"gh">
name("gh"), 
route<"pr", readonly [Extension<readonly [RoutesElement<readonly [Route<"list", "help" | "execute", [Done<{}, []>]>]>, RoutesElement<readonly [Route<"create", "help" | "execute", [Done<{}, []>]>]>]>]>(start: Definition<...>, elements_0: Extension<...>): Route<...>
route(
name<"pr">(name: "pr"): Definition<"pr">
name("pr"), 
const prCommands: Extension<readonly [RoutesElement<readonly [Route<"list", "help" | "execute", [Done<{}, []>]>]>, RoutesElement<readonly [Route<"create", "help" | "execute", [Done<{}, []>]>]>]>
prCommands));

transform(schema)

Validates and reshapes a route’s whole model with a schema. The schema’s output becomes the model type:

import {
  
function command<const N extends string, const E extends readonly Input[]>(start: Definition<N>, ...elements: E & Validate<CommandZero<N>, E>): Materialize<Fold<CommandZero<N>, Normalize<E>>>
command,
  
function name<N extends string>(name: N): Definition<N>
name,
  
function option<const N extends string, const E extends readonly Unary[]>(named: Definition<N>, ...elements: E & Check<Zero<N>, E>): ElementOf<...>
option,
  
function schema<S extends Schema>(schema: S): TransformElement<SchemaTransform<OutputOf<S>>>
schema,
  
function transform<Input extends object, Output extends object>(schema: Schema<Input, Output>): ModelElement<SchemaTransform<Input, Output>>
transform,
} from "@bomb.sh/router";
import * as 
import z
z from "zod";

const 
const list: Route<"list", "help" | "execute", readonly [Done<{
    perPage: number;
    limit: number;
}, []>]>
list = 
command<"list", readonly [ModelElement<ParamModel<"limit", number>>, ModelElement<SchemaTransform<{
    limit: number;
}, {
    perPage: number;
    limit: number;
}>>]>(start: Definition<...>, elements_0: ModelElement<ParamModel<"limit", number>>, elements_1: ModelElement<...>): Route<...>
command(
  
name<"list">(name: "list"): Definition<"list">
name("list"),
  
option<"limit", readonly [TransformElement<SchemaTransform<number>>]>(named: Definition<"limit">, elements_0: TransformElement<SchemaTransform<number>>): ModelElement<...>
option(
name<"limit">(name: "limit"): Definition<"limit">
name("limit"), 
schema<z.ZodDefault<z.ZodNumber>>(schema: z.ZodDefault<z.ZodNumber>): TransformElement<SchemaTransform<number>>
schema(
import z
z.
function number(params?: z.RawCreateParams & {
    coerce?: boolean;
}): z.ZodNumber
export number
number().
ZodType<number, ZodNumberDef, number>.default(def: number): z.ZodDefault<z.ZodNumber> (+1 overload)
default(30))),
  
transform<{
    limit: number;
}, {
    perPage: number;
    limit: number;
}>(schema: Schema<{
    limit: number;
}, {
    perPage: number;
    limit: number;
}>): ModelElement<SchemaTransform<{
    limit: number;
}, {
    perPage: number;
    limit: number;
}>>
transform(
    
import z
z
      .
object<{
    limit: z.ZodNumber;
}>(shape: {
    limit: z.ZodNumber;
}, params?: z.RawCreateParams): z.ZodObject<{
    limit: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    limit: number;
}, {
    ...;
}>
export object
object({ 
limit: z.ZodNumber
limit: 
import z
z.
function number(params?: z.RawCreateParams & {
    coerce?: boolean;
}): z.ZodNumber
export number
number() })
      .
ZodType<{ limit: number; }, ZodObjectDef<{ limit: ZodNumber; }, "strip", ZodTypeAny>, { limit: number; }>.transform<{
    perPage: number;
    limit: number;
}>(transform: (arg: {
    limit: number;
}, ctx: z.RefinementCtx) => {
    perPage: number;
    limit: number;
} | Promise<{
    perPage: number;
    limit: number;
}>): z.ZodEffects<...>
transform((
m: {
    limit: number;
}
m) => ({ ...
m: {
    limit: number;
}
m, 
perPage: number
perPage: 
var Math: Math
An intrinsic object that provides basic mathematics functionality and constants.
Math.
Math.min(...values: number[]): number
Returns the smaller of a set of supplied numeric expressions.
@param ― values Numeric expressions to be evaluated.
min(
m: {
    limit: number;
}
m.
limit: number
limit, 100) })),
  ),
);

checkpoint()

Pauses parsing so the application can load configuration before parsing continues. parse() returns a step whose resume() takes the list of value sources to load. See Checkpoints and dynamic phases.

dynamic(schema, extension)

Pauses parsing until the application supplies a value. resume() takes that value, schema validates it, and extension receives the validated value and returns the elements to add, such as options or child routes. An invalid value fails with unprocessable-content. See Checkpoints and dynamic phases.

Running

parse(app, input)

Matches input.argv, plus optional input.values and input.envs, against the route tree. Returns an intent or a failure. Never prints, exits, or performs I/O.

printHelp(intent)

Returns the help text for a help intent.

printVersion(intent)

Returns the version text for a version intent.

printErrors(failure)

Returns the error text for a method-not-allowed or unprocessable-content failure. An unprocessable-content failure prints one line per issue.

Low-level functions

These build custom parameter kinds and elements. Applications do not need them.

Export	Description
`param(name, ...elements)`	Returns a bare parameter object, the base that `option()`, `toggle()`, and `argument()` build on.
`mark(element)`	Brands a function as a custom transform element.

Types

Results

Type	Description
`Outcome<T>`	`T`, or a `MethodNotAllowed` or `UnprocessableContent` failure.
`AnyIntent`	Any help, version, or execute intent.
`Intent<M, P>`	A successful match: `ok`, `method`, `route`, `definition`, `path`, and the `literals` that came after `--`.
`Help<P>`	A help intent for route `P`.
`Version<P>`	A version intent for route `P`.
`Execute<P, Models>`	An execute intent with `model`, `models`, and `issues`.
`MethodNotAllowed`	A failure with the requested `method` and the `allowed` methods.
`UnprocessableContent`	A failure with a list of `issues`.
`Issue`	A Standard Schema issue: a `message` and an optional `path`.
`Method`	`"help"`, `"version"`, or `"execute"`.
`Result<T>`	`{ ok: true, value }` or `{ ok: false, issues }`.

Inference helpers

Type	Description
`ModelOf<R, P>`	The model of route `P` in route tree `R`. `P` defaults to `"/"`.
`IntentsOf<R>`	Every intent route tree `R` can produce.
`MethodsOf<R>`	The methods route `R` supports.
`ModelsByRoute`	Models keyed by route path.
`RoutePath`	A route path such as `"/pr/list"`.
`PathOf<P>`	A route path split into segments. `"/pr/list"` becomes `["pr", "list"]`.
`Path`	A list of route segments.

For example, ModelOf gives you a route’s model type without calling parse():

import {
  
function command<const N extends string, const E extends readonly Input[]>(start: Definition<N>, ...elements: E & Validate<CommandZero<N>, E>): Materialize<Fold<CommandZero<N>, Normalize<E>>>
command,
  
function name<N extends string>(name: N): Definition<N>
name,
  
function option<const N extends string, const E extends readonly Unary[]>(named: Definition<N>, ...elements: E & Check<Zero<N>, E>): ElementOf<...>
option,
  
function route<const N extends string, const E extends readonly Input[]>(start: Definition<N>, ...elements: E & Validate<RouteZero<N>, E>): Materialize<Fold<RouteZero<N>, Normalize<E>>>
route,
  
function schema<S extends Schema>(schema: S): TransformElement<SchemaTransform<OutputOf<S>>>
schema,
  type 
type ModelOf<R extends AnyRoute, P extends RoutePath = "/"> = ModelsIn<RouteAt<R, P>["phases"]> extends infer Model extends object ? { [K in keyof Model]: Model[K]; } : never
ModelOf,
} from "@bomb.sh/router";
import * as 
import z
z from "zod";

const 
const app: Route<"gh", "help" | "execute", readonly [Done<{}, readonly [Route<"pr", "help", readonly [Done<{}, readonly [Route<"list", "help" | "execute", readonly [Done<{
    limit: number;
}, []>]>]>]>]>]>
app = 
command<"gh", readonly [Route<"pr", "help", readonly [Done<{}, readonly [Route<"list", "help" | "execute", readonly [Done<{
    limit: number;
}, []>]>]>]>]>(start: Definition<"gh">, elements_0: Route<...>): Route<...>
command(
  
name<"gh">(name: "gh"): Definition<"gh">
name("gh"),
  
route<"pr", readonly [Route<"list", "help" | "execute", readonly [Done<{
    limit: number;
}, []>]>]>(start: Definition<"pr">, elements_0: Route<"list", "help" | "execute", readonly [Done<{
    limit: number;
}, []>]>): Route<...>
route(
    
name<"pr">(name: "pr"): Definition<"pr">
name("pr"),
    
command<"list", readonly [ModelElement<ParamModel<"limit", number>>]>(start: Definition<"list">, elements_0: ModelElement<ParamModel<"limit", number>>): Route<...>
command(
      
name<"list">(name: "list"): Definition<"list">
name("list"),
      
option<"limit", readonly [TransformElement<SchemaTransform<number>>]>(named: Definition<"limit">, elements_0: TransformElement<SchemaTransform<number>>): ModelElement<...>
option(
name<"limit">(name: "limit"): Definition<"limit">
name("limit"), 
schema<z.ZodDefault<z.ZodNumber>>(schema: z.ZodDefault<z.ZodNumber>): TransformElement<SchemaTransform<number>>
schema(
import z
z.
function number(params?: z.RawCreateParams & {
    coerce?: boolean;
}): z.ZodNumber
export number
number().
ZodType<number, ZodNumberDef, number>.default(def: number): z.ZodDefault<z.ZodNumber> (+1 overload)
default(30))),
    ),
  ),
);

type 
type ListModel = {
    limit: number;
}
ListModel = 
type ModelOf<R extends AnyRoute, P extends RoutePath = "/"> = ModelsIn<RouteAt<R, P>["phases"]> extends infer Model extends object ? { [K in keyof Model]: Model[K]; } : never
ModelOf<typeof 
const app: Route<"gh", "help" | "execute", readonly [Done<{}, readonly [Route<"pr", "help", readonly [Done<{}, readonly [Route<"list", "help" | "execute", readonly [Done<{
    limit: number;
}, []>]>]>]>]>]>
app, "/pr/list">; // { limit: number }

Inputs

Type	Description
`Input`	The second argument of `parse()`: `argv`, plus optional `values` and `envs`.
`ValueSource`	A named value source: `{ name, value }`.
`EnvSource`	A named environment source: `{ name, value }`.
`Environment`	A record of environment variable names to string values.
`Schema`	A Standard Schema.

Definitions

Type	Description
`Definition<N>`	A name and an optional description.
`Route<N, M, P>`	A route named `N` that supports methods `M`.
`AnyRoute`	Any route.
`CommandZero`	The type of a `command()` before any elements are applied.
`RouteZero`	The type of a `route()` before any elements are applied.
`Param<K, T, C>`	A parameter named `K` with value type `T`.
`Literal`	A token that came after `--`, with its `text` and its `index` in `argv`. An intent’s `literals` lists them in order.

Low-level types

These describe the parser’s internals. Applications do not need them.

Type	Description
`CLIOptions`	The options of `cli()`.
`CLIRead`	The result of reading one parameter from the command line.
`ReadCLI`	A function that reads one parameter from the command line.
`CLISymbol`	A command-line token: a flag, a setter, or a word.
`Rest`	The input left after a parse phase.
`Transform`	The input and output types of a custom transform.
`TransformElement<F>`	An element created with `mark()`.