@nifrajs/core 1.13.0 → 2.1.0

package/dist/server/install.js

@@ -0,0 +1,21 @@
+/**
+ * Symbol-keyed install seams the opt-in feature plugins (`idempotency()`, `effectLedger()`) use to
+ * hand their runtime to a server. Kept in a dependency-free leaf, and keyed by symbol, so:
+ *   - the kernel can implement the seam without importing a feature's code (importing a bare symbol
+ *     never drags the lane's implementation into the base bundle), and
+ *   - the seam stays off the server's public typed surface (symbol-keyed methods are not part of it).
+ * Both sides reference the SAME registered symbol, so no module has to import the other.
+ */
+/** @internal Install the idempotency runtime on a server (called by the `idempotency()` plugin). */
+export const INSTALL_IDEMPOTENCY = Symbol.for("@nifrajs/core/install-idempotency");
+/** @internal Install the effect-ledger runtime on a server (called by the `effectLedger()` plugin). */
+export const INSTALL_EFFECT_LEDGER = Symbol.for("@nifrajs/core/install-effect-ledger");
+/** @internal Install the MCP runtime on a server (called by the `mcp()` plugin). */
+export const INSTALL_MCP = Symbol.for("@nifrajs/core/install-mcp");
+/** @internal Install the SSE streaming runtime on a server (called by the `sse()` plugin). */
+export const INSTALL_SSE = Symbol.for("@nifrajs/core/install-sse");
+/** @internal Install the Node-direct renderer on a server (called by the `nodeDirect()` plugin). */
+export const INSTALL_NODE_DIRECT = Symbol.for("@nifrajs/core/install-node-direct");
+/** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
+export const INSTALL_WS = Symbol.for("@nifrajs/core/install-ws");
+//# sourceMappingURL=install.js.map

package/dist/server/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/server/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,uGAAuG;AACvG,MAAM,CAAC,MAAM,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAC5D,qCAAqC,CACtC,CAAA;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;AAEjF,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAA;AAEjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA"}

package/dist/server/ledger-lane.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The opt-in per-request effect ledger. Installed by `.use(effectLedger())` and reached only by routes
+ * that declare `schema.capabilities`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the ledger machinery out.
+ *
+ * The kernel resolves a capability-declaring route's ledger wiring at registration (via
+ * {@link EffectLedgerRuntime.resolve}) and, on the request path, creates + attaches a ledger before the
+ * handler and settles it after (via {@link EffectLedgerRuntime.create}/`attach`/`settle`). Nothing here
+ * depends on server internals; the sink-error log is supplied per settle.
+ */
+import { type EffectLedgerOptions, type RequestLedger } from "../ledger.js";
+import type { IdentityPlugin } from "./server.js";
+/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
+export interface ResolvedEffectLedger {
+    readonly sink: EffectLedgerOptions["sink"];
+    readonly maxEntries: number;
+    readonly chain: boolean;
+    /** The registered route pattern - what the sealed ledger names (never the concrete URL). */
+    readonly method: string;
+    readonly path: string;
+    /** The route's declared capability tokens, surfaced on the sealed ledger. */
+    readonly declared: readonly string[];
+}
+/** The injected effect-ledger implementation the kernel calls through when the plugin is installed. */
+export interface EffectLedgerRuntime {
+    /** Resolve a capability-declaring route into its ledger wiring, or `undefined` when it declares none. */
+    resolve(capabilities: readonly string[], method: string, path: string): ResolvedEffectLedger | undefined;
+    /** Create the per-request ledger for a ledgered route. */
+    create(resolved: ResolvedEffectLedger): RequestLedger;
+    /** Attach a ledger to the request context so `useCapability` can append to it. */
+    attach(context: object, ledger: RequestLedger): void;
+    /** Seal the ledger and deliver it to the sink (empty ledgers are not delivered). */
+    settle<T>(ledger: RequestLedger, resolved: ResolvedEffectLedger, value: T, onSinkError: (fields: {
+        method: string;
+        path: string;
+        name: string;
+    }) => void): Promise<T>;
+}
+/**
+ * Build an effect-ledger runtime from the app-wide options. `sink` receives the sealed, token-only
+ * ledger when a capability-declaring route settles with recorded entries; `maxEntries` bounds a single
+ * request's ledger; `chain` opts into the per-entry hash chain.
+ */
+export declare function createEffectLedgerRuntime(options: EffectLedgerOptions): EffectLedgerRuntime;
+/**
+ * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a bounded,
+ * token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink receives the
+ * sealed ledger when the response settles (only when it recorded entries). Token-only by construction -
+ * capability ids, phases, counters, digests; never payloads, values, or the concrete URL (the route
+ * pattern is recorded). Without this plugin, capability-declaring routes simply carry no ledger.
+ */
+export declare function effectLedger(options: EffectLedgerOptions): IdentityPlugin;
+//# sourceMappingURL=ledger-lane.d.ts.map

