@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/routing/finalize.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { REQUEST } from "../context/context.js";
+import { withInput } from "../input/input.js";
+import { compileResponseHeaders } from "../response/response-headers.js";
+import { compileOutput, outputValidationOn, withOutput } from "../validation/validate-output.js";
+import { collectMiddlewareMeta, compileChain, } from "../middleware/middleware.js";
+import { assertTreeCurrent, delegatedRecords } from "./delegate.js";
+import { commonPrefix } from "./middleware-chain.js";
+import { canonical, expandOptional, isStaticPattern, variantsCoverage, splitRouteId, } from "./pattern.js";
+import { assertNothingDiscarded, chainErrorKeys } from "./register.js";
+import { assertSettingsAgree } from "./settings.js";
+import { answering, firing, tapsFor } from "./tap.js";
+import { dict } from "./tree.js";
+const EMPTY_META = /* @__PURE__ */ Object.freeze({});
+/** Route meta: what the middleware contributes, overlaid by everything stated explicitly. */
+function routeMeta(chain, explicit) {
+    const contributed = collectMiddlewareMeta([chain]);
+    if (contributed === null)
+        return explicit === null ? null : Object.freeze({ ...explicit });
+    return Object.freeze(explicit === null ? contributed : { ...contributed, ...explicit });
+}
+/** The keys a route may throw: the app's defaults, its chain's, its own and its boundary. */
+function declaredKeys(src, chain, own, boundaryKey) {
+    const declared = new Set([...src.defaultErrorKeys, ...chainErrorKeys(chain), ...own]);
+    if (boundaryKey !== null)
+        declared.add(boundaryKey);
+    return declared;
+}
+/**
+ * ctx.errors: a frozen copy, so a handler never reaches a factory itself. An open route (nothing
+ * declared) gets every key of the app's factory; a declared key comes from the factory the route
+ * named, else the app's.
+ */
+function ctxErrors(factory, named, declared) {
+    if (factory === null && named === null)
+        return null;
+    const subset = Object.create(null);
+    if (declared === null)
+        return Object.freeze(Object.assign(subset, factory));
+    for (const key of declared) {
+        const from = named !== null && Object.hasOwn(named, key) ? named : factory;
+        if (from !== null && Object.hasOwn(from, key))
+            subset[key] = from[key];
+    }
+    return Object.freeze(subset);
+}
+/** The error keys, boundary and factory a chain resolves to under `src`'s defaults. */
+function resolveErrors(src, chain, route) {
+    const boundaryKey = route?.rb ?? src.defaultBoundaryKey;
+    const keys = declaredKeys(src, chain, route?.dk ?? new Set(), boundaryKey);
+    const declared = keys.size > 0 ? keys : null;
+    const errors = ctxErrors(src.errorFactory, route?.ef ?? null, declared);
+    return { errors, policy: { boundaryKey, declared, factory: src.errorFactory } };
+}
+/** The scoped middleware a pattern runs: whole where the scope covers it, behind the path check where it covers part. */
+export function scopesFor(g, variants) {
+    const out = [];
+    for (const entry of g.scoped) {
+        const coverage = variantsCoverage(variants, entry.segs);
+        if (coverage === "all")
+            out.push(entry.mw);
+        else if (coverage === "some")
+            out.push(entry.guard);
+    }
+    return out;
+}
+/** The runtime's `process`, where there is one (Node, Bun); Workers have none. */
+function globalProcess() {
+    return globalThis.process;
+}
+/** The request's trace: an app with telemetry traces every request it serves, and only its chains are wrapped. */
+function traceOf(ctx) {
+    return ctx[REQUEST].trace;
+}
+/** `mw` inside a `middleware.<name>` span on a traced request. */
+function tracedMiddleware(mw) {
+    const name = `middleware.${mw.name || "anonymous"}`;
+    return (ctx, next) => traceOf(ctx).within(name, () => mw(ctx, next));
+}
+/** The route handler inside an `http.handler` span, active for the app's own instrumentation. */
+function tracedHandler(handler) {
+    return (ctx) => {
+        const trace = traceOf(ctx);
+        return trace.within("http.handler", (span) => trace.run(span, () => handler(ctx)));
+    };
+}
+function planRoute(g, r, variants, hooks) {
+    const src = r.own.errorFactory === null ? g.settings : r.own;
+    const chain = [...r.cm, ...scopesFor(g, variants), ...r.rm];
+    const { errors, policy } = resolveErrors(src, chain, r);
+    const meta = routeMeta(chain, r.xm);
+    r.mt = meta;
+    /* only a route with taps pays for them: the handler marks its answer, the chain fires after */
+    const taps = tapsFor(g.settings, r.own);
+    const traced = g.settings.telemetry !== null;
+    const run = traced ? chain.map(tracedMiddleware) : chain;
+    /* only a route with .input() pays for it: the step runs between the middleware and the handler */
+    const input = r.in === null ? r.fn : withInput(r.in, r.fn);
+    /* only a route with .output() in an app checking answers pays for the check */
+    const checked = r.out !== null && outputValidationOn(g.settings.outputValidation, globalProcess());
+    const fn = checked
+        ? withOutput(compileOutput(r.out, compileResponseHeaders(r.out.headers)), input)
+        : input;
+    const handler = traced ? tracedHandler(taps === null ? fn : answering(fn)) : taps === null ? fn : answering(fn);
+    const compiled = compileChain(run, handler, hooks.convert);
+    return {
+        cv: r.cv,
+        mw: chain,
+        pf: null,
+        pfChain: run,
+        policy,
+        route: { errors, id: r.id, meta: meta ?? EMPTY_META, pattern: r.rp },
+        run: taps === null ? compiled : firing(compiled, taps),
+    };
+}
+/**
+ * 404 and 405 run through the same pipeline as a route: the middleware every route starts with
+ * (with no routes: every handle that served a request), then every scope behind its path check.
+ * So an app-wide logger or CORS policy covers unknown paths, and a scope's guard answers before
+ * "not found" leaks what exists under it.
+ */
+function planMiss(g, hooks) {
+    const chains = [...g.records.values()].map((r) => r.cm);
+    const prefix = commonPrefix(chains.length > 0 ? chains : [...g.served]);
+    const chain = [...prefix, ...g.scoped.map((entry) => entry.guard)];
+    const { errors, policy } = resolveErrors(g.settings, chain, null);
+    const meta = routeMeta(chain, null);
+    const run = g.settings.telemetry === null ? chain : chain.map(tracedMiddleware);
+    return {
+        cv: null,
+        mw: chain,
+        pf: null,
+        pfChain: run,
+        policy,
+        route: { errors, id: "", meta: meta ?? EMPTY_META, pattern: "" },
+        run: compileChain(run, hooks.miss, hooks.convert),
+    };
+}
+/** The graph's final table, recompiled only when a registration moved its epoch. */
+export function finalize(g, hooks) {
+    if (g.final !== null && g.final.epoch === g.epoch)
+        return g.final;
+    assertNothingDiscarded(g);
+    assertSettingsAgree(g.settings);
+    assertTreeCurrent(g);
+    const plans = new Map();
+    const statics = dict();
+    let ws = false;
+    for (const [id, r] of [...g.records, ...delegatedRecords(g)]) {
+        const variants = expandOptional(r.sg);
+        const plan = planRoute(g, r, variants, hooks);
+        plans.set(id, plan);
+        const { method } = splitRouteId(id);
+        if (method === "WS")
+            ws = true;
+        for (const variant of variants) {
+            if (isStaticPattern(variant))
+                (statics[method] ??= dict())[canonical(variant)] = plan;
+        }
+    }
+    const miss = planMiss(g, hooks);
+    g.final = { epoch: g.epoch, miss, notFound: miss.pfChain.length === 0 ? hooks.notFound : null, plans, statics, ws };
+    return g.final;
+}

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

