@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/routing/tree.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Router topology. Leaves are `RouteId`s, never handler objects: what a leaf runs is looked up in
+ * the serving app's own route table, so two apps that load one tree never share a record.
+ */
+import { type RouteId, type Segment } from "./pattern.ts";
+import type { InputSchemas } from "../input/input.ts";
+import type { OutputSchemas } from "./output-types.ts";
+import type { RouteRecord } from "./record.ts";
+import type { HttpMethod } from "./types.ts";
+export type TreeNode = {
+    /** dynamic param child: { n: param name, c: child subtree } */
+    d: {
+        c: TreeNode;
+        n: string;
+    } | null;
+    /** method → route id at this exact path */
+    m: Record<string, RouteId> | null;
+    /** static children: literal path segment → child subtree (null-prototype) */
+    s: Record<string, TreeNode>;
+    /** wildcard: { n: wildcard name, m: method → route id } */
+    w: {
+        m: Record<string, RouteId>;
+        n: string;
+    } | null;
+    /** websocket route id for this path */
+    ws: RouteId | null;
+};
+/** Descriptive data for one route in a tree. Generated files carry only this. */
+export type RouteEntry = {
+    /** boundary error key */
+    bek?: string | null;
+    /** declared error keys */
+    ek?: readonly string[];
+    /** each declared key's status key, read off its factory: a generated tree has no factory to ask */
+    es?: Readonly<Record<string, string>>;
+    /** live record: only in `app.toRouteTree()` snapshots, never in generated files */
+    h?: RouteRecord;
+    /** internal route (spec, docs, manifest) */
+    i?: 1 | true;
+    /** what `.input()` declares: a delegated leaf's body media type is checked against it */
+    iv?: InputSchemas | null;
+    /** route meta */
+    mt?: Readonly<Record<string, unknown>> | null;
+    /** what `.output()` declares */
+    out?: OutputSchemas | null;
+};
+export interface RouteMeta {
+}
+/** Format of route trees: topology + per-route data. */
+export declare const ROUTE_TREE_VERSION = 2;
+export type RouteTree = {
+    meta: Record<string, RouteMeta>;
+    root: TreeNode;
+    routes: Record<RouteId, RouteEntry>;
+    v?: number;
+};
+/** A null-prototype record, so a segment or method named `__proto__` is just a key. */
+export declare function dict<T>(): Record<string, T>;
+export declare function createNode(): TreeNode;
+/**
+ * Put `id` at the leaf for `segments` × `method` (`"WS"` for the websocket slot). The same id
+ * already there is a no-op; any other id is a duplicate. Optional params are expanded by the
+ * caller: every call places exactly one leaf.
+ */
+export declare function insertLeaf(root: TreeNode, segments: readonly Segment[], method: string, id: RouteId): void;
+/** Place a route's leaves by pattern (an optional last param places two); returns the leaf id. */
+export declare function insertRoute(root: TreeNode, method: HttpMethod | "ALL", path: string, id?: RouteId): RouteId;
+/** Place a websocket route's leaf by pattern; returns its `RouteId`. */
+export declare function insertWsRoute(root: TreeNode, path: string, id?: RouteId): RouteId;
+/** Exact lookup: the id at the leaf for `segments` × `method`, without matching params against values. */
+export declare function findLeaf(root: TreeNode, segments: readonly Segment[], method: string): RouteId | undefined;
+/** True when the tree holds at least one websocket leaf. */
+export declare function hasWsLeaf(node: TreeNode): boolean;
+/** Every leaf, with its concrete path pattern (optional params already expanded by insertion). */
+export declare function forEachLeaf(node: TreeNode, cb: (method: string, path: string, id: RouteId) => void, prefix?: string): void;
+/** Deep copy into fresh null-prototype nodes; with `keep`, only the static leaves it keeps. */
+export declare function cloneTree(node: TreeNode, keep?: (id: RouteId) => boolean): TreeNode;
+/** Deep-freeze a loaded tree so no app can mutate a module other apps also import. */
+export declare function freezeTree(node: TreeNode): TreeNode;
+/** Reject a tree whose leaves are not route ids: a `routes.gen.ts` written by an older honey holds handler objects there. */
+export declare function assertTreeFormat(tree: {
+    root?: unknown;
+    routes?: unknown;
+    v?: unknown;
+}): void;

package/dist/routing/tree.js