package/dist/server/ledger-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-lane.d.ts","sourceRoot":"","sources":["../../src/server/ledger-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAErB,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5D,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAA;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,yGAAyG;IACzG,OAAO,CACL,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,oBAAoB,GAAG,SAAS,CAAA;IACnC,0DAA0D;IAC1D,MAAM,CAAC,QAAQ,EAAE,oBAAoB,GAAG,aAAa,CAAA;IACrD,kFAAkF;IAClF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IACpD,oFAAoF;IACpF,MAAM,CAAC,CAAC,EACN,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,CAAC,EACR,WAAW,EAAE,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAC5E,OAAO,CAAC,CAAC,CAAC,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CA6C3F;AAOD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAOzE"}

package/dist/server/ledger-lane.js

@@ -0,0 +1,82 @@
+/**
+ * The opt-in per-request effect ledger. Installed by `.use(effectLedger())` and reached only by routes
+ * that declare `schema.capabilities`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the ledger machinery out.
+ *
+ * The kernel resolves a capability-declaring route's ledger wiring at registration (via
+ * {@link EffectLedgerRuntime.resolve}) and, on the request path, creates + attaches a ledger before the
+ * handler and settles it after (via {@link EffectLedgerRuntime.create}/`attach`/`settle`). Nothing here
+ * depends on server internals; the sink-error log is supplied per settle.
+ */
+import { attachEffectLedger, createRequestLedger, DEFAULT_MAX_ENTRIES, } from "../ledger.js";
+import { INSTALL_EFFECT_LEDGER } from "./install.js";
+/**
+ * Build an effect-ledger runtime from the app-wide options. `sink` receives the sealed, token-only
+ * ledger when a capability-declaring route settles with recorded entries; `maxEntries` bounds a single
+ * request's ledger; `chain` opts into the per-entry hash chain.
+ */
+export function createEffectLedgerRuntime(options) {
+    if (typeof options.sink !== "function") {
+        throw new TypeError("effectLedger.sink must be a function");
+    }
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new RangeError("effectLedger.maxEntries must be a positive safe integer");
+    }
+    const chain = options.chain ?? false;
+    const sink = options.sink;
+    return {
+        resolve(capabilities, method, path) {
+            if (capabilities.length === 0)
+                return undefined;
+            return Object.freeze({ sink, maxEntries, chain, method, path, declared: capabilities });
+        },
+        create(resolved) {
+            return createRequestLedger({
+                method: resolved.method,
+                path: resolved.path,
+                declared: resolved.declared,
+                maxEntries: resolved.maxEntries,
+                chain: resolved.chain,
+            });
+        },
+        attach(context, ledger) {
+            attachEffectLedger(context, ledger);
+        },
+        async settle(ledger, resolved, value, onSinkError) {
+            const sealed = await ledger.seal();
+            if (sealed.entries.length === 0)
+                return value;
+            try {
+                await resolved.sink(sealed);
+            }
+            catch (err) {
+                // Token-only: the route pattern and the failure name - never entry payloads (there are none)
+                // and never the request. The ledger is observational, so a sink outage never fails the effect.
+                onSinkError({
+                    method: resolved.method,
+                    path: resolved.path,
+                    name: err instanceof Error ? err.name : "Error",
+                });
+            }
+            return value;
+        },
+    };
+}
+/**
+ * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a bounded,
+ * token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink receives the
+ * sealed ledger when the response settles (only when it recorded entries). Token-only by construction -
+ * capability ids, phases, counters, digests; never payloads, values, or the concrete URL (the route
+ * pattern is recorded). Without this plugin, capability-declaring routes simply carry no ledger.
+ */
+export function effectLedger(options) {
+    const runtime = createEffectLedgerRuntime(options);
+    const apply = (app) => {
+        ;
+        app[INSTALL_EFFECT_LEDGER](runtime);
+        return app;
+    };
+    return Object.assign(apply, { pluginName: "nifra:effect-ledger" });
+}
+//# sourceMappingURL=ledger-lane.js.map

