@bomb.sh/router 0.0.1 → 0.7.0

package/README.md

@@ -0,0 +1,293 @@
+# @bomb.sh/router
+
+**A statically typed entry-point router for command-line applications.**
+
+An argument parser tells you what the user typed. `@bomb.sh/router` tells you
+where and how they intend to enter your program. For execution, it binds a
+validated, statically typed model for that entry point.
+
+`@bomb.sh/router` matches input to an intent: a method at an
+application-relative route, such as:
+
+```text
+HELP    /
+VERSION /
+EXECUTE /serve
+HELP    /database/clean
+EXECUTE /database/clean
+```
+
+Every reachable intent appears in the result type. Narrow `method` and `route`,
+and TypeScript knows the exact model available at that entry point.
+
+`@bomb.sh/router` is not a CLI framework. It does not own handlers, effects,
+output, or process lifetime. It is not a CLI parser whose product is a bag of
+flags. Its product is a typed intent; your application decides what that intent
+does.
+
+## Define every way into the program
+
+`route()` declares an address, and every `command()` is just an address that
+declares an intent to execute. Every route supports help, whereas version and
+execution exist only where they are explicitly added.
+
+Definitions are immutable composition pipelines, not handler registrations:
+
+```ts
+import {
+  command,
+  description,
+  name,
+  option,
+  route,
+  routes,
+  schema,
+  toggle,
+  version,
+} from "@bomb.sh/router";
+import * as z from "zod";
+
+export const app = command(
+  name("simulacrum"),
+  description("Run and manage local service simulators."),
+  version("1.0.0"),
+  toggle(name("verbose")),
+  routes(
+    command(
+      name("serve"),
+      option(name("port"), schema(z.number().default(4000))),
+    ),
+    route(
+      name("database"),
+      routes(
+        command(
+          name("clean"),
+          toggle(name("dryRun")),
+        ),
+      ),
+    ),
+  ),
+);
+```
+
+That definition makes these entry points—and no others—reachable:
+
+```text
+HELP /                  VERSION /              EXECUTE /
+HELP /serve                                    EXECUTE /serve
+HELP /database
+HELP /database/clean                           EXECUTE /database/clean
+```
+
+The root name identifies the executable; it is not repeated in route IDs.
+`simulacrum serve` therefore selects `/serve`, not `/simulacrum/serve`.
+
+## Route an intent
+
+`parse()` returns a discriminated union of the reachable entry points. Dispatch
+can stay flat even when the route tree is deep:
+
+```ts
+import process from "node:process";
+import { parse, printErrors, printHelp, printVersion } from "@bomb.sh/router";
+import { app } from "./app.ts";
+
+const result = parse(app, { argv: process.argv.slice(2) });
+
+if (!result.ok) {
+  console.error(printErrors(result));
+  process.exit(1);
+}
+
+switch (result.method) {
+  case "help":
+    console.log(printHelp(result));
+    break;
+
+  case "version":
+    console.log(printVersion(result));
+    break;
+
+  case "execute":
+    switch (result.route) {
+      case "/":
+        result.model.verbose; // boolean
+        break;
+
+      case "/serve":
+        result.model.port; // number
+        result.models["/"].verbose; // boolean
+        break;
+
+      case "/database/clean":
+        result.model.dryRun; // boolean
+        result.models["/"]; // { verbose: boolean }
+        result.models["/database"]; // {}
+        break;
+    }
+}
+```
+
+An execute intent has two views of configuration:
+
+- `model` is owned by the selected route.
+- `models` contains the statically typed model for every route along the
+  selected path. Sibling routes are absent from both the value and its type.
+
+| Invocation                            | Intent and model                                                    |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| `simulacrum --verbose`                | `EXECUTE /` with `{ verbose: true }`                                |
+| `simulacrum serve --port 4100`        | `EXECUTE /serve` with `{ port: 4100 }`                              |
+| `simulacrum database clean --dry-run` | `EXECUTE /database/clean` with `{ dryRun: true }`                   |
+| `simulacrum --help database clean`    | `HELP /database/clean`; controls target the deepest selected route  |
+| `simulacrum database`                 | `method-not-allowed`; `/database` does not support execution        |
+| `simulacrum serve --port nope`        | `unprocessable-content`; invalid data never reaches the application |
+
+Command literals are routing tokens, not positional arguments. As route segments
+become discoverable, `@bomb.sh/router` scopes parameter binding to the segment
+that owns each token. This makes identical option names on parent and child
+routes unambiguous.
+
+## Bind route parameters from multiple sources
+
+CLI arguments are only one source. `@bomb.sh/router` can bind JavaScript values
+and flat environment records onto the same route-local models:
+
+```ts
+const result = parse(app, {
+  argv: process.argv.slice(2),
+  values: [{
+    name: "config.json",
+    value: { serve: { port: 4200 } },
+  }],
+  envs: [{
+    name: "process",
+    value: process.env,
+  }],
+});
+```
+
+For `/serve`, `serve.port` and `SERVE_PORT` both address its `port` parameter.
+CLI text and environment text are decoded; JavaScript values are used directly.
+The resulting value is then validated by its
+[Standard Schema](https://standardschema.dev/) schema. Zod, ArkType, Valibot,
+and other conforming libraries work without adapters.
+
+Source precedence is explicit:
+
+```text
+CLI → environment → JavaScript values → schema default
+```
+
+## Pause without surrendering the type system
+
+Sometimes the route cannot be fully configured, or even fully discovered, until
+the application performs I/O. `@bomb.sh/router` can pause at a typed checkpoint
+and resume with the result.
+
+Dynamic phases serve two common cases:
+
+- Load a configuration file, then use its contents as value sources for later
+  parameters.
+- Load plugins, then extend the route graph with their options and routes.
+
+`checkpoint()` is the configuration-file convenience; `dynamic()` is the general
+route-extension mechanism. Both keep I/O in the application while preserving the
+exact type of what parsing can produce next.
+
+### Help and version cross checkpoints
+
+`--help` and `--version` request methods; they do not settle an intent or bypass
+parsing. `@bomb.sh/router` cannot produce either intent until it knows the
+deepest selected route. A dynamic phase may introduce that route, its options,
+or its version.
+
+The driver must therefore resume every increment until parsing returns an
+intent—even when the arguments contain `--help` or `--version`. This applies
+recursively when one continuation exposes another increment.
+
+```text
+app --config app.json auth0 --help
+  → bind the configuration phase
+  → load configuration and resume
+  → discover /auth0
+  → HELP /auth0
+```
+
+Help and version are not escape hatches around configuration loading. Do not
+inspect `argv` to skip a checkpoint. A phase may be required by `HELP`,
+`VERSION`, or `EXECUTE`, so its driver work must be safe for all three: return
+loading and validation failures as `Result` issues, avoid command side effects,
+and defer execution until an `EXECUTE` intent. If discovery fails, report that
+failure rather than printing incomplete help for an unresolved route graph.
+Routes without dynamic phases still resolve directly; the rule is to stop only
+at an intent or failure, never merely because the arguments look informational.
+
+```ts
+import process from "node:process";
+import {
+  checkpoint,
+  command,
+  name,
+  option,
+  parse,
+  printErrors,
+  printHelp,
+  printVersion,
+  type Result,
+  schema,
+  type ValueSource,
+  version,
+} from "@bomb.sh/router";
+import * as z from "zod";
+
+const app = command(
+  name("server"),
+  version("1.0.0"),
+  option(name("config"), schema(z.string())),
+  checkpoint(),
+  option(name("port"), schema(z.number())),
+);
+
+const step = parse(app, { argv: process.argv.slice(2) });
+
+if (!step.ok) {
+  console.error(printErrors(step));
+  process.exit(1);
+}
+
+step.model.config; // string—the model resolved before the checkpoint
+
+const loaded = await load(step.model.config);
+const result = step.resume(loaded);
+
+if (!result.ok) {
+  console.error(printErrors(result));
+  process.exit(1);
+}
+
+switch (result.method) {
+  case "help":
+    console.log(printHelp(result));
+    break;
+
+  case "version":
+    console.log(printVersion(result));
+    break;
+
+  case "execute":
+    result.model; // { config: string; port: number }
+    break;
+}
+
+declare function load(path: string): Promise<Result<ValueSource[]>>;
+```
+
+The parser remains synchronous and performs no I/O. The caller loads the file
+and resumes with a `Result`; loader failures enter the ordinary issue path.
+Unconsumed CLI input survives the pause, so a later `--port 5000` can override
+the value loaded from the file.
+
+The same phase mechanism can add options or routes from runtime data. Parsing
+then continues against the expanded route graph, and the continuation type
+describes the entry points that can appear next.

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,11 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};

