@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/routing/register.js

@@ -0,0 +1,155 @@
+import { describeMw, errorFactoryOf, errorsOf, scopeGuard } from "./middleware-chain.js";
+import { canonical, expandOptional, joinPatterns, normalizePattern, parsePattern, routeId, splitRouteId, } from "./pattern.js";
+import { createSettings } from "./settings.js";
+import { cloneTree, createNode, insertLeaf } from "./tree.js";
+/** An app's graph slot: not exported from the package; finalize readers (tests, codegen) reach the graph through it. */
+export const GRAPH = /* @__PURE__ */ Symbol("honey.graph");
+/** A handle's view slot: what a handle-level helper (serving a document) reads its basePath off. */
+export const VIEW = /* @__PURE__ */ Symbol("honey.view");
+/**
+ * The meta marker of a route an app serves about itself (its document, docs page or manifest).
+ * Such a route belongs to the app that registered it: mounting another app copies none of its
+ * served routes, a route tree leaves them out, and an app loaded from a tree registers its own.
+ */
+export const SERVED = /* @__PURE__ */ Symbol.for("honey.served");
+export const ROOT_VIEW = /* @__PURE__ */ Object.freeze({
+    basePath: "/",
+    chain: [],
+    chainMeta: null,
+    contextValues: null,
+    node: null,
+});
+export function createGraph() {
+    return {
+        catchAll: new Map(),
+        chains: [],
+        epoch: 0,
+        final: null,
+        hooks: null,
+        loaded: null,
+        pending: new Set(),
+        records: new Map(),
+        root: createNode(),
+        scoped: [],
+        served: new Set(),
+        settings: createSettings(),
+        unexpected: [],
+    };
+}
+/** Every `use()` on the way to a handle that registers, mounts or serves is in use. */
+export function markUsed(node) {
+    let at = node;
+    while (at !== null && !at.used) {
+        at.used = true;
+        at = at.parent;
+    }
+}
+/** A new `use(mw)` node under `parent`. */
+export function addChain(g, parent, mw) {
+    const node = { mw, parent, used: false };
+    g.chains.push(node);
+    return node;
+}
+/** Register one route at every leaf its pattern occupies (an optional last param places two). */
+/** Throw the duplicate-route error when `g` already has a route at `method` and `segments`. */
+export function assertRouteFree(g, method, segments) {
+    const id = routeId(method, canonical(segments));
+    if (g.records.get(id)?.lt === undefined && (g.records.has(id) || g.catchAll.has(id))) {
+        throw new Error(`Duplicate route: ${id}`);
+    }
+    return id;
+}
+/** Whether a route's own meta marks it served: the app's own, never copied with it. */
+export function isServed(r) {
+    return r.xm?.[SERVED] === true;
+}
+export function addRoute(g, method, segments, source) {
+    const id = assertRouteFree(g, method, segments);
+    const record = { ...source, id, mt: null, rp: canonical(segments), sg: segments };
+    g.epoch++;
+    /* a loaded app serves its own document beside its tree: on a copy, the loaded tree untouched */
+    const beside = g.loaded !== null && isServed(source) && !Object.hasOwn(g.loaded, id);
+    if (beside && Object.isFrozen(g.root))
+        g.root = cloneTree(g.root);
+    if (g.loaded === null || beside)
+        for (const variant of expandOptional(segments))
+            insertLeaf(g.root, variant, method, id);
+    else if (!Object.hasOwn(g.loaded, id)) {
+        /* a loaded app binds the routes its tree holds; a root wildcard it lacks is the catch-all */
+        if (segments.length === 1 && segments[0]?.k === "wildcard")
+            g.catchAll.set(id, record);
+        else
+            g.unexpected.push(id);
+        return id;
+    }
+    g.records.set(id, record);
+    return id;
+}
+/** Guard every request path under `path` (rebased on `basePath`) with `mw`, whichever handle registered the route. */
+export function addScope(g, basePath, path, mw) {
+    const prefix = joinPatterns(basePath, normalizePattern(path));
+    const segs = parsePattern(prefix);
+    g.scoped.push({ guard: scopeGuard(segs, mw), mw, prefix, segs });
+    g.epoch++;
+}
+/** A builder registered or was abandoned on purpose: no longer pending. */
+export function settle(g, pending, node) {
+    g.pending.delete(pending);
+    markUsed(node);
+}
+/** `use(mw)` handles that never registered, mounted or served, and builders without `.handler()`. */
+export function assertNothingDiscarded(g) {
+    const problems = [];
+    for (const node of g.chains) {
+        if (node.used)
+            continue;
+        problems.push(`app.use(${describeMw(node.mw)}) returned a handle that never registers a route, so the middleware runs nowhere. ` +
+            "use() does not change the handle it is called on: keep the returned value and register routes on it " +
+            "(`const authed = app.use(auth); authed.get(...)`), or chain it (`honey().use(mw).get(...)`).");
+    }
+    for (const p of g.pending)
+        problems.push(`${p.id} was declared but never got a .handler(), so the route is not registered.`);
+    if (problems.length > 0)
+        throw new Error(`honey: ${problems.join("\n  ")}`);
+}
+/**
+ * Mount a sub-app: re-register its routes under the view's basePath, with the view's chain running
+ * before theirs and its context values and chain meta under theirs. Nothing is shared by
+ * reference, so routes the sub registers later stay its own; each record keeps the settings of the
+ * app it was registered on. The sub's scopes guard the paths it brought.
+ */
+export function mount(g, view, sub) {
+    if (sub === g)
+        return;
+    assertNothingDiscarded(sub);
+    const base = view.basePath;
+    const at = (pattern) => (base === "/" ? pattern : joinPatterns(base, pattern));
+    for (const [id, r] of sub.records) {
+        if (isServed(r))
+            continue;
+        const { method, pattern } = splitRouteId(id);
+        addRoute(g, method, parsePattern(at(pattern)), {
+            ...r,
+            cm: [...view.chain, ...r.cm],
+            cv: view.contextValues ? { ...view.contextValues, ...r.cv } : r.cv,
+            xm: view.chainMeta ? { ...view.chainMeta, ...r.xm } : r.xm,
+        });
+    }
+    g.settings.metaSpec.absorbed.push(sub.settings.metaSpec);
+    for (const entry of sub.scoped) {
+        const prefix = at(entry.prefix);
+        if (g.scoped.some((e) => e.mw === entry.mw && e.prefix === prefix))
+            continue;
+        const segs = parsePattern(prefix);
+        g.scoped.push({ guard: scopeGuard(segs, entry.mw), mw: entry.mw, prefix, segs });
+    }
+    g.epoch++;
+}
+/** The error keys a middleware chain declares, in run order. */
+export function chainErrorKeys(chain) {
+    return chain.flatMap((mw) => errorsOf(mw) ?? []);
+}
+/** The factories a middleware chain's keys come from, each once, in run order. */
+export function chainErrorFactories(chain) {
+    return [...new Set(chain.flatMap((mw) => errorFactoryOf(mw) ?? []))];
+}