@@ -0,0 +1,196 @@
+/**
+ * Router topology. Leaves are `RouteId`s, never handler objects: what a leaf runs is looked up in
+ * the serving app's own route table, so two apps that load one tree never share a record.
+ */
+import { canonical, expandOptional, parsePattern, routeId } from "./pattern.js";
+/** Format of route trees: topology + per-route data. */
+export const ROUTE_TREE_VERSION = 2;
+/** A null-prototype record, so a segment or method named `__proto__` is just a key. */
+export function dict() {
+    return Object.create(null);
+}
+export function createNode() {
+    return { d: null, m: null, s: dict(), w: null, ws: null };
+}
+function describe(method, path) {
+    return method === "WS" ? `WebSocket route: ${path}` : `route: ${method} ${path}`;
+}
+/** Put the id in a method map; the same id already there is a no-op, any other id a duplicate. */
+function setLeaf(map, leaf) {
+    const prev = map[leaf.method];
+    if (prev !== undefined && prev !== leaf.id)
+        throw new Error(`Duplicate ${describe(leaf.method, leaf.path)}`);
+    map[leaf.method] = leaf.id;
+}
+function wildcardLeaf(node, name, leaf) {
+    if (leaf.method === "WS")
+        throw new Error("Wildcard segments not supported for WebSocket routes");
+    if (node.w !== null && node.w.n !== name)
+        throw new Error(`Wildcard name conflict: "${node.w.n}" vs "${name}"`);
+    node.w ??= { m: dict(), n: name };
+    setLeaf(node.w.m, leaf);
+}
+function paramChild(node, name, path) {
+    if (node.d !== null && node.d.n !== name) {
+        throw new Error(`Route "${path}": param name conflict — expected ":${node.d.n}" but got ":${name}"`);
+    }
+    node.d ??= { c: createNode(), n: name };
+    return node.d.c;
+}
+function staticChild(node, value) {
+    const child = node.s[value] ?? createNode();
+    node.s[value] = child;
+    return child;
+}
+/**
+ * Put `id` at the leaf for `segments` × `method` (`"WS"` for the websocket slot). The same id
+ * already there is a no-op; any other id is a duplicate. Optional params are expanded by the
+ * caller: every call places exactly one leaf.
+ */
+export function insertLeaf(root, segments, method, id) {
+    const leaf = { id, method, path: canonical(segments) };
+    let node = root;
+    for (const seg of segments) {
+        if (seg.k === "wildcard")
+            return wildcardLeaf(node, seg.n, leaf);
+        node = seg.k === "param" ? paramChild(node, seg.n, leaf.path) : staticChild(node, seg.v);
+    }
+    if (method !== "WS")
+        return setLeaf((node.m ??= dict()), leaf);
+    if (node.ws !== null && node.ws !== id)
+        throw new Error(`Duplicate WebSocket route: ${leaf.path}`);
+    node.ws = id;
+}
+function placeVariants(root, method, path, id) {
+    const segments = parsePattern(path);
+    const rid = id ?? routeId(method, canonical(segments));
+    for (const variant of expandOptional(segments)) {
+        if (findLeaf(root, variant, method) !== undefined)
+            throw new Error(`Duplicate ${describe(method, canonical(variant))}`);
+        insertLeaf(root, variant, method, rid);
+    }
+    return rid;
+}
+/** Place a route's leaves by pattern (an optional last param places two); returns the leaf id. */
+export function insertRoute(root, method, path, id) {
+    return placeVariants(root, method, path, id);
+}
+/** Place a websocket route's leaf by pattern; returns its `RouteId`. */
+export function insertWsRoute(root, path, id) {
+    return placeVariants(root, "WS", path, id);
+}
+/** Exact lookup: the id at the leaf for `segments` × `method`, without matching params against values. */
+export function findLeaf(root, segments, method) {
+    let node = root;
+    for (const seg of segments) {
+        if (node === undefined)
+            return undefined;
+        if (seg.k === "wildcard")
+            return node.w?.n === seg.n ? node.w.m[method] : undefined;
+        if (seg.k === "static")
+            node = node.s[seg.v];
+        else
+            node = node.d?.n === seg.n ? node.d.c : undefined;
+    }
+    if (node === undefined)
+        return undefined;
+    return method === "WS" ? (node.ws ?? undefined) : node.m?.[method];
+}
+/** True when the tree holds at least one websocket leaf. */
+export function hasWsLeaf(node) {
+    if (node.ws !== null)
+        return true;
+    if (Object.values(node.s).some(hasWsLeaf))
+        return true;
+    return node.d !== null && hasWsLeaf(node.d.c);
+}
+/** Every leaf, with its concrete path pattern (optional params already expanded by insertion). */
+export function forEachLeaf(node, cb, prefix = "") {
+    const here = prefix || "/";
+    for (const method in node.m)
+        cb(method, here, node.m[method]);
+    if (node.ws !== null)
+        cb("WS", here, node.ws);
+    for (const seg in node.s)
+        forEachLeaf(node.s[seg], cb, `${prefix}/${seg}`);
+    if (node.d !== null)
+        forEachLeaf(node.d.c, cb, `${prefix}/:${node.d.n}`);
+    if (node.w === null)
+        return;
+    const wildcard = node.w.n === "*" ? "*" : `*${node.w.n}`;
+    for (const method in node.w.m)
+        cb(method, `${prefix}/${wildcard}`, node.w.m[method]);
+}
+/** Whether `node` routes nothing, here or below. */
+function isEmpty(node) {
+    return node.m === null && node.d === null && node.w === null && node.ws === null && Object.keys(node.s).length === 0;
+}
+/** Deep copy into fresh null-prototype nodes; with `keep`, only the static leaves it keeps. */
+export function cloneTree(node, keep) {
+    const out = createNode();
+    for (const seg in node.s) {
+        const child = cloneTree(node.s[seg], keep);
+        /* a static subtree `keep` emptied goes with its leaves */
+        if (keep === undefined || !isEmpty(child))
+            out.s[seg] = child;
+    }
+    if (node.m !== null)
+        out.m = Object.assign(dict(), node.m);
+    if (keep !== undefined && out.m !== null) {
+        for (const method in out.m)
+            if (!keep(out.m[method]))
+                delete out.m[method];
+        if (Object.keys(out.m).length === 0)
+            out.m = null;
+    }
+    if (node.d !== null)
+        out.d = { c: cloneTree(node.d.c), n: node.d.n };
+    if (node.w !== null)
+        out.w = { m: Object.assign(dict(), node.w.m), n: node.w.n };
+    out.ws = node.ws;
+    return out;
+}
+/** Deep-freeze a loaded tree so no app can mutate a module other apps also import. */
+export function freezeTree(node) {
+    if (Object.isFrozen(node))
+        return node;
+    for (const seg in node.s)
+        freezeTree(node.s[seg]);
+    Object.freeze(node.s);
+    if (node.m !== null)
+        Object.freeze(node.m);
+    if (node.d !== null) {
+        freezeTree(node.d.c);
+        Object.freeze(node.d);
+    }
+    if (node.w !== null) {
+        Object.freeze(node.w.m);
+        Object.freeze(node.w);
+    }
+    return Object.freeze(node);
+}
+const STALE = "routeTree(): this route tree was generated by an older honey (leaves are handler objects, not route ids). Run `honey generate`.";
+function isObject(value) {
+    return value !== null && typeof value === "object";
+}
+function allIds(map) {
+    return !isObject(map) || Object.values(map).every((id) => typeof id === "string");
+}
+function wellFormed(node) {
+    if (!allIds(node.m) || !allIds(node.w?.m))
+        return false;
+    if (node.ws !== null && node.ws !== undefined && typeof node.ws !== "string")
+        return false;
+    if (!isObject(node.s))
+        return false;
+    if (!Object.values(node.s).every(wellFormed))
+        return false;
+    return !isObject(node.d) || wellFormed(node.d.c);
+}
+/** Reject a tree whose leaves are not route ids: a `routes.gen.ts` written by an older honey holds handler objects there. */
+export function assertTreeFormat(tree) {
+    if (!isObject(tree) || !isObject(tree.root) || !isObject(tree.routes))
+        throw new Error(STALE);
+    if (!wellFormed(tree.root))
+        throw new Error(STALE);
+}