@@ -0,0 +1,19 @@
+import { GRAPH, type HoneyGraph } from "./register.ts";
+import { type RouteTree } from "./tree.ts";
+type App = {
+    readonly [GRAPH]: HoneyGraph;
+};
+/**
+ * The tree a gateway serves: `source` (its services' merged routes) with the gateway's own routes
+ * as further leaves. Its root wildcards stay out, as the catch-all the services' routes delegate
+ * to, and so do the routes it serves about itself (serveOpenApi, serveManifest). An own route that is also a service route throws, unless `source` is the gateway's own snapshot.
+ */
+export declare function gatewayTree(app: App, source: RouteTree): RouteTree;
+/**
+ * Give `app`'s routes the input and output declarations `source` holds for them where they
+ * declare none: a gateway documents each service route by the service's schemas. Its own stay.
+ * A gateway serving its generated tree holds its services' routes as loaded leaves, without a
+ * record (bit 19 h2): those leaves take the schemas the same way.
+ */
+export declare function overlaySchemas(app: App, source: RouteTree): void;
+export {};

package/dist/routing/gateway-tree.js

@@ -0,0 +1,74 @@
+/**
+ * Generate time, for a gateway: the tree it serves (its services' routes and its own) and the
+ * schemas it documents its services' routes with. Pure: the gateway serves the result through
+ * `routeTree()` like any generated tree.
+ */
+import { expandOptional, parsePattern, splitRouteId } from "./pattern.js";
+import { GRAPH, isServed } from "./register.js";
+import { snapshotRouteTree } from "./route-tree.js";
+import { assertTreeFormat, cloneTree, dict, insertLeaf, ROUTE_TREE_VERSION, } from "./tree.js";
+/** An entry as a generated file carries it: data only, no live record. */
+function dataOf({ h: _live, ...data }) {
+    return data;
+}
+const isRootWildcard = (id) => {
+    const segments = parsePattern(splitRouteId(id).pattern);
+    return segments.length === 1 && segments[0]?.k === "wildcard";
+};
+/**
+ * The tree a gateway serves: `source` (its services' merged routes) with the gateway's own routes
+ * as further leaves. Its root wildcards stay out, as the catch-all the services' routes delegate
+ * to, and so do the routes it serves about itself (serveOpenApi, serveManifest). An own route that is also a service route throws, unless `source` is the gateway's own snapshot.
+ */
+export function gatewayTree(app, source) {
+    assertTreeFormat(source);
+    const g = app[GRAPH];
+    const routes = dict();
+    for (const [id, entry] of Object.entries(source.routes))
+        routes[id] = dataOf(entry);
+    /* a route the app serves about itself stays out, as in its snapshot: each app serving the tree mounts its own */
+    const own = [...g.records].filter(([id, r]) => !isRootWildcard(id) && !isServed(r)).map(([id]) => id);
+    const shadowed = own.filter((id) => Object.hasOwn(routes, id));
+    const served = (id) => g.records.has(id) || g.catchAll.has(id);
+    const self = own.length > 0 && shadowed.length === own.length && Object.keys(routes).every(served);
+    if (shadowed.length > 0 && !self) {
+        throw new Error(`Gateway routes are also downstream routes in the merged tree: ${shadowed.join(", ")}`);
+    }
+    const root = cloneTree(source.root);
+    if (!self) {
+        const snapshot = snapshotRouteTree(g);
+        for (const id of own) {
+            const { method } = splitRouteId(id);
+            for (const variant of expandOptional(g.records.get(id).sg))
+                insertLeaf(root, variant, method, id);
+            routes[id] = dataOf(snapshot.routes[id]);
+        }
+    }
+    return { meta: { ...source.meta }, root, routes, v: ROUTE_TREE_VERSION };
+}
+/**
+ * Give `app`'s routes the input and output declarations `source` holds for them where they
+ * declare none: a gateway documents each service route by the service's schemas. Its own stay.
+ * A gateway serving its generated tree holds its services' routes as loaded leaves, without a
+ * record (bit 19 h2): those leaves take the schemas the same way.
+ */
+export function overlaySchemas(app, source) {
+    const g = app[GRAPH];
+    const leaves = dict();
+    for (const [id, entry] of Object.entries(source.routes)) {
+        const target = g.records.get(id);
+        const leaf = g.loaded?.[id];
+        if (target !== undefined)
+            g.records.set(id, { ...target, ...schemasOf(target, entry) });
+        else if (leaf !== undefined)
+            leaves[id] = { ...leaf, ...schemasOf(leaf, entry) };
+    }
+    if (g.loaded !== null && Object.keys(leaves).length > 0)
+        g.loaded = Object.assign(dict(), g.loaded, leaves);
+    g.epoch++;
+}
+/** `target`'s own schemas, else what `entry` declares, else its live record's. */
+function schemasOf(target, entry) {
+    const live = entry.h;
+    return { iv: target.iv ?? entry.iv ?? live?.iv ?? null, out: target.out ?? entry.out ?? live?.out ?? null };
+}

