@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/routing/app.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The app: `honey()` and the `Honey` handle. A handle is a view (basePath, chain, context values,
+ * chain meta) over one shared graph; `use()`, `basePath()`, `context()` and `meta()` return a new
+ * handle on the same graph, and the settings setters apply to the whole app.
+ */
+import { type ExecutionCtx, type HoneyContext } from "../context/context.ts";
+import type { MaybePromise, MiddlewareFn } from "../middleware/middleware.ts";
+import type { AllChainMeta, DeclaredMeta, DefaultMeta, ScopedMwEntry, WithChainMeta } from "./app-types.ts";
+import { GRAPH, type HandleView, type HoneyGraph, VIEW } from "./register.ts";
+import { type StartOf } from "./route-builder.ts";
+import { RouteTreeChain } from "./route-tree.ts";
+import type { HttpMethod, MergePath, PrefixRoutes } from "./types.ts";
+export { GRAPH } from "./register.ts";
+export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta = never, TErrorFactory = never, TDefaultErrors extends string = never, TBasePath extends string = "/", TTaps extends Record<string, unknown> = {}, TScopedMw extends readonly ScopedMwEntry[] = []> extends RouteTreeChain<TEnv> {
+    #private;
+    readonly $basePath: TBasePath;
+    readonly $ctx: TCtx;
+    readonly $env: TEnv;
+    readonly $errorFactory: TErrorFactory;
+    readonly $meta: TMeta;
+    readonly $routes: TRoutes;
+    readonly $taps: TTaps;
+    /** this handle's view: read-only, reached through a symbol the package does not export */
+    readonly [VIEW]: HandleView;
+    constructor(graph?: HoneyGraph, view?: HandleView);
+    get [GRAPH](): HoneyGraph;
+    basePath<P extends string>(prefix: P): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, MergePath<TBasePath, P>, TTaps, TScopedMw>;
+    /** Static values every route registered through the new handle finds on `ctx`. */
+    context<TAdds extends Record<string, unknown>>(values: TAdds): Honey<TEnv, TCtx & Readonly<TAdds>, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** The app's error factory; routes mounted from another app keep that app's. */
+    errorFactory<TFactory extends Record<string, (...args: never[]) => unknown>>(factory: TFactory): Honey<TEnv, TCtx, TRoutes, TMeta, TFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** Error keys every route of this app declares, registered before or after the call. */
+    defaultErrors<TKeys extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(...keys: TKeys[]): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKeys, TBasePath, TTaps, TScopedMw>;
+    /** The error an undeclared or unknown throw becomes on routes without their own `.boundary()`. */
+    defaultBoundary<TKey extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(key: TKey): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKey, TBasePath, TTaps, TScopedMw>;
+    protected invalidate(): void;
+    /** Type only: constrain what route `.meta()` accepts; declared tap keys stay allowed. */
+    meta<TNewMeta extends Record<string, unknown>>(): Honey<TEnv, TCtx, TRoutes, [
+        keyof TTaps
+    ] extends [never] ? TNewMeta : TNewMeta & Partial<TTaps>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /**
+     * Typed chain meta in one call (`meta<AppMeta>({ … })`): every declared key counts as set, so a route may omit
+     * any of them. One call cannot know which it set (no partial type-argument inference), so `meta<AppMeta>()`
+     * then `meta({ … })` is the precise form. `TNewMeta` defaults to `never`: a bare call takes the next overload.
+     */
+    meta<TNewMeta extends Record<string, unknown> = never, TValues extends Partial<DefaultMeta> & Partial<TNewMeta> = Partial<DefaultMeta> & Partial<TNewMeta>>(values: TValues): Honey<TEnv, TCtx, TRoutes, AllChainMeta<TNewMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** Chain meta, merged into every route registered through the new handle; its values reach the routes' types (`internal: true`). */
+    meta<const TValues extends Partial<DefaultMeta> & ([DeclaredMeta<TMeta>] extends [never] ? Record<string, unknown> : Partial<DeclaredMeta<TMeta>>)>(values: TValues): Honey<TEnv, TCtx, TRoutes, WithChainMeta<TMeta, TValues>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** Chain middleware: a new handle whose routes run `mw`; this handle is unchanged. */
+    use<TAdds>(mw: MiddlewareFn<TCtx, TAdds>): Honey<TEnv, TCtx & TAdds, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** Scoped middleware: runs for every request path under `path`, whichever handle registered the route. */
+    use<const TPath extends string, TAdds>(path: TPath, mw: MiddlewareFn<TCtx, TAdds>): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, readonly [...TScopedMw, {
+        readonly adds: TAdds;
+        readonly path: MergePath<TBasePath, TPath>;
+    }]>;
+    /**
+     * Mount a sub-app under this handle's basePath (and `prefix`): this handle's chain runs before
+     * the sub's; the sub's own basePath stays part of each path.
+     */
+    route<TSubRoutes, TSubMeta, TSubFactory, TSubDefaults extends string, TSubBase extends string>(sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubFactory, TSubDefaults, TSubBase>): Honey<TEnv, TCtx, TRoutes & PrefixRoutes<TBasePath, TSubRoutes>, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    route<const TPrefix extends string, TSubRoutes, TSubMeta, TSubFactory, TSubDefaults extends string, TSubBase extends string>(prefix: TPrefix, sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubFactory, TSubDefaults, TSubBase>): Honey<TEnv, TCtx, TRoutes & PrefixRoutes<MergePath<TBasePath, TPrefix>, TSubRoutes>, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** One route for several methods: one record per method. */
+    on<const TPath extends string, const TMethods extends readonly [HttpMethod | "ALL", ...(HttpMethod | "ALL")[]]>(methods: TMethods, path: TPath): StartOf<this, TPath, TMethods[number]>;
+    all<const TPath extends string>(path: TPath): StartOf<this, TPath, "ALL">;
+    delete<const TPath extends string>(path: TPath): StartOf<this, TPath, "DELETE">;
+    get<const TPath extends string>(path: TPath): StartOf<this, TPath, "GET">;
+    head<const TPath extends string>(path: TPath): StartOf<this, TPath, "HEAD">;
+    options<const TPath extends string>(path: TPath): StartOf<this, TPath, "OPTIONS">;
+    patch<const TPath extends string>(path: TPath): StartOf<this, TPath, "PATCH">;
+    post<const TPath extends string>(path: TPath): StartOf<this, TPath, "POST">;
+    put<const TPath extends string>(path: TPath): StartOf<this, TPath, "PUT">;
+    /** The Fetch handler an adapter calls. Finalizes once; a later registration re-finalizes. */
+    fetch(request: Request, env: TEnv, executionCtx?: ExecutionCtx): MaybePromise<Response>;
+}
+/** A new app typed to the runtime env `TEnv`. */
+export declare function honey<TEnv>(): Honey<TEnv>;