package/dist/routing/request-path.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The request path the router, scopes, `ctx.path`, `proxy()` and `staticFiles()` all see.
+ *
+ * Policy, applied the same way on every runtime:
+ * - empty segments collapse: `//admin///users` is `/admin/users`
+ * - dot segments resolve: `.` is dropped and `..` removes the segment before it, never past the
+ *   root; `%2e` counts as a dot, as it does for WHATWG URL parsing
+ * - a trailing slash is kept (the router and `trailingSlash()` decide what it means)
+ * - a backslash is a `/`, and characters a URL path cannot hold raw (space, controls, `"`, `<`,
+ *   `>`, `` ` ``, `{`, `}`, `^`, non-ASCII) are percent-encoded as UTF-8, so `ctx.path` does not
+ *   depend on which runtime parsed the target
+ * - an encoded `/` or `\` (`%2F`, `%5C`) is rejected unless `encodedSlashes` is `"allow"`: a
+ *   segment that decodes to a separator means one thing here and another to whatever the path is
+ *   forwarded to (a proxy upstream, a file system). Allowed, it stays encoded and decodes into a
+ *   param value.
+ * - everything else stays percent-encoded; params are decoded when they are extracted
+ */
+/** The canonical request path, or `null` for a rejected one (the app answers 400). */
+export declare function normalizePath(raw: string, encodedSlashes?: "allow" | "reject"): string | null;
+/**
+ * One path segment as a normalized request path holds it: characters a URL path cannot hold raw
+ * become UTF-8 percent escapes, everything else (existing escapes included) is kept. Route
+ * patterns encode their static segments with this too, so `app.get("/é")` matches the `/%C3%A9`
+ * every runtime hands the app.
+ */
+export declare function encodeSegment(seg: string): string;
+/** The path of a request URL without `new URL()`: from the path start up to `?` or `#`. */
+export declare function pathOfUrl(rawUrl: string): string;
+/** `?query` of a request URL (with the `?`), or `""`. Never includes a fragment. */
+export declare function searchOfUrl(rawUrl: string): string;

package/dist/routing/request-path.js

@@ -0,0 +1,173 @@
+/**
+ * The request path the router, scopes, `ctx.path`, `proxy()` and `staticFiles()` all see.
+ *
+ * Policy, applied the same way on every runtime:
+ * - empty segments collapse: `//admin///users` is `/admin/users`
+ * - dot segments resolve: `.` is dropped and `..` removes the segment before it, never past the
+ *   root; `%2e` counts as a dot, as it does for WHATWG URL parsing
+ * - a trailing slash is kept (the router and `trailingSlash()` decide what it means)
+ * - a backslash is a `/`, and characters a URL path cannot hold raw (space, controls, `"`, `<`,
+ *   `>`, `` ` ``, `{`, `}`, `^`, non-ASCII) are percent-encoded as UTF-8, so `ctx.path` does not
+ *   depend on which runtime parsed the target
+ * - an encoded `/` or `\` (`%2F`, `%5C`) is rejected unless `encodedSlashes` is `"allow"`: a
+ *   segment that decodes to a separator means one thing here and another to whatever the path is
+ *   forwarded to (a proxy upstream, a file system). Allowed, it stays encoded and decodes into a
+ *   param value.
+ * - everything else stays percent-encoded; params are decoded when they are extracted
+ */
+const PLAIN = 0;
+/* a character the rewrite changes: a backslash, or one encodeSegment percent-encodes */
+const SLOW = 1;
+const PERCENT = 2;
+const SLASH = 3;
+/**
+ * The WHATWG path percent-encode set, plus every non-ASCII code point. `^` joined the set in 2023;
+ * it is encoded here so `ctx.path` does not depend on the runtime's URL parser version.
+ */
+function needsEncoding(c) {
+    return c <= 0x20 || c >= 0x7f || c === 34 || c === 60 || c === 62 || c === 94 || c === 96 || c === 123 || c === 125;
+}
+function charClasses() {
+    const table = new Uint8Array(128);
+    for (let c = 0; c < 128; c++)
+        if (c === 92 || needsEncoding(c))
+            table[c] = SLOW;
+    table[37] = PERCENT;
+    table[47] = SLASH;
+    return table;
+}
+/* ASCII → PLAIN | SLOW | PERCENT | SLASH; built once, never written after */
+const CHAR_CLASS = /* @__PURE__ */ charClasses();
+/** What the escape at `i` decodes to, as far as the policy cares. */
+function escapeKind(raw, i) {
+    const hi = raw.charCodeAt(i + 1);
+    const lo = raw.charCodeAt(i + 2) | 0x20;
+    if (hi === 50 /* 2 */)
+        return lo === 102 /* f */ ? "separator" : lo === 101 /* e */ ? "dot" : "other";
+    return hi === 53 /* 5 */ && lo === 99 /* c */ ? "separator" : "other";
+}
+/** One pass: is `raw` already canonical, rejected, or in need of the rewrite? */
+function scan(raw, rejectEncoded) {
+    let canonical = raw.charCodeAt(0) === 47;
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw.charCodeAt(i);
+        const kind = c < 128 ? CHAR_CLASS[c] : SLOW;
+        if (kind === PLAIN)
+            continue;
+        if (kind === SLOW) {
+            canonical = false;
+        }
+        else if (kind === PERCENT) {
+            const escape = escapeKind(raw, i);
+            if (escape === "separator" && rejectEncoded)
+                return "reject";
+            if (escape === "dot")
+                canonical = false;
+        }
+        else {
+            /* `//` or a segment starting with a dot may collapse or resolve */
+            const next = raw.charCodeAt(i + 1);
+            if (next === 47 || next === 46)
+                canonical = false;
+        }
+    }
+    return canonical ? "canonical" : "rewrite";
+}
+/** 1 for `.`, 2 for `..` (either may be written `%2e`), 0 for anything else. */
+function dotSegment(seg) {
+    if (seg.length > 6)
+        return 0;
+    const s = seg.toLowerCase().replaceAll("%2e", ".");
+    return s === "." ? 1 : s === ".." ? 2 : 0;
+}
+function rewrite(raw) {
+    const out = [];
+    const segments = raw.replaceAll("\\", "/").split("/");
+    let trailing = false;
+    segments.forEach((seg, i) => {
+        const last = i === segments.length - 1;
+        if (seg === "") {
+            if (last && i > 0)
+                trailing = true;
+            return;
+        }
+        const dots = dotSegment(seg);
+        if (dots === 0) {
+            out.push(encodeSegment(seg));
+            return;
+        }
+        if (dots === 2)
+            out.pop();
+        /* `/a/b/..` is `/a/`, like URL resolution */
+        if (last)
+            trailing = true;
+    });
+    if (out.length === 0)
+        return "/";
+    const path = `/${out.join("/")}`;
+    return trailing ? `${path}/` : path;
+}
+/** The canonical request path, or `null` for a rejected one (the app answers 400). */
+export function normalizePath(raw, encodedSlashes = "reject") {
+    const verdict = scan(raw, encodedSlashes === "reject");
+    if (verdict === "reject")
+        return null;
+    return verdict === "canonical" ? raw : rewrite(raw);
+}
+/**
+ * One path segment as a normalized request path holds it: characters a URL path cannot hold raw
+ * become UTF-8 percent escapes, everything else (existing escapes included) is kept. Route
+ * patterns encode their static segments with this too, so `app.get("/é")` matches the `/%C3%A9`
+ * every runtime hands the app.
+ */
+export function encodeSegment(seg) {
+    /* most segments need nothing: return them without building a copy */
+    let plain = true;
+    for (let i = 0; i < seg.length && plain; i++)
+        plain = !needsEncoding(seg.charCodeAt(i));
+    if (plain)
+        return seg;
+    let out = "";
+    for (const ch of seg) {
+        if (!needsEncoding(ch.codePointAt(0))) {
+            out += ch;
+            continue;
+        }
+        try {
+            out += encodeURIComponent(ch);
+        }
+        catch {
+            /* a lone surrogate: U+FFFD, as URL parsing encodes it */
+            out += "%EF%BF%BD";
+        }
+    }
+    return out;
+}
+/** Where the path of a request URL starts: after the authority, or 0 for an origin-form target. */
+function pathStart(rawUrl) {
+    const protoEnd = rawUrl.indexOf("//");
+    return protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2);
+}
+/** The path of a request URL without `new URL()`: from the path start up to `?` or `#`. */
+export function pathOfUrl(rawUrl) {
+    const start = pathStart(rawUrl);
+    if (start === -1)
+        return "/";
+    for (let i = start; i < rawUrl.length; i++) {
+        const c = rawUrl.charCodeAt(i);
+        if (c === 63 /* ? */ || c === 35 /* # */)
+            return rawUrl.substring(start, i);
+    }
+    return rawUrl.substring(start);
+}
+/** `?query` of a request URL (with the `?`), or `""`. Never includes a fragment. */
+export function searchOfUrl(rawUrl) {
+    const start = pathStart(rawUrl);
+    if (start === -1)
+        return "";
+    const q = rawUrl.indexOf("?", start);
+    if (q === -1)
+        return "";
+    const hash = rawUrl.indexOf("#", q);
+    return hash === -1 ? rawUrl.substring(q) : rawUrl.substring(q, hash);
+}

