@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/routing/route-tree.js

@@ -0,0 +1,91 @@
+/**
+ * Route trees in and out. `app.routeTree(tree)` serves a generated tree, another app's snapshot or
+ * a `mergeTree()` of them: the tree gives the topology, and each leaf runs the route this app
+ * registers for it, else the snapshot's live record, else the app's catch-all (routing/delegate.ts).
+ * `app.toRouteTree()` is the snapshot: a copy of the topology and, per route, its resolved data
+ * and a live record carrying the scopes that cover it here.
+ */
+import { ERROR_META } from "../errors/errors.js";
+import { compareCodeUnits } from "../schema/canonicalize.js";
+import { finalTable } from "./dispatch.js";
+import { scopesFor } from "./finalize.js";
+import { expandOptional } from "./pattern.js";
+import { chainErrorFactories, GRAPH, isServed } from "./register.js";
+import { SettingsChain } from "./settings-chain.js";
+import { assertTreeFormat, cloneTree, dict, forEachLeaf, freezeTree, ROUTE_TREE_VERSION, } from "./tree.js";
+/** Serve `tree` on `g`: frozen in place, its live records copied, the rest bound as routes register. */
+export function loadRouteTree(g, tree) {
+    assertTreeFormat(tree);
+    if (g.loaded !== null)
+        throw new Error("routeTree() was already called on this app");
+    const registered = [...g.records.keys(), ...g.catchAll.keys()][0];
+    if (registered !== undefined)
+        throw new Error(`routeTree() must be called before routes are registered (${registered} is)`);
+    forEachLeaf(tree.root, (method, path, id) => {
+        if (!Object.hasOwn(tree.routes, id))
+            throw new Error(`routeTree(): leaf ${method} ${path} has no route entry (${id})`);
+    });
+    g.root = freezeTree(tree.root);
+    g.loaded = Object.assign(dict(), tree.routes);
+    for (const [id, entry] of Object.entries(tree.routes)) {
+        if (entry.h !== undefined)
+            g.records.set(id, { ...entry.h, lt: true });
+    }
+    g.epoch++;
+}
+/** Each key's status key from the first factory whose ERROR_META knows it; `null` when none does. */
+function statusKeysOf(keys, factories) {
+    const out = {};
+    for (const key of keys) {
+        const meta = factories
+            .map((f) => f?.[ERROR_META])
+            .find((m) => m !== undefined && Object.hasOwn(m, key));
+        if (meta !== undefined)
+            out[key] = meta[key].statusKey;
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+/** `g`'s routes as a tree another app serves; nothing in it is shared with `g`. */
+export function snapshotRouteTree(g) {
+    const { plans } = finalTable(g);
+    const routes = Object.assign(dict(), g.loaded);
+    const served = new Set();
+    for (const [id, r] of g.records) {
+        /* an app's served routes are its own: an app loading the tree registers its own */
+        if (isServed(r)) {
+            served.add(id);
+            continue;
+        }
+        const { mw, policy, route } = plans.get(id);
+        const ek = [...(policy.declared ?? [])].sort(compareCodeUnits);
+        /* the record resolves the same way anywhere: its chain carries the scopes covering it here */
+        const cm = [...r.cm, ...scopesFor(g, expandOptional(r.sg))];
+        const h = { ...r, cm, dk: new Set(ek), rb: policy.boundaryKey, xm: route.meta };
+        const es = statusKeysOf(ek, [r.ef, ...chainErrorFactories(mw), r.own.errorFactory]);
+        routes[id] = {
+            bek: policy.boundaryKey,
+            ek,
+            ...(es === null ? {} : { es }),
+            h,
+            iv: r.iv,
+            mt: route.meta,
+            out: r.out,
+        };
+    }
+    return { meta: {}, root: cloneTree(g.root, (id) => !served.has(id)), routes, v: ROUTE_TREE_VERSION };
+}
+/** `app.routeTree()` and `app.toRouteTree()`: every app handle has them. */
+export class RouteTreeChain extends SettingsChain {
+    /**
+     * 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) {
+        loadRouteTree(this[GRAPH], tree);
+        return this;
+    }
+    /** A copy of the routes this app serves, for another app to serve with `routeTree()`. */
+    toRouteTree() {
+        return snapshotRouteTree(this[GRAPH]);
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The settings setters every app handle shares: each applies to the whole app and returns the handle.
+ */
+import type { HoneyError } from "../errors/error.ts";
+import type { ErrorFormat } from "../errors/problem-json.ts";
+import type { CustomErrorFormatter, ErrorFormatter } from "../errors/projector.ts";
+import type { HoneyMetaSpec } from "../meta/meta-spec-merge.ts";
+import { type Logger } from "../telemetry/logger.ts";
+import type { Telemetry } from "../telemetry/request-trace.ts";
+import type { InferOutput, StandardSchemaLike } from "../validation/standard-schema.ts";
+import type { OutputValidationMode } from "../validation/validate-output.ts";
+import type { WSAdapter } from "../ws/contract.ts";
+import type { WithTaps } from "./app-types.ts";
+import { type AppSettings, type ErrorI18n, type OnErrorFn, type OnMethodNotAllowedFn, type OnNotFoundFn, type RequestLogOptions } from "./settings.ts";
+import type { TapHandler } from "./tap.ts";
+/** The settings surface every handle shares: each setter applies to the whole app and returns the handle. */
+export declare abstract class SettingsChain<TEnv> {
+    protected readonly settings: AppSettings<TEnv>;
+    constructor(settings: AppSettings<TEnv>);
+    /** Recompile what the app serves on its next request: a setting finalize reads changed. */
+    protected abstract invalidate(): void;
+    /** A tap fired after a route's handler answered, in the background (see routing/tap.ts). */
+    tap<const TKey extends string>(key: TKey, handler: TapHandler<TEnv, this extends {
+        readonly $taps: infer T;
+    } ? T : {}, TKey>): this;
+    /** Type only: each tap key's payload, for `ctx.tap()`, tap handlers and route meta. */
+    taps<TNewTaps extends Record<string, unknown>>(): WithTaps<this, TNewTaps>;
+    /** Check `.output()` answers: `"off"` (default), `"always"`, or `"dev"` (not production; never without a process). */
+    outputValidation(mode: OutputValidationMode): this;
+    /** `"strip"` redirects `/a/` to `/a`, `"enforce"` redirects `/a` to `/a/` (308); `"ignore"` serves both. */
+    trailingSlash(mode: "enforce" | "ignore" | "strip"): this;
+    /** An encoded `/` or `\` in the path is a 400 by default; `"allow"` decodes it into a param value. */
+    encodedSlashes(mode: "allow" | "reject"): this;
+    /** Strip a URL path prefix before matching: whole segments only; a path without it passes through. */
+    stripPrefix(prefix: string): this;
+    /**
+     * The policy that maps route meta and schema metadata into the OpenAPI document. Declared once;
+     * a mounted sub-app's is merged under it when a document is built, whichever came first.
+     */
+    metaSpec<TThis extends {
+        readonly $meta: unknown;
+    }>(this: TThis, config: HoneyMetaSpec<TThis["$meta"]>): TThis;
+    /** Where every server-side line goes; default `createLogger()` (by NODE_ENV), `false` for none. */
+    logger(logger: Logger | false): this;
+    /** One `info` line per request once its body ends (or is aborted); off by default, `skip` drops a line. */
+    requestLog(options: boolean | RequestLogOptions): this;
+    /**
+     * Trace every request (a root span, the middleware and the handler under it) and report thrown
+     * errors in the background. Pass `otelAdapter(api, options)` from `@lovrozagar/honey/telemetry`.
+     */
+    telemetry(value: Telemetry): this;
+    /**
+     * Translate error answers per request: the message from the locale's template, field paths to
+     * display names. Pass `errorI18n({ errors, fieldNames, resolveLocale })` from
+     * `@lovrozagar/honey/i18n`; a raw config object is refused here, at startup.
+     */
+    errorI18n(value: ErrorI18n<TEnv>): this;
+    onError(handler: OnErrorFn<TEnv>): this;
+    onMethodNotAllowed(handler: OnMethodNotAllowedFn<TEnv>): this;
+    onNotFound(handler: OnNotFoundFn<TEnv>): this;
+    /**
+     * The runtime's WebSocket adapter, which ws routes upgrade through: `cfWebSocket()` on
+     * Workers. `serve(app)` sets the runtime's own on Node and Bun when none is set; on Bun, set
+     * it before `serve()`.
+     */
+    wsAdapter(adapter: WSAdapter): this;
+    /** Answer errors as honey's envelope (the default) or RFC 9457 Problem Details; schema errors keep their body. */
+    errorFormat(format: ErrorFormat): this;
+    /** Shape every standard error body; with a schema, the body type is the schema's output. */
+    defaultErrorFormatter<TSchema extends StandardSchemaLike>(schema: TSchema, fn: (error: HoneyError) => InferOutput<TSchema>): this;
+    defaultErrorFormatter(fn: ErrorFormatter): this;
+    /** Shape every schema error body; with a schema, the body type is the schema's output. */
+    customErrorFormatter<TSchema extends StandardSchemaLike>(schema: TSchema, fn: (error: HoneyError, data: Record<string, unknown>) => InferOutput<TSchema>): this;
+    customErrorFormatter(fn: CustomErrorFormatter): this;
+}

package/dist/routing/settings-chain.js

@@ -0,0 +1,137 @@
+import { SILENT } from "../telemetry/logger.js";
+import { normalizeStripPrefix, } from "./settings.js";
+/** The settings surface every handle shares: each setter applies to the whole app and returns the handle. */
+export class SettingsChain {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    /** A tap fired after a route's handler answered, in the background (see routing/tap.ts). */
+    tap(key, handler) {
+        ;
+        (this.settings.taps ??= new Map()).set(key, handler);
+        this.invalidate();
+        return this;
+    }
+    /** Type only: each tap key's payload, for `ctx.tap()`, tap handlers and route meta. */
+    taps() {
+        return this;
+    }
+    /** Check `.output()` answers: `"off"` (default), `"always"`, or `"dev"` (not production; never without a process). */
+    outputValidation(mode) {
+        this.settings.outputValidation = mode;
+        this.invalidate();
+        return this;
+    }
+    /** `"strip"` redirects `/a/` to `/a`, `"enforce"` redirects `/a` to `/a/` (308); `"ignore"` serves both. */
+    trailingSlash(mode) {
+        this.settings.trailingSlash = mode;
+        return this;
+    }
+    /** An encoded `/` or `\` in the path is a 400 by default; `"allow"` decodes it into a param value. */
+    encodedSlashes(mode) {
+        this.settings.encodedSlashes = mode;
+        return this;
+    }
+    /** Strip a URL path prefix before matching: whole segments only; a path without it passes through. */
+    stripPrefix(prefix) {
+        this.settings.stripPrefix = normalizeStripPrefix(prefix);
+        return this;
+    }
+    /**
+     * The policy that maps route meta and schema metadata into the OpenAPI document. Declared once;
+     * a mounted sub-app's is merged under it when a document is built, whichever came first.
+     */
+    metaSpec(config) {
+        const source = this.settings.metaSpec;
+        if (source.declared !== null)
+            throw new Error("metaSpec() was already called on this app");
+        source.declared = config;
+        return this;
+    }
+    /** Where every server-side line goes; default `createLogger()` (by NODE_ENV), `false` for none. */
+    logger(logger) {
+        this.settings.logger = logger === false ? SILENT : logger;
+        return this;
+    }
+    /** One `info` line per request once its body ends (or is aborted); off by default, `skip` drops a line. */
+    requestLog(options) {
+        this.settings.requestLog = options === false ? null : options === true ? {} : options;
+        return this;
+    }
+    /**
+     * Trace every request (a root span, the middleware and the handler under it) and report thrown
+     * errors in the background. Pass `otelAdapter(api, options)` from `@lovrozagar/honey/telemetry`.
+     */
+    telemetry(value) {
+        if (typeof value?.tracer?.startSpan !== "function") {
+            throw new TypeError("app.telemetry(): pass otelAdapter(api) from @lovrozagar/honey/telemetry, or a value with a tracer");
+        }
+        this.settings.telemetry = value;
+        this.invalidate();
+        return this;
+    }
+    /**
+     * Translate error answers per request: the message from the locale's template, field paths to
+     * display names. Pass `errorI18n({ errors, fieldNames, resolveLocale })` from
+     * `@lovrozagar/honey/i18n`; a raw config object is refused here, at startup.
+     */
+    errorI18n(value) {
+        const candidate = value;
+        if (typeof candidate?.translate !== "function" || typeof candidate.resolveLocale !== "function") {
+            throw new TypeError("app.errorI18n(): pass errorI18n({ ... }) from @lovrozagar/honey/i18n, not its config");
+        }
+        this.settings.errorI18n = value;
+        return this;
+    }
+    onError(handler) {
+        this.settings.onError = handler;
+        return this;
+    }
+    onMethodNotAllowed(handler) {
+        this.settings.onMethodNotAllowed = handler;
+        return this;
+    }
+    onNotFound(handler) {
+        this.settings.onNotFound = handler;
+        return this;
+    }
+    /**
+     * The runtime's WebSocket adapter, which ws routes upgrade through: `cfWebSocket()` on
+     * Workers. `serve(app)` sets the runtime's own on Node and Bun when none is set; on Bun, set
+     * it before `serve()`.
+     */
+    wsAdapter(adapter) {
+        this.settings.wsAdapter = adapter;
+        return this;
+    }
+    /** Answer errors as honey's envelope (the default) or RFC 9457 Problem Details; schema errors keep their body. */
+    errorFormat(format) {
+        this.settings.errorFormat = format;
+        return this;
+    }
+    defaultErrorFormatter(schemaOrFn, fn) {
+        if (typeof schemaOrFn === "function") {
+            this.settings.errorSchema = null;
+            this.settings.errorFormatter = schemaOrFn;
+        }
+        else {
+            const mapper = fn;
+            this.settings.errorSchema = schemaOrFn;
+            this.settings.errorFormatter = (error) => mapper(error);
+        }
+        return this;
+    }
+    customErrorFormatter(schemaOrFn, fn) {
+        if (typeof schemaOrFn === "function") {
+            this.settings.customErrorSchema = null;
+            this.settings.customErrorFormatter = schemaOrFn;
+        }
+        else {
+            const mapper = fn;
+            this.settings.customErrorSchema = schemaOrFn;
+            this.settings.customErrorFormatter = (error, data) => mapper(error, data);
+        }
+        return this;
+    }
+}

package/dist/routing/settings.d.ts

@@ -0,0 +1,90 @@
+/**
+ * App settings: one object per app graph, shared by every handle derived from it (`use()`,
+ * `basePath()`, `context()`, `meta()`), so a setter called on any handle applies to all of them.
+ * A route keeps the settings of the app it was registered on, so a mounted sub-app's routes keep
+ * their own error factory, default errors and boundary. Feature bits add their own fields.
+ */
+import type { ErrorFormat } from "../errors/problem-json.ts";
+import type { MetaSpecSource } from "../meta/meta-spec-merge.ts";
+import type { OutputValidationMode } from "../validation/validate-output.ts";
+import type { HoneyError } from "../errors/error.ts";
+import type { CustomErrorFormatter, ErrorFormatter } from "../errors/projector.ts";
+import type { MaybePromise } from "../middleware/middleware.ts";
+import type { RequestLogEntry } from "../telemetry/fields.ts";
+import { type Logger } from "../telemetry/logger.ts";
+import type { Telemetry } from "../telemetry/request-trace.ts";
+import type { StandardSchemaLike } from "../validation/standard-schema.ts";
+import type { WSAdapter } from "../ws/contract.ts";
+import type { TapFn } from "./tap.ts";
+/** An app's error factory (`defineErrors`), as its settings hold it. */
+export type ErrorFactories = Readonly<Record<string, (...args: never[]) => unknown>>;
+/** What the error and miss hooks receive. */
+export type ErrorCtx<TEnv> = {
+    env: TEnv;
+    jsonFromError: (err: HoneyError) => Response;
+    req: Request;
+};
+/** What `resolveLocale` reads the request's locale from. */
+export type ResolveLocaleCtx<TEnv> = {
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly env: TEnv;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly params: Readonly<Record<string, string>>;
+    readonly req: Request;
+    readonly search: Readonly<Record<string, string>>;
+};
+/** `app.errorI18n`, built by `errorI18n()` from `@lovrozagar/honey/i18n`; `translate` answers a copy. */
+export type ErrorI18n<TEnv = unknown> = {
+    readonly resolveLocale: (ctx: ResolveLocaleCtx<TEnv>) => MaybePromise<string>;
+    translate(error: HoneyError, locale: string): HoneyError;
+};
+/** Map a thrown value: a HoneyError replaces the error, a Response answers, nothing falls through. */
+export type OnErrorFn<TEnv> = (error: unknown, ctx: ErrorCtx<TEnv>) => MaybePromise<HoneyError | Response | undefined | void>;
+export type OnMethodNotAllowedFn<TEnv> = (ctx: ErrorCtx<TEnv> & {
+    allowed: string[];
+}) => MaybePromise<Response>;
+export type OnNotFoundFn<TEnv> = (ctx: ErrorCtx<TEnv>) => MaybePromise<Response>;
+/** The request log's options: `skip` answers true for a line not to write. */
+export type RequestLogOptions = {
+    readonly skip?: (entry: RequestLogEntry) => boolean;
+};
+export type AppSettings<TEnv = unknown> = {
+    customErrorFormatter: CustomErrorFormatter | null;
+    /** the body schema of schema errors, for the OpenAPI document */
+    customErrorSchema: StandardSchemaLike | null;
+    defaultBoundaryKey: string | null;
+    defaultErrorKeys: Set<string>;
+    encodedSlashes: "allow" | "reject";
+    errorFactory: ErrorFactories | null;
+    errorFormat: ErrorFormat;
+    errorFormatter: ErrorFormatter;
+    /** translates the answer to an unhandled throw and to an onError HoneyError; `null`: off */
+    errorI18n: ErrorI18n<TEnv> | null;
+    /** the body schema of standard errors, for the OpenAPI document */
+    errorSchema: StandardSchemaLike | null;
+    /** where every server-side line goes: the default createLogger(), the app's own, or SILENT */
+    logger: Logger;
+    /** the metaSpec policy this app declared, and each mounted sub-app's: merged when a document is built */
+    readonly metaSpec: MetaSpecSource;
+    /** whether `.output()` routes check what they answer: resolved per route at finalize */
+    outputValidation: OutputValidationMode;
+    onError: OnErrorFn<TEnv> | null;
+    onMethodNotAllowed: OnMethodNotAllowedFn<TEnv> | null;
+    onNotFound: OnNotFoundFn<TEnv> | null;
+    /** one info line per request after its body ends; `null`: off */
+    requestLog: RequestLogOptions | null;
+    /** spans per request and the error reporter; `null`: off, at the cost of one check */
+    telemetry: Telemetry | null;
+    stripPrefix: string | null;
+    /** `app.tap()` handlers by key; `null` until one is registered */
+    taps: Map<string, TapFn<TEnv>> | null;
+    trailingSlash: "enforce" | "ignore" | "strip";
+    wsAdapter: WSAdapter | null;
+};
+/** The default shape, unchanged. Identity, so finalize can tell a formatter was never set. */
+export declare function defaultErrorFormatter(_error: HoneyError, defaultShape: Record<string, unknown>): Record<string, unknown>;
+export declare function createSettings<TEnv>(): AppSettings<TEnv>;
+/** A path prefix as stripped: leading slash, no trailing slash; `null` for none. */
+export declare function normalizeStripPrefix(prefix: string): string | null;
+/** Settings that cannot work together, refused before the first request is served. */
+export declare function assertSettingsAgree(s: AppSettings<unknown>): void;

package/dist/routing/settings.js

@@ -0,0 +1,44 @@
+import { createLogger, SILENT } from "../telemetry/logger.js";
+/** The default shape, unchanged. Identity, so finalize can tell a formatter was never set. */
+export function defaultErrorFormatter(_error, defaultShape) {
+    return defaultShape;
+}
+export function createSettings() {
+    return {
+        outputValidation: "off",
+        customErrorFormatter: null,
+        customErrorSchema: null,
+        defaultBoundaryKey: null,
+        defaultErrorKeys: new Set(),
+        encodedSlashes: "reject",
+        errorFactory: null,
+        errorFormat: "honey",
+        errorFormatter: defaultErrorFormatter,
+        errorI18n: null,
+        errorSchema: null,
+        logger: createLogger(),
+        metaSpec: { absorbed: [], declared: null },
+        onError: null,
+        onMethodNotAllowed: null,
+        onNotFound: null,
+        requestLog: null,
+        telemetry: null,
+        stripPrefix: null,
+        taps: null,
+        trailingSlash: "ignore",
+        wsAdapter: null,
+    };
+}
+/** A path prefix as stripped: leading slash, no trailing slash; `null` for none. */
+export function normalizeStripPrefix(prefix) {
+    let normalized = prefix.replace(/\/+$/, "");
+    if (normalized.length > 0 && !normalized.startsWith("/"))
+        normalized = `/${normalized}`;
+    return normalized === "" ? null : normalized;
+}
+/** Settings that cannot work together, refused before the first request is served. */
+export function assertSettingsAgree(s) {
+    if (s.requestLog !== null && s.logger === SILENT) {
+        throw new Error("honey: requestLog() is on, but logger(false) writes nothing: set a logger, or turn requestLog off");
+    }
+}

package/dist/routing/tap.d.ts

@@ -0,0 +1,31 @@
+import type { CompiledChain, MaybePromise } from "../middleware/middleware.ts";
+import type { AppSettings } from "./settings.ts";
+/** What a tap handler sees: the request, never `res` or `tap`, so it can neither answer nor recurse. */
+export type TapContext<TEnv = unknown> = {
+    readonly background: (promise: Promise<unknown>) => void;
+    readonly env: TEnv;
+    readonly headers: Record<string, string>;
+    readonly meta: Record<string, unknown>;
+    readonly params: Record<string, string>;
+    readonly path: string;
+    readonly req: Request;
+    readonly routePattern: string;
+    readonly search: Record<string, string>;
+};
+export type TapFn<TEnv = unknown> = (ctx: TapContext<TEnv>, payload: never) => unknown;
+/** `app.tap(key, handler)`'s handler: the payload is the declared one for `key` (`.taps<T>()`), else unknown. */
+export type TapHandler<TEnv, TTaps, TKey extends string> = (ctx: TapContext<TEnv>, payload: TKey extends keyof TTaps ? TTaps[TKey] : unknown) => unknown;
+/** `ctx.tap()` as a handler sees it: the declared keys and their payloads, or any key without `.taps<T>()`. */
+export type TapMethod<TTaps> = [keyof TTaps] extends [never] ? {
+    tap(key: string, payload: unknown): void;
+} : {
+    tap<const TKey extends keyof TTaps & string>(key: TKey, payload: TTaps[TKey]): void;
+};
+type Taps = ReadonlyMap<string, TapFn>;
+/** The taps a route fires: the serving app's over those of the app it was registered on; `null` for none. */
+export declare function tapsFor(serving: AppSettings<unknown>, own: AppSettings<unknown>): Taps | null;
+/** The route handler, marking the request when it answered (a throw or a rejection marks nothing). */
+export declare function answering(handler: (ctx: object) => MaybePromise<Response>): (ctx: object) => MaybePromise<Response>;
+/** `run`, firing `taps` once the whole chain settled on the handler's answer. */
+export declare function firing(run: CompiledChain, taps: Taps): CompiledChain;
+export {};

package/dist/routing/tap.js

@@ -0,0 +1,77 @@
+/**
+ * Taps: `app.tap(key, handler)` registers an observation hook a route fires after its handler
+ * answered: for each tap key in the route's meta (with the meta value), then for each
+ * `ctx.tap(key, payload)` the handler called. Nothing fires on an error answer, a 404 or 405, a
+ * middleware that answered without the handler, or an upgrade. A tap runs after the response, in
+ * the background (`waitUntil` where there is one), so it never delays or shapes it; a failing tap is
+ * contained (invokeUser) and logged as a warn, "tap failed", never reaching onError.
+ */
+import { HoneyError } from "../errors/error.js";
+import { REQUEST, TAPS } from "../context/context.js";
+import { invokeUser } from "../realtime/invoke-user.js";
+/** The taps a route fires: the serving app's over those of the app it was registered on; `null` for none. */
+export function tapsFor(serving, own) {
+    /* a taps map exists only once a tap is set: never empty */
+    const outer = serving.taps;
+    const inner = own === serving ? null : own.taps;
+    if (inner === null)
+        return outer;
+    if (outer === null)
+        return inner;
+    return new Map([...inner, ...outer]);
+}
+function stateOf(ctx) {
+    return ctx[REQUEST];
+}
+/** The route handler, marking the request when it answered (a throw or a rejection marks nothing). */
+export function answering(handler) {
+    return (ctx) => {
+        const answer = handler(ctx);
+        if (answer instanceof Promise) {
+            return answer.then((response) => {
+                stateOf(ctx).answered = true;
+                return response;
+            });
+        }
+        stateOf(ctx).answered = true;
+        return answer;
+    };
+}
+/** Run `fn` for `key` after this turn, contained, in the request's background. */
+function schedule(ctx, key, fn, payload) {
+    const warn = (error) => ctx.log.warn({ err: HoneyError.serialize(error), tap: key }, "tap failed");
+    ctx.background(Promise.resolve().then(() => invokeUser(() => fn(ctx, payload), {
+        onError: warn,
+        phase: "tap",
+    })));
+}
+/** The route's meta taps, then its `ctx.tap()` calls, when the handler's answer is what goes out. */
+function fire(ctx, response, taps) {
+    if (stateOf(ctx).answered !== true || ctx.error !== undefined || response.status === 101)
+        return;
+    const meta = ctx.meta;
+    for (const [key, fn] of taps) {
+        const value = Object.hasOwn(meta, key) ? meta[key] : undefined;
+        if (value !== undefined)
+            schedule(ctx, key, fn, value);
+    }
+    for (const call of ctx[TAPS] ?? []) {
+        const fn = taps.get(call.key);
+        if (fn !== undefined)
+            schedule(ctx, call.key, fn, call.payload);
+    }
+}
+/** `run`, firing `taps` once the whole chain settled on the handler's answer. */
+export function firing(run, taps) {
+    return (ctx) => {
+        const response = run(ctx);
+        if (response instanceof Promise) {
+            return response.then((settled) => {
+                fire(ctx, settled, taps);
+                return settled;
+            });
+        }
+        fire(ctx, response, taps);
+        return response;
+    };
+}

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

@@ -0,0 +1,7 @@
+import { type RouteTree, type TreeNode } from "./tree.ts";
+type TreeInput = RouteTree | [RouteTree, Record<string, unknown>];
+/** Merge `source` topology into `target` (mutates target; never shares source nodes). */
+export declare function mergeInto(target: TreeNode, source: TreeNode): void;
+/** Merge several trees into a new one. Inputs are never mutated; extra meta given per tree is applied to copies of its route entries. */
+export declare function mergeTree(...trees: TreeInput[]): RouteTree;
+export {};

package/dist/routing/tree-merge.js

@@ -0,0 +1,77 @@
+import { assertTreeFormat, cloneTree, createNode, dict, ROUTE_TREE_VERSION, } from "./tree.js";
+function mergeMethodMap(target, source, path) {
+    for (const method in source) {
+        if (target[method] !== undefined)
+            throw new Error(`Merge conflict: duplicate ${method} ${path}`);
+        target[method] = source[method];
+    }
+}
+function mergeParam(target, source, path) {
+    if (source.d === null)
+        return;
+    if (target.d === null) {
+        target.d = { c: cloneTree(source.d.c), n: source.d.n };
+        return;
+    }
+    if (target.d.n !== source.d.n) {
+        throw new Error(`Merge conflict: param name mismatch at ${path || "/"}: "${target.d.n}" vs "${source.d.n}"`);
+    }
+    mergeNodes(target.d.c, source.d.c, `${path}/:${target.d.n}`);
+}
+function mergeWildcard(target, source, path) {
+    if (source.w === null)
+        return;
+    if (target.w === null) {
+        target.w = { m: Object.assign(dict(), source.w.m), n: source.w.n };
+        return;
+    }
+    if (target.w.n !== source.w.n) {
+        throw new Error(`Merge conflict: wildcard name mismatch at ${path || "/"}: "${target.w.n}" vs "${source.w.n}"`);
+    }
+    mergeMethodMap(target.w.m, source.w.m, `${path}/*${target.w.n}`);
+}
+function mergeNodes(target, source, path) {
+    if (source.m !== null)
+        mergeMethodMap((target.m ??= dict()), source.m, path || "/");
+    for (const seg in source.s) {
+        const child = source.s[seg];
+        const existing = target.s[seg];
+        if (existing === undefined)
+            target.s[seg] = cloneTree(child);
+        else
+            mergeNodes(existing, child, `${path}/${seg}`);
+    }
+    mergeParam(target, source, path);
+    mergeWildcard(target, source, path);
+    if (source.ws === null)
+        return;
+    if (target.ws !== null)
+        throw new Error(`Merge conflict: duplicate WebSocket handler at ${path || "/"}`);
+    target.ws = source.ws;
+}
+/** Merge `source` topology into `target` (mutates target; never shares source nodes). */
+export function mergeInto(target, source) {
+    mergeNodes(target, source, "");
+}
+function withExtraMeta(entry, extra) {
+    if (extra === undefined)
+        return { ...entry };
+    const mt = Object.freeze({ ...entry.mt, ...extra });
+    return entry.h === undefined ? { ...entry, mt } : { ...entry, h: { ...entry.h, mt }, mt };
+}
+/** Merge several trees into a new one. Inputs are never mutated; extra meta given per tree is applied to copies of its route entries. */
+export function mergeTree(...trees) {
+    const merged = { meta: {}, root: createNode(), routes: dict(), v: ROUTE_TREE_VERSION };
+    for (const input of trees) {
+        const [tree, extra] = Array.isArray(input) ? input : [input, undefined];
+        assertTreeFormat(tree);
+        mergeNodes(merged.root, tree.root, "");
+        for (const id in tree.routes) {
+            if (id in merged.routes)
+                throw new Error(`Merge conflict: duplicate ${id}`);
+            merged.routes[id] = withExtraMeta(tree.routes[id], extra);
+        }
+        Object.assign(merged.meta, tree.meta);
+    }
+    return merged;
+}