@lovrozagar/honey 0.6.5 → 0.7.0

package/dist/ws/shared.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Options every WebSocket adapter takes, with the same meaning and defaults on Node, Bun, Deno
+ * and Workers. Each adapter enforces what its runtime does not.
+ */
+export type WSAdapterOptions = {
+    /**
+     * Largest inbound message in bytes. A bigger one closes the connection with 1009.
+     * Default 1 MiB.
+     */
+    maxPayload?: number;
+    /**
+     * Outbound bytes a socket may hold unsent before `backpressurePolicy` applies to the next
+     * `send()`. Default 8 MiB.
+     */
+    backpressureLimit?: number;
+    /**
+     * Over `backpressureLimit`: `"close"` closes the connection with 1013 (try again later),
+     * `"drop"` discards the message. Default `"close"`.
+     */
+    backpressurePolicy?: "close" | "drop";
+    /**
+     * Close a connection that has received nothing (no message, no pong) for this many
+     * milliseconds. Idle peers are pinged first where the runtime allows it. `0` disables.
+     * Default 120 000 (Bun's default). Deno and Bun take whole seconds.
+     */
+    idleTimeout?: number;
+    /**
+     * Choose the subprotocol from the ones the client offered (`Sec-WebSocket-Protocol`).
+     * Return `null` or `undefined` for none. Default: the first one offered.
+     */
+    protocol?: (offered: string[], req: Request) => string | null | undefined;
+};
+export type ResolvedWSOptions = {
+    backpressureLimit: number;
+    backpressurePolicy: "close" | "drop";
+    idleTimeout: number;
+    maxPayload: number;
+    protocol: (offered: string[], req: Request) => string | null | undefined;
+};
+export declare const DEFAULT_MAX_PAYLOAD: number;
+export declare const DEFAULT_BACKPRESSURE_LIMIT: number;
+export declare const DEFAULT_IDLE_TIMEOUT = 120000;
+/** Close codes the adapters and the realtime server use. */
+export declare const CLOSE_NORMAL = 1000;
+export declare const CLOSE_GOING_AWAY = 1001;
+export declare const CLOSE_POLICY = 1008;
+export declare const CLOSE_TOO_BIG = 1009;
+export declare const CLOSE_INTERNAL = 1011;
+export declare const CLOSE_TRY_AGAIN = 1013;
+/** Longest close reason a frame can carry (125-byte control payload minus the 2-byte code). */
+export declare const MAX_CLOSE_REASON = 123;
+export declare function resolveWSOptions(opts: WSAdapterOptions | undefined): ResolvedWSOptions;
+/** The subprotocols the client offered, in order. */
+export declare function offeredProtocols(req: Request): string[];
+/** The subprotocol to answer with, or `null`. A choice the client did not offer is ignored. */
+export declare function selectProtocol(req: Request, opts: ResolvedWSOptions): string | null;
+/** Outbound bytes the runtime holds for this socket, when it reports them. */
+export declare function bufferedAmountOf(raw: unknown): number;
+/** Whether an inbound message is larger than `limit` bytes. */
+export declare function exceedsPayload(data: ArrayBuffer | ArrayBufferView | Blob | string, limit: number): boolean;
+/** `data` as an `ArrayBuffer` holding exactly its bytes (a pooled Buffer's backing store is larger). */
+export declare function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;
+/** A close code a server may send: 1000, 1001-1014 except the reserved ones, or 3000-4999. */
+export declare function sendableCloseCode(code: number | undefined): number;
+//# sourceMappingURL=shared.d.ts.map

package/dist/ws/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/ws/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CACzE,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC/B,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,OAAO,GAAG,MAAM,CAAA;IACpC,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CACxE,CAAA;AAED,eAAO,MAAM,mBAAmB,QAAc,CAAA;AAC9C,eAAO,MAAM,0BAA0B,QAAkB,CAAA;AACzD,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAE3C,4DAA4D;AAC5D,eAAO,MAAM,YAAY,OAAO,CAAA;AAChC,eAAO,MAAM,gBAAgB,OAAO,CAAA;AACpC,eAAO,MAAM,YAAY,OAAO,CAAA;AAChC,eAAO,MAAM,aAAa,OAAO,CAAA;AACjC,eAAO,MAAM,cAAc,OAAO,CAAA;AAClC,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAYnC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,iBAAiB,CActF;AAED,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CASvD;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAKnF;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQrD;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAS1G;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,WAAW,CAK9E;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKlE"}