package/dist/routing/types.d.ts

@@ -0,0 +1,20 @@
+/** The HTTP methods a route registers for; `ALL` in a tree leaf answers any of them. */
+export type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+/** A param name with its optional marker dropped: `id?` → `id`. */
+type ParamKey<T extends string> = T extends `${infer Name}?` ? Name : T;
+/**
+ * The param names of a route pattern, as a union: `/users/:id/posts/:postId` → `"id" | "postId"`.
+ * An optional param counts under its name; a named wildcard under its name, an unnamed one as `"*"`.
+ */
+export type ParamKeys<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? ParamKey<Param> | ParamKeys<`/${Rest}`> : Path extends `${string}:${infer Param}` ? ParamKey<Param> : Path extends `${string}*${infer Name}` ? Name extends "" ? "*" : Name : never;
+/** `ctx.params` for a route pattern; a pattern without params reads as a string record. */
+export type ParamsFromPath<Path extends string> = [ParamKeys<Path>] extends [never] ? Record<string, string> : {
+    [K in ParamKeys<Path>]: string;
+};
+/** Join a base path and a route path at the type level; `/` is the identity on either side. */
+export type MergePath<A extends string, B extends string> = A extends "/" ? B : B extends "/" ? A : `${A}${B}`;
+/** The routes of a mounted sub-app, moved under the mounting handle's base path. */
+export type PrefixRoutes<TBase extends string, TRoutes> = TBase extends "/" ? TRoutes : {
+    [P in keyof TRoutes & string as MergePath<TBase, P>]: TRoutes[P];
+};
+export {};

