@daloyjs/core 1.0.0-beta.6 → 1.0.0-rc.0

package/README.md

@@ -509,7 +509,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.6`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
+DaloyJS is now at its **first `1.0.0` release candidate** (`1.0.0-rc.0`). The public API is frozen for the 1.0 line: only bug fixes and documentation land between RC and GA, and from `1.0.0` onward breaking changes follow SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 
@@ -520,7 +520,7 @@ DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.6`). The public API is featu
 - Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
 - RFC 7231 + RFC 5789 HTTP-method allowlist enforced inside `app.route()` (WebDAV, `TRACE`, `CONNECT` rejected at the framework boundary).
 - AI-friendly route metadata via optional `meta: { examples, extensions, summary, description, tags }`; examples are validated against your schemas at build time, surfaced as OpenAPI `examples` + `x-daloy-*` extensions, and dumped as `routes.json` / `routes.yaml` via `daloy inspect --ai`.
-- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools, resources, and prompts over JSON-RPC 2.0, while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app.
+- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools (with `outputSchema`, `annotations`, and icons), resources, RFC 6570 resource templates, and prompts (with required-argument enforcement) over JSON-RPC 2.0 and validates `Origin` against DNS rebinding (with an `allowedOrigins` allowlist), while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes — with the JSON-RPC envelope schema surfaced in OpenAPI — for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app.
 - API lifecycle and breaking-change detection: mark routes `deprecated` or give them a `sunset` date to emit RFC 8594 `Deprecation` / `Sunset` headers and an `x-sunset` OpenAPI extension, then gate CI with `diffOpenAPI()` / the `daloy diff` command, which fail on a breaking change versus the last published spec.
 - In-process test client (`app.request()`), contract-test runner (gated in CI via `daloy inspect --check` and shipped as a default test in every `create-daloy` template), in-process typed client, and Hey API codegen via `pnpm gen`.
 

package/dist/adapters/bun.d.ts