package/dist/ws/shared.js

@@ -0,0 +1,103 @@
+export const DEFAULT_MAX_PAYLOAD = 1024 * 1024;
+export const DEFAULT_BACKPRESSURE_LIMIT = 8 * 1024 * 1024;
+export const DEFAULT_IDLE_TIMEOUT = 120_000;
+/** Close codes the adapters and the realtime server use. */
+export const CLOSE_NORMAL = 1000;
+export const CLOSE_GOING_AWAY = 1001;
+export const CLOSE_POLICY = 1008;
+export const CLOSE_TOO_BIG = 1009;
+export const CLOSE_INTERNAL = 1011;
+export const CLOSE_TRY_AGAIN = 1013;
+/** Longest close reason a frame can carry (125-byte control payload minus the 2-byte code). */
+export const MAX_CLOSE_REASON = 123;
+const firstOffered = (offered) => offered[0] ?? null;
+function nonNegative(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`WebSocket adapter: ${name} must be a non-negative number`);
+    }
+    return value;
+}
+export function resolveWSOptions(opts) {
+    const policy = opts?.backpressurePolicy ?? "close";
+    if (policy !== "close" && policy !== "drop") {
+        throw new TypeError('WebSocket adapter: backpressurePolicy must be "close" or "drop"');
+    }
+    const maxPayload = nonNegative("maxPayload", opts?.maxPayload, DEFAULT_MAX_PAYLOAD);
+    if (maxPayload === 0)
+        throw new TypeError("WebSocket adapter: maxPayload must be positive");
+    return {
+        backpressureLimit: nonNegative("backpressureLimit", opts?.backpressureLimit, DEFAULT_BACKPRESSURE_LIMIT),
+        backpressurePolicy: policy,
+        idleTimeout: nonNegative("idleTimeout", opts?.idleTimeout, DEFAULT_IDLE_TIMEOUT),
+        maxPayload,
+        protocol: opts?.protocol ?? firstOffered,
+    };
+}
+/** The subprotocols the client offered, in order. */
+export function offeredProtocols(req) {
+    const raw = req.headers.get("sec-websocket-protocol");
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const part of raw.split(",")) {
+        const p = part.trim();
+        if (p !== "")
+            out.push(p);
+    }
+    return out;
+}
+/** The subprotocol to answer with, or `null`. A choice the client did not offer is ignored. */
+export function selectProtocol(req, opts) {
+    const offered = offeredProtocols(req);
+    if (offered.length === 0)
+        return null;
+    const chosen = opts.protocol(offered, req);
+    return typeof chosen === "string" && offered.includes(chosen) ? chosen : null;
+}
+/** Outbound bytes the runtime holds for this socket, when it reports them. */
+export function bufferedAmountOf(raw) {
+    if (raw === null || typeof raw !== "object")
+        return 0;
+    const r = raw;
+    if (typeof r.getBufferedAmount === "function") {
+        const n = r.getBufferedAmount();
+        return typeof n === "number" ? n : 0;
+    }
+    return typeof r.bufferedAmount === "number" ? r.bufferedAmount : 0;
+}
+/** Whether an inbound message is larger than `limit` bytes. */
+export function exceedsPayload(data, limit) {
+    if (typeof data === "string") {
+        if (data.length > limit)
+            return true;
+        /* a UTF-16 unit is at most 3 UTF-8 bytes, so most strings need no encode */
+        if (data.length * 3 <= limit)
+            return false;
+        return new TextEncoder().encode(data).byteLength > limit;
+    }
+    if (typeof Blob !== "undefined" && data instanceof Blob)
+        return data.size > limit;
+    return data.byteLength > limit;
+}
+/** `data` as an `ArrayBuffer` holding exactly its bytes (a pooled Buffer's backing store is larger). */
+export function toArrayBuffer(data) {
+    if (data instanceof ArrayBuffer)
+        return data;
+    const { buffer, byteLength, byteOffset } = data;
+    if (byteOffset === 0 && byteLength === buffer.byteLength && buffer instanceof ArrayBuffer)
+        return buffer;
+    return buffer.slice(byteOffset, byteOffset + byteLength);
+}
+/** A close code a server may send: 1000, 1001-1014 except the reserved ones, or 3000-4999. */
+export function sendableCloseCode(code) {
+    if (code === undefined)
+        return 1000;
+    if (code === 1000 || (code >= 3000 && code <= 4999))
+        return code;
+    if (code >= 1001 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006)
+        return code;
+    return 1000;
+}
+//# sourceMappingURL=shared.js.map

