@bomb.sh/router 0.7.0 → 0.8.0

package/README.md

@@ -40,7 +40,6 @@ import {
   name,
   option,
   route,
-  routes,
   schema,
   toggle,
   version,
@@ -52,19 +51,15 @@ export const app = command(
   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"),
     command(
-      name("serve"),
-      option(name("port"), schema(z.number().default(4000))),
-    ),
-    route(
-      name("database"),
-      routes(
-        command(
-          name("clean"),
-          toggle(name("dryRun")),
-        ),
-      ),
+      name("clean"),
+      toggle(name("dryRun")),
     ),
   ),
 );
@@ -79,6 +74,10 @@ HELP /database
 HELP /database/clean                           EXECUTE /database/clean
 ```
 
+Nest `route()` and `command()` directly inside another route, command, or
+`extend()`. Each child is mounted at that point in the pipeline. Use `extend()`
+to package reusable groups of children and other elements.
+
 The root name identifies the executable; it is not repeated in route IDs.
 `simulacrum serve` therefore selects `/serve`, not `/simulacrum/serve`.
 
@@ -195,6 +194,32 @@ Dynamic phases serve two common cases:
 route-extension mechanism. Both keep I/O in the application while preserving the
 exact type of what parsing can produce next.
 
+`dynamic(schema, extension)` requires a Standard Schema for the value supplied
+to `resume()`. The schema's input type determines what `resume()` accepts; its
+validated output is passed to the extension, including any schema transforms.
+
+```ts
+import { command, dynamic, extend, name, parse } from "@bomb.sh/router";
+import * as z from "zod";
+
+const app = command(
+  name("plugins"),
+  dynamic(
+    z.array(z.string()),
+    (plugins) => extend(...plugins.map((plugin) => command(name(plugin)))),
+  ),
+);
+
+const step = parse(app, { argv: ["serve"] });
+if (step.ok) {
+  const result = step.resume(["serve"]); // EXECUTE /serve
+}
+```
+
+Invalid input produces `unprocessable-content` with the schema's issues and
+paths, without applying the extension. Validation must be synchronous; async
+schemas also produce `unprocessable-content`.
+
 ### Help and version cross checkpoints
 
 `--help` and `--version` request methods; they do not settle an intent or bypass
@@ -216,12 +241,12 @@ app --config app.json auth0 --help
 
 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.
+`VERSION`, or `EXECUTE`, so its driver work must be safe for all three: handle
+loading failures in the application, 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";
@@ -234,7 +259,6 @@ import {
   printErrors,
   printHelp,
   printVersion,
-  type Result,
   schema,
   type ValueSource,
   version,
@@ -280,13 +304,15 @@ switch (result.method) {
     break;
 }
 
-declare function load(path: string): Promise<Result<ValueSource[]>>;
+declare function load(path: string): Promise<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.
+and resumes directly with a value-source array. `checkpoint()` validates the
+source names and the presence of their values; later parameter schemas validate
+the contents. The application handles I/O failures before resuming. 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

package/esm/lib/checkpoint.js

@@ -1,5 +1,30 @@
 import { dynamic } from "./dynamic.js";
 import { withValues } from "./values.js";
 export function checkpoint() {
-    return dynamic((values) => withValues(values));
+    return dynamic(sources, (values) => withValues(values));
 }
+const sources = {
+    "~standard": {
+        version: 1,
+        vendor: "@bomb.sh/router",
+        validate(value) {
+            if (!Array.isArray(value)) {
+                return { issues: [{ message: "expected an array of value sources" }] };
+            }
+            let issues = [];
+            for (let [index, source] of value.entries()) {
+                if (source === null || typeof source !== "object") {
+                    issues.push({ message: "expected a value source", path: [index] });
+                    continue;
+                }
+                if (typeof source.name !== "string") {
+                    issues.push({ message: "expected a string", path: [index, "name"] });
+                }
+                if (!("value" in source)) {
+                    issues.push({ message: "expected a value", path: [index, "value"] });
+                }
+            }
+            return issues.length > 0 ? { issues } : { value: value };
+        },
+    },
+};

package/esm/lib/command.d.ts

@@ -1,6 +1,7 @@
-import type { Check, Fold, Materialize, Unary } from "./pipeline.js";
+import type { Fold, Materialize } from "./pipeline.js";
+import { type Input, type Normalize, type Validate } from "./route.js";
 import type { Definition, Done, Route } from "./types.js";
 export type CommandZero<N extends string = string> = Route<N, "help" | "execute", [
     Done<{}, []>
 ]>;
-export declare function command<const N extends string, const E extends readonly Unary[]>(start: Definition<N>, ...elements: E & Check<CommandZero<N>, E>): Materialize<Fold<CommandZero<N>, E>>;
+export declare 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>>>;

package/esm/lib/command.js

@@ -1,3 +1,4 @@
+import { normalize, } from "./route.js";
 export function command(start, ...elements) {
     let zero = {
         ...start,
@@ -12,5 +13,5 @@ export function command(start, ...elements) {
                 envs: [],
             }],
     };
-    return elements.reduce((value, element) => element(value), zero);
+    return normalize(elements).reduce((value, element) => element(value), zero);
 }

package/esm/lib/dynamic.d.ts

@@ -1,6 +1,6 @@
-import type { AnyRoute } from "./types.js";
-import { type AnyElement, type DynamicElement } from "./pipeline.js";
+import type { AnyRoute, Schema } from "./types.js";
+import { type AnyElement, type DynamicElement, type Element } from "./pipeline.js";
 export type { ConjoinPhases, Seed } from "./pipeline.js";
 export type PhaseOf<R extends AnyRoute> = R["phases"][0];
 export type PhasesOf<R extends AnyRoute> = R["phases"];
-export declare function dynamic<Requirement, E>(extension: (requires: Requirement) => E, ..._valid: E extends AnyElement ? [] : [never]): DynamicElement<Requirement, Extract<E, AnyElement>>;
+export declare function dynamic<Input, Output, E extends Element>(schema: Schema<Input, Output>, extension: (requires: Output) => E): DynamicElement<Input, Extract<E, AnyElement>>;

package/esm/lib/dynamic.js

@@ -1,11 +1,28 @@
-import { brand } from "./pipeline.js";
-export function dynamic(extension, ..._valid) {
+import { brand, } from "./pipeline.js";
+// Constrain only the brand while inferring E. The full operation would
+// contextually widen extend() tuples and erase their continuation types.
+export function dynamic(schema, extension) {
     return brand((route) => {
         let phases = [...route.phases];
         let phase = phases.pop();
         phases.push({
             ...phase,
-            resolver: extension,
+            resolver(requirement) {
+                let result = schema["~standard"].validate(requirement);
+                if (result instanceof Promise) {
+                    return {
+                        ok: false,
+                        issues: [{ message: "async schemas are not allowed" }],
+                    };
+                }
+                if (result.issues) {
+                    return { ok: false, issues: result.issues };
+                }
+                return {
+                    ok: true,
+                    value: extension(result.value),
+                };
+            },
         });
         phases.push({
             model: {

package/esm/lib/extend.d.ts

@@ -1,2 +1,3 @@
-import { type Extension, type Unary } from "./pipeline.js";
-export declare function extend<const E extends readonly Unary[]>(...elements: E): Extension<E>;
+import { type Input, type Normalize } from "./route.js";
+import { type Extension } from "./pipeline.js";
+export declare function extend<const E extends readonly Input[]>(...elements: E): Extension<Normalize<E>>;

package/esm/lib/extend.js

@@ -1,4 +1,6 @@
+import { normalize } from "./route.js";
 import { brand } from "./pipeline.js";
 export function extend(...elements) {
-    return brand((start) => elements.reduce((value, element) => element(value), start));
+    let normalized = normalize(elements);
+    return brand((start) => normalized.reduce((value, element) => element(value), start));
 }

package/esm/lib/parse.js

@@ -118,16 +118,17 @@ function advance(state) {
                 ok: true,
                 route: segment.id,
                 model: binding.model,
-                resume(result) {
-                    if (!result.ok) {
-                        return unprocessableContent(segment, result.issues);
-                    }
+                resume(value) {
                     // AnyPhase erases these exact types with `never`; dynamic() already
                     // proved them at its public boundary.
                     let resolver = phase.resolver;
+                    let result = resolver(value);
+                    if (!result.ok) {
+                        return unprocessableContent(segment, result.issues);
+                    }
                     // The extension operates against the same aggregate route metadata,
                     // but begins with one fresh, empty phase.
-                    let continuation = resolver(result.value)(seed(segment.route));
+                    let continuation = result.value(seed(segment.route));
                     let phases = stitch(continuation.phases, segment.phases.slice(1));
                     let history = [...segment.history, phase];
                     let next = {

package/esm/lib/pipeline.d.ts

@@ -1,5 +1,5 @@
 import type { AddRoutesToLast, AnyPhase, AnyPhases, AnyRoute, Done, Method, MethodsOf, Next, Phase, Route } from "./types.js";
-export type Element<D extends Delta> = {
+export type Element<D = unknown> = {
     readonly [operation]: D;
 };
 export type AnyElement = Element<Delta>;

package/esm/lib/route.d.ts

@@ -1,9 +1,22 @@
-import { type Check, type Fold, type Materialize, type MethodElement, type RoutesElement, type Unary } from "./pipeline.js";
+import { type Fold, type Materialize, type MethodElement, type RoutesElement, type Unary } from "./pipeline.js";
 import type { AnyRoute, Definition, Done, Route } from "./types.js";
 export type RouteZero<N extends string = string> = Route<N, "help", [
     Done<{}, []>
 ]>;
-export declare function route<const N extends string, const E extends readonly Unary[]>(start: Definition<N>, ...elements: E & Check<RouteZero<N>, E>): Materialize<Fold<RouteZero<N>, E>>;
+export declare 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>>>;
 export declare function version(semver: string): MethodElement<"version">;
 export declare function executable(): MethodElement<"execute">;
-export declare function routes<const C extends readonly AnyRoute[]>(...children: C): RoutesElement<C>;
+export type Input = Unary | AnyRoute;
+export type Normalize<E extends readonly Input[]> = {
+    [K in keyof E]: Normalized<E[K]>;
+};
+export type Validate<S, E extends readonly Input[]> = [
+    Fold<S, Normalize<E>>
+] extends [never] ? Invalid<S, E> : unknown;
+export declare function normalize<const E extends readonly Input[]>(elements: E): Normalize<E>;
+type Normalized<E extends Input> = E extends Unary ? E : E extends AnyRoute ? RoutesElement<readonly [E]> : never;
+type Invalid<S, E extends readonly Input[]> = E extends readonly [
+    infer Head extends Input,
+    ...infer Tail extends readonly Input[]
+] ? Fold<S, readonly [Normalized<Head>]> extends infer Next ? [Next] extends [never] ? readonly [never, ...Tail] : readonly [Head, ...Invalid<Next, Tail>] : never : E;
+export {};

package/esm/lib/route.js

@@ -14,7 +14,7 @@ export function route(start, ...elements) {
                 envs: [],
             }],
     };
-    return elements.reduce((value, element) => element(value), zero);
+    return normalize(elements).reduce((value, element) => element(value), zero);
 }
 export function version(semver) {
     return brand((route) => ({
@@ -29,7 +29,10 @@ export function executable() {
         methods: [...route.methods, "execute"],
     }));
 }
-export function routes(...children) {
+export function normalize(elements) {
+    return elements.map((element) => typeof element === "function" ? element : routes(element));
+}
+function routes(...children) {
     return brand((route) => {
         let phases = [...route.phases];
         let phase = phases.pop();

package/esm/lib/types.d.ts

@@ -27,7 +27,7 @@ export type Next<Model extends object, Routes extends readonly AnyRoute[], T> =
     readonly routes: Routes;
     readonly values: readonly ValueSource[];
     readonly envs: readonly EnvSource[];
-    readonly resolver: (requirement: T) => (input: AnyRoute) => AnyRoute;
+    readonly resolver: (requirement: T) => Result<(input: AnyRoute) => AnyRoute>;
 };
 export type Done<Model extends object, Routes extends readonly AnyRoute[]> = {
     readonly [phaseModel]?: Model;
@@ -44,7 +44,7 @@ export interface ParseIncrement<R extends AnyRoute, P extends RoutePath = "/", M
     readonly ok: true;
     readonly route: P;
     readonly model: IncrementModelOf<R>;
-    resume(result: Result<RequirementOf<R>>): Outcome<ParseAt<ContinuationOf<R>, P, Models>>;
+    resume(value: RequirementOf<R>): Outcome<ParseAt<ContinuationOf<R>, P, Models>>;
 }
 export type ContinuationOf<R extends AnyRoute> = Route<R["name"], MethodsOf<R>, SettleNext<R["phases"]>>;
 export type ModelOf<R extends AnyRoute, P extends RoutePath = "/"> = ModelOfRoute<RouteAt<R, P>>;
@@ -65,7 +65,7 @@ export interface AnyPhase {
     readonly routes: readonly AnyRoute[];
     readonly values: readonly ValueSource[];
     readonly envs: readonly EnvSource[];
-    readonly resolver?: (requirement: never) => (route: never) => AnyRoute;
+    readonly resolver?: (requirement: never) => Result<(route: never) => AnyRoute>;
 }
 export type AnyPhases = readonly [AnyPhase, ...AnyPhase[]];
 export type Method = "help" | "version" | "execute";
@@ -154,7 +154,7 @@ type NextModelIn<P extends readonly AnyPhase[]> = P extends readonly [
     ...infer Tail extends readonly AnyPhase[]
 ] ? Head extends Next<infer Model, readonly AnyRoute[], infer _Requirement> ? Model : NextModelIn<Tail> : never;
 type RequirementIn<P extends AnyPhase> = P extends {
-    readonly resolver: (requirement: infer Requirement) => (route: AnyRoute) => AnyRoute;
+    readonly resolver: (requirement: infer Requirement) => Result<(route: AnyRoute) => AnyRoute>;
 } ? Requirement : never;
 type RequirementInPhases<P extends readonly AnyPhase[]> = P extends readonly [
     infer Head extends AnyPhase,

package/esm/mod.d.ts

@@ -4,6 +4,7 @@ export { extend } from "./lib/extend.js";
 export { command } from "./lib/command.js";
 export type { CommandZero } from "./lib/command.js";
 export { checkpoint } from "./lib/checkpoint.js";
+export { dynamic } from "./lib/dynamic.js";
 export { description, name } from "./lib/definition.js";
 export { env, withEnvs } from "./lib/env.js";
 export type { Environment, EnvSource } from "./lib/env.js";
@@ -18,7 +19,7 @@ export { printErrors, printHelp, printVersion } from "./lib/print.js";
 export type { Rest } from "./lib/rest.js";
 export { cli } from "./lib/read.js";
 export type { CLIOptions, CLIRead, ReadCLI, Symbol as CLISymbol, } from "./lib/read.js";
-export { executable, route, routes, version } from "./lib/route.js";
+export { executable, route, version } from "./lib/route.js";
 export type { RouteZero } from "./lib/route.js";
 export { toggle } from "./lib/toggle.js";
 export { transform } from "./lib/transform.js";

package/esm/mod.js

@@ -3,6 +3,7 @@ export { argument } from "./lib/argument.js";
 export { extend } from "./lib/extend.js";
 export { command } from "./lib/command.js";
 export { checkpoint } from "./lib/checkpoint.js";
+export { dynamic } from "./lib/dynamic.js";
 export { description, name } from "./lib/definition.js";
 export { env, withEnvs } from "./lib/env.js";
 export { option } from "./lib/option.js";
@@ -12,7 +13,7 @@ export { parse } from "./lib/parse.js";
 export { mark } from "./lib/pipeline.js";
 export { printErrors, printHelp, printVersion } from "./lib/print.js";
 export { cli } from "./lib/read.js";
-export { executable, route, routes, version } from "./lib/route.js";
+export { executable, route, version } from "./lib/route.js";
 export { toggle } from "./lib/toggle.js";
 export { transform } from "./lib/transform.js";
 export { withValues } from "./lib/values.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bomb.sh/router",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Configuration for programs",
   "author": "Bombshell Authors (https://github.com/bombshell-dev)",
   "repository": {

package/src/_dnt.polyfills.ts

@@ -1,27 +0,0 @@
-// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
-if (!Object.hasOwn) {
-  Object.defineProperty(Object, "hasOwn", {
-    value: function (object: any, property: any) {
-      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,
-  });
-}
-
-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/src/lib/argument.ts

@@ -1,100 +0,0 @@
-import { type AnyParam, type Param, param, type ParamModel } from "./param.js";
-import {
-  brand,
-  type Check,
-  type Fold,
-  type ModelElement,
-  type Unary,
-} from "./pipeline.js";
-import type { CLIRead, ReadCLI } from "./read.js";
-import type { Word } from "./tokenize.js";
-import type { AnyRoute, Definition } from "./types.js";
-
-export 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>> {
-  const added = elements.reduce<unknown>(
-    (value, element) => element(value as never),
-    param(named, positional),
-  ) as AnyParam;
-
-  return brand<ElementOf<N, Fold<Zero<N>, E>>>(
-    (route: AnyRoute) => {
-      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,
-      };
-    },
-  );
-}
-
-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;
-
-function positional<P extends AnyParam>(param: P): P {
-  return {
-    ...param,
-    cli: {
-      read,
-      syntax: {
-        type: "argument",
-        label: `<${param.name.toUpperCase()}>`,
-      },
-    },
-  };
-}
-
-const read: ReadCLI = (tokens): CLIRead => {
-  let claim = tokens.claimOne((token): token is Word => 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: Parameters<ReadCLI>[0]): CLIRead {
-  let claim = tokens.claimAll(() => false);
-
-  return {
-    claim,
-    result: {
-      ok: true,
-      value: { exists: false },
-      issues: [],
-    },
-  };
-}