@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

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

@@ -0,0 +1,91 @@
+/**
+ * The `.output()` type algebra: what a route declares it answers (a media type's bodies by status
+ * key, its redirects, the headers of each status), and ctx.res narrowed to it. A declared helper
+ * takes only the declared status keys, each body typed by its status's schema and its options
+ * carrying the status's declared headers; an undeclared one is gone; noContent, raw, redirect and
+ * stream are always there; sse only for an event stream; binary for octet-stream or an open type.
+ */
+import type { BinaryBody } from "../response/binary.ts";
+import type { HoneyRes, ResponseOptions, TypedResponse } from "../response/response.ts";
+import type { StatusKey } from "../response/status.ts";
+import type { InferInput, InferOutput, StandardSchemaLike } from "../validation/standard-schema.ts";
+/** A media type's declared bodies by status key: a schema, or `true` for a body with none. */
+export type StatusSchemas = {
+    readonly [K in StatusKey]?: StandardSchemaLike | true;
+};
+/** The headers each status carries, by status key: a schema over the headers by lowercased name. */
+export type HeaderSchemas = {
+    readonly [K in StatusKey]?: StandardSchemaLike;
+};
+/** Redirect statuses a route declares, for the generators: no body, no schema. */
+export type RedirectStatuses = {
+    readonly [K in StatusKey]?: true;
+};
+/**
+ * What `.output()` takes: each media type it answers with (`type/subtype`), the redirects it may
+ * answer (`redirect`), and the headers each status carries (`headers`).
+ */
+export type OutputSchemas = {
+    readonly [mediaType: `${string}/${string}`]: StatusSchemas;
+} & {
+    readonly headers?: HeaderSchemas;
+    readonly redirect?: RedirectStatuses;
+};
+/**
+ * `TOutput` with every key under a media type, `headers` or `redirect` that names no status, and every outer key
+ * that is none of those, mapped to `never`: intersected with the declaration, a typo is an error where it is
+ * written. `assertOutputKeys` (openapi/output-keys.ts) refuses the same keys where an app is documented.
+ */
+export type KnownStatusKeys<TOutput> = {
+    readonly [CT in keyof TOutput]: CT extends `${string}/${string}` | "headers" | "redirect" ? {
+        readonly [K in keyof TOutput[CT]]: K extends StatusKey ? TOutput[CT][K] : never;
+    } : never;
+};
+/** The helper each media type is answered with. */
+type HelperOf = {
+    "application/json": "json";
+    "application/xml": "xml";
+    "text/csv": "csv";
+    "text/event-stream": "sse";
+    "text/html": "html";
+    "text/plain": "text";
+};
+/** The media types answered through `binary`: octet-stream and any type no other helper answers. */
+type BinaryTypes<TOutput> = Exclude<Extract<keyof TOutput, `${string}/${string}`>, keyof HelperOf>;
+/** The helpers a declaration allows. */
+export type AllowedResMethods<TOutput> = {
+    [CT in keyof HelperOf]: CT extends keyof TOutput ? HelperOf[CT] : never;
+}[keyof HelperOf] | ([BinaryTypes<TOutput>] extends [never] ? never : "binary");
+/** The helpers every route keeps, whatever it declares. */
+type UniversalRes = Pick<HoneyRes, "noContent" | "raw" | "redirect" | "stream">;
+/** A declared body's type: its schema's output; `unknown` for a body declared without one. */
+type BodyOf<S> = S extends StandardSchemaLike ? InferOutput<S> : unknown;
+/** The header schema status `K` declares, or `never`. */
+type HeadersOf<TOutput, K> = TOutput extends {
+    readonly headers?: infer H;
+} ? K extends keyof NonNullable<H> ? Exclude<NonNullable<H>[K], undefined> : never : never;
+/** The headers status `K` must carry in its options: its declared ones, others beside them. */
+type HeaderOpt<TOutput, K> = [HeadersOf<TOutput, K>] extends [never] ? {} : {
+    headers: InferInput<HeadersOf<TOutput, K>> & Record<string, string>;
+};
+/** The options for status `K`: required when it declares headers, optional otherwise. */
+type OptsFor<TOutput, K, TExtra = {}> = [HeadersOf<TOutput, K>] extends [never] ? [opts?: ResponseOptions & TExtra] : [opts: ResponseOptions & TExtra & HeaderOpt<TOutput, K>];
+/** `method` narrowed to `CT`'s declared status keys, the body typed (`json`) or text (the others). */
+type Narrowed<TOutput, CT extends keyof HelperOf, TText extends boolean> = CT extends keyof TOutput ? {
+    [M in HelperOf[CT]]: <K extends keyof TOutput[CT] & StatusKey>(statusKey: K, body: TText extends true ? string : BodyOf<TOutput[CT][K]>, ...opts: OptsFor<TOutput, K>) => TypedResponse<CT, K>;
+} : {};
+/** `binary` for a declared open type, its content type named; octet-stream may leave it out. */
+type BinaryCall<TOutput> = (<CT extends BinaryTypes<TOutput>, K extends keyof TOutput[CT] & StatusKey>(statusKey: K, body: BinaryBody, opts: ResponseOptions & HeaderOpt<TOutput, K> & {
+    contentType: CT;
+}) => TypedResponse<CT, K>) & ("application/octet-stream" extends keyof TOutput ? <K extends keyof TOutput["application/octet-stream"] & StatusKey>(statusKey: K, body: BinaryBody, ...opts: OptsFor<TOutput, K, {
+    contentType?: "application/octet-stream";
+}>) => TypedResponse<"application/octet-stream", K> : unknown);
+/** ctx.res for a route declaring `TOutput`. */
+type OutputRes<TOutput> = UniversalRes & Narrowed<TOutput, "application/json", false> & Narrowed<TOutput, "text/plain", true> & Narrowed<TOutput, "text/html", true> & Narrowed<TOutput, "application/xml", true> & Narrowed<TOutput, "text/csv", true> & ("text/event-stream" extends keyof TOutput ? Pick<HoneyRes, "sse"> : {}) & ([BinaryTypes<TOutput>] extends [never] ? {} : {
+    binary: BinaryCall<TOutput>;
+});
+/** `TCtx` with ctx.res narrowed to `TOutput`; a route without `.output()` keeps the whole HoneyRes. */
+export type ApplyOutput<TCtx, TOutput> = [TOutput] extends [never] ? TCtx : Omit<TCtx, "res"> & {
+    readonly res: OutputRes<TOutput>;
+};
+export {};