package/dist/routing/types.js

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

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

@@ -0,0 +1,62 @@
+import type { MiddlewareFn, RuntimeMiddleware } from "../middleware/middleware.ts";
+import type { WSHandler } from "../ws/contract.ts";
+import { type WSOriginPolicy } from "../ws/origin.ts";
+import { type InferInputMap, type NonBodyInput, type InputStep } from "../input/input.ts";
+import { type HandleView, type HoneyGraph, type PendingRoute } from "./register.ts";
+import type { DefaultMeta } from "./app-types.ts";
+import type { ErrorFactories } from "./settings.ts";
+import type { ParamsFromPath } from "./types.ts";
+/** The ctx a ws route's callbacks receive: the chain's ctx with the route's params. */
+export type WSRouteCtx<TCtx, TPath extends string> = TCtx & {
+    readonly params: ParamsFromPath<TPath>;
+};
+type WSBuilderState = {
+    readonly errorKeys: ReadonlySet<string>;
+    readonly errorSource: ErrorFactories | null;
+    readonly graph: HoneyGraph;
+    /** `.input()`: the schemas as written (for documentation) and the step they compile to */
+    readonly input: {
+        readonly schemas: NonBodyInput;
+        readonly step: InputStep;
+    } | null;
+    readonly meta: Readonly<Record<string, unknown>> | null;
+    readonly middlewares: readonly RuntimeMiddleware[];
+    readonly origins: WSOriginPolicy | null;
+    readonly parent: unknown;
+    readonly path: string;
+    readonly pending: PendingRoute;
+    readonly view: HandleView;
+};
+/** The builtins the build drops from a WebSocket route (`ws: false`): an upgrade has none of them. */
+type HttpOnlyMeta = "deprecated" | "invalidate" | "mcp" | "security";
+/** What a WebSocket route's `.meta()` takes: an HTTP route's meta, the HTTP-only builtins refused. */
+export type WsMeta<TMeta = never> = Omit<Partial<DefaultMeta>, HttpOnlyMeta> & {
+    readonly [K in HttpOnlyMeta]?: never;
+} & ([TMeta] extends [never] ? {} : TMeta);
+export declare class WSRouteBuilder<TCtx, TPath extends string, TParent> {
+    #private;
+    constructor(state: WSBuilderState);
+    /** Declare the error keys this route may throw, from a factory or the app's. */
+    errors(factory: Record<string, (...args: never[]) => unknown>, ...keys: string[]): WSRouteBuilder<TCtx, TPath, TParent>;
+    errors(...keys: string[]): WSRouteBuilder<TCtx, TPath, TParent>;
+    /** Validate the upgrade request's params, search, headers and cookies onto ctx.input. */
+    input<const TSchemas extends NonBodyInput>(schemas: TSchemas): WSRouteBuilder<TCtx & {
+        readonly input: InferInputMap<TSchemas>;
+    }, TPath, TParent>;
+    meta<TRouteMeta extends WsMeta<TParent extends {
+        readonly $meta: infer TMeta;
+    } ? TMeta : never>>(meta: TRouteMeta): WSRouteBuilder<TCtx, TPath, TParent>;
+    /**
+     * Browser origins allowed to open this socket: `"*"`, a list of origins, or a predicate.
+     * Same-origin (scheme, host and port) always passes. Without it, a cross-origin upgrade that
+     * carries `Cookie` or `Authorization` gets 403.
+     */
+    origins(policy: WSOriginPolicy): WSRouteBuilder<TCtx, TPath, TParent>;
+    /** Route-level middleware, after the chain and the scopes, before the upgrade. */
+    use<TAdds>(mw: MiddlewareFn<TCtx, TAdds>): WSRouteBuilder<TCtx & TAdds, TPath, TParent>;
+    /** Register the route with its connection callbacks and return the app. */
+    handler(callbacks: WSHandler<WSRouteCtx<TCtx, TPath>>): TParent;
+}
+/** The builder `ws(app, path)` starts on `view`'s handle, pending until `.handler()`. */
+export declare function startWsRoute<TCtx, TPath extends string, TParent>(graph: HoneyGraph, view: HandleView, parent: TParent, path: string): WSRouteBuilder<TCtx, TPath, TParent>;
+export {};