package/esm/_dnt.polyfills.js

@@ -0,0 +1,15 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+export {};

package/esm/lib/argument.d.ts

@@ -0,0 +1,7 @@
+import { type Param, type ParamModel } from "./param.js";
+import { type Check, type Fold, type ModelElement, type Unary } from "./pipeline.js";
+import type { Definition } from "./types.js";
+export declare function argument<const N extends string, const E extends readonly Unary[]>(named: Definition<N>, ...elements: E & Check<Zero<N>, E>): ElementOf<N, Fold<Zero<N>, E>>;
+type Zero<N extends string> = Param<N, unknown, "one">;
+type ElementOf<N extends string, P> = P extends Param<N, infer Model, infer _Cardinality> ? ModelElement<ParamModel<N, Model>> : never;
+export {};

package/esm/lib/argument.js

@@ -0,0 +1,66 @@
+import { param } from "./param.js";
+import { brand, } from "./pipeline.js";
+export function argument(named, ...elements) {
+    const added = elements.reduce((value, element) => element(value), param(named, positional));
+    return brand((route) => {
+        let phases = [...route.phases];
+        let phase = phases.pop();
+        phases.push({
+            ...phase,
+            model: {
+                params: {
+                    ...phase.model.params,
+                    [added.name]: added,
+                },
+                steps: phase.model.steps.concat((current, bindings) => ({
+                    ok: true,
+                    value: {
+                        ...current,
+                        [added.name]: bindings[added.name],
+                    },
+                })),
+            },
+        });
+        return {
+            ...route,
+            phases,
+        };
+    });
+}
+function positional(param) {
+    return {
+        ...param,
+        cli: {
+            read,
+            syntax: {
+                type: "argument",
+                label: `<${param.name.toUpperCase()}>`,
+            },
+        },
+    };
+}
+const read = (tokens) => {
+    let claim = tokens.claimOne((token) => token.type === "word");
+    let [word] = claim.tokens;
+    return word
+        ? {
+            claim,
+            result: {
+                ok: true,
+                value: { exists: true, value: word.text },
+                issues: [],
+            },
+        }
+        : nothing(tokens);
+};
+function nothing(tokens) {
+    let claim = tokens.claimAll(() => false);
+    return {
+        claim,
+        result: {
+            ok: true,
+            value: { exists: false },
+            issues: [],
+        },
+    };
+}