package/dist/routing/output-types.js

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

package/dist/routing/pattern.d.ts

@@ -0,0 +1,55 @@
+export type StaticSegment = {
+    readonly k: "static";
+    readonly v: string;
+};
+export type ParamSegment = {
+    readonly k: "param";
+    readonly n: string;
+    readonly o: boolean;
+};
+export type WildcardSegment = {
+    readonly k: "wildcard";
+    readonly n: string;
+};
+export type Segment = ParamSegment | StaticSegment | WildcardSegment;
+/** `METHOD /canonical/pattern`: the stable identity of a route across apps, trees and codegen. */
+export type RouteId = string;
+/** How much of a route a scope covers: every path it serves, none, or only some. */
+export type ScopeCoverage = "all" | "none" | "some";
+/** Name given to a `*` wildcard without a name. */
+export declare const UNNAMED_WILDCARD = "*";
+export declare function parsePattern(path: string): Segment[];
+export declare function formatSegment(seg: Segment): string;
+/** Canonical pattern string: leading slash, no empty segments, no trailing slash. */
+export declare function canonical(segments: readonly Segment[]): string;
+/** Parse and re-print; throws on anything the grammar cannot express. */
+export declare function normalizePattern(path: string): string;
+/** Join two patterns: `joinPatterns("/api/", "users")` is `/api/users`. */
+export declare function joinPatterns(base: string, path: string): string;
+/** Concrete variants: an optional last param yields the pattern with and without it. */
+export declare function expandOptional(segments: readonly Segment[]): Segment[][];
+export declare function isStaticPattern(segments: readonly Segment[]): boolean;
+/** Parameter and wildcard names, in order. */
+export declare function patternParams(segments: readonly Segment[]): string[];
+export declare function routeId(method: string, pattern: string): RouteId;
+/** Split a RouteId back into method and canonical pattern. */
+export declare function splitRouteId(id: RouteId): {
+    method: string;
+    pattern: string;
+};
+/** OpenAPI path template: `:id` and named wildcards become `{name}`. */
+export declare function toOpenApiTemplate(segments: readonly Segment[]): string;
+/**
+ * Decide at registration whether a scope covers a route. `"some"` means the answer depends on the
+ * request path (a route param or wildcard can land inside the scope), so the scope's middleware is
+ * guarded by {@link pathInScope} at request time.
+ */
+export declare function scopeCoverage(route: readonly Segment[], scope: readonly Segment[]): ScopeCoverage;
+/** {@link scopeCoverage} for a route already expanded into its optional-param variants, so finalize expands each route once, not once per scope. */
+export declare function variantsCoverage(variants: readonly (readonly Segment[])[], scope: readonly Segment[]): ScopeCoverage;
+/**
+ * Is a request path inside a scope? Splits the path the way the router does (empty segments
+ * dropped) and compares each segment both as sent and percent-decoded, so a route param that
+ * decodes to a scoped literal is guarded exactly like the literal.
+ */
+export declare function pathInScope(path: string, scope: readonly Segment[]): boolean;