package/dist/routing/route-builder.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The route builder: what `app.get(path)` returns. `.meta()`, `.errors()`, `.boundary()`, `.use()`,
+ * `.input()` and `.output()` shape the route; `.handler()` registers it (one record per method) and
+ * returns the app typed with the new route. A one-shot method disappears from the chain once called.
+ */
+import type { ERROR_META } from "../errors/errors.ts";
+import { type InputSchemas, type InputStep, type InputTypes } from "../input/input.ts";
+import type { KnownStatusKeys, OutputSchemas } from "./output-types.ts";
+import type { ErrorFactories } from "./settings.ts";
+import type { MaybePromise, MiddlewareFn, RuntimeMiddleware } from "../middleware/middleware.ts";
+import type { TypedResponse } from "../response/response.ts";
+import type { Honey } from "./app.ts";
+import type { ApplyScoped, ComputeErrorsByStatus, DefaultMeta, HandlerCtx, InitAccMeta, MergeRoute, RouteMeta, ScopedMwEntry, SkipRouteRecord } from "./app-types.ts";
+import { type HandleView, type HoneyGraph, type PendingRoute } from "./register.ts";
+import type { MergePath, ParamsFromPath } from "./types.ts";
+/** Everything a builder carries at the type level. */
+export type BuilderTypes = {
+    accMeta: unknown;
+    baseCtx: unknown;
+    basePath: string;
+    ctx: unknown;
+    defaultErrors: string;
+    env: unknown;
+    errorFactory: unknown;
+    errorKeys: string;
+    /** ctx.input once `.input()` ran, `never` before; `request` what a client sends, `{}` before */
+    input: unknown;
+    request: unknown;
+    /** what `.output()` declares; `never` before */
+    output: unknown;
+    meta: unknown;
+    method: string;
+    path: string;
+    routes: unknown;
+    scopedMw: readonly ScopedMwEntry[];
+    taps: Record<string, unknown>;
+    used: string;
+};
+/** `B` with the fields of `U` replaced. */
+type Next<B extends BuilderTypes, U extends Partial<BuilderTypes>> = {
+    [K in keyof BuilderTypes]: K extends keyof U ? U[K] : B[K];
+};
+type OneShotKey = "boundary" | "errors" | "input" | "meta" | "output";
+/** The builder with the one-shot methods already used removed. */
+export type BuilderChain<B extends BuilderTypes> = Omit<RouteBuilder<B>, B["used"] & OneShotKey>;
+/** The keys a route may still declare: the factory's, minus the app defaults. */
+type DeclarableKey<B extends BuilderTypes> = [B["errorFactory"]] extends [never] ? never : Exclude<keyof B["errorFactory"] & string, B["defaultErrors"]>;
+type ErrorMetaOf<F> = F extends {
+    readonly [ERROR_META]: infer M;
+} ? M : {};
+/** The route's factory once `.errors(named, ...)` ran: the named factory's keys and meta over the app's. */
+type WithNamedFactory<TApp, TNamed> = [TApp] extends [never] ? TNamed : Omit<TApp, keyof TNamed> & Omit<TNamed, typeof ERROR_META> & {
+    readonly [ERROR_META]: Omit<ErrorMetaOf<TApp>, keyof ErrorMetaOf<TNamed>> & ErrorMetaOf<TNamed>;
+};
+/** What `.errors(named, ...keys)` changes. */
+type NamedErrors<B extends BuilderTypes, TFactory, TKeys extends string> = {
+    errorFactory: WithNamedFactory<B["errorFactory"], TFactory>;
+    errorKeys: B["errorKeys"] | TKeys;
+    used: B["used"] | "errors";
+};
+/** The handler's ctx for the route `B` describes. */
+export type RouteHandlerCtx<B extends BuilderTypes> = HandlerCtx<B["ctx"], ParamsFromPath<B["path"]>, B["accMeta"], B["errorFactory"], B["errorKeys"] | B["defaultErrors"], B["path"], B["taps"], B["input"], B["output"]>;
+/** The app `.handler()` returns: the same handle, typed with the new route. */
+export type HandlerReturn<B extends BuilderTypes> = Honey<B["env"], B["baseCtx"], SkipRouteRecord<B["accMeta"]> extends true ? B["routes"] : MergeRoute<B["routes"], B["path"], B["method"], [
+    B["input"]
+] extends [never] ? {} : B["input"], [
+    B["output"]
+] extends [never] ? {} : B["output"], RouteHandlerCtx<B>, RouteMeta<B["accMeta"]>, B["errorKeys"] | B["defaultErrors"], ComputeErrorsByStatus<B["errorFactory"], B["errorKeys"] | B["defaultErrors"], typeof ERROR_META>, B["request"]>, B["meta"], B["errorFactory"], B["defaultErrors"], B["basePath"], B["taps"], B["scopedMw"]>;
+/** The builder `app.get(path)` starts, from the app handle's own type. */
+export type StartOf<H, TPath extends string, TMethod extends string> = H extends Honey<infer TEnv, infer TCtx, infer TRoutes, infer TMeta, infer TFactory, infer TDefaults extends string, infer TBase extends string, infer TTaps extends Record<string, unknown>, infer TScoped extends readonly ScopedMwEntry[]> ? BuilderChain<{
+    accMeta: InitAccMeta<TMeta>;
+    baseCtx: TCtx;
+    basePath: TBase;
+    ctx: TCtx & ApplyScoped<TScoped, MergePath<TBase, TPath>>;
+    defaultErrors: TDefaults;
+    env: TEnv;
+    errorFactory: TFactory;
+    errorKeys: never;
+    input: never;
+    meta: TMeta;
+    output: never;
+    request: {};
+    method: TMethod;
+    path: MergePath<TBase, TPath>;
+    routes: TRoutes;
+    scopedMw: TScoped;
+    taps: TTaps;
+    used: never;
+}> : never;
+/** What a builder carries at runtime. */
+export type BuilderState = {
+    readonly boundaryKey: string | null;
+    /** keys the route declares itself */
+    readonly errorKeys: ReadonlySet<string>;
+    /** the factory `.errors(factory, ...keys)` named */
+    readonly errorSource: ErrorFactories | null;
+    readonly extraMethods: readonly string[];
+    readonly graph: HoneyGraph;
+    /** `.input()`: the schemas as written (for documentation) and the step they compile to */
+    readonly input: {
+        readonly schemas: InputSchemas;
+        readonly step: InputStep;
+    } | null;
+    /** what `.output()` declared */
+    readonly output: OutputSchemas | null;
+    /** explicit meta: chain `.meta()` overlaid by route `.meta()` */
+    readonly meta: Readonly<Record<string, unknown>> | null;
+    readonly method: string;
+    readonly middlewares: readonly RuntimeMiddleware[];
+    /** the handle `.handler()` returns */
+    readonly parent: unknown;
+    /** canonical full pattern */
+    readonly path: string;
+    readonly pending: PendingRoute;
+    readonly view: HandleView;
+};
+export declare class RouteBuilder<B extends BuilderTypes> {
+    #private;
+    readonly $ctx: B["ctx"];
+    readonly $method: B["method"];
+    readonly $path: B["path"];
+    constructor(state: BuilderState);
+    /** Declare the error keys this route may throw, from a factory or the app's. */
+    errors<TFactory extends Record<string, (...args: never[]) => unknown>, TKeys extends Exclude<keyof TFactory & string, B["defaultErrors"]>>(factory: TFactory, ...keys: TKeys[]): BuilderChain<Next<B, NamedErrors<B, TFactory, TKeys>>>;
+    errors<TKeys extends DeclarableKey<B>>(...keys: TKeys[]): BuilderChain<Next<B, {
+        errorKeys: B["errorKeys"] | TKeys;
+        used: B["used"] | "errors";
+    }>>;
+    /** The error an undeclared or unknown throw becomes on this route. */
+    boundary<TKey extends DeclarableKey<B>>(key: TKey): BuilderChain<Next<B, {
+        errorKeys: B["errorKeys"] | TKey;
+        used: B["used"] | "boundary";
+    }>>;
+    meta<TRouteMeta extends Partial<DefaultMeta> & ([B["meta"]] extends [never] ? {} : B["meta"])>(meta: TRouteMeta): BuilderChain<Next<B, {
+        accMeta: B["accMeta"] & TRouteMeta;
+        used: B["used"] | "meta";
+    }>>;
+    /** Validate params, query, headers, cookies and one body onto ctx.input: the first failure is a 400 (415). */
+    input<const TSchemas extends InputSchemas>(schemas: TSchemas): BuilderChain<Next<B, InputTypes<TSchemas> & {
+        used: B["used"] | "input";
+    }>>;
+    /** Declare what the route answers: ctx.res narrows to it, and `outputValidation` checks it. */
+    output<const TOutput extends OutputSchemas>(schemas: TOutput & KnownStatusKeys<TOutput>): BuilderChain<Next<B, {
+        output: TOutput;
+        used: B["used"] | "output";
+    }>>;
+    /** Route-level middleware, after the chain and the scopes. */
+    use<TAdds>(mw: MiddlewareFn<B["ctx"], TAdds>): BuilderChain<Next<B, {
+        ctx: B["ctx"] & TAdds;
+    }>>;
+    /** Register the route, once per method, and return the app typed with it. */
+    handler(fn: (ctx: RouteHandlerCtx<B>) => MaybePromise<TypedResponse>): HandlerReturn<B>;
+}
+/** The builder for `method` (and `extraMethods`) at `path` under `view`'s basePath, pending until `.handler()`. */
+export declare function startRoute(graph: HoneyGraph, view: HandleView, parent: unknown, route: {
+    readonly extraMethods: readonly string[];
+    readonly method: string;
+    readonly path: string;
+}): unknown;
+export {};