package/dist/routing/invalidate-check.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Codegen-time check: mutations that declare no `invalidate`.
+ *
+ * A correctness signal, not a documentation one: `x-invalidate` drives generated SDK behavior (the
+ * Rust and Go clients expand it into an invalidation post-flight, the Python client reads it), so a
+ * mutation with no `invalidate` produces clients that refresh nothing after the call.
+ *
+ * It warns and never blocks by default: plenty of mutations correctly invalidate nothing (login,
+ * logout, webhook receipt) and plenty of honey users never generate an SDK. A rule that fails the
+ * build teaches people to paste the shortest token that makes it pass. This module only decides;
+ * the OpenAPI emitter throws or logs the report.
+ */
+/** How a missing `invalidate` is reported. Default `"warn"`. */
+export type InvalidateCheckLevel = "error" | "off" | "warn";
+export type InvalidateCheckConfig = {
+    /**
+     * Operation extension naming the entity an operation touches, e.g. `"x-entity"`. A mutation and
+     * a read carrying the same value is a sharper signal than path shape. honey does not own the
+     * key's name; the app says which one it uses.
+     */
+    entityKey?: string;
+    level?: InvalidateCheckLevel;
+} | InvalidateCheckLevel;
+export type InvalidateCheckOperation = {
+    /** lowercased HTTP method */
+    method: string;
+    /** route meta as authored, to tell "absent" from a deliberate "nothing" */
+    meta: Record<string, unknown> | null;
+    /** the emitted operation object */
+    operation: Record<string, unknown>;
+    /** OpenAPI-style path */
+    path: string;
+};
+export type InvalidateFinding = {
+    /** read operations that make this mutation look like an oversight */
+    affects: string[];
+    method: string;
+    path: string;
+};
+/** The level an `invalidate` config reports at. */
+export declare function invalidateLevel(config: InvalidateCheckConfig | undefined): InvalidateCheckLevel;
+/** Mutations with no `invalidate` that the document suggests should have one. */
+export declare function findMissingInvalidate(operations: readonly InvalidateCheckOperation[], entityKey: string | undefined): InvalidateFinding[];
+/**
+ * The report for mutations with no `invalidate`, or `null` when the check is off or finds nothing.
+ * One summary, never one line per operation: a warning that fires 53 times gets filtered out of
+ * the log; one that fires once and lists 10 gets read.
+ */
+export declare function missingInvalidateReport(operations: readonly InvalidateCheckOperation[], config: InvalidateCheckConfig | undefined): string | null;
+/**
+ * `invalidate` selectors that name no route. A selector is `"<METHOD> <pattern>"`, exactly as the
+ * generated `RouteSelector` union spells it; anything else invalidates nothing at runtime.
+ */
+export declare function findInvalidSelectors(operations: readonly InvalidateCheckOperation[], inventory: ReadonlySet<string>): Array<{
+    method: string;
+    path: string;
+    selector: unknown;
+}>;