package/dist/routing/pattern.js

@@ -0,0 +1,219 @@
+/**
+ * The one route-pattern grammar. Registration, the router tree, scope matching, codegen selectors
+ * and OpenAPI paths all consume the parsed form; nothing re-derives params from a pattern string
+ * with its own regex.
+ *
+ *     pattern  = "/" | ("/" segment)+ ["/"]
+ *     segment  = static | param | wildcard
+ *     param    = ":" name ["?"]        optional only as the last segment
+ *     wildcard = "*" [name]            last segment only; unnamed is called "*"
+ *     name     = [A-Za-z_$][A-Za-z0-9_$-]*
+ *
+ * Empty segments are dropped (`//a` is `/a`), a trailing slash is not significant, and a pattern
+ * without a leading slash gets one. `.` and `..` segments are rejected.
+ */
+import { encodeSegment } from "./request-path.js";
+const NAME = /^[A-Za-z_$][A-Za-z0-9_$-]*$/;
+/* `%2e` is a dot to every URL parser, so `/%2e%2e` can never be requested either */
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+/** Name given to a `*` wildcard without a name. */
+export const UNNAMED_WILDCARD = "*";
+function invalid(path, why) {
+    throw new Error(`Invalid route pattern "${path}": ${why}`);
+}
+function paramSegment(path, seg, names) {
+    const optional = seg.endsWith("?");
+    const name = optional ? seg.slice(1, -1) : seg.slice(1);
+    if (!NAME.test(name)) {
+        invalid(path, `parameter ":${name}" is not a valid name (letters, digits, "_", "$" and "-"; it takes the whole segment)`);
+    }
+    if (names.has(name))
+        invalid(path, `parameter ":${name}" appears twice`);
+    names.add(name);
+    return { k: "param", n: name, o: optional };
+}
+function wildcardSegment(path, seg, names) {
+    const name = seg.length > 1 ? seg.slice(1) : UNNAMED_WILDCARD;
+    if (name !== UNNAMED_WILDCARD && !NAME.test(name))
+        invalid(path, `wildcard "*${name}" is not a valid name`);
+    if (names.has(name))
+        invalid(path, `"${name}" appears twice`);
+    names.add(name);
+    return { k: "wildcard", n: name };
+}
+function segmentOf(path, seg, names) {
+    if (DOT_SEGMENT.test(seg))
+        invalid(path, `"${seg}" segments are not allowed`);
+    if (seg.startsWith(":"))
+        return paramSegment(path, seg, names);
+    if (seg.startsWith("*"))
+        return wildcardSegment(path, seg, names);
+    if (seg.includes("?"))
+        invalid(path, "query strings are not part of a route pattern");
+    /* the request path is percent-encoded the way URL parsing encodes it; so is a literal */
+    return { k: "static", v: encodeSegment(seg) };
+}
+/** A wildcard or an optional param: it matches everything at and below its depth. */
+function isOpenEnded(seg) {
+    return seg.k === "wildcard" || (seg.k === "param" && seg.o);
+}
+export function parsePattern(path) {
+    if (typeof path !== "string")
+        invalid(String(path), "must be a string");
+    if (path.includes("#"))
+        invalid(path, "fragments are not part of a route pattern");
+    const names = new Set();
+    const segments = path
+        .split("/")
+        .filter((seg) => seg !== "")
+        .map((seg) => segmentOf(path, seg, names));
+    for (const seg of segments.slice(0, -1)) {
+        if (seg.k === "wildcard")
+            invalid(path, "a wildcard must be the last segment");
+        if (isOpenEnded(seg))
+            invalid(path, "an optional parameter must be the last segment");
+    }
+    return segments;
+}
+export function formatSegment(seg) {
+    if (seg.k === "static")
+        return seg.v;
+    if (seg.k === "param")
+        return `:${seg.n}${seg.o ? "?" : ""}`;
+    return seg.n === UNNAMED_WILDCARD ? "*" : `*${seg.n}`;
+}
+/** Canonical pattern string: leading slash, no empty segments, no trailing slash. */
+export function canonical(segments) {
+    return segments.length === 0 ? "/" : segments.map((seg) => `/${formatSegment(seg)}`).join("");
+}
+/** Parse and re-print; throws on anything the grammar cannot express. */
+export function normalizePattern(path) {
+    return canonical(parsePattern(path));
+}
+/** Join two patterns: `joinPatterns("/api/", "users")` is `/api/users`. */
+export function joinPatterns(base, path) {
+    const head = parsePattern(base);
+    const tail = parsePattern(path);
+    const last = head.at(-1);
+    if (last !== undefined && isOpenEnded(last) && tail.length > 0) {
+        invalid(`${base}${path}`, "cannot append to a wildcard or optional parameter");
+    }
+    /* re-parse: a name used on both sides (`/:id` + `/:id`) is only caught on the whole pattern */
+    return normalizePattern(canonical([...head, ...tail]));
+}
+/** Concrete variants: an optional last param yields the pattern with and without it. */
+export function expandOptional(segments) {
+    const last = segments.at(-1);
+    if (last?.k !== "param" || !last.o)
+        return [[...segments]];
+    const head = segments.slice(0, -1);
+    return [head, [...head, { k: "param", n: last.n, o: false }]];
+}
+export function isStaticPattern(segments) {
+    return segments.every((seg) => seg.k === "static");
+}
+/** Parameter and wildcard names, in order. */
+export function patternParams(segments) {
+    return segments.flatMap((seg) => (seg.k === "static" ? [] : [seg.n]));
+}
+export function routeId(method, pattern) {
+    return `${method} ${pattern}`;
+}
+/** Split a RouteId back into method and canonical pattern. */
+export function splitRouteId(id) {
+    const space = id.indexOf(" ");
+    return { method: id.slice(0, space), pattern: id.slice(space + 1) };
+}
+/** OpenAPI path template: `:id` and named wildcards become `{name}`. */
+export function toOpenApiTemplate(segments) {
+    if (segments.length === 0)
+        return "/";
+    return segments
+        .map((seg) => {
+        if (seg.k === "static")
+            return `/${seg.v}`;
+        return seg.n === UNNAMED_WILDCARD ? "/{wildcard}" : `/{${seg.n}}`;
+    })
+        .join("");
+}
+/*
+ * Scopes. `app.use("/admin", mw)` guards request paths: a path is inside the scope when its leading
+ * segments match the scope pattern: static segments literally, `:param` any one segment, `*` and
+ * an optional last param everything below. The scope uses the route grammar, so `/orgs/:id` and
+ * `/admin/*` mean what they mean in a route.
+ */
+function safeDecode(s) {
+    if (!s.includes("%"))
+        return s;
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        /* a malformed escape in a pattern literal: kept as written, so it still matches itself */
+        return s;
+    }
+}
+/* both sides decoded: a literal is stored encoded (`%C3%A9`), and a request may spell the same
+ * bytes with lowercase escapes (`%c3%a9`) or raw */
+function sameLiteral(a, b) {
+    return a === b || safeDecode(a) === safeDecode(b);
+}
+function coverVariant(route, scope) {
+    let uncertain = false;
+    for (let i = 0; i < scope.length; i++) {
+        const s = scope[i];
+        if (isOpenEnded(s))
+            return uncertain ? "some" : "all";
+        const r = route[i];
+        /* the route's paths end before the scope's do */
+        if (r === undefined)
+            return "none";
+        /* a route wildcard serves paths both inside and outside the rest of the scope */
+        if (r.k === "wildcard")
+            return "some";
+        if (r.k === "static" && s.k === "static" && !sameLiteral(r.v, s.v))
+            return "none";
+        /* a route param against a scope literal: inside the scope only when the value matches */
+        if (r.k === "param" && s.k === "static")
+            uncertain = true;
+    }
+    return uncertain ? "some" : "all";
+}
+/**
+ * Decide at registration whether a scope covers a route. `"some"` means the answer depends on the
+ * request path (a route param or wildcard can land inside the scope), so the scope's middleware is
+ * guarded by {@link pathInScope} at request time.
+ */
+export function scopeCoverage(route, scope) {
+    return variantsCoverage(expandOptional(route), scope);
+}
+/** {@link scopeCoverage} for a route already expanded into its optional-param variants, so finalize expands each route once, not once per scope. */
+export function variantsCoverage(variants, scope) {
+    const first = coverVariant(variants[0], scope);
+    for (let i = 1; i < variants.length; i++)
+        if (coverVariant(variants[i], scope) !== first)
+            return "some";
+    return first;
+}
+/**
+ * Is a request path inside a scope? Splits the path the way the router does (empty segments
+ * dropped) and compares each segment both as sent and percent-decoded, so a route param that
+ * decodes to a scoped literal is guarded exactly like the literal.
+ */
+export function pathInScope(path, scope) {
+    let pos = 0;
+    for (const s of scope) {
+        if (isOpenEnded(s))
+            return true;
+        while (path.charCodeAt(pos) === 47)
+            pos++;
+        if (pos >= path.length)
+            return false;
+        const slash = path.indexOf("/", pos);
+        const end = slash === -1 ? path.length : slash;
+        if (s.k === "static" && !sameLiteral(path.substring(pos, end), s.v))
+            return false;
+        pos = end;
+    }
+    return true;
+}