package/esm/lib/bind.d.ts

@@ -0,0 +1,41 @@
+import { type Maybe } from "./maybe.js";
+import type { AnyParam, Param } from "./param.js";
+import type { Symbol } from "./read.js";
+import type { Rest } from "./rest.js";
+import type { Result } from "./result.js";
+import type { TokenInput, TokenRange } from "./tokenizer.js";
+import type { AnyPhase, Issue, OutputOf, Path } from "./types.js";
+export interface Binding<T> {
+    readonly rest: Rest;
+    readonly result: Result<T>;
+}
+export interface PhaseBinding {
+    readonly rest: Rest;
+    readonly model: Record<string, unknown>;
+    readonly issues: Issue[];
+    readonly valid: boolean;
+}
+export interface PhaseSegment {
+    readonly range: TokenRange;
+    readonly path: Path;
+}
+export declare function fromCLI<P extends Param<string, unknown, "one">>(options: {
+    readonly param: P;
+    readonly view: TokenInput<Symbol>;
+    readonly rest: Rest;
+}): Maybe<Binding<OutputOf<P["schema"]>>>;
+export declare function fromValues<P extends AnyParam>(options: {
+    readonly param: P;
+    readonly route: Path;
+    readonly rest: Rest;
+}): Maybe<Binding<OutputOf<P["schema"]>>>;
+export declare function fromEnv<P extends AnyParam>(options: {
+    readonly param: P;
+    readonly route: Path;
+    readonly rest: Rest;
+}): Maybe<Binding<OutputOf<P["schema"]>>>;
+export declare function bindPhase(options: {
+    readonly phase: AnyPhase;
+    readonly segment: PhaseSegment;
+    readonly rest: Rest;
+}): PhaseBinding;