package/dist/server/ledger-lane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-lane.js","sourceRoot":"","sources":["../../src/server/ledger-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GAGpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAoCpD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAA4B;IACpE,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAA;IAC7D,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAC5D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,UAAU,CAAC,yDAAyD,CAAC,CAAA;IACjF,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;IAEzB,OAAO;QACL,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI;YAChC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAA;YAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAA;QACzF,CAAC;QACD,MAAM,CAAC,QAAQ;YACb,OAAO,mBAAmB,CAAC;gBACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU;gBAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK;aACtB,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,CAAC,OAAO,EAAE,MAAM;YACpB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACrC,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW;YAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;YAClC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC7C,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAC7B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,6FAA6F;gBAC7F,+FAA+F;gBAC/F,WAAW,CAAC;oBACV,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,IAAI,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;iBAChD,CAAC,CAAA;YACJ,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;AACH,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,OAAO,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAA;IAClD,MAAM,KAAK,GAAG,CAAsB,GAAM,EAAK,EAAE;QAC/C,CAAC;QAAC,GAA0C,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,CAAA;QAC5E,OAAO,GAAG,CAAA;IACZ,CAAC,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,qBAAqB,EAAE,CAAmB,CAAA;AACtF,CAAC"}

package/dist/server/mcp-hook.d.ts

@@ -0,0 +1,28 @@
+import type { StandardSchemaV1 } from "../schema/standard.js";
+import type { Context, RouteSchema } from "./context.js";
+import type { McpPromptDescriptor, McpResourceDescriptor, PromptArgument, RouteDescriptor, ToolAnnotations } from "./server-types.js";
+export interface McpToolConfig {
+    readonly description: string;
+    readonly input: StandardSchemaV1;
+    readonly output?: StandardSchemaV1;
+    readonly annotations?: ToolAnnotations;
+}
+export interface McpToolPlan {
+    readonly path: string;
+    readonly schema: RouteSchema;
+    readonly run: (context: Context) => unknown;
+    readonly descriptor: NonNullable<RouteDescriptor["tool"]>;
+}
+export interface McpRuntime {
+    tool(name: string, config: McpToolConfig, handler: (input: unknown, context: Context) => unknown): McpToolPlan;
+    resource(uri: string, config: {
+        readonly name: string;
+        readonly description?: string;
+        readonly mimeType?: string;
+    }, read: McpResourceDescriptor["read"]): McpResourceDescriptor;
+    prompt(name: string, config: {
+        readonly description: string;
+        readonly arguments?: readonly PromptArgument[];
+    }, handler: McpPromptDescriptor["handler"]): McpPromptDescriptor;
+}
+//# sourceMappingURL=mcp-hook.d.ts.map

package/dist/server/mcp-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-hook.d.ts","sourceRoot":"","sources":["../../src/server/mcp-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAA;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;IAC3C,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,GACrD,WAAW,CAAA;IACd,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5F,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,GAClC,qBAAqB,CAAA;IACxB,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;KAAE,EACxF,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GACtC,mBAAmB,CAAA;CACvB"}

package/dist/server/mcp-hook.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mcp-hook.js.map

package/dist/server/mcp-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-hook.js","sourceRoot":"","sources":["../../src/server/mcp-hook.ts"],"names":[],"mappings":""}

package/dist/server/node-outcome-hook.d.ts