@@ -18,7 +18,9 @@ export interface BunTLSOptions {
 }
 /** Options forwarded to `Bun.serve` by {@link serve}. */
 export interface BunServeOptions {
+    /** TCP port to listen on. Ignored when `unix` is set. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Ignored when `unix` is set. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /** Maximum request body bytes (Bun-level cap). Default: 16 MiB. */
     maxRequestBodySize?: number;
@@ -33,9 +35,19 @@ export interface BunServeOptions {
 }
 /** Handle returned by {@link serve} for shutdown and listener introspection. */
 export interface BunServerHandle {
+    /** Port the server is actually listening on (as reported by Bun). */
     port: number;
+    /** Server URL as reported by `Bun.serve` (e.g. for startup logging), if available. */
     url: URL | undefined;
+    /** Graceful stop: drains {@link App.shutdown} hooks first, then force-stops the Bun server. */
     stop: () => Promise<void>;
 }
-/** Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes. */
+/**
+ * Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener options forwarded to `Bun.serve`; see {@link BunServeOptions}.
+ * @returns A {@link BunServerHandle} exposing the bound `port`, `url`, and a graceful `stop()`.
+ * @throws Error when the Bun runtime (`globalThis.Bun.serve`) is not detected.
+ */
 export declare function serve(app: App, opts?: BunServeOptions): BunServerHandle;

package/dist/adapters/bun.js

@@ -1,5 +1,12 @@
 import { WS_READY_STATE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, encodeSendPayload, parseSubprotocols, validateSelectedSubprotocol, checkWebSocketOrigin, WebSocketProtocolError, } from "../websocket.js";
-/** Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes. */
+/**
+ * Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener options forwarded to `Bun.serve`; see {@link BunServeOptions}.
+ * @returns A {@link BunServerHandle} exposing the bound `port`, `url`, and a graceful `stop()`.
+ * @throws Error when the Bun runtime (`globalThis.Bun.serve`) is not detected.
+ */
 export function serve(app, opts = {}) {
     const Bun = globalThis.Bun;
     if (!Bun?.serve)

package/dist/adapters/cloudflare.d.ts

@@ -18,12 +18,18 @@
 import type { App } from "../app.js";
 /** Module shape expected by the Cloudflare Workers runtime as `export default`. */
 export interface ExportedFetchHandler<Env = unknown> {
+    /** Worker entry point: forwards the request to {@link App.fetch}. `env`/`ctx` are accepted but unused by the adapter. */
     fetch: (request: Request, env?: Env, ctx?: ExecutionContextLike) => Promise<Response>;
 }
 interface ExecutionContextLike {
     waitUntil?: (promise: Promise<unknown>) => void;
     passThroughOnException?: () => void;
 }
-/** Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts. */
+/**
+ * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
+ */
 export declare function toFetchHandler<Env = unknown>(app: App): ExportedFetchHandler<Env>;
 export {};

package/dist/adapters/cloudflare.js

@@ -1,4 +1,9 @@
-/** Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts. */
+/**
+ * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
+ */
 export function toFetchHandler(app) {
     return {
         fetch: (req) => app.fetch(req),

package/dist/adapters/deno.d.ts

@@ -9,7 +9,9 @@
 import type { App } from "../app.js";
 /** Options forwarded to `Deno.serve` by {@link serve}. */
 export interface DenoServeOptions {
+    /** TCP port to listen on. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /** Optional external signal that triggers graceful shutdown. */
     signal?: AbortSignal;
@@ -31,7 +33,15 @@ export interface DenoServeOptions {
 }
 /** Handle returned by {@link serve}; call `shutdown()` to drain. */
 export interface DenoServerHandle {
+    /** Graceful shutdown: drains {@link App.shutdown} hooks, then stops the Deno server. Idempotent. */
     shutdown: () => Promise<void>;
 }
-/** Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring. */
+/**
+ * Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` serves each request.
+ * @param opts - Listener/TLS/shutdown options; see {@link DenoServeOptions}.
+ * @returns A {@link DenoServerHandle} whose `shutdown()` drains in-flight requests.
+ * @throws Error when the Deno runtime (`globalThis.Deno.serve`) is not detected.
+ */
 export declare function serve(app: App, opts?: DenoServeOptions): DenoServerHandle;

package/dist/adapters/deno.js

@@ -1,4 +1,11 @@
-/** Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring. */
+/**
+ * Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` serves each request.
+ * @param opts - Listener/TLS/shutdown options; see {@link DenoServeOptions}.
+ * @returns A {@link DenoServerHandle} whose `shutdown()` drains in-flight requests.
+ * @throws Error when the Deno runtime (`globalThis.Deno.serve`) is not detected.
+ */
 export function serve(app, opts = {}) {
     const D = globalThis.Deno;
     const denoServe = D?.serve;

package/dist/adapters/fastly.d.ts

@@ -18,7 +18,17 @@
  * multipart helpers that rely on `node:stream`).
  */
 import type { App } from "../app.js";
-/** Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute. */
+/**
+ * Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A web-standard handler delegating to {@link App.fetch}.
+ */
 export declare function toFastlyHandler(app: App): (req: Request) => Promise<Response>;
-/** Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}. */
+/**
+ * Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @throws Error when `globalThis.addEventListener` is missing (not a Fastly Compute runtime).
+ */
 export declare function installFastlyListener(app: App): void;

package/dist/adapters/fastly.js

@@ -1,8 +1,18 @@
-/** Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute. */
+/**
+ * Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A web-standard handler delegating to {@link App.fetch}.
+ */
 export function toFastlyHandler(app) {
     return (req) => app.fetch(req);
 }
-/** Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}. */
+/**
+ * Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @throws Error when `globalThis.addEventListener` is missing (not a Fastly Compute runtime).
+ */
 export function installFastlyListener(app) {
     const g = globalThis;
     if (typeof g.addEventListener !== "function") {

package/dist/adapters/lambda.d.ts

@@ -13,28 +13,45 @@ import type { App } from "../app.js";
  * The adapter performs no Node-only I/O, so it is safe in any runtime that
  * provides the standard `Request`/`Response`/`atob`/`btoa` globals.
  */
+/** API Gateway REST API event (payload format v1.0). */
 export interface LambdaEventV1 {
+    /** Payload format version; `"1.0"` or absent for REST API events. */
     version?: "1.0" | string;
+    /** URL path of the request (e.g. `/users/42`). */
     path?: string;
+    /** HTTP method (e.g. `GET`). */
     httpMethod?: string;
+    /** Request headers, one value per name (last value wins in v1.0). */
     headers?: Record<string, string | undefined>;
+    /** Request headers with every value per name; `cookie` values are re-joined with `; `. */
     multiValueHeaders?: Record<string, string[] | undefined>;
+    /** Query parameters, one value per name. Used only when the multi-value map is empty. */
     queryStringParameters?: Record<string, string | undefined> | null;
+    /** Query parameters with every value per name; preferred over the single-value map. */
     multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    /** Request context; `domainName` is the host fallback and `path` the path fallback. */
     requestContext?: {
         domainName?: string;
         path?: string;
     };
+    /** Raw request body; base64-encoded when {@link LambdaEventV1.isBase64Encoded} is true. */
     body?: string;
+    /** True when `body` is base64-encoded (binary payloads). */
     isBase64Encoded?: boolean;
 }
 /** API Gateway HTTP API or Lambda Function URL event (payload format v2.0). */
 export interface LambdaEventV2 {
+    /** Payload format version; `"2.0"` for HTTP API / Function URL events. */
     version?: string;
+    /** URL path of the request, without the query string. */
     rawPath?: string;
+    /** Raw query string without the leading `?` (empty string when none). */
     rawQueryString?: string;
+    /** Request headers; multi-value headers arrive comma-joined in v2.0. */
     headers?: Record<string, string | undefined>;
+    /** Request cookies as individual strings; re-joined with `; ` into a `cookie` header. */
     cookies?: string[];
+    /** Request context; `http.method`/`http.path` carry the method and path, `domainName` the host fallback. */
     requestContext?: {
         http?: {
             method?: string;
@@ -42,32 +59,51 @@ export interface LambdaEventV2 {
         };
         domainName?: string;
     };
+    /** Raw request body; base64-encoded when {@link LambdaEventV2.isBase64Encoded} is true. */
     body?: string;
+    /** True when `body` is base64-encoded (binary payloads). */
     isBase64Encoded?: boolean;
 }
 /** Either payload format accepted by {@link toLambdaHandler}. */
 export type LambdaEvent = LambdaEventV1 | LambdaEventV2;
 /** Lambda response shape required by API Gateway REST API (payload format v1.0). */
 export interface LambdaResponseV1 {
+    /** HTTP status code of the response. */
     statusCode: number;
+    /** Response headers, one value per name (`set-cookie` excluded; see `multiValueHeaders`). */
     headers: Record<string, string>;
+    /** Multi-value headers; used to carry each `set-cookie` value separately in v1.0. */
     multiValueHeaders?: Record<string, string[]>;
+    /** Never present in v1.0 responses; cookies travel via `multiValueHeaders`. */
     cookies?: never;
+    /** Response body; base64-encoded when {@link LambdaResponseV1.isBase64Encoded} is true. */
     body: string;
+    /** True when `body` is base64-encoded (non-text content types). */
     isBase64Encoded: boolean;
 }
 /** Lambda response shape required by API Gateway HTTP API and Function URLs (payload format v2.0). */
 export interface LambdaResponseV2 {
+    /** HTTP status code of the response. */
     statusCode: number;
+    /** Response headers, one value per name (`set-cookie` excluded; see `cookies`). */
     headers: Record<string, string>;
+    /** Response cookies, one `set-cookie` value per entry (v2.0's cookie channel). */
     cookies?: string[];
+    /** Never present in v2.0 responses; cookies travel via `cookies`. */
     multiValueHeaders?: never;
+    /** Response body; base64-encoded when {@link LambdaResponseV2.isBase64Encoded} is true. */
     body: string;
+    /** True when `body` is base64-encoded (non-text content types). */
     isBase64Encoded: boolean;
 }
 /** Either response shape produced by {@link toLambdaHandler}, chosen automatically per event. */
 export type LambdaResponse = LambdaResponseV1 | LambdaResponseV2;
 /** Async handler shape consumed by AWS Lambda / Netlify Functions runtimes. */
 export type LambdaHandler = (event: LambdaEvent) => Promise<LambdaResponse>;
-/** Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads. */
+/**
+ * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
+ */
 export declare function toLambdaHandler(app: App): LambdaHandler;

package/dist/adapters/lambda.js

@@ -1,5 +1,10 @@
 const TEXT_TYPE_RE = /^(text\/|application\/(json|xml|javascript|x-www-form-urlencoded|.*\+json|.*\+xml))/i;
-/** Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads. */
+/**
+ * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
+ */
 export function toLambdaHandler(app) {
     return async (event) => {
         const request = eventToRequest(event);

package/dist/adapters/node.d.ts

@@ -6,7 +6,9 @@ import { type Server } from "node:http";
 import type { App } from "../app.js";
 /** Options for the Node.js {@link serve} entry point. */
 export interface NodeServerOptions {
+    /** TCP port to listen on. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /**
      * Connection-level timeout in ms, applied to BOTH `headersTimeout` and
@@ -72,9 +74,18 @@ export interface NodeServerOptions {
 }
 /** Handle returned by {@link serve} exposing the underlying Node `Server` plus a `close()` for graceful shutdown. */
 export interface NodeServerHandle {
+    /** The underlying `node:http` `Server` instance, for advanced wiring (extra listeners, address introspection). */
     server: Server;
+    /** Port the server was asked to listen on ({@link NodeServerOptions.port}, default `3000`). */
     port: number;
+    /** Graceful shutdown: drains {@link App.shutdown} hooks, destroys WebSocket sockets, then closes the server. Idempotent. */
     close(): Promise<void>;
 }
-/** Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}. */
+/**
+ * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener, timeout, proxy-trust, and hardening options; see {@link NodeServerOptions}.
+ * @returns A {@link NodeServerHandle} exposing the Node `Server`, the `port`, and a graceful `close()`.
+ */
 export declare function serve(app: App, opts?: NodeServerOptions): NodeServerHandle;

package/dist/adapters/node.js

@@ -4,10 +4,16 @@
  */
 import { createServer, } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, } from "../app.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
-/** Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}. */
+/**
+ * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener, timeout, proxy-trust, and hardening options; see {@link NodeServerOptions}.
+ * @returns A {@link NodeServerHandle} exposing the Node `Server`, the `port`, and a graceful `close()`.
+ */
 export function serve(app, opts = {}) {
     const trustProxy = opts.trustProxy === true;
     const bufferedBodyMaxBytes = typeof opts.bufferedBodyMaxBytes === "number" && opts.bufferedBodyMaxBytes >= 0
@@ -285,6 +291,209 @@ function writeAdapterError(res, e) {
         res.destroy(e);
     }
 }
+/**
+ * Lazily-materializing stand-in for an incoming WHATWG `Request`.
+ *
+ * Constructing a real (undici) `Request` costs ~4µs for GET and far more for
+ * POST-with-body (the constructor wraps the body bytes in a WHATWG
+ * `ReadableStream` that DaloyJS then bypasses anyway via the
+ * `DALOY_REQUEST_RAW_BODY` fast path). The dispatch hot path only ever reads
+ * `url`, `method`, `headers`, `signal`, and the raw-body symbol — so this
+ * shell carries those directly and defers the real `Request` until one of the
+ * less common surfaces (`json()`, `clone()`, `body`, `formData()`, …) is
+ * actually touched.
+ *
+ * Fidelity notes:
+ * - `instanceof Request` holds (prototype chain is re-rooted onto
+ *   `Request.prototype`), and every WHATWG method/getter is overridden here,
+ *   so nothing hits undici's brand-checked prototype accessors.
+ * - `signal` is an inert per-instance `AbortSignal`. This matches the real
+ *   adapter behaviour today: the Node adapter never wires socket aborts into
+ *   the request signal, so the signal never fires in either implementation.
+ * - Passing this object directly to `fetch()` is not supported (undici
+ *   brand-checks its input) — forward with `request.clone()` instead, which
+ *   returns a real `Request`. This mirrors @hono/node-server's shim.
+ *
+ * Security parity: the `Headers` instance is built eagerly from `rawHeaders`
+ * exactly as before, so the duplicate-singleton / reserved-header /
+ * header-count guards in `App.dispatch` see the identical view they saw with
+ * a real `Request`.
+ */
+/** Shared decoder for LightRequest's direct body reads. */
+const LIGHT_TEXT_DECODER = new TextDecoder();
+class LightRequest {
+    #url;
+    #method;
+    #headers;
+    #bodyBytes;
+    #real;
+    #signal;
+    constructor(url, method, headers, bodyBytes) {
+        this.#url = url;
+        this.#method = method;
+        this.#headers = headers;
+        this.#bodyBytes = bodyBytes;
+    }
+    /** Build (once) and return the real undici `Request` for rare surfaces. */
+    #materialize() {
+        return (this.#real ??=
+            this.#bodyBytes !== undefined
+                ? new Request(this.#url, {
+                    method: this.#method,
+                    headers: this.#headers,
+                    body: this.#bodyBytes,
+                })
+                : new Request(this.#url, { method: this.#method, headers: this.#headers }));
+    }
+    get url() {
+        return this.#url;
+    }
+    get method() {
+        return this.#method;
+    }
+    get headers() {
+        return this.#headers;
+    }
+    get signal() {
+        // Inert, lazily created: the Node adapter has never wired socket
+        // teardown into the request signal, so a never-firing signal is
+        // behaviourally identical to the one a real `Request` would carry.
+        return (this.#signal ??= new AbortController().signal);
+    }
+    get body() {
+        return this.#materialize().body;
+    }
+    get bodyUsed() {
+        if (this.#real !== undefined)
+            return this.#real.bodyUsed;
+        return this.#directlyConsumed;
+    }
+    /**
+     * Set when a body method served the pre-buffered bytes directly (no real
+     * `Request` ever existed). Subsequent body reads reject with a `TypeError`
+     * exactly like a consumed WHATWG body would.
+     */
+    #directlyConsumed = false;
+    /**
+     * Serve a body read straight from the pre-buffered bytes when possible.
+     * Returns `undefined` when the caller must delegate to the materialized
+     * real `Request` (no buffered bytes, or a real `Request` already owns the
+     * body state). Enforces single-read semantics via {@link #directlyConsumed}.
+     */
+    #consumeBytes() {
+        if (this.#real !== undefined || this.#bodyBytes === undefined)
+            return undefined;
+        if (this.#directlyConsumed) {
+            throw new TypeError("Body is unusable: Body has already been read");
+        }
+        this.#directlyConsumed = true;
+        return this.#bodyBytes;
+    }
+    // Spec-constant getters: these are exactly the values undici assigns to a
+    // server-side `new Request(url, { method, headers, body })`, hardcoded so
+    // reading them does not force materialization.
+    get cache() {
+        return "default";
+    }
+    get credentials() {
+        return "same-origin";
+    }
+    get destination() {
+        return "";
+    }
+    get integrity() {
+        return "";
+    }
+    get keepalive() {
+        return false;
+    }
+    get mode() {
+        return "cors";
+    }
+    get redirect() {
+        return "follow";
+    }
+    get referrer() {
+        return "about:client";
+    }
+    get referrerPolicy() {
+        return "";
+    }
+    arrayBuffer() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().arrayBuffer();
+            // Copy: the underlying buffer is also the framework's raw-body cache.
+            return Promise.resolve(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    blob() {
+        return this.#materialize().blob();
+    }
+    bytes() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().bytes();
+            return Promise.resolve(new Uint8Array(bytes));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    formData() {
+        return this.#materialize().formData();
+    }
+    json() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().json();
+            // JSON.parse (not the framework's safeJsonParse): request.json() is the
+            // raw WHATWG surface, and its error semantics (SyntaxError rejection)
+            // must match a real Request exactly. Framework-parsed bodies go through
+            // readBody()/safeJsonParse and never hit this method.
+            return Promise.resolve(JSON.parse(LIGHT_TEXT_DECODER.decode(bytes)));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    text() {
+        try {
+            const bytes = this.#consumeBytes();
+            if (bytes === undefined)
+                return this.#materialize().text();
+            return Promise.resolve(LIGHT_TEXT_DECODER.decode(bytes));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    /**
+     * Returns a real, fully-branded `Request` clone — safe to pass to `fetch()`.
+     * Throws a `TypeError` if the body has already been read, per spec.
+     */
+    clone() {
+        if (this.#directlyConsumed) {
+            throw new TypeError("Request body is already used");
+        }
+        return this.#materialize().clone();
+    }
+}
+// `instanceof Request` must hold for handler code and the framework's own
+// checks. Every own getter/method above shadows the brand-checked undici
+// accessors, so the re-rooted chain is only consulted for identity.
+Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
+// This adapter consumes responses via status/headers/DALOY_RAW_BODY only
+// (see sendWebResponse), so serializeResult may skip the undici Response
+// construction for requests dispatched through this shim. Set once on the
+// prototype: zero per-request cost.
+LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
 function toWebRequest(req, trustProxy, bufferedBody) {
     const reqHeaders = req.headers;
     const forwardedHost = trustProxy
@@ -317,18 +526,20 @@ function toWebRequest(req, trustProxy, bufferedBody) {
     const headers = new Headers(headerPairs);
     const method = req.method ?? "GET";
     if (method === "GET" || method === "HEAD") {
-        return new Request(url, { method, headers });
+        // LightRequest: skips the ~4µs undici Request constructor on the GET
+        // hot path. Headers are still built eagerly above, so every header
+        // guard sees the same view as before.
+        return new LightRequest(url, method, headers, undefined);
     }
     if (bufferedBody !== undefined) {
-        const req2 = new Request(url, {
-            method,
-            headers,
-            body: bufferedBody,
-        });
-        // Stash the validated bytes so readBodyLimited (and any other internal
-        // body reader) can skip the WHATWG ReadableStream reader loop. The
-        // adapter has already enforced BUFFERED_BODY_MAX_BYTES + Content-Length
-        // here; readBodyLimited re-checks against the caller's limit.
+        // LightRequest with the pre-buffered bytes: skips the (much more
+        // expensive) body-wrapping undici Request constructor. The bytes are
+        // stashed via DALOY_REQUEST_RAW_BODY so readBodyLimited (and any other
+        // internal body reader) skips the WHATWG ReadableStream reader loop.
+        // The adapter has already enforced BUFFERED_BODY_MAX_BYTES +
+        // Content-Length here; readBodyLimited re-checks against the caller's
+        // limit.
+        const req2 = new LightRequest(url, method, headers, bufferedBody);
         req2[DALOY_REQUEST_RAW_BODY] = bufferedBody;
         return req2;
     }

package/dist/adapters/vercel.d.ts

@@ -23,16 +23,25 @@ import type { App } from "../app.js";
 export type WebHandler = (req: Request) => Promise<Response>;
 /** Default export shape for Vercel's web-standard `{ fetch }` runtime. */
 export interface FetchHandler {
+    /** Request entry point: forwards the request to {@link App.fetch}. */
     fetch: WebHandler;
 }
 declare const NEXT_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
 /** Record of per-method handlers expected by a Next.js App Router `route.ts` file. */
 export type RouteHandlers = Record<(typeof NEXT_METHODS)[number], WebHandler>;
-/** Wrap an {@link App} as a single web-standard fetch handler. */
+/**
+ * Wrap an {@link App} as a single web-standard fetch handler.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link WebHandler} delegating to {@link App.fetch}.
+ */
 export declare function toWebHandler(app: App): WebHandler;
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions
  * in the `/api` directory.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link FetchHandler} object suitable as the module's `export default`.
  */
 export declare function toFetchHandler(app: App): FetchHandler;
 /** Backward-compatible alias for {@link toWebHandler}. */
@@ -40,6 +49,9 @@ export declare const toEdgeHandler: typeof toWebHandler;
 /**
  * Build the `{ GET, POST, ... }` object expected by Next.js App Router
  * `route.ts` files when a DaloyJS app is mounted inside an existing Next app.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link RouteHandlers} record mapping every supported HTTP method to the same {@link WebHandler}.
  */
 export declare function toRouteHandlers(app: App): RouteHandlers;
 export {};

package/dist/adapters/vercel.js

@@ -1,11 +1,19 @@
 const NEXT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
-/** Wrap an {@link App} as a single web-standard fetch handler. */
+/**
+ * Wrap an {@link App} as a single web-standard fetch handler.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link WebHandler} delegating to {@link App.fetch}.
+ */
 export function toWebHandler(app) {
     return (req) => app.fetch(req);
 }
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions
  * in the `/api` directory.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link FetchHandler} object suitable as the module's `export default`.
  */
 export function toFetchHandler(app) {
     return { fetch: toWebHandler(app) };
@@ -15,6 +23,9 @@ export const toEdgeHandler = toWebHandler;
 /**
  * Build the `{ GET, POST, ... }` object expected by Next.js App Router
  * `route.ts` files when a DaloyJS app is mounted inside an existing Next app.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link RouteHandlers} record mapping every supported HTTP method to the same {@link WebHandler}.
  */
 export function toRouteHandlers(app) {
     const handler = toWebHandler(app);