package/dist/routing/route-builder.js

@@ -0,0 +1,86 @@
+import { compileInput } from "../input/input.js";
+import { joinPatterns, parsePattern } from "./pattern.js";
+import { addRoute, settle } from "./register.js";
+export class RouteBuilder {
+    #s;
+    constructor(state) {
+        this.#s = state;
+    }
+    #next(changes) {
+        return new RouteBuilder({ ...this.#s, ...changes });
+    }
+    errors(...args) {
+        const named = typeof args[0] === "object" && args[0] !== null ? args[0] : null;
+        const keys = (named === null ? args : args.slice(1));
+        return this.#next({ errorKeys: new Set([...this.#s.errorKeys, ...keys]), errorSource: named });
+    }
+    /** The error an undeclared or unknown throw becomes on this route. */
+    boundary(key) {
+        return this.#next({ boundaryKey: key, errorKeys: new Set([...this.#s.errorKeys, key]) });
+    }
+    meta(meta) {
+        const merged = { ...this.#s.meta, ...meta };
+        const invalidate = merged.invalidate;
+        if (Array.isArray(invalidate) && invalidate.length > 1)
+            merged.invalidate = [...new Set(invalidate)];
+        return this.#next({ meta: merged });
+    }
+    /** Validate params, query, headers, cookies and one body onto ctx.input: the first failure is a 400 (415). */
+    input(schemas) {
+        const step = compileInput(schemas, [this.#s.method, ...this.#s.extraMethods], this.#s.path);
+        return this.#next({ input: { schemas, step } });
+    }
+    /** Declare what the route answers: ctx.res narrows to it, and `outputValidation` checks it. */
+    output(schemas) {
+        return this.#next({ output: schemas });
+    }
+    /** Route-level middleware, after the chain and the scopes. */
+    use(mw) {
+        return this.#next({ middlewares: [...this.#s.middlewares, mw] });
+    }
+    /** Register the route, once per method, and return the app typed with it. */
+    handler(fn) {
+        const s = this.#s;
+        settle(s.graph, s.pending, s.view.node);
+        const source = {
+            cm: s.view.chain,
+            cv: s.view.contextValues,
+            dk: s.errorKeys,
+            ef: s.errorSource,
+            fn: fn,
+            in: s.input?.step ?? null,
+            iv: s.input?.schemas ?? null,
+            out: s.output,
+            own: s.graph.settings,
+            rb: s.boundaryKey,
+            rm: s.middlewares,
+            xm: s.meta,
+        };
+        const segments = parsePattern(s.path);
+        for (const method of [s.method, ...s.extraMethods])
+            addRoute(s.graph, method, segments, source);
+        return s.parent;
+    }
+}
+/** The builder for `method` (and `extraMethods`) at `path` under `view`'s basePath, pending until `.handler()`. */
+export function startRoute(graph, view, parent, route) {
+    const fullPath = joinPatterns(view.basePath, route.path);
+    const pending = { id: `${[route.method, ...route.extraMethods].join(",")} ${fullPath}` };
+    graph.pending.add(pending);
+    return new RouteBuilder({
+        boundaryKey: null,
+        errorKeys: new Set(),
+        errorSource: null,
+        extraMethods: route.extraMethods,
+        graph,
+        input: null,
+        meta: view.chainMeta,
+        method: route.method,
+        output: null,
+        middlewares: [],
+        parent,
+        path: fullPath,
+        pending,
+        view,
+    });
+}

package/dist/routing/route-tree.d.ts

@@ -0,0 +1,18 @@
+import { GRAPH, type HoneyGraph } from "./register.ts";
+import { SettingsChain } from "./settings-chain.ts";
+import { type RouteTree } from "./tree.ts";
+/** Serve `tree` on `g`: frozen in place, its live records copied, the rest bound as routes register. */
+export declare function loadRouteTree(g: HoneyGraph, tree: RouteTree): void;
+/** `g`'s routes as a tree another app serves; nothing in it is shared with `g`. */
+export declare function snapshotRouteTree(g: HoneyGraph): RouteTree;
+/** `app.routeTree()` and `app.toRouteTree()`: every app handle has them. */
+export declare abstract class RouteTreeChain<TEnv> extends SettingsChain<TEnv> {
+    abstract get [GRAPH](): HoneyGraph;
+    /**
+     * Serve `tree` (a generated `routes.gen.ts`, a `toRouteTree()` snapshot, or a `mergeTree()` of
+     * them). Call it before registering routes; a route registered afterwards binds to its leaf.
+     */
+    routeTree(tree: RouteTree): this;
+    /** A copy of the routes this app serves, for another app to serve with `routeTree()`. */
+    toRouteTree(): RouteTree;
+}