@@ -0,0 +1,9 @@
+/** Lazy Node-direct renderer seam. The base server retains the typed method but not its renderer. */
+import type { NodeServeOutcome } from "./node-outcome.js";
+import type { CtxSet } from "./server.js";
+export interface NodeOutcomeRuntime {
+    toOutcome(result: unknown, set: CtxSet): NodeServeOutcome;
+    fromResponse(response: Response): NodeServeOutcome;
+    timeout(): NodeServeOutcome;
+}
+//# sourceMappingURL=node-outcome-hook.d.ts.map

package/dist/server/node-outcome-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-outcome-hook.d.ts","sourceRoot":"","sources":["../../src/server/node-outcome-hook.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;IACzD,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,CAAA;IAClD,OAAO,IAAI,gBAAgB,CAAA;CAC5B"}

package/dist/server/node-outcome-hook.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=node-outcome-hook.js.map

package/dist/server/node-outcome-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-outcome-hook.js","sourceRoot":"","sources":["../../src/server/node-outcome-hook.ts"],"names":[],"mappings":""}

package/dist/server/node-outcome.d.ts

@@ -0,0 +1,37 @@
+import { type HandlerResult } from "./runtime-core.js";
+import type { CtxSet } from "./server.js";
+/**
+ * What {@link Server.resolveNode} returns: either a plain-data render the `@nifrajs/node` adapter writes
+ * to the socket directly (`kind: "json"` - status + headers + cookies + a pre-stringified body, **no**
+ * undici `Response` built or drained), a marked buffered response body (`kind: "body"` - e.g.
+ * @nifrajs/web's non-deferred SSR HTML), or a `Response` (`kind: "response"`) for everything else
+ * (redirects, 404/405/errors, unmarked or streaming bodies). Internal to the nifra<->node bridge.
+ */
+export type NodeServeOutcome = {
+    readonly kind: "response";
+    readonly response: Response;
+} | {
+    readonly kind: "json";
+    readonly status: number;
+    /** `c.set.headers` backing, or `undefined` when the handler never set a header. */
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    /** Queued `Set-Cookie` lines, or `undefined`; the adapter emits one header line each. */
+    readonly cookies: readonly string[] | undefined;
+    /** The JSON body already stringified, or `null` for an empty (204) response. */
+    readonly body: string | null;
+} | {
+    readonly kind: "body";
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined;
+    readonly body: string | Uint8Array;
+};
+/**
+ * `finalize` for the node-direct path - mirror of `toResponse` that skips the `Response` build:
+ * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
+ * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
+ * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
+ * works on Node).
+ */
+export declare function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutcome;
+export declare function nodeOutcomeFromResponse(response: Response): NodeServeOutcome;
+//# sourceMappingURL=node-outcome.d.ts.map

package/dist/server/node-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-outcome.d.ts","sourceRoot":"","sources":["../../src/server/node-outcome.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IAC9D,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC/C,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAA;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;CACnC,CAAA;AAEL;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAwBlF;AAID,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,CAK5E"}

package/dist/server/node-outcome.js

@@ -0,0 +1,75 @@
+/**
+ * Node-direct outcome shaping: the `@nifrajs/node` bridge's render form and the `Response` -> outcome
+ * conversion. Mirrors `respond.ts` but skips the undici `Response` build where the adapter can write a
+ * plain-data render straight to the socket. Imports only runtime-core + respond + the spine types.
+ */
+import { appendCookiesToResponse } from "./respond.js";
+import { isResponseResult } from "./runtime-core.js";
+/**
+ * `finalize` for the node-direct path - mirror of `toResponse` that skips the `Response` build:
+ * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
+ * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
+ * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
+ * works on Node).
+ */
+export function toNodeOutcome(result, set) {
+    if (isResponseResult(result)) {
+        const body = result.toNodeBody?.();
+        if (body !== undefined) {
+            return {
+                kind: "body",
+                status: body.status,
+                headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+                body: body.body,
+            };
+        }
+        return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set));
+    }
+    if (result instanceof Response) {
+        return nodeOutcomeFromResponse(appendCookiesToResponse(result, set));
+    }
+    const status = set.status ?? (result === undefined ? 204 : 200);
+    return {
+        kind: "json",
+        status,
+        headers: set._headers,
+        cookies: set._cookies,
+        body: result === undefined ? null : JSON.stringify(result),
+    };
+}
+const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
+export function nodeOutcomeFromResponse(response) {
+    const body = nodeResponseBody(response);
+    return body === undefined
+        ? { kind: "response", response }
+        : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body };
+}
+function nodeResponseBody(response) {
+    if (response.bodyUsed)
+        return undefined;
+    const body = response[NODE_RESPONSE_BODY];
+    return typeof body === "string" || body instanceof Uint8Array ? body : undefined;
+}
+function responseHeadersForNode(response) {
+    let headers;
+    response.headers.forEach((value, key) => {
+        headers ??= {};
+        headers[key] = value;
+    });
+    const setCookies = response.headers.getSetCookie?.();
+    if (setCookies !== undefined && setCookies.length > 0) {
+        headers ??= {};
+        headers["set-cookie"] = setCookies;
+    }
+    return headers;
+}
+function appendCookiesToNodeHeaders(headers, cookies) {
+    if (cookies === undefined || cookies.length === 0)
+        return headers;
+    const out = headers === undefined ? {} : { ...headers };
+    const existing = out["set-cookie"];
+    const setCookies = existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing];
+    out["set-cookie"] = [...setCookies, ...cookies];
+    return out;
+}
+//# sourceMappingURL=node-outcome.js.map