package/dist/routing/ws-builder.js

@@ -0,0 +1,109 @@
+/**
+ * The WebSocket route builder: what `ws(app, path)` returns. A ws route is an ordinary route record
+ * with method `WS`, so the chain, the scopes, meta and error declarations work as on any route; its
+ * handler is the upgrade itself. The origin check and the chain run first, so a refused upgrade is
+ * answered before any 101 (H18.12). `.input()` takes the non-body sources (an upgrade is a bodyless
+ * GET) and validates them after the chain, so a refused request answers 400 before any 101.
+ */
+import { REQUEST } from "../context/context.js";
+import { HoneyError } from "../errors/error.js";
+import { originAllowed, validateOriginPolicy } from "../ws/origin.js";
+import { createWsSession } from "../ws/session.js";
+import { compileInput } from "../input/input.js";
+import { joinPatterns, parsePattern } from "./pattern.js";
+import { addRoute, settle } from "./register.js";
+const NO_ADAPTER = "honey: a WebSocket route was requested but no adapter is set: call app.wsAdapter(adapter), or serve(app) on Node or Bun";
+/** The route's terminal: check the origin, then hand the request to the serving app's adapter. */
+function upgrader(callbacks, policy, route) {
+    return async (ctx) => {
+        const context = ctx;
+        const req = context.req;
+        const url = new URL(req.url);
+        const credentialed = req.headers.has("cookie") || req.headers.has("authorization");
+        /* the full origin, scheme + host + port, as the adapter's canonical URL spells it */
+        if (!originAllowed(policy, req.headers.get("origin"), url.origin, credentialed)) {
+            throw new HoneyError({ errorKey: "forbidden", status: "forbidden" });
+        }
+        /* the serving app's adapter: dispatch puts it on the request state of a ws request */
+        const adapter = context[REQUEST].ws;
+        if (adapter == null)
+            throw new Error(NO_ADAPTER);
+        const reconnectToken = url.searchParams.get("reconnect_token");
+        const handler = createWsSession({ callbacks, ctx, log: context[REQUEST].logger, reconnectToken, route });
+        return (await adapter.upgrade(req, context.env, handler)).response;
+    };
+}
+export class WSRouteBuilder {
+    #s;
+    constructor(state) {
+        this.#s = state;
+    }
+    #next(changes) {
+        return new WSRouteBuilder({ ...this.#s, ...changes });
+    }
+    errors(...args) {
+        const named = typeof args[0] === "object" && args[0] !== null ? args[0] : null;
+        const keys = (named === null ? args : args.slice(1));
+        return this.#next({ errorKeys: new Set([...this.#s.errorKeys, ...keys]), errorSource: named });
+    }
+    /** Validate the upgrade request's params, search, headers and cookies onto ctx.input. */
+    input(schemas) {
+        return this.#next({
+            input: { schemas, step: compileInput(schemas, ["GET"], this.#s.path) },
+        });
+    }
+    meta(meta) {
+        return this.#next({ meta: { ...this.#s.meta, ...meta } });
+    }
+    /**
+     * Browser origins allowed to open this socket: `"*"`, a list of origins, or a predicate.
+     * Same-origin (scheme, host and port) always passes. Without it, a cross-origin upgrade that
+     * carries `Cookie` or `Authorization` gets 403.
+     */
+    origins(policy) {
+        return this.#next({ origins: validateOriginPolicy(policy) });
+    }
+    /** Route-level middleware, after the chain and the scopes, before the upgrade. */
+    use(mw) {
+        return this.#next({ middlewares: [...this.#s.middlewares, mw] });
+    }
+    /** Register the route with its connection callbacks and return the app. */
+    handler(callbacks) {
+        const s = this.#s;
+        settle(s.graph, s.pending, s.view.node);
+        addRoute(s.graph, "WS", parsePattern(s.path), {
+            cm: s.view.chain,
+            cv: s.view.contextValues,
+            dk: s.errorKeys,
+            ef: s.errorSource,
+            fn: upgrader(callbacks, s.origins, s.path),
+            in: s.input?.step ?? null,
+            iv: s.input?.schemas ?? null,
+            out: null,
+            own: s.graph.settings,
+            rb: null,
+            rm: s.middlewares,
+            xm: s.meta,
+        });
+        return s.parent;
+    }
+}
+/** The builder `ws(app, path)` starts on `view`'s handle, pending until `.handler()`. */
+export function startWsRoute(graph, view, parent, path) {
+    const fullPath = joinPatterns(view.basePath, path);
+    const pending = { id: `WS ${fullPath}` };
+    graph.pending.add(pending);
+    return new WSRouteBuilder({
+        errorKeys: new Set(),
+        errorSource: null,
+        graph,
+        input: null,
+        meta: view.chainMeta,
+        middlewares: [],
+        origins: null,
+        parent,
+        path: fullPath,
+        pending,
+        view,
+    });
+}

package/dist/runtime/detect-runtime.d.ts

@@ -0,0 +1,16 @@
+/** The runtimes honey serves on. Cloudflare Workers is detected so `serve()` can say to export the app instead. */
+export type ServeRuntime = "bun" | "cloudflare" | "node";
+type RuntimeGlobals = {
+    readonly Bun?: unknown;
+    readonly navigator?: {
+        readonly userAgent?: string;
+    };
+    readonly process?: {
+        readonly versions?: {
+            readonly node?: string;
+        };
+    };
+};
+/** Bun first: it also reports a Node version. `g` is the global object, swapped in tests. */
+export declare function detectRuntime(g?: RuntimeGlobals): ServeRuntime;
+export {};

package/dist/runtime/detect-runtime.js

@@ -0,0 +1,11 @@
+/** Bun first: it also reports a Node version. `g` is the global object, swapped in tests. */
+export function detectRuntime(g = globalThis) {
+    if (g.Bun !== undefined)
+        return "bun";
+    const agent = g.navigator?.userAgent ?? "";
+    if (agent.startsWith("Cloudflare-Workers") || agent.startsWith("workerd"))
+        return "cloudflare";
+    if (g.process?.versions?.node !== undefined)
+        return "node";
+    throw new Error("serve() could not detect the runtime: expected Bun, Node, or Cloudflare Workers");
+}

package/dist/runtime/optional-peer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * An optional npm peer dependency, loaded the first time it is needed. `load` is the caller's own
+ * literal `import("ws")`, so bundlers see the specifier; this is a plain dynamic import of a real
+ * dependency, not a registry (H23). A missing peer fails with the package to install.
+ */
+/**
+ * A loader for peer `name`: the first call imports it, later calls share that import. A failed
+ * import is not remembered, so installing the peer later works without a restart.
+ */
+export declare function optionalPeer<T>(name: string, purpose: string, load: () => Promise<T>): () => Promise<T>;

package/dist/runtime/optional-peer.js

@@ -0,0 +1,19 @@
+/**
+ * An optional npm peer dependency, loaded the first time it is needed. `load` is the caller's own
+ * literal `import("ws")`, so bundlers see the specifier; this is a plain dynamic import of a real
+ * dependency, not a registry (H23). A missing peer fails with the package to install.
+ */
+/**
+ * A loader for peer `name`: the first call imports it, later calls share that import. A failed
+ * import is not remembered, so installing the peer later works without a restart.
+ */
+export function optionalPeer(name, purpose, load) {
+    let loading = null;
+    return () => {
+        loading ??= load().catch((cause) => {
+            loading = null;
+            throw new Error(`${purpose} need the "${name}" package, an optional peer dependency of honey. Install it: npm install ${name}`, { cause });
+        });
+        return loading;
+    };
+}

package/dist/schema/arktype.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ArkType → JSON Schema through the instance converter older ArkType carries; current ArkType
+ * publishes Standard JSON Schema, which the dispatch reads first. Core never imports arktype (F2).
+ */
+import type { JsonSchema } from "./to-json-schema.ts";
+/** The JSON Schema `schema`'s own `toJsonSchema` gives; {} without one, or when it throws. */
+export declare function arktypeJsonSchema(schema: unknown): JsonSchema;

package/dist/schema/arktype.js

@@ -0,0 +1,13 @@
+/** The JSON Schema `schema`'s own `toJsonSchema` gives; {} without one, or when it throws. */
+export function arktypeJsonSchema(schema) {
+    const convert = schema.toJsonSchema;
+    if (typeof convert !== "function")
+        return {};
+    try {
+        return convert.call(schema);
+    }
+    catch {
+        /* ArkType throws for a node JSON Schema cannot say, such as a morph */
+        return {};
+    }
+}

package/dist/schema/canonicalize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One text per schema, the same on every machine: object keys in UTF-16 code-unit order, never a
+ * locale's, so two schemas that differ only in key order canonicalize alike and dedupe as one.
+ */
+/** Locale-independent string order: UTF-16 code units. */
+export declare function compareCodeUnits(a: string, b: string): number;
+/** `schema` as JSON text, every object's keys sorted at every depth; array order kept. */
+export declare function canonicalizeSchema(schema: Record<string, unknown>): string;

package/dist/schema/canonicalize.js

@@ -0,0 +1,19 @@
+/**
+ * One text per schema, the same on every machine: object keys in UTF-16 code-unit order, never a
+ * locale's, so two schemas that differ only in key order canonicalize alike and dedupe as one.
+ */
+/** Locale-independent string order: UTF-16 code units. */
+export function compareCodeUnits(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/** `schema` as JSON text, every object's keys sorted at every depth; array order kept. */
+export function canonicalizeSchema(schema) {
+    return JSON.stringify(schema, (_key, value) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return value;
+        /* fromEntries defines each key as its own property: a `__proto__` key stays a key */
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => compareCodeUnits(a, b)));
+    });
+}