package/dist/routing/record.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A route record: what one registered route is. Records live in a per-app table keyed by
+ * `RouteId`; the tree only holds ids, so two apps that load the same tree, or a sub-app mounted
+ * into two parents, never share a record.
+ */
+import type { RouteId, Segment } from "./pattern.ts";
+export type RouteRecord = {
+    /** route identity: `METHOD /canonical/pattern` */
+    readonly id: RouteId;
+    /** route meta, frozen: what `ctx.meta` reads */
+    mt: Readonly<Record<string, unknown>> | null;
+    /** canonical route pattern, e.g. `/users/:id` */
+    readonly rp: string;
+    /** the pattern's segments, parsed once at registration so finalize never parses again */
+    readonly sg: readonly Segment[];
+};
+/** A fresh record for another graph; the meta object is frozen, so it is shared, not copied. */
+export declare function copyRecord<T extends RouteRecord>(record: T): T;

package/dist/routing/record.js

@@ -0,0 +1,4 @@
+/** A fresh record for another graph; the meta object is frozen, so it is shared, not copied. */
+export function copyRecord(record) {
+    return { ...record };
+}

package/dist/routing/register.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Route registration: the app graph every handle of one app shares, the routes and scopes
+ * registered into it, and mounting a sub-app. Records are per graph, keyed by `RouteId`; the
+ * tree holds ids only, so a sub-app mounted into two parents never shares a record.
+ */
+import type { InputSchemas, InputStep } from "../input/input.ts";
+import type { OutputSchemas } from "./output-types.ts";
+import type { MaybePromise, RuntimeMiddleware } from "../middleware/middleware.ts";
+import type { FinalizeHooks, FinalTable } from "./finalize.ts";
+import { type RouteId, type Segment } from "./pattern.ts";
+import type { RouteRecord } from "./record.ts";
+import { type AppSettings, type ErrorFactories } from "./settings.ts";
+import { type RouteEntry, type TreeNode } from "./tree.ts";
+/** An app's graph slot: not exported from the package; finalize readers (tests, codegen) reach the graph through it. */
+export declare const GRAPH: unique symbol;
+/** A handle's view slot: what a handle-level helper (serving a document) reads its basePath off. */
+export declare const VIEW: unique symbol;
+/**
+ * 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 declare const SERVED: unique symbol;
+/** A registered route: what it was registered with, before finalize resolves it against the graph. */
+export type RouteHandler = RouteRecord & {
+    /** came with the loaded route tree: a registration of the same route replaces it */
+    readonly lt?: true;
+    /** the chain middleware captured at registration, plus any mounting chain */
+    readonly cm: readonly RuntimeMiddleware[];
+    /** `.context()` values of the registering handle, merged under the mounting handle's */
+    readonly cv: Readonly<Record<string, unknown>> | null;
+    /** error keys the route declared itself (`.errors()`, `.boundary()`) */
+    readonly dk: ReadonlySet<string>;
+    /** the factory `.errors(factory, ...keys)` named; its keys come from it, not the app's */
+    readonly ef: ErrorFactories | null;
+    readonly fn: (ctx: object) => MaybePromise<Response>;
+    /** the compiled `.input()` step, run after the middleware and before `fn`; `null` without `.input()` */
+    readonly in: InputStep | null;
+    /** what `.input()` declares, as written: read by documentation, never at dispatch; `null` without it */
+    readonly iv: InputSchemas | null;
+    /** what `.output()` declares, checked at finalize when the app's mode is on; `null` without it */
+    readonly out: OutputSchemas | null;
+    /** the settings of the app the route was registered on */
+    readonly own: AppSettings<unknown>;
+    /** route-level boundary key (`.boundary()`) */
+    readonly rb: string | null;
+    /** route-level middleware (`.get(...).use(mw)`) */
+    readonly rm: readonly RuntimeMiddleware[];
+    /** explicit meta: chain `.meta()` overlaid by route `.meta()` */
+    readonly xm: Readonly<Record<string, unknown>> | null;
+};
+/** What a builder hands over; the graph gives it its id and pattern. */
+export type RouteSource = Omit<RouteHandler, "id" | "mt" | "rp" | "sg">;
+/** One `app.use(mw)`: the handle it returns has to register a route, or `mw` runs nowhere. */
+export type ChainNode = {
+    readonly mw: RuntimeMiddleware;
+    readonly parent: ChainNode | null;
+    used: boolean;
+};
+/** A route builder still waiting for `.handler()`, reported at finalize. */
+export type PendingRoute = {
+    readonly id: string;
+};
+/** One path-scoped `use(path, mw)`. */
+export type ScopedEntry = {
+    /** the middleware behind a request-path check, for routes the scope covers only partly */
+    readonly guard: RuntimeMiddleware;
+    readonly mw: RuntimeMiddleware;
+    /** canonical full-path pattern, rebased against the handle's basePath */
+    readonly prefix: string;
+    readonly segs: readonly Segment[];
+};
+export type HoneyGraph = {
+    /** root wildcards a loaded app registered outside its tree: what its unserved leaves delegate to */
+    readonly catchAll: Map<RouteId, RouteHandler>;
+    /** every `use(mw)` handle; one that never registers a route is reported at finalize */
+    readonly chains: ChainNode[];
+    /** bumped by every registration; finalize re-runs when it moves */
+    epoch: number;
+    final: FinalTable | null;
+    /** the error boundary and miss answer dispatch compiles into every chain, created once */
+    hooks: FinalizeHooks | null;
+    readonly pending: Set<PendingRoute>;
+    /** the route data of the tree `routeTree()` loaded; `null` while the app builds its own tree */
+    loaded: Readonly<Record<RouteId, RouteEntry>> | null;
+    readonly records: Map<RouteId, RouteHandler>;
+    root: TreeNode;
+    /** path-scoped middleware, in registration order */
+    readonly scoped: ScopedEntry[];
+    /** chains of the handles that served a request: what 404 and 405 run when there are no routes */
+    readonly served: Set<readonly RuntimeMiddleware[]>;
+    readonly settings: AppSettings<unknown>;
+    /** routes a loaded app registered that its tree lacks: the tree is stale, said at finalize */
+    readonly unexpected: RouteId[];
+};
+/** What one handle contributes to the routes registered or mounted through it. */
+export type HandleView = {
+    readonly basePath: string;
+    readonly chain: readonly RuntimeMiddleware[];
+    readonly chainMeta: Readonly<Record<string, unknown>> | null;
+    readonly contextValues: Readonly<Record<string, unknown>> | null;
+    /** the `use(mw)` call that created this chain; `null` on the root handle */
+    readonly node: ChainNode | null;
+};
+export declare const ROOT_VIEW: HandleView;
+export declare function createGraph(): HoneyGraph;
+/** Every `use()` on the way to a handle that registers, mounts or serves is in use. */
+export declare function markUsed(node: ChainNode | null): void;
+/** A new `use(mw)` node under `parent`. */
+export declare function addChain(g: HoneyGraph, parent: ChainNode | null, mw: RuntimeMiddleware): ChainNode;
+/** 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 declare function assertRouteFree(g: HoneyGraph, method: string, segments: readonly Segment[]): RouteId;
+/** Whether a route's own meta marks it served: the app's own, never copied with it. */
+export declare function isServed(r: {
+    readonly xm: Readonly<Record<string, unknown>> | null;
+}): boolean;
+export declare function addRoute(g: HoneyGraph, method: string, segments: readonly Segment[], source: RouteSource): RouteId;
+/** Guard every request path under `path` (rebased on `basePath`) with `mw`, whichever handle registered the route. */
+export declare function addScope(g: HoneyGraph, basePath: string, path: string, mw: RuntimeMiddleware): void;
+/** A builder registered or was abandoned on purpose: no longer pending. */
+export declare function settle(g: HoneyGraph, pending: PendingRoute, node: ChainNode | null): void;
+/** `use(mw)` handles that never registered, mounted or served, and builders without `.handler()`. */
+export declare function assertNothingDiscarded(g: HoneyGraph): void;
+/**
+ * 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 declare function mount(g: HoneyGraph, view: HandleView, sub: HoneyGraph): void;
+/** The error keys a middleware chain declares, in run order. */
+export declare function chainErrorKeys(chain: readonly RuntimeMiddleware[]): string[];
+/** The factories a middleware chain's keys come from, each once, in run order. */
+export declare function chainErrorFactories(chain: readonly RuntimeMiddleware[]): ErrorFactories[];