package/dist/server/node-outcome.js.map

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

package/dist/server/plugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Plugin definers and their types. A plugin is a function that augments an app (calling
+ * `use`/`derive`/`decorate` and/or registering routes) and returns it; these helpers attach a name
+ * for idempotent dedupe and pin the type-threading so `.use()` preserves the caller's typed server.
+ */
+import type { AnyServer } from "./server.js";
+/**
+ * A nifra **plugin**: a function that augments an app - calling `use`/`derive`/`decorate` and/or
+ * registering routes - and returns it. Because `derive`/`decorate` are type-threaded, an **inline**
+ * `app.use((a) => a.derive(...).decorate(...))` carries the added context to handlers defined after
+ * it (the `use` overload is generic over the concrete `this`). Wrap with {@link definePlugin} to
+ * attach a name for idempotent dedupe (applying the same named plugin twice - e.g. transitively - is
+ * a no-op).
+ */
+export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer = In> = ((app: In) => Out) & {
+    readonly pluginName?: string;
+};
+/**
+ * A named type-identity plugin built with {@link defineIdentityPlugin}. It returns the same concrete
+ * server type it receives, preserving the caller's typed registry and context across `.use()` while
+ * still allowing the plugin to register runtime hooks or handlers.
+ */
+export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
+    readonly pluginName?: string;
+};
+/**
+ * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
+ * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
+ * other without double-registering hooks.
+ *
+ * ```ts
+ * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * app.use(requestId)   // downstream handlers see c.requestId
+ * ```
+ *
+ * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
+ * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
+ * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
+ * and your whole typed client silently collapses to `any` - no type error, no runtime error.
+ */
+export declare function definePlugin<In extends AnyServer, Out extends AnyServer>(name: string, apply: (app: In) => Out): NifraPlugin<In, Out>;
+/**
+ * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
+ * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
+ * add context types - e.g. one mounting an auth handler. It threads the caller's *concrete* server type
+ * through `use`, so routes declared after `app.use(plugin)` keep their types.
+ *
+ * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
+ * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
+ * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
+ *
+ * ```ts
+ * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
+ * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export declare function defineIdentityPlugin(name: string, apply: <S extends AnyServer>(app: S) => S): IdentityPlugin;
+/**
+ * Alias of {@link defineIdentityPlugin} with a name that says what it's FOR: a plugin that **mounts
+ * routes/hooks but adds no context type** (an auth router, an audit logger). Use this - not
+ * {@link definePlugin} - for any such plugin, or the typed client silently collapses to `any`. The
+ * "identity" in {@link defineIdentityPlugin} refers to the type-identity it preserves; `defineRouterPlugin`
+ * is the same thing under a clearer name.
+ *
+ * Mount routes as a **side effect**, then return the app unchanged (registering via `.get`/`.post` would
+ * change the type away from the identity `S`; the mounted routes run but aren't in the caller's typed
+ * registry - that's the trade that keeps everything else typed):
+ *
+ * ```ts
+ * export const scim = defineRouterPlugin("scim", (app) => {
+ *   app.get("/scim/v2/Users", listUsers) // side effect: mounted at runtime
+ *   return app                           // return S unchanged → routes added after .use(scim) stay typed
+ * })
+ * const api = server().get("/a", h).use(scim).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export declare const defineRouterPlugin: typeof defineIdentityPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/server/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/server/plugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,SAAS,SAAS,GAAG,EAAE,IAAI,CAAC,CACvF,GAAG,EAAE,EAAE,KACJ,GAAG,CAAC,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,CAAC,SAAS,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,SAAS,EACtE,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,KAAK,GAAG,GACtB,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAEtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GACxC,cAAc,CAEhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,oBAA2C,CAAA"}

package/dist/server/plugin.js

@@ -0,0 +1,57 @@
+/**
+ * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
+ * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
+ * other without double-registering hooks.
+ *
+ * ```ts
+ * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * app.use(requestId)   // downstream handlers see c.requestId
+ * ```
+ *
+ * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
+ * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
+ * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
+ * and your whole typed client silently collapses to `any` - no type error, no runtime error.
+ */
+export function definePlugin(name, apply) {
+    return Object.assign(apply, { pluginName: name });
+}
+/**
+ * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
+ * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
+ * add context types - e.g. one mounting an auth handler. It threads the caller's *concrete* server type
+ * through `use`, so routes declared after `app.use(plugin)` keep their types.
+ *
+ * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
+ * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
+ * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
+ *
+ * ```ts
+ * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
+ * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export function defineIdentityPlugin(name, apply) {
+    return Object.assign(apply, { pluginName: name });
+}
+/**
+ * Alias of {@link defineIdentityPlugin} with a name that says what it's FOR: a plugin that **mounts
+ * routes/hooks but adds no context type** (an auth router, an audit logger). Use this - not
+ * {@link definePlugin} - for any such plugin, or the typed client silently collapses to `any`. The
+ * "identity" in {@link defineIdentityPlugin} refers to the type-identity it preserves; `defineRouterPlugin`
+ * is the same thing under a clearer name.
+ *
+ * Mount routes as a **side effect**, then return the app unchanged (registering via `.get`/`.post` would
+ * change the type away from the identity `S`; the mounted routes run but aren't in the caller's typed
+ * registry - that's the trade that keeps everything else typed):
+ *
+ * ```ts
+ * export const scim = defineRouterPlugin("scim", (app) => {
+ *   app.get("/scim/v2/Users", listUsers) // side effect: mounted at runtime
+ *   return app                           // return S unchanged → routes added after .use(scim) stay typed
+ * })
+ * const api = server().get("/a", h).use(scim).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export const defineRouterPlugin = defineIdentityPlugin;
+//# sourceMappingURL=plugin.js.map

package/dist/server/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/server/plugin.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,KAAuB;IAEvB,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAyB,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,KAAyC;IAEzC,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAmB,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgC,oBAAoB,CAAA"}

package/dist/server/query.d.ts

@@ -0,0 +1,18 @@
+import type { RequestSource } from "./server.js";
+export declare function searchOf(url: string): string;
+/** A query value: a single occurrence is a string; a repeated key promotes to a string[] so an
+ * array query schema (`t.array(t.string())`) can validate `?tag=a&tag=b` - last-wins silently
+ * dropped values before (audit 2026-06). Single-occurrence keys stay plain strings, so existing
+ * `t.string()` schemas are untouched; a repeated key against a string schema now FAILS validation
+ * (an explicit 400 beats silently picking one). */
+export type QueryValue = string | string[];
+export declare function queryObjectOf(search: string): Record<string, QueryValue>;
+/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+export declare function isUrlEncodedForm(contentType: string): boolean;
+/**
+ * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
+ * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
+ * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ */
+export declare function readBoundedForm(req: RequestSource, maxBytes: number): Promise<Record<string, QueryValue> | Response>;
+//# sourceMappingURL=query.d.ts.map