package/dist/schema/effect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Effect → JSON Schema through the converter the caller passes (`JSONSchema.make`): core never
+ * imports effect (F2), so without one there is nothing to convert with.
+ */
+import type { EffectConverter, JsonSchema } from "./to-json-schema.ts";
+/** The JSON Schema `convert` gives for `schema`, its `$defs` kept for the document to lift into components; null without a converter. */
+export declare function effectJsonSchema(schema: unknown, convert: EffectConverter | undefined): JsonSchema | null;

package/dist/schema/effect.js

@@ -0,0 +1,4 @@
+/** The JSON Schema `convert` gives for `schema`, its `$defs` kept for the document to lift into components; null without a converter. */
+export function effectJsonSchema(schema, convert) {
+    return convert === undefined ? null : convert(schema);
+}

package/dist/schema/naming.d.ts

@@ -0,0 +1,31 @@
+import type { JsonSchema } from "./to-json-schema.ts";
+export type SchemaNameContext = {
+    readonly fieldPath?: readonly string[];
+    readonly method: string;
+    readonly path: string;
+    readonly role: "request";
+} | {
+    readonly fieldPath?: readonly string[];
+    readonly method: string;
+    readonly path: string;
+    readonly role: "response";
+    readonly status: number;
+};
+/** Six hex characters of `canonical`'s hash: the suffix that tells two clashing names apart. */
+export declare function shortHash(canonical: string): string;
+/**
+ * A name OpenAPI takes as a `components.schemas` key that also reads as an identifier in every
+ * SDK language: letters, digits and `_`, never a leading digit.
+ */
+export declare function sanitizeComponentName(name: string): string;
+/** The component name of the schema at `context`: verb, resource, then the field path or the role. */
+export declare function deriveSchemaName(context: SchemaNameContext): string;
+/** The name of an object nested in the component `owner` at `fieldPath`. */
+export declare function nestedSchemaName(owner: string, fieldPath: readonly string[]): string;
+/** Whether `schema` is honey's error body: `error_key`, `status`, and a `success` that can only be false. */
+export declare function isErrorEnvelope(schema: JsonSchema): boolean;
+/**
+ * The name of an error envelope several answers share: `Err`, its status (declared, else the
+ * answer's `fallback`, else none), then every error key, sorted.
+ */
+export declare function deriveErrorEnvelopeName(schema: JsonSchema, fallback: number | undefined): string;