package/dist/routing/invalidate-check.js

@@ -0,0 +1,124 @@
+/**
+ * Codegen-time check: mutations that declare no `invalidate`.
+ *
+ * A correctness signal, not a documentation one: `x-invalidate` drives generated SDK behavior (the
+ * Rust and Go clients expand it into an invalidation post-flight, the Python client reads it), so a
+ * mutation with no `invalidate` produces clients that refresh nothing after the call.
+ *
+ * It warns and never blocks by default: plenty of mutations correctly invalidate nothing (login,
+ * logout, webhook receipt) and plenty of honey users never generate an SDK. A rule that fails the
+ * build teaches people to paste the shortest token that makes it pass. This module only decides;
+ * the OpenAPI emitter throws or logs the report.
+ */
+const MUTATION_METHODS = ["delete", "patch", "post", "put"];
+const MAX_LISTED = 20;
+function resolveConfig(config) {
+    if (config === undefined)
+        return { level: "warn" };
+    if (typeof config === "string")
+        return { level: config };
+    return { entityKey: config.entityKey, level: config.level ?? "warn" };
+}
+/** The level an `invalidate` config reports at. */
+export function invalidateLevel(config) {
+    return resolveConfig(config).level;
+}
+/**
+ * Did the author record a decision? `null` and `[]` both say "this mutation refreshes nothing";
+ * absent says nothing at all, which is what this check looks for.
+ */
+function declaredNothing(meta) {
+    if (meta === null || !Object.hasOwn(meta, "invalidate"))
+        return false;
+    const value = meta.invalidate;
+    return value === null || (Array.isArray(value) && value.length === 0);
+}
+const nonEmpty = (value) => Array.isArray(value) && value.length > 0;
+/** Declared in the meta, or emitted: a profile that leaves `x-invalidate` out must not make every mutation look undeclared. */
+function alreadyInvalidates(entry) {
+    return nonEmpty(entry.meta?.invalidate) || nonEmpty(entry.operation["x-invalidate"]);
+}
+/**
+ * Paths a mutation plausibly affects: its own, and its collection when it targets an item.
+ * `DELETE /tables/{id}` affects `GET /tables/{id}` and `GET /tables`.
+ */
+function pathFamily(path) {
+    const segments = path.split("/");
+    const last = segments.at(-1);
+    const item = last.startsWith("{") && last.endsWith("}") && segments.length > 2;
+    return item ? [path, segments.slice(0, -1).join("/")] : [path];
+}
+function entityOf(entry, entityKey) {
+    const entity = entityKey === undefined ? undefined : entry.operation[entityKey];
+    return entity === undefined || entity === null ? null : JSON.stringify(entity);
+}
+function readIndex(operations, entityKey) {
+    const paths = new Set();
+    const byEntity = new Map();
+    for (const entry of operations.filter((o) => o.method === "get")) {
+        paths.add(entry.path);
+        const entity = entityOf(entry, entityKey);
+        if (entity !== null)
+            byEntity.set(entity, [...(byEntity.get(entity) ?? []), `GET ${entry.path}`]);
+    }
+    return { byEntity, paths };
+}
+/** Mutations with no `invalidate` that the document suggests should have one. */
+export function findMissingInvalidate(operations, entityKey) {
+    const reads = readIndex(operations, entityKey);
+    const undeclared = operations.filter((e) => MUTATION_METHODS.includes(e.method) && !alreadyInvalidates(e) && !declaredNothing(e.meta));
+    return undeclared.flatMap((entry) => {
+        const entity = entityOf(entry, entityKey);
+        /* the same entity read elsewhere is sharper than path shape; with no tagged reader, path shape still speaks */
+        const byEntity = entity === null ? [] : (reads.byEntity.get(entity) ?? []);
+        const affects = byEntity.length > 0
+            ? byEntity
+            : pathFamily(entry.path)
+                .filter((p) => reads.paths.has(p))
+                .map((p) => `GET ${p}`);
+        return affects.length === 0 ? [] : [{ affects, method: entry.method.toUpperCase(), path: entry.path }];
+    });
+}
+/**
+ * The report for mutations with no `invalidate`, or `null` when the check is off or finds nothing.
+ * One summary, never one line per operation: a warning that fires 53 times gets filtered out of
+ * the log; one that fires once and lists 10 gets read.
+ */
+export function missingInvalidateReport(operations, config) {
+    const { entityKey, level } = resolveConfig(config);
+    if (level === "off")
+        return null;
+    const findings = findMissingInvalidate(operations, entityKey);
+    if (findings.length === 0)
+        return null;
+    const width = Math.max(...findings.map((f) => f.method.length));
+    const shown = findings
+        .slice(0, MAX_LISTED)
+        .map((f) => `  ${f.method.padEnd(width)} ${f.path} → ${f.affects.join(", ")}`);
+    const more = findings.length > shown.length ? `\n  … and ${findings.length - shown.length} more` : "";
+    return (`[honey:invalidate] ${findings.length} mutation(s) declare no \`invalidate\`, but the document has ` +
+        "read routes they plausibly affect.\nGenerated SDK clients refresh nothing after these calls.\n" +
+        `${shown.join("\n")}${more}\n` +
+        "Declare the routes each one refreshes, or `invalidate: null` to record that it refreshes nothing.");
+}
+/**
+ * `invalidate` selectors that name no route. A selector is `"<METHOD> <pattern>"`, exactly as the
+ * generated `RouteSelector` union spells it; anything else invalidates nothing at runtime.
+ */
+export function findInvalidSelectors(operations, inventory) {
+    const out = [];
+    const seen = new Set();
+    for (const entry of operations) {
+        const declared = entry.meta?.invalidate;
+        if (!Array.isArray(declared))
+            continue;
+        for (const selector of declared) {
+            const key = `${entry.method} ${entry.path} ${String(selector)}`;
+            if ((typeof selector === "string" && inventory.has(selector)) || seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ method: entry.method.toUpperCase(), path: entry.path, selector });
+        }
+    }
+    return out;
+}