package/dist/routing/app.js

@@ -0,0 +1,137 @@
+/**
+ * The app: `honey()` and the `Honey` handle. A handle is a view (basePath, chain, context values,
+ * chain meta) over one shared graph; `use()`, `basePath()`, `context()` and `meta()` return a new
+ * handle on the same graph, and the settings setters apply to the whole app.
+ */
+import { isReservedCtxKey } from "../context/context.js";
+import { dispatch } from "./dispatch.js";
+import { joinPatterns } from "./pattern.js";
+import { addChain, addScope, createGraph, GRAPH, markUsed, mount, ROOT_VIEW, VIEW, } from "./register.js";
+import { startRoute } from "./route-builder.js";
+import { RouteTreeChain } from "./route-tree.js";
+export { GRAPH } from "./register.js";
+export class Honey extends RouteTreeChain {
+    #graph;
+    /** this handle's view: read-only, reached through a symbol the package does not export */
+    [VIEW];
+    constructor(graph = createGraph(), view = ROOT_VIEW) {
+        super(graph.settings);
+        this.#graph = graph;
+        this[VIEW] = view;
+    }
+    get [GRAPH]() {
+        return this.#graph;
+    }
+    /** A new handle on the same graph with part of this handle's view replaced. */
+    #derive(changes) {
+        return new Honey(this.#graph, { ...this[VIEW], ...changes });
+    }
+    basePath(prefix) {
+        return this.#derive({ basePath: joinPatterns(this[VIEW].basePath, prefix) });
+    }
+    /** Static values every route registered through the new handle finds on `ctx`. */
+    context(values) {
+        for (const key in values)
+            if (isReservedCtxKey(key))
+                throw new Error(`context() cannot set reserved key "${key}"`);
+        return this.#derive({ contextValues: { ...this[VIEW].contextValues, ...values } });
+    }
+    /** The app's error factory; routes mounted from another app keep that app's. */
+    errorFactory(factory) {
+        this.settings.errorFactory = factory;
+        this.#graph.epoch++;
+        return this;
+    }
+    /** Error keys every route of this app declares, registered before or after the call. */
+    defaultErrors(...keys) {
+        for (const key of keys)
+            this.settings.defaultErrorKeys.add(key);
+        this.#graph.epoch++;
+        return this;
+    }
+    /** The error an undeclared or unknown throw becomes on routes without their own `.boundary()`. */
+    defaultBoundary(key) {
+        this.settings.defaultBoundaryKey = key;
+        this.settings.defaultErrorKeys.add(key);
+        this.#graph.epoch++;
+        return this;
+    }
+    invalidate() {
+        this.#graph.epoch++;
+    }
+    meta(values) {
+        if (values === undefined)
+            return this;
+        return this.#derive({ chainMeta: { ...this[VIEW].chainMeta, ...values } });
+    }
+    use(pathOrMw, scopedMw) {
+        if (typeof pathOrMw === "string") {
+            addScope(this.#graph, this[VIEW].basePath, pathOrMw, scopedMw);
+            return this.#derive({});
+        }
+        const mw = pathOrMw;
+        return this.#derive({ chain: [...this[VIEW].chain, mw], node: addChain(this.#graph, this[VIEW].node, mw) });
+    }
+    route(prefixOrSub, maybeSub) {
+        if (typeof prefixOrSub === "string") {
+            if (!(maybeSub instanceof Honey))
+                throw new TypeError("honey: route(prefix, sub) needs the sub-app");
+            markUsed(this[VIEW].node);
+            this.basePath(prefixOrSub).#mount(maybeSub);
+            return this;
+        }
+        return this.#mount(prefixOrSub);
+    }
+    #mount(sub) {
+        markUsed(this[VIEW].node);
+        markUsed(sub[VIEW].node);
+        mount(this.#graph, this[VIEW], sub.#graph);
+        return this;
+    }
+    #builder(method, path, extraMethods = []) {
+        return startRoute(this.#graph, this[VIEW], this, { extraMethods, method, path });
+    }
+    /** One route for several methods: one record per method. */
+    on(methods, path) {
+        const [first, ...rest] = methods;
+        return this.#builder(first, path, rest);
+    }
+    all(path) {
+        return this.#builder("ALL", path);
+    }
+    delete(path) {
+        return this.#builder("DELETE", path);
+    }
+    get(path) {
+        return this.#builder("GET", path);
+    }
+    head(path) {
+        return this.#builder("HEAD", path);
+    }
+    options(path) {
+        return this.#builder("OPTIONS", path);
+    }
+    patch(path) {
+        return this.#builder("PATCH", path);
+    }
+    post(path) {
+        return this.#builder("POST", path);
+    }
+    put(path) {
+        return this.#builder("PUT", path);
+    }
+    /** The Fetch handler an adapter calls. Finalizes once; a later registration re-finalizes. */
+    fetch(request, env, executionCtx) {
+        const g = this.#graph;
+        if (!g.served.has(this[VIEW].chain)) {
+            markUsed(this[VIEW].node);
+            g.served.add(this[VIEW].chain);
+            g.epoch++;
+        }
+        return dispatch(g, request, env, executionCtx);
+    }
+}
+/** A new app typed to the runtime env `TEnv`. */
+export function honey() {
+    return new Honey();
+}

package/dist/routing/codegen-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The types an app's generated `_gen/types.gen.d.ts` meets core through. `HoneyCodegen` is empty
+ * until codegen augments it (`interface HoneyCodegen { routeSelector: RouteSelector }`), so an
+ * ungenerated app keeps plain strings. Type-only.
+ */
+import type { ApplyOutput } from "./output-types.ts";
+/** Augmented by the generated types: `routeSelector` names every documented route as `"METHOD /path"`. */
+export interface HoneyCodegen {
+}
+/** The route selectors codegen `C` declares; any string when it declares none. */
+export type SelectorOf<C> = C extends {
+    routeSelector: infer R;
+} ? (R extends string ? R : string) : string;
+/** An `invalidate` target: one of the app's route selectors once codegen ran, any string before. */
+export type RouteSelectorOf = SelectorOf<HoneyCodegen>;
+/** A route ctx with `ctx.res` narrowed to what the route declares: the generated `Routes` ctx types. */
+export type WithOutput<TCtx, TOutput> = ApplyOutput<TCtx, TOutput>;

package/dist/routing/codegen-types.js

@@ -0,0 +1 @@
+export {};

package/dist/routing/delegate.d.ts

@@ -0,0 +1,9 @@
+import { type RouteId } from "./pattern.ts";
+import type { HoneyGraph, RouteHandler } from "./register.ts";
+/** The records the unserved leaves of a loaded tree run, through the app's catch-all. */
+export declare function delegatedRecords(g: HoneyGraph): [RouteId, RouteHandler][];
+/**
+ * A loaded tree that disagrees with what the app registers is stale: a route it lacks, or a
+ * catch-all with no leaf left to serve. Regenerating it (`honey generate`) brings them back in step.
+ */
+export declare function assertTreeCurrent(g: HoneyGraph): void;

package/dist/routing/delegate.js

@@ -0,0 +1,75 @@
+/**
+ * Delegation: a leaf of a loaded route tree that no route of this app serves goes to the app's
+ * catch-all (a root wildcard it registered outside the tree), as a gateway forwards its services'
+ * routes. The leaf keeps its identity: its id, pattern, params, meta, error keys and the scopes
+ * covering its path. Its declared body media type is checked first, and its body is left unread.
+ */
+import { binaryRanges, binaryType } from "../input/binary.js";
+import { assertRequestContentType } from "../validation/content-type.js";
+import { parsePattern, splitRouteId } from "./pattern.js";
+/** The catch-all serving `method`: the one registered for it, else the one for every method. */
+function catchAllFor(g, method) {
+    const all = [...g.catchAll.values()];
+    return all.find((r) => splitRouteId(r.id).method === method) ?? all.find((r) => splitRouteId(r.id).method === "ALL");
+}
+/** Middleware refusing a request whose media type the declared body does not take, before anything reads it. */
+function bodyGate(iv, method, pattern) {
+    const ranges = iv.binary === undefined ? null : binaryRanges(iv.binary, method, pattern);
+    if (ranges === null && iv.json === undefined && iv.form === undefined)
+        return null;
+    return (ctx, next) => {
+        const contentType = ctx.req.headers.get("content-type");
+        if (ranges === null)
+            assertRequestContentType(iv, contentType);
+        else
+            binaryType(ranges, contentType);
+        return next();
+    };
+}
+/** The record a leaf serves through `catchAll`: the catch-all's chain and handler, under the leaf's identity and data. */
+function delegated(id, entry, catchAll) {
+    const { method, pattern } = splitRouteId(id);
+    const gate = entry.iv === undefined || entry.iv === null ? null : bodyGate(entry.iv, method, pattern);
+    return {
+        ...catchAll,
+        cm: gate === null ? catchAll.cm : [gate, ...catchAll.cm],
+        dk: new Set(entry.ek),
+        ef: null,
+        id,
+        iv: entry.iv ?? null,
+        mt: null,
+        out: entry.out ?? null,
+        rb: entry.bek ?? null,
+        rp: pattern,
+        sg: parsePattern(pattern),
+        xm: entry.mt ?? null,
+    };
+}
+/** The loaded leaves no route serves: a WebSocket leaf or one without a catch-all for its method answers as a miss. */
+function unserved(g) {
+    if (g.loaded === null)
+        return [];
+    return Object.entries(g.loaded).filter(([id]) => !g.records.has(id));
+}
+/** The records the unserved leaves of a loaded tree run, through the app's catch-all. */
+export function delegatedRecords(g) {
+    const out = [];
+    for (const [id, entry] of unserved(g)) {
+        const { method } = splitRouteId(id);
+        const catchAll = method === "WS" ? undefined : catchAllFor(g, method);
+        if (catchAll !== undefined)
+            out.push([id, delegated(id, entry, catchAll)]);
+    }
+    return out;
+}
+/**
+ * A loaded tree that disagrees with what the app registers is stale: a route it lacks, or a
+ * catch-all with no leaf left to serve. Regenerating it (`honey generate`) brings them back in step.
+ */
+export function assertTreeCurrent(g) {
+    const stale = g.catchAll.size > 0 && unserved(g).length === 0 ? [...g.unexpected, ...g.catchAll.keys()] : g.unexpected;
+    if (stale.length === 0)
+        return;
+    const verb = stale.length === 1 ? "is" : "are";
+    throw new Error(`${stale.join(", ")} ${verb} registered but missing from the loaded route tree. Run \`honey generate\`.`);
+}

package/dist/routing/dispatch.d.ts

@@ -0,0 +1,22 @@
+import { type RequestState } from "../context/context.ts";
+import { type MaybePromise } from "../middleware/middleware.ts";
+import { type FinalTable, type Plan } from "./finalize.ts";
+import type { HoneyGraph } from "./register.ts";
+import { type AppSettings } from "./settings.ts";
+import type { WSAdapter } from "../ws/contract.ts";
+/** The request state of one fetch: the context's request fields, the plan it runs, the 405 answer. */
+export type FetchState<TEnv = unknown> = RequestState<TEnv> & {
+    allowed: string[] | null;
+    plan: Plan;
+    /** on a ws upgrade, the serving app's adapter (`null` when none is set) */
+    ws?: WSAdapter | null;
+};
+/** The graph's final table, compiled with its hooks. */
+export declare function finalTable(g: HoneyGraph): FinalTable;
+/** 400 for a request path the normalization policy rejects. No boundary, no onError. */
+export declare function badRequestTarget(s: AppSettings<unknown>, request: Request): Response;
+/**
+ * Serve one request from the graph, observed until its body ends when the request log or telemetry
+ * is on. Routing never rejects; a throw (an app that cannot finalize) ends the root and goes on.
+ */
+export declare function dispatch(g: HoneyGraph, request: Request, env: unknown, executionCtx: RequestState<unknown>["executionCtx"]): MaybePromise<Response>;

package/dist/routing/dispatch.js

@@ -0,0 +1,255 @@
+/**
+ * The fetch pipeline: normalize the request path, redirect a non-canonical trailing slash, strip
+ * the app prefix, find the route (statics first), and run its compiled chain. Every exit — 400,
+ * redirect, 404, 405, preflight, a handler, a throw — yields one Response. A throw becomes a
+ * response at the `next()` boundary (`errors/on-error.ts`); the boundary never rejects.
+ */
+import { headResponse } from "../input/body-kind.js";
+import { HoneyContext, REQUEST } from "../context/context.js";
+import { HoneyError } from "../errors/error.js";
+import { boundary, errorCtx, formatterReport } from "../errors/on-error.js";
+import { createErrorResponse, jsonAnswer } from "../errors/projector.js";
+import { compileChain } from "../middleware/middleware.js";
+import { isNodeOutbound, replaceResponse } from "../response/builder.js";
+import { observe, startTrace } from "../telemetry/span-lifecycle.js";
+import { finalize } from "./finalize.js";
+import { matchRoute, matchWsRoute } from "./match.js";
+import { normalizePath, pathOfUrl, searchOfUrl } from "./request-path.js";
+import { defaultErrorFormatter } from "./settings.js";
+const EMPTY_PARAMS = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+function stateOf(ctx) {
+    return ctx[REQUEST];
+}
+/** The app's error for a framework condition: its factory's, else a plain one. */
+function frameworkError(s, errorKey, status) {
+    const make = s.errorFactory?.[errorKey];
+    return typeof make === "function" ? make() : new HoneyError({ errorKey, status });
+}
+/** Add `Allow` to a 405, rebuilding a response whose headers are immutable. */
+function withAllow(res, allowed) {
+    const value = allowed.join(", ");
+    try {
+        res.headers.set("allow", value);
+        return res;
+    }
+    catch {
+        /* immutable headers (a fetch() response): not a failure, the response is rebuilt with Allow */
+        const headers = new Headers(res.headers);
+        headers.set("allow", value);
+        return replaceResponse(res, { headers });
+    }
+}
+function make404(s, state) {
+    if (s.onNotFound !== null)
+        return s.onNotFound(errorCtx(s, state));
+    return errorCtx(s, state).jsonFromError(frameworkError(s, "not_found", "not_found"));
+}
+function make405(s, state, allowed) {
+    const res = s.onMethodNotAllowed === null
+        ? errorCtx(s, state).jsonFromError(frameworkError(s, "method_not_allowed", "method_not_allowed"))
+        : s.onMethodNotAllowed({ ...errorCtx(s, state), allowed });
+    return res instanceof Promise ? res.then((r) => withAllow(r, allowed)) : withAllow(res, allowed);
+}
+/**
+ * The fixed 404, built per request from one payload, for a miss nothing observes: the miss chain runs
+ * nothing (finalize decides) and, checked per request since a setter may come later, no
+ * `onNotFound`, the default formatter (a custom one may stamp each body) and no factory override.
+ */
+function fixedNotFound() {
+    const error = new HoneyError({ errorKey: "not_found", status: "not_found" });
+    const payload = JSON.stringify({
+        error_key: error.errorKey,
+        fields: error.fields,
+        message: error.message,
+        status: error.status,
+        status_key: error.statusKey,
+        success: false,
+    });
+    return (nodeOut) => jsonAnswer(payload, { "content-type": "application/json" }, 404, nodeOut);
+}
+function plainNotFound(s) {
+    return (s.onNotFound === null &&
+        s.errorFormatter === defaultErrorFormatter &&
+        s.customErrorFormatter === null &&
+        s.errorFactory === null);
+}
+/** The hooks a graph's chains are compiled with, created once per graph. */
+function hooksOf(g) {
+    const s = g.settings;
+    g.hooks ??= {
+        convert: boundary(s),
+        miss: (ctx) => {
+            const state = stateOf(ctx);
+            return state.allowed === null ? make404(s, state) : make405(s, state, state.allowed);
+        },
+        notFound: fixedNotFound(),
+    };
+    return g.hooks;
+}
+/** The graph's final table, compiled with its hooks. */
+export function finalTable(g) {
+    return finalize(g, hooksOf(g));
+}
+/** 400 for a request path the normalization policy rejects. No boundary, no onError. */
+export function badRequestTarget(s, request) {
+    const error = frameworkError(s, "bad_request", "bad_request");
+    return createErrorResponse(error, s.errorFormatter, s.customErrorFormatter, {
+        format: s.errorFormat,
+        nodeOut: isNodeOutbound(request),
+        report: formatterReport(s, null),
+    });
+}
+/** The canonical path a non-canonical trailing slash redirects to, or `null`. */
+function trailingSlashTarget(s, path) {
+    if (path.length <= 1)
+        return null;
+    if (s.trailingSlash === "strip" && path.endsWith("/"))
+        return path.slice(0, -1);
+    if (s.trailingSlash === "enforce" && !path.endsWith("/"))
+        return `${path}/`;
+    return null;
+}
+/** The path under the app prefix: whole segments only; a path without the prefix passes through. */
+function afterPrefix(prefix, path) {
+    if (prefix === null)
+        return path;
+    if (path === prefix)
+        return "/";
+    return path.startsWith(prefix) && path.charCodeAt(prefix.length) === 47 ? path.slice(prefix.length) : path;
+}
+function run(state, plan, params) {
+    state.plan = plan;
+    state.trace?.routed(plan.route, state.req.method);
+    const ctx = new HoneyContext(state, plan.route, params);
+    if (plan.cv !== null)
+        Object.assign(ctx, plan.cv);
+    return plan.run(ctx);
+}
+function miss(s, final, state, allowed) {
+    if (allowed === null)
+        state.trace?.event("not_found");
+    else
+        state.trace?.event("method_not_allowed", { "http.allowed_methods": allowed.join(", ") });
+    if (allowed === null && final.notFound !== null && plainNotFound(s))
+        return final.notFound(isNodeOutbound(state.req));
+    state.allowed = allowed;
+    return run(state, final.miss, EMPTY_PARAMS);
+}
+/**
+ * A CORS preflight for a path with no OPTIONS route runs the chain of the route it asks about
+ * (`Access-Control-Request-Method`) without the handler: middleware that answers it (cors)
+ * short-circuits, else the answer is the 405 with `Allow`.
+ */
+function preflight(g, final, state, allowed) {
+    const requested = state.req.headers.get("access-control-request-method");
+    if (requested === null)
+        return null;
+    const hit = matchRoute(g.root, requested.trim().toUpperCase(), state.path);
+    if (hit === null || !hit.matched || !final.plans.has(hit.id))
+        return null;
+    const plan = final.plans.get(hit.id);
+    const hooks = hooksOf(g);
+    plan.pf ??= compileChain(plan.pfChain, hooks.miss, hooks.convert);
+    state.allowed = allowed;
+    state.plan = plan;
+    return plan.pf(new HoneyContext(state, plan.route, hit.params));
+}
+function isWebSocketUpgrade(request) {
+    return request.headers.get("upgrade")?.toLowerCase() === "websocket";
+}
+/** A plain GET to a ws-only path: the client must ask for the upgrade. */
+function upgradeRequired() {
+    return new Response("Upgrade Required", { headers: { upgrade: "websocket" }, status: 426 });
+}
+/** A ws upgrade on a ws route's path runs that route with the serving app's adapter; `null` when it is not one. */
+function upgrade(g, final, state, method) {
+    if (!final.ws || method !== "GET" || !isWebSocketUpgrade(state.req))
+        return null;
+    const ws = matchWsRoute(g.root, state.path);
+    /* a loaded ws leaf no route serves is no upgrade */
+    if (ws === null || !final.plans.has(ws.id))
+        return null;
+    state.ws = g.settings.wsAdapter;
+    return run(state, final.plans.get(ws.id), ws.params);
+}
+/** A plain GET that no HTTP route answers, on a path a ws route serves. */
+function onlyWs(g, final, state, matched) {
+    return !matched && final.ws && state.req.method === "GET" && matchWsRoute(g.root, state.path) !== null;
+}
+/** The request state of `incoming`, recorded for the request log and given its trace when they are on. */
+function newState(s, incoming, path, plan) {
+    const { env, executionCtx, request, seen } = incoming;
+    const state = { allowed: null, env, executionCtx, logger: s.logger, path, plan, req: request };
+    if (seen !== undefined) {
+        seen.state = state;
+        if (seen.trace !== undefined)
+            state.trace = seen.trace;
+    }
+    return state;
+}
+/** Serve one request from the graph. */
+function route(g, incoming) {
+    const { request } = incoming;
+    const s = g.settings;
+    const fullPath = normalizePath(pathOfUrl(request.url), s.encodedSlashes);
+    if (fullPath === null)
+        return badRequestTarget(s, request);
+    const final = finalTable(g);
+    const target = trailingSlashTarget(s, fullPath);
+    if (target !== null) {
+        /* a relative Location: the client keeps the scheme, host and port it used */
+        return new Response(null, { headers: { location: target + searchOfUrl(request.url) }, status: 308 });
+    }
+    const path = afterPrefix(s.stripPrefix, fullPath);
+    const method = request.method.toUpperCase();
+    const state = newState(s, incoming, path, final.miss);
+    /* a ws upgrade goes to the ws route on its path; an app without one never reads the header */
+    const upgraded = upgrade(g, final, state, method);
+    if (upgraded !== null)
+        return upgraded;
+    const hit = final.statics[method]?.[path] ?? (method === "HEAD" ? final.statics.GET?.[path] : undefined);
+    if (hit !== undefined)
+        return run(state, hit, EMPTY_PARAMS);
+    const match = matchRoute(g.root, method, path);
+    if (onlyWs(g, final, state, match?.matched === true))
+        return upgradeRequired();
+    if (match === null)
+        return miss(s, final, state, null);
+    if (!match.matched) {
+        const answered = method === "OPTIONS" ? preflight(g, final, state, match.allowed) : null;
+        return answered ?? miss(s, final, state, match.allowed);
+    }
+    return runMatched(s, final, state, match);
+}
+/** A matched leaf's plan; a loaded leaf no route serves, and no catch-all takes, answers like a path without one. */
+function runMatched(s, final, state, match) {
+    const plan = final.plans.get(match.id);
+    return plan === undefined ? miss(s, final, state, null) : run(state, plan, match.params);
+}
+/** The routed answer; a HEAD request's without its body, as GET's answer would be sent. */
+function routed(g, incoming) {
+    const answer = route(g, incoming);
+    if (incoming.request.method !== "HEAD")
+        return answer;
+    return answer instanceof Promise ? answer.then(headResponse) : headResponse(answer);
+}
+/**
+ * Serve one request from the graph, observed until its body ends when the request log or telemetry
+ * is on. Routing never rejects; a throw (an app that cannot finalize) ends the root and goes on.
+ */
+export function dispatch(g, request, env, executionCtx) {
+    const s = g.settings;
+    if (s.requestLog === null && s.telemetry === null)
+        return routed(g, { env, executionCtx, request, seen: undefined });
+    const trace = s.telemetry === null ? undefined : startTrace(s, s.telemetry, request, env);
+    const seen = { request, started: performance.now(), state: null, trace };
+    let answer;
+    try {
+        answer = routed(g, { env, executionCtx, request, seen });
+    }
+    catch (thrown) {
+        trace?.fail(thrown);
+        throw thrown;
+    }
+    return answer instanceof Promise ? answer.then((response) => observe(s, seen, response)) : observe(s, seen, answer);
+}

package/dist/routing/finalize.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Finalize: resolve every registered route against its graph once, and compile what it runs.
+ * A route runs `chain → scopes covering it → route middleware`; its error keys, boundary, error
+ * factory and meta come from that chain and the app it was registered on. Re-runs whenever a
+ * registration moved the graph's epoch.
+ */
+import { type RouteInfo } from "../context/context.ts";
+import type { ErrorPolicy } from "../errors/projector.ts";
+import { type ChainErrorConverter, type CompiledChain, type MaybePromise, type RuntimeMiddleware } from "../middleware/middleware.ts";
+import { type Segment, type RouteId } from "./pattern.ts";
+import { type HoneyGraph } from "./register.ts";
+/** Everything a matched route runs, compiled once. */
+export type Plan = {
+    /** `.context()` values copied onto each request context */
+    readonly cv: Readonly<Record<string, unknown>> | null;
+    /** the route's middleware as registered, untraced: what a document reads their names and error factories off */
+    readonly mw: readonly RuntimeMiddleware[];
+    readonly policy: ErrorPolicy;
+    /** what a CORS preflight for this route runs: the chain without the handler, compiled on first use */
+    pf: CompiledChain | null;
+    readonly pfChain: readonly RuntimeMiddleware[];
+    readonly route: RouteInfo;
+    /** chain + handler; never rejects */
+    readonly run: CompiledChain;
+};
+/** What dispatch compiles into every chain: the error boundary and the 404/405 answer. */
+export type FinalizeHooks = {
+    readonly convert: ChainErrorConverter;
+    readonly miss: (ctx: object) => MaybePromise<Response>;
+    /** the fixed 404, for a miss whose chain runs nothing */
+    readonly notFound: (nodeOut: boolean) => Response;
+};
+/** What one graph serves. */
+export type FinalTable = {
+    readonly epoch: number;
+    readonly miss: Plan;
+    readonly notFound: ((nodeOut: boolean) => Response) | null;
+    readonly plans: ReadonlyMap<RouteId, Plan>;
+    /** method → path → plan, for patterns without params or wildcards */
+    readonly statics: Readonly<Record<string, Readonly<Record<string, Plan>>>>;
+    /** whether any WebSocket route exists: an app without one never reads the Upgrade header */
+    readonly ws: boolean;
+};
+/** The scoped middleware a pattern runs: whole where the scope covers it, behind the path check where it covers part. */
+export declare function scopesFor(g: HoneyGraph, variants: readonly (readonly Segment[])[]): RuntimeMiddleware[];
+/** The graph's final table, recompiled only when a registration moved its epoch. */
+export declare function finalize(g: HoneyGraph, hooks: FinalizeHooks): FinalTable;