package/dist/ws/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/ws/shared.ts"],"names":[],"mappings":"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"}

package/dist/ws-origin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which browser origins may open a WebSocket. A browser lets any page open a socket to any host
+ * and sends that host's cookies with it, so a cookie-authenticated socket is open to cross-site
+ * hijacking unless the server checks `Origin`.
+ *
+ * - `"*"`: every origin.
+ * - a list: those exact origins (`https://app.example.com`), plus same-origin.
+ * - a function: called with the `Origin` value; same-origin always passes.
+ * - unset (the default): same-origin always passes; a cross-origin upgrade is rejected when it
+ *   carries credentials (`Cookie` or `Authorization`), since that is what hijacking needs. A
+ *   request without `Origin` (not a browser) passes.
+ */
+export type WSOriginPolicy = "*" | readonly string[] | ((origin: string) => boolean);
+export declare function validateOriginPolicy(policy: unknown): WSOriginPolicy;
+/**
+ * Whether an upgrade from `origin` may proceed. `host` is the host the client asked for
+ * (`clientInfo(ctx).host`, which follows `trustProxy`).
+ */
+export declare function originAllowed(policy: WSOriginPolicy | null, origin: string | null, host: string | null, hasCredentials: boolean): boolean;
+//# sourceMappingURL=ws-origin.d.ts.map

package/dist/ws-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-origin.d.ts","sourceRoot":"","sources":["../src/ws-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAA;AAWpF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAUpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,cAAc,GAAG,IAAI,EAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,cAAc,EAAE,OAAO,GACrB,OAAO,CAQT"}

package/dist/ws-origin.js