package/dist/routing/match.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Request matching over the route tree. Depth-first in precedence order (static, then param, then
+ * wildcard), retrying the next branch on a dead end and on a method miss. A trie node sits at one
+ * depth, so each node is visited at most once per request: the walk is linear in the route set,
+ * and recursion depth is bounded by the deepest registered route, not by the request path.
+ */
+import type { RouteId } from "./pattern.ts";
+import { type TreeNode } from "./tree.ts";
+import type { HttpMethod } from "./types.ts";
+export type MatchResult = {
+    allowed: HttpMethod[];
+    matched: false;
+} | {
+    id: RouteId;
+    matched: true;
+    params: Record<string, string>;
+} | null;
+export declare function matchRoute(root: TreeNode, method: HttpMethod | string, path: string): MatchResult;
+export declare function matchWsRoute(root: TreeNode, path: string): {
+    id: RouteId;
+    params: Record<string, string>;
+} | null;

package/dist/routing/match.js

@@ -0,0 +1,108 @@
+import { dict } from "./tree.js";
+function decode(s) {
+    if (!s.includes("%"))
+        return s;
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        /* a malformed escape is client data: the param keeps it as written */
+        return s;
+    }
+}
+/** The exact method, then GET for HEAD, then ALL. */
+function pickMethod(m, method) {
+    return m[method] ?? (method === "HEAD" ? m.GET : undefined) ?? m.ALL;
+}
+function addAllowed(st, m) {
+    st.allowed ??= new Set();
+    /* a map holding ALL never misses (pickMethod falls back to it), so every key here is a method */
+    for (const k in m)
+        st.allowed.add(k);
+}
+/** A wildcard's leaf for the method, capturing `rest`; on a method miss its methods join Allow. */
+function wildcardHit(node, rest, st) {
+    if (node.w === null)
+        return undefined;
+    const id = pickMethod(node.w.m, st.method);
+    if (id === undefined) {
+        addAllowed(st, node.w.m);
+        return undefined;
+    }
+    st.names.push(node.w.n);
+    st.values.push(rest);
+    return id;
+}
+function skipSlashes(path, pos) {
+    let at = pos;
+    while (path.charCodeAt(at) === 47)
+        at++;
+    return at;
+}
+/** The leaf at the end of the path: this node's methods, else an empty wildcard below it. */
+function endOfPath(node, st) {
+    if (node.m !== null) {
+        const id = pickMethod(node.m, st.method);
+        if (id !== undefined)
+            return id;
+        addAllowed(st, node.m);
+    }
+    return wildcardHit(node, "", st);
+}
+/** Try the param branch with `seg` bound; unbind it again on a dead end. */
+function tryParam(node, seg, end, st) {
+    if (node.d === null)
+        return undefined;
+    const depth = st.names.length;
+    st.names.push(node.d.n);
+    st.values.push(decode(seg));
+    const id = st.walk(node.d.c, end, st);
+    if (id !== undefined)
+        return id;
+    st.names.length = depth;
+    st.values.length = depth;
+    return undefined;
+}
+function walk(node, from, st) {
+    const pos = skipSlashes(st.path, from);
+    if (pos >= st.path.length)
+        return endOfPath(node, st);
+    const slash = st.path.indexOf("/", pos);
+    const end = slash === -1 ? st.path.length : slash;
+    const seg = st.path.substring(pos, end);
+    const staticChild = node.s[seg];
+    const viaStatic = staticChild === undefined ? undefined : walk(staticChild, end, st);
+    return viaStatic ?? tryParam(node, seg, end, st) ?? wildcardHit(node, decode(st.path.substring(pos)), st);
+}
+function paramsOf(st) {
+    const params = dict();
+    st.names.forEach((name, i) => {
+        params[name] = st.values[i];
+    });
+    return params;
+}
+export function matchRoute(root, method, path) {
+    const st = { allowed: null, method, names: [], path, values: [], walk };
+    const id = walk(root, 0, st);
+    if (id !== undefined)
+        return { id, matched: true, params: paramsOf(st) };
+    if (st.allowed !== null)
+        return { allowed: [...st.allowed], matched: false };
+    return null;
+}
+function walkWs(node, from, st) {
+    const pos = skipSlashes(st.path, from);
+    if (pos >= st.path.length)
+        return node.ws ?? undefined;
+    const slash = st.path.indexOf("/", pos);
+    const end = slash === -1 ? st.path.length : slash;
+    const seg = st.path.substring(pos, end);
+    const staticChild = node.s[seg];
+    const viaStatic = staticChild === undefined ? undefined : walkWs(staticChild, end, st);
+    return viaStatic ?? tryParam(node, seg, end, st);
+}
+export function matchWsRoute(root, path) {
+    const st = { allowed: null, method: "WS", names: [], path, values: [], walk: walkWs };
+    const id = walkWs(root, 0, st);
+    return id === undefined ? null : { id, params: paramsOf(st) };
+}