package/dist/server/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/server/query.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAMhD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;mDAImD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;AAqC1C,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAyBxE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAK7D;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,CAchD"}

package/dist/server/query.js

@@ -0,0 +1,102 @@
+/**
+ * Query-string and urlencoded-form parsing. Pure request-shaping helpers with no server internals:
+ * the fast scanner for `c.query`, the repeated-key -> `string[]` promotion shared by query + form,
+ * and the byte-capped HTML-form reader. Split out of the server kernel so the file stays one domain.
+ */
+import { readBoundedBytes } from "./body.js";
+import { jsonError, urlPartsOf } from "./http.js";
+// The query string ("?a=1", or "" when absent) - for lazily building `c.query` only when read.
+// The fragment (after the first `#`) bounds the search: a `?` that appears only inside the fragment
+// is NOT a query (matches WHATWG). Fragments never reach the server in `req.url`, so this is purely
+// for provable equivalence with `new URL(req.url).search`.
+export function searchOf(url) {
+    return urlPartsOf(url).search;
+}
+/** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
+ * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key - the
+ * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
+ * case (direct assignment on a null-proto object creates an own property). */
+function setQueryValue(out, key, value) {
+    const existing = out[key];
+    if (existing === undefined) {
+        out[key] = value;
+    }
+    else if (typeof existing === "string") {
+        out[key] = [existing, value];
+    }
+    else {
+        existing.push(value);
+    }
+}
+function queryObjectFallback(search) {
+    // Manual iteration instead of Object.fromEntries: repeated keys must promote to arrays
+    // (fromEntries is last-wins), and __proto__ needs the same own-property guard.
+    const out = Object.create(null);
+    for (const [key, value] of new URLSearchParams(search)) {
+        setQueryValue(out, key, value);
+    }
+    return out;
+}
+/**
+ * Build the plain object passed to query schemas. Plain ASCII-ish queries avoid
+ * `URLSearchParams` + iterator allocations; encoded queries fall back to the Web API so `+`,
+ * percent-decoding, malformed escapes, and empty-key behavior stay exact. Repeated keys promote
+ * to `string[]` on BOTH paths (see {@link setQueryValue}).
+ */
+// Shared empty result for no-query requests: frozen + null-prototype (same shape contract as the
+// populated path), allocated once instead of per request.
+const EMPTY_QUERY = Object.freeze(Object.create(null));
+export function queryObjectOf(search) {
+    const start = search.charCodeAt(0) === 63 /* ? */ ? 1 : 0;
+    if (start >= search.length)
+        return EMPTY_QUERY;
+    for (let i = start; i < search.length; i++) {
+        const c = search.charCodeAt(i);
+        if (c === 37 /* % */ || c === 43 /* + */)
+            return queryObjectFallback(search);
+    }
+    const out = Object.create(null);
+    let pos = start;
+    while (pos <= search.length) {
+        const amp = search.indexOf("&", pos);
+        const end = amp === -1 ? search.length : amp;
+        if (end > pos) {
+            const eq = search.indexOf("=", pos);
+            const split = eq !== -1 && eq < end ? eq : end;
+            const key = search.slice(pos, split);
+            const value = split === end ? "" : search.slice(split + 1, end);
+            setQueryValue(out, key, value);
+        }
+        if (amp === -1)
+            break;
+        pos = amp + 1;
+    }
+    return out;
+}
+/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+export function isUrlEncodedForm(contentType) {
+    return (contentType === "application/x-www-form-urlencoded" ||
+        contentType.startsWith("application/x-www-form-urlencoded;"));
+}
+const FORM_DECODER = new TextDecoder();
+/**
+ * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
+ * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
+ * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ */
+export async function readBoundedForm(req, maxBytes) {
+    const read = await readBoundedBytes(req, maxBytes);
+    if (!read.ok) {
+        return read.status === 413
+            ? jsonError(413, "payload_too_large")
+            : jsonError(400, "invalid_content_length");
+    }
+    const out = Object.create(null);
+    // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);
+    // it never throws on junk input, so no try/catch is needed here.
+    for (const [key, value] of new URLSearchParams(FORM_DECODER.decode(read.bytes))) {
+        setQueryValue(out, key, value);
+    }
+    return out;
+}
+//# sourceMappingURL=query.js.map