@@ -0,0 +1,41 @@
+function originHost(origin) {
+    if (origin === "null")
+        return null;
+    try {
+        return new URL(origin).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+export function validateOriginPolicy(policy) {
+    if (policy === "*" || typeof policy === "function")
+        return policy;
+    if (Array.isArray(policy) && policy.every((o) => typeof o === "string")) {
+        for (const o of policy) {
+            if (originHost(o) === null)
+                throw new TypeError(`allowedOrigins: "${o}" is not an origin like https://example.com`);
+        }
+        return Object.freeze([...policy]);
+    }
+    throw new TypeError('allowedOrigins must be "*", a list of origins, or a function');
+}
+/**
+ * Whether an upgrade from `origin` may proceed. `host` is the host the client asked for
+ * (`clientInfo(ctx).host`, which follows `trustProxy`).
+ */
+export function originAllowed(policy, origin, host, hasCredentials) {
+    if (policy === "*")
+        return true;
+    if (origin === null)
+        return true;
+    const oh = originHost(origin);
+    if (oh !== null && host !== null && oh === host.toLowerCase())
+        return true;
+    if (policy === null)
+        return !hasCredentials;
+    if (typeof policy === "function")
+        return policy(origin) === true;
+    return policy.includes(origin);
+}
+//# sourceMappingURL=ws-origin.js.map

package/dist/ws-origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-origin.js","sourceRoot":"","sources":["../src/ws-origin.ts"],"names":[],"mappings":"AAcA,SAAS,UAAU,CAAC,MAAc;IACjC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,CAAC;QACJ,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAA;IAC1C,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAe;IACnD,IAAI,MAAM,KAAK,GAAG,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,MAAwB,CAAA;IACnF,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QACzE,KAAK,MAAM,CAAC,IAAI,MAAkB,EAAE,CAAC;YACpC,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI;gBACzB,MAAM,IAAI,SAAS,CAAC,oBAAoB,CAAC,6CAA6C,CAAC,CAAA;QACzF,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAI,MAAmB,CAAC,CAAC,CAAA;IAChD,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAA;AACpF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC5B,MAA6B,EAC7B,MAAqB,EACrB,IAAmB,EACnB,cAAuB;IAEvB,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAC/B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAChC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC7B,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAA;IAC1E,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,CAAC,cAAc,CAAA;IAC3C,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,CAAA;IAChE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC/B,CAAC"}

package/dist/yaml.d.ts

@@ -1,4 +1,18 @@
-/** JSON-compatible YAML 1.2 emitter — same document as JSON.stringify, different encoding. */
+/**
+ * JSON-compatible YAML 1.2 emitter: the same document as `JSON.stringify`, in a
+ * different encoding. Input is first normalized through JSON (so `undefined` keys
+ * are skipped, `Date` becomes its ISO string, `NaN` becomes `null`), then every
+ * string that is not plainly safe is written as a double-quoted scalar, which
+ * also reads the same under YAML 1.1 parsers.
+ */
 export declare function yamlSiblingPath(jsonPath: string): string;
+/**
+ * Where an OpenAPI output configured at `path` is written. A `.yaml`/`.yml` path is that YAML file
+ * alone; any other path is JSON there plus its YAML sibling.
+ */
+export declare function openApiOutputPaths(path: string): {
+    json: string | null;
+    yaml: string;
+};
 export declare function toYaml(value: unknown): string;
 //# sourceMappingURL=yaml.d.ts.map

package/dist/yaml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAI9F,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C"}
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAGtF;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK7C"}

package/dist/yaml.js

@@ -0,0 +1,101 @@
+/**
+ * JSON-compatible YAML 1.2 emitter: the same document as `JSON.stringify`, in a
+ * different encoding. Input is first normalized through JSON (so `undefined` keys
+ * are skipped, `Date` becomes its ISO string, `NaN` becomes `null`), then every
+ * string that is not plainly safe is written as a double-quoted scalar, which
+ * also reads the same under YAML 1.1 parsers.
+ */
+const INDENT = "  ";
+export function yamlSiblingPath(jsonPath) {
+    if (jsonPath.endsWith(".yaml") || jsonPath.endsWith(".yml"))
+        return jsonPath.replace(/\.yml$/, ".yaml");
+    return jsonPath.endsWith(".json") ? `${jsonPath.slice(0, -5)}.yaml` : `${jsonPath}.yaml`;
+}
+/**
+ * Where an OpenAPI output configured at `path` is written. A `.yaml`/`.yml` path is that YAML file
+ * alone; any other path is JSON there plus its YAML sibling.
+ */
+export function openApiOutputPaths(path) {
+    if (path.endsWith(".yaml") || path.endsWith(".yml"))
+        return { json: null, yaml: path };
+    return { json: path, yaml: yamlSiblingPath(path) };
+}
+export function toYaml(value) {
+    const json = JSON.stringify(value);
+    /* JSON.stringify(undefined) is undefined; emit the JSON equivalent of "nothing". */
+    const normalized = json === undefined ? null : JSON.parse(json);
+    return `${emit(normalized, 0)}\n`;
+}
+function emit(value, indent) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "string")
+        return emitString(value);
+    if (Array.isArray(value))
+        return emitArray(value, indent);
+    return emitObject(value, indent);
+}
+/*
+ * A plain scalar is used only for a conservative shape: starts with a letter,
+ * `_`, `/` or `$`; contains only word characters, `.`, `/`, `$`, `-`, `+`,
+ * `{}`, `()` and inner spaces. That excludes every indicator, `: `, ` #`,
+ * leading digits (numbers, YAML 1.1 octal and sexagesimal), and `.inf`/`.nan`.
+ */
+const PLAIN_RE = /^[A-Za-z_/$](?:[\w./${}()+-]| (?! ))*$/;
+/* Words YAML 1.1 or 1.2 resolves to null or a boolean. */
+const RESERVED_RE = /^(?:y|n|yes|no|on|off|true|false|null|~)$/i;
+function emitString(value) {
+    if (PLAIN_RE.test(value) && !value.endsWith(" ") && !RESERVED_RE.test(value))
+        return value;
+    return quote(value);
+}
+/*
+ * JSON string syntax is a valid YAML double-quoted scalar, except that YAML
+ * forbids raw DEL, C1 controls (other than NEL) and the BOM/non-characters.
+ */
+function quote(value) {
+    return JSON.stringify(value).replace(/[\u007f-\u0084\u0086-\u009f￾￿]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function isNonEmptyCollection(value) {
+    if (Array.isArray(value))
+        return value.length > 0;
+    return value !== null && typeof value === "object" && Object.keys(value).length > 0;
+}
+function emitArray(value, indent) {
+    if (value.length === 0)
+        return "[]";
+    const pad = INDENT.repeat(indent);
+    const childPad = INDENT.repeat(indent + 1);
+    return value
+        .map((item) => {
+        if (isNonEmptyCollection(item)) {
+            const inner = emit(item, indent + 1);
+            const lines = inner.split("\n");
+            const first = lines[0]?.startsWith(childPad) ? lines[0].slice(childPad.length) : (lines[0] ?? "");
+            return [`${pad}- ${first}`, ...lines.slice(1)].join("\n");
+        }
+        return `${pad}- ${emit(item, 0)}`;
+    })
+        .join("\n");
+}
+function emitObject(value, indent) {
+    const keys = Object.keys(value);
+    if (keys.length === 0)
+        return "{}";
+    const pad = INDENT.repeat(indent);
+    return keys
+        .map((key) => {
+        const child = value[key];
+        const renderedKey = emitString(key);
+        if (isNonEmptyCollection(child)) {
+            return `${pad}${renderedKey}:\n${emit(child, indent + 1)}`;
+        }
+        return `${pad}${renderedKey}: ${emit(child, 0)}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=yaml.js.map

package/dist/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"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"}

package/docs/invalidate-spec.md

@@ -2,7 +2,9 @@
 
 ## Status
 
-Draft
+Implemented. Generated route types narrow `invalidate` to the selector union, and generation
+validates every authored selector against the route graph (a selector that names no route fails
+`honey generate`; duplicates are removed). See "Validation Rules".
 
 ## Goal
 
@@ -74,6 +76,8 @@ Reason:
 
 ### Mutation Invalidating Collection Read
 
+<!-- snippet:skip -->
+
 ```ts
 .meta({
   operationId: "project.create",
@@ -83,6 +87,8 @@ Reason:
 
 ### Mutation Invalidating Collection And Entity Reads
 
+<!-- snippet:skip -->
+
 ```ts
 .meta({
   operationId: "project.update",
@@ -95,6 +101,8 @@ Reason:
 
 ### Mutation Invalidating Query-Like POST Reads
 
+<!-- snippet:skip -->
+
 ```ts
 .meta({
   operationId: "project.import",
@@ -148,12 +156,16 @@ type GeneratedInvalidateRoute =
 
 Then the generated meta type becomes effectively:
 
+<!-- snippet:skip -->
+
 ```ts
 invalidate?: readonly GeneratedInvalidateRoute[] | null
 ```
 
 If generated route-aware types are unavailable, the type falls back to:
 
+<!-- snippet:skip -->
+
 ```ts
 readonly string[] | null
 ```

package/docs/meta-spec.md

@@ -7,6 +7,8 @@ Status: implemented in `@lovrozagar/honey` (tree of record: `packages/core`).
 Before this feature, `generateOpenApi` mapped route meta onto the operation object with a
 hardcoded allowlist of eight fields:
 
+<!-- snippet:skip -->
+
 ```ts
 summary, description, tags, deprecated, operationId, security, invalidate → x-invalidate, mcp → x-mcp
 ```
@@ -141,6 +143,8 @@ response, the query descriptor on the search input.
 `read` plus `match` expresses that. Several entries read one key and are told apart by the union's
 discriminant:
 
+<!-- snippet:skip -->
+
 ```ts
 schema: {
 	entityFacts: {
@@ -202,6 +206,8 @@ design assumes.
 
 ### 2.4 Profiles (multi-document)
 
+<!-- snippet:skip -->
+
 ```ts
 profiles: {
   public:  { include: ["x-entity", "x-query"] },       // default-deny — preferred
@@ -224,6 +230,8 @@ things to withhold is genuinely shorter than the list to publish.
 
 - A document selects a profile:
 
+<!-- snippet:skip -->
+
 ```ts
 codegen: {
   openApi: [
@@ -245,6 +253,8 @@ covers "never, anywhere".
 
 `OpenApiMeta` now carries:
 
+<!-- snippet:skip -->
+
 ```ts
 extensions?: Record<`x-${string}`, unknown>
 ```
@@ -263,6 +273,8 @@ separation, and fails on nothing.
 A fact enforced by middleware should not be retyped on every route it protects. Middleware can
 contribute meta to every route that mounts it:
 
+<!-- snippet:skip -->
+
 ```ts
 export const shard = createMiddleware(fn, { meta: { tenant: "project_id" } })
 // or: defineMiddleware({ fn, errors: […], meta: { tenant: "project_id" } })
@@ -279,26 +291,26 @@ one, because it makes a consumer confident about the wrong parameter.
 Rules:
 
 - **Explicit always wins.** Chain `.meta()` and route `.meta()` both outrank a contributed value.
-  Among middleware, later mount order wins.
+  Among middleware, the one that runs later wins: chain, then scoped, then route level.
 - **Contributed meta is real meta.** It lands in the route's `mt`, so it appears on `ctx.meta`, in
   the manifest, and — critically — it is subject to the policy. A middleware cannot smuggle an
   untagged fact into the document: with `strict: "error"`, contributing `sla` with no policy entry
   fails the build exactly as writing it on a route would.
-- **A scoped middleware registered after its routes still reaches them.** `.use("/prefix", mw)`
-  back-fills already-registered handlers, mirroring what honey already does for scoped error keys.
-  A tag missing where enforcement happens is the failure direction that matters.
+- **A scoped middleware registered after its routes still reaches them.** Meta is resolved from
+  the chain each route runs when the app finalizes, so registration order does not matter, and a
+  route mounted with `.route(sub)` gets the meta of the chain it is mounted on. A tag missing where
+  enforcement happens is the failure direction that matters.
 - **`internal` may not be contributed.** It controls whether a route appears in generated artifacts
   at all; a middleware that removed 104 routes from the document would be invisible in both the
   route and the middleware. `createMiddleware` throws.
 
-### Why it is resolved at registration, not per request
+### Why it is resolved at finalize, not per request
 
-The precompiled route tree bakes `mt` as a JSON literal (`mw` is never serialized), and
-`.routeTree()` patch mode deliberately does not overwrite `mt` — the baked value is what production
-serves. Contributed meta is therefore collected once, when the route registers, so the JIT and
-precompiled paths cannot disagree. A lazily-derived value would produce one answer in development
-and a different, stale one in production — the exact class of divergence this feature exists to
-remove. The usual contract applies: change what a middleware contributes, regenerate.
+Contributed meta is collected once, when the app finalizes (first request, `toRouteTree()` or
+codegen), from the same resolved chain the route runs — so the request path, `ctx.meta`, the
+manifest and the document cannot disagree, with or without a loaded route tree. A lazily-derived
+value per request would make the served meta depend on timing. The generated `routes.gen.ts` carries
+the meta of the generating build; change what a middleware contributes, then regenerate.
 
 ### Two things to put in a release note
 
@@ -326,6 +338,8 @@ stamped with `searchable: null` or `tenantColumn: null` means _"I don't know"_,
 straight through publishes `"x-searchable": null`, which a consumer reads as _"nothing is
 searchable"_ — a confident wrong answer, worse than silence. Normalize in the policy:
 
+<!-- snippet:skip -->
+
 ```ts
 expand: (e) => ({
 	"x-entity": e.table,
@@ -423,6 +437,8 @@ Every message carries `method`, `path`, source key and target key.
 
 ## 6. Validating what is emitted
 
+<!-- snippet:skip -->
+
 ```ts
 rateLimit: {
   key: "x-rate-limit",
@@ -451,9 +467,17 @@ eight mappings, unchanged, with the same truthiness gates and the same emit orde
 | `security`    | `security` (normalized)      | truthy           | ✓    | —   |
 | `invalidate`  | `x-invalidate`               | array, non-empty | ✓    | —   |
 | `mcp`         | `x-mcp`                      | `=== true`       | ✓    | —   |
-| `internal`    | _hidden_                     | —                | —    | —   |
+| `internal`    | _route left out_             | `=== true`       | —    | —   |
 | `extensions`  | verbatim passthrough         | —                | ✓    | ✓   |
 
+A route with `internal: true` is left out of the served and generated OpenAPI document and the
+served `/manifest.json`; it still serves requests and still appears in `types.gen.d.ts`, so
+services can type against it. `security` must be a scheme name, a list of names, a list of name
+groups, or standard requirement objects — anything else fails generation instead of documenting the
+route as public — and every scheme it names must be in `securitySchemes`. `invalidate` selectors
+must name a registered route (`"GET /users/:id"`); a selector that names nothing fails generation
+unless the document is generated with `invalidate: "off"`.
+
 The WS column reproduces the previous WS mapping exactly (it was a strict subset). App entries
 default to `on: "both"`; the asymmetry is preserved only for the built-ins.