package/dist/routing/middleware-chain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dispatch-side middleware helpers, run once at finalize: the request-path guard behind a scoped
+ * `use()`, and what 404/405 run (the run of middleware every route starts with). Tracing wraps
+ * middleware in telemetry/request-trace.ts.
+ */
+import type { RuntimeMiddleware } from "../middleware/middleware.ts";
+import { type Segment } from "./pattern.ts";
+/** The error keys a middleware declares (`defineMiddleware`). */
+export declare function errorsOf(mw: RuntimeMiddleware): readonly string[] | undefined;
+/** The factory a middleware's error keys come from (`defineMiddleware`). */
+export declare function errorFactoryOf(mw: RuntimeMiddleware): Readonly<Record<string, unknown>> | undefined;
+/** A scoped middleware behind a request-path check: it runs only when the path is inside the scope. */
+export declare function scopeGuard(segs: readonly Segment[], mw: RuntimeMiddleware): RuntimeMiddleware;
+/** The longest run of middleware every chain starts with: what 404 and 405 run. */
+export declare function commonPrefix(chains: ReadonlyArray<readonly RuntimeMiddleware[]>): RuntimeMiddleware[];
+export declare function describeMw(mw: RuntimeMiddleware): string;

package/dist/routing/middleware-chain.js

@@ -0,0 +1,41 @@
+import { pathInScope } from "./pattern.js";
+/** The error keys a middleware declares (`defineMiddleware`). */
+export function errorsOf(mw) {
+    return mw.errors;
+}
+/** The factory a middleware's error keys come from (`defineMiddleware`). */
+export function errorFactoryOf(mw) {
+    return mw.errorFactory;
+}
+/** A scoped middleware behind a request-path check: it runs only when the path is inside the scope. */
+export function scopeGuard(segs, mw) {
+    const guard = (ctx, next) => (pathInScope(ctx.path, segs) ? mw(ctx, next) : next());
+    Object.defineProperty(guard, "name", { configurable: true, value: mw.name });
+    const errors = errorsOf(mw);
+    const factory = errorFactoryOf(mw);
+    const meta = mw.meta;
+    if (errors)
+        Object.defineProperty(guard, "errors", { value: errors });
+    if (factory)
+        Object.defineProperty(guard, "errorFactory", { value: factory });
+    if (meta)
+        Object.defineProperty(guard, "meta", { value: meta });
+    return guard;
+}
+/** The longest run of middleware every chain starts with: what 404 and 405 run. */
+export function commonPrefix(chains) {
+    const [first, ...rest] = chains;
+    if (first === undefined)
+        return [];
+    let n = first.length;
+    for (const chain of rest) {
+        let i = 0;
+        while (i < n && i < chain.length && chain[i] === first[i])
+            i++;
+        n = i;
+    }
+    return first.slice(0, n);
+}
+export function describeMw(mw) {
+    return mw.name ? `"${mw.name}"` : "an anonymous middleware";
+}