@daloyjs/core 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/app.js

@@ -195,10 +195,28 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  */
 export const DALOY_RAW_STREAM = Symbol.for("daloyjs.response.rawStream");
 /**
+ * The DaloyJS application: a contract-first router plus a web-standard
+ * `fetch(Request): Promise<Response>` handler that runs unchanged on Node,
+ * Bun, Deno, Cloudflare Workers, and Vercel via the adapters.
+ *
+ * Routes registered with {@link App.route} are validated against their
+ * declared schemas on the way in and out, accumulate in the typed
+ * {@link App.routes} tuple (powering OpenAPI generation and the typed
+ * client), and are served with secure defaults: body limits, request
+ * timeouts, security headers, and prod-mode error redaction.
+ *
+ * @typeParam Routes - Compile-time tuple of registered route definitions,
+ * grown by each {@link App.route} call.
  * @since 0.1.0
  */
 export class App {
+    /**
+     * Resolved constructor options. The security-relevant trio is always
+     * populated: `validateResponses` (default `true`), `bodyLimitBytes`
+     * (default 1 MiB), and `requestTimeoutMs` (default 30_000 ms).
+     */
     options;
+    /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     log;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
@@ -932,6 +950,9 @@ export class App {
             operationId: "getOpenAPIDocument",
             ...(tags.length ? { tags } : {}),
             summary: "OpenAPI 3.1 document",
+            // Framework-owned body (the generated spec document); the missing
+            // schema is intentional, not an OWASP API3 leak risk.
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "OpenAPI 3.1 document for this application." },
             },
@@ -947,6 +968,7 @@ export class App {
                 operationId: "getOpenAPIDocumentYaml",
                 ...(tags.length ? { tags } : {}),
                 summary: "OpenAPI 3.1 document (YAML)",
+                acknowledgeNoResponseBodySchema: true,
                 responses: {
                     200: { description: "OpenAPI 3.1 document for this application, in YAML." },
                 },
@@ -985,6 +1007,7 @@ export class App {
             operationId: "getDocsUI",
             ...(tags.length ? { tags } : {}),
             summary: "Interactive API reference",
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "Interactive API documentation UI." },
             },
@@ -1082,6 +1105,8 @@ export class App {
             operationId: "getAsyncAPIDocument",
             ...(tags.length ? { tags } : {}),
             summary: "AsyncAPI 3.0 document",
+            // Framework-owned bodies on the AsyncAPI surface, like mountDocs above.
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "AsyncAPI 3.0 document for this application's WebSocket channels." },
             },
@@ -1094,6 +1119,7 @@ export class App {
                 operationId: "getAsyncAPIDocumentYaml",
                 ...(tags.length ? { tags } : {}),
                 summary: "AsyncAPI 3.0 document (YAML)",
+                acknowledgeNoResponseBodySchema: true,
                 responses: {
                     200: { description: "AsyncAPI 3.0 document for this application, in YAML." },
                 },
@@ -1115,6 +1141,7 @@ export class App {
             operationId: "getAsyncAPIUI",
             ...(tags.length ? { tags } : {}),
             summary: "Interactive AsyncAPI reference",
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "Interactive AsyncAPI documentation UI." },
             },
@@ -1443,6 +1470,8 @@ export class App {
             operationId: "metrics",
             tags: ["Observability"],
             summary: "Prometheus metrics scrape endpoint",
+            // Prometheus text exposition rendered by the framework registry.
+            acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
                     const key = healthRouteKey(request);
@@ -1561,6 +1590,8 @@ export class App {
             operationId: isHealth ? "healthcheck" : "readinesscheck",
             tags: ["Health"],
             summary: isHealth ? "Liveness probe" : "Readiness probe",
+            // Framework-serialized probe payload; missing schema is intentional.
+            acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
                     const key = healthRouteKey(request);
@@ -1799,6 +1830,20 @@ export class App {
         this.resetBootGuardCache();
         return this;
     }
+    /**
+     * Apply an ordered list of plugin extensions to the
+     * group-level hook chain. Each extension's `handler` is wrapped into a
+     * single-event {@link Hooks} bundle so subsequent route registrations
+     * pick it up via the normal hook composition path.
+     * @internal
+     */
+    applyExtensions(ordered) {
+        for (const ext of ordered) {
+            const hooks = { [ext.event]: ext.handler };
+            this.groupHooks.push(hooks);
+        }
+        this._coldPathHooksCache = undefined;
+    }
     /**
      * Decorate `ctx.state` with a value available inside every handler and hook.
      *
@@ -1821,22 +1866,10 @@ export class App {
      *
      * @param key - Property name on `ctx.state`.
      * @param value - Value bound to that property on every request.
+     * @param opts - Pass `{ override: true }` to replace an existing decoration (logged as a warning).
      * @returns This `App` instance for chaining.
+     * @throws Error if `key` is already decorated and `opts.override` is not `true`.
      */
-    /**
-     * Apply an ordered list of plugin extensions to the
-     * group-level hook chain. Each extension's `handler` is wrapped into a
-     * single-event {@link Hooks} bundle so subsequent route registrations
-     * pick it up via the normal hook composition path.
-     * @internal
-     */
-    applyExtensions(ordered) {
-        for (const ext of ordered) {
-            const hooks = { [ext.event]: ext.handler };
-            this.groupHooks.push(hooks);
-        }
-        this._coldPathHooksCache = undefined;
-    }
     decorate(key, value, opts = {}) {
         if (Object.prototype.hasOwnProperty.call(this.decorations, key) && opts.override !== true) {
             // Namespace-protected decorators. Refuse to silently
@@ -2440,13 +2473,6 @@ export class App {
         const req = url instanceof Request ? url : new Request(url, init);
         return this.fetch(req);
     }
-    /**
-     * Return a JSON-serializable summary of every registered route. Useful for
-     * dead-route detection, dashboards, and tests that want to assert against
-     * the route table without parsing the OpenAPI document.
-     *
-     * @returns Array of one {@link IntrospectedRoute} per registered route.
-     */
     /**
      * Emit a one-time development warning when any route declares a `2xx`
      * response without a body schema, because response-field stripping
@@ -2469,9 +2495,18 @@ export class App {
             routes: offending.slice(0, 20),
         }, `${offending.length} route(s) declare a 2xx response with no body schema; ` +
             "response field-level stripping (OWASP API3) is not applied there, so a handler that " +
-            "returns undeclared fields will leak them. Declare a response body schema, or ignore if " +
-            "the route intentionally returns no body. Run `daloy doctor` to list them.");
+            "returns undeclared fields will leak them. Declare a response body schema, or set " +
+            "`acknowledgeNoResponseBodySchema: true` on routes that intentionally return an opaque " +
+            "or body-less response. Run `daloy doctor` to list them. " +
+            "See https://daloyjs.dev/docs/security/owasp-api-top-10#api3");
     }
+    /**
+     * Return a JSON-serializable summary of every registered route. Useful for
+     * dead-route detection, dashboards, and tests that want to assert against
+     * the route table without parsing the OpenAPI document.
+     *
+     * @returns Array of one {@link IntrospectedRoute} per registered route.
+     */
     introspect() {
         return this.routes.map((r) => {
             const route = {
@@ -2639,6 +2674,12 @@ function detectHeaderMutatingMiddleware(layers) {
 /**
  * Topological sort of plugin extensions. Refuses-at-call
  * on cyclic ordering with a structured error naming the cycle.
+ *
+ * @param exts - Extensions to order by their `before` / `after` constraints (Kahn's algorithm).
+ * @returns The extensions in a valid execution order.
+ * @throws Error on duplicate extension names, on a `before`/`after` cycle
+ * (naming the members), or when two extensions mutate the same response
+ * header without declaring an ordering between each other.
  * @internal
  */
 export function topoSortExtensions(exts) {
@@ -3018,7 +3059,10 @@ function hasRequestSchema(request, key) {
  * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
  * the development-mode boot warning emitted on the first request. The result
  * is advisory — a route may legitimately return no body — so callers treat
- * it as a `warn`, never a hard error.
+ * it as a `warn`, never a hard error. Routes that set
+ * `acknowledgeNoResponseBodySchema: true` (including the framework-mounted
+ * docs, AsyncAPI, health, and metrics routes, whose bodies DaloyJS itself
+ * serializes) are skipped: the missing schema is declared intentional.
  *
  * @param routes - Route definitions to inspect (typically `app.routes`).
  * @returns One entry per offending route with the affected `2xx` status codes.
@@ -3027,6 +3071,8 @@ function hasRequestSchema(request, key) {
 export function findRoutesMissingResponseBodySchema(routes) {
     const offending = [];
     for (const route of routes) {
+        if (route.acknowledgeNoResponseBodySchema === true)
+            continue;
         const statuses = [];
         const responses = route.responses;
         for (const key of Object.keys(responses)) {
@@ -3238,15 +3284,33 @@ async function readBody(req, ct, limit, multipart) {
         // in memory on runtimes whose adapter does not cap at the socket layer
         // (Workers / Deno / Vercel). `readBodyLimited` streams the body and
         // throws `PayloadTooLargeError` the instant it exceeds `limit`; we then
-        // re-parse the bounded bytes with the standard `formData()` parser,
-        // preserving the multipart boundary via the original Content-Type. This is
+        // re-parse the bounded bytes with the standard `formData()` parser. This is
         // Web-standard only (`Request` + `formData`), so it stays runtime-portable.
         const bytes = await readBodyLimited(req, limit);
-        const fd = await new Request(req.url, {
-            method: "POST",
-            headers: { "content-type": ct },
-            body: bytes,
-        }).formData();
+        // The `ct` argument is lower-cased by the caller for case-insensitive
+        // media-type matching, but multipart boundaries are case-SENSITIVE (RFC
+        // 2046 §5.1.1). Reconstructing the Request with the lower-cased boundary
+        // would stop it matching the delimiter in the raw body, so the platform
+        // parser throws and every upload from a client that uses a mixed-case
+        // boundary — Chromium/WebKit browsers (`----WebKitFormBoundary…`) and curl
+        // (`------------------------…`) — fails. Re-read the ORIGINAL-case
+        // Content-Type header to preserve the boundary verbatim.
+        const rawContentType = req.headers.get("content-type") ?? ct;
+        let fd;
+        try {
+            fd = await new Request(req.url, {
+                method: "POST",
+                headers: { "content-type": rawContentType },
+                body: bytes,
+            }).formData();
+        }
+        catch {
+            // A body the platform parser cannot read is a malformed client request,
+            // not a server fault: surface it as an RFC 9457 400 rather than letting
+            // the raw parser TypeError bubble up as a generic 500 (which would also
+            // pollute server-error monitoring with client-controlled input).
+            throw new BadRequestError("Malformed multipart/form-data body");
+        }
         const out = {};
         let fields = 0;
         let files = 0;
@@ -3449,6 +3513,8 @@ function serializeErr(err) {
  * for ergonomics and matches the factory pattern used by Express, Fastify,
  * and Hono adapters.
  *
+ * @param options - Same {@link AppOptions} accepted by the `App` constructor. Default: `{}`.
+ * @returns A new {@link App} instance.
  * @since 0.3.0
  */
 export function createApp(options = {}) {

package/dist/banner.d.ts

@@ -30,10 +30,16 @@ export interface StartupBannerOptions {
 /**
  * Build the multi-line startup banner string without printing it. Useful for
  * tests, custom loggers, or wrapping the output in additional context.
+ *
+ * @param options Banner content and rendering flags ({@link StartupBannerOptions}).
+ * @returns The framed banner as a single string with `\n` line separators.
  */
 export declare function formatStartupBanner(options: StartupBannerOptions): string;
 /**
  * Print {@link formatStartupBanner} to stdout (or a custom writer). Designed to
  * replace ad-hoc `console.log("listening on …")` calls in starter templates.
+ *
+ * @param options Banner content and rendering flags ({@link StartupBannerOptions}).
+ * @param write Output sink for the banner text. Defaults to `process.stdout.write`.
  */
 export declare function printStartupBanner(options: StartupBannerOptions, write?: (s: string) => void): void;

package/dist/banner.js

@@ -86,6 +86,9 @@ function visibleWidth(s) {
 /**
  * Build the multi-line startup banner string without printing it. Useful for
  * tests, custom loggers, or wrapping the output in additional context.
+ *
+ * @param options Banner content and rendering flags ({@link StartupBannerOptions}).
+ * @returns The framed banner as a single string with `\n` line separators.
  */
 export function formatStartupBanner(options) {
     const useColor = options.color ?? detectColor();
@@ -126,6 +129,9 @@ export function formatStartupBanner(options) {
 /**
  * Print {@link formatStartupBanner} to stdout (or a custom writer). Designed to
  * replace ad-hoc `console.log("listening on …")` calls in starter templates.
+ *
+ * @param options Banner content and rendering flags ({@link StartupBannerOptions}).
+ * @param write Output sink for the banner text. Defaults to `process.stdout.write`.
  */
 export function printStartupBanner(options, write = (s) => process.stdout.write(s)) {
     write(`\n${formatStartupBanner(options)}\n\n`);

package/dist/cli.d.ts

@@ -12,7 +12,9 @@
 import type { App } from "./app.js";
 /** I/O hooks used by {@link runCli} to read modules, write output, and spawn child processes. */
 export interface CliIO {
+    /** Write a chunk to standard output (tables, JSON/YAML dumps). */
     stdout: (chunk: string) => void;
+    /** Write a chunk to standard error (usage errors, diagnostics). */
     stderr: (chunk: string) => void;
     /** Resolve a user-provided entry specifier to a module to import. */
     importEntry: (specifier: string) => Promise<unknown>;
@@ -37,15 +39,22 @@ export interface CliIO {
 }
 /** Return value of {@link runCli}. The caller wires `exitCode` into `process.exit(...)`. */
 export interface CliResult {
+    /** Process exit code: `0` on success, `1` on load failures or failed checks, `2` on usage errors. */
     exitCode: number;
 }
 /** Parsed CLI flags accepted by {@link runCli}. See {@link parseArgs}. */
 export interface CliOptions {
+    /** `--json`: print machine-readable JSON instead of a table. */
     json: boolean;
+    /** `--check`: run the contract test suite; exit 1 on errors. */
     check: boolean;
+    /** `--schemas`: include per-route schema presence (body/query/params/headers). */
     schemas: boolean;
+    /** `--openapi`: print the App's OpenAPI 3.1 document. */
     openapi: boolean;
+    /** `--asyncapi`: print the AsyncAPI 3.0 document for the App's WebSocket surfaces. */
     asyncapi: boolean;
+    /** `--ai`: print the AI/codegen-friendly route-catalog dump ({@link buildAiDump}). */
     ai: boolean;
     /**
      * Output format for `--ai` and `--openapi`. Defaults to `"json"`.
@@ -56,10 +65,15 @@ export interface CliOptions {
      * @since 0.14.2
      */
     format?: "json" | "yaml";
+    /** `--tag <tag>`: only show routes that declare this tag. */
     tag?: string;
+    /** `--method <method>`: only show routes for this HTTP method (uppercased by {@link parseArgs}). */
     method?: string;
+    /** Entry file to load the App from (last positional argument). */
     entry?: string;
+    /** `-h` / `--help`: print usage and exit 0. */
     help: boolean;
+    /** `-v` / `--version`: print the CLI version and exit 0. */
     version: boolean;
     /** Override runtime detection for `daloy dev`. */
     runtime?: DevRuntime;
@@ -76,6 +90,7 @@ export type DevRuntime = "node" | "bun" | "deno";
  * Detect which JS runtime is hosting the CLI. Inspects
  * `globalThis.process.versions` for Bun/Deno markers; falls back to Node.
  *
+ * @returns `"bun"`, `"deno"`, or `"node"` (the default when no marker is found).
  * @since 0.3.0
  */
 export declare function detectRuntime(): DevRuntime;
@@ -92,6 +107,9 @@ export declare function detectRuntime(): DevRuntime;
  * `runCli()` callers and tests so the invariant holds regardless of how the
  * entry value was produced.
  *
+ * @param entry - Entry path to validate.
+ * @param context - Label prefixed to error messages (e.g. `"daloy dev"`).
+ * @throws Error when the path is empty, contains NUL/CR/LF, or starts with `-`.
  * @internal
  */
 export declare function assertSafeEntryPath(entry: string, context: string): void;
@@ -102,6 +120,8 @@ export declare function assertSafeEntryPath(entry: string, context: string): voi
  * paths like `src/server.ts` are rewritten to `./src/server.ts`. This is
  * the second half of the {@link assertSafeEntryPath} defense.
  *
+ * @param entry - Entry path to anchor.
+ * @returns The path unchanged if already absolute or `./`/`../`-anchored (Windows drive paths included); otherwise `./` + path.
  * @internal
  */
 export declare function normalizeEntryArg(entry: string): string;
@@ -124,6 +144,10 @@ export declare function normalizeEntryArg(entry: string): string;
  * `SECURITY.md` § "CLI threat model" for the full rationale (and why we
  * are not vulnerable to the class of bug Snyk reported as CVE-2022-22984).
  *
+ * @param runtime - Host runtime to build the command for.
+ * @param entry - Entry file to run; validated and `./`-anchored before use.
+ * @returns The executable name and argv array to pass to `spawn({ shell: false })`.
+ * @throws Error via {@link assertSafeEntryPath} when the entry path is unsafe.
  * @since 0.3.0
  */
 export declare function buildDevCommand(runtime: DevRuntime, entry: string): {
@@ -133,6 +157,10 @@ export declare function buildDevCommand(runtime: DevRuntime, entry: string): {
 /**
  * Parse a process-style argv (without the `node`/`daloy` prefix) into a
  * `{ command, opts }` pair. Throws on unknown flags or invalid enum values.
+ *
+ * @param argv - Arguments after the binary name, e.g. `["inspect", "--json", "./src/server.ts"]`.
+ * @returns The resolved command (default `"inspect"`) and parsed {@link CliOptions}.
+ * @throws Error on unknown `-`-prefixed flags, missing flag values, or invalid `--format`/`--runtime` values.
  */
 export declare function parseArgs(argv: readonly string[]): {
     command: string;
@@ -142,6 +170,10 @@ export declare function parseArgs(argv: readonly string[]): {
  * Execute the CLI against the supplied argv and {@link CliIO}. Does not read
  * `process.argv`, write to process stdio, or call `process.exit()` directly,
  * so tests can drive `inspect`/`dev`/`doctor` with in-memory stdio.
+ *
+ * @param argv - Process-style arguments (without the `node`/`daloy` prefix); see {@link parseArgs}.
+ * @param io - I/O hooks for stdout/stderr, module import, spawning, and file reads.
+ * @returns A {@link CliResult} whose `exitCode` the caller feeds to `process.exit()`.
  */
 export declare function runCli(argv: readonly string[], io: CliIO): Promise<CliResult>;
 /**
@@ -151,6 +183,9 @@ export declare function runCli(argv: readonly string[], io: CliIO): Promise<CliR
  * stable and self-describing so LLMs and SDK builders can consume it
  * without round-tripping through OpenAPI.
  *
+ * @param app - Loaded App whose route registry is dumped.
+ * @param opts - Parsed CLI options; `--tag` / `--method` filter the catalog.
+ * @returns JSON-serializable dump with `daloy.ai` version marker, `generatedAt`, and the `routes` array.
  * @since 0.14.0
  */
 export declare function buildAiDump(app: App, opts: CliOptions): Record<string, unknown>;

package/dist/cli.js

@@ -118,6 +118,7 @@ const DEFAULT_DEV_ENTRIES = [
  * Detect which JS runtime is hosting the CLI. Inspects
  * `globalThis.process.versions` for Bun/Deno markers; falls back to Node.
  *
+ * @returns `"bun"`, `"deno"`, or `"node"` (the default when no marker is found).
  * @since 0.3.0
  */
 export function detectRuntime() {
@@ -142,6 +143,9 @@ export function detectRuntime() {
  * `runCli()` callers and tests so the invariant holds regardless of how the
  * entry value was produced.
  *
+ * @param entry - Entry path to validate.
+ * @param context - Label prefixed to error messages (e.g. `"daloy dev"`).
+ * @throws Error when the path is empty, contains NUL/CR/LF, or starts with `-`.
  * @internal
  */
 export function assertSafeEntryPath(entry, context) {
@@ -163,6 +167,8 @@ export function assertSafeEntryPath(entry, context) {
  * paths like `src/server.ts` are rewritten to `./src/server.ts`. This is
  * the second half of the {@link assertSafeEntryPath} defense.
  *
+ * @param entry - Entry path to anchor.
+ * @returns The path unchanged if already absolute or `./`/`../`-anchored (Windows drive paths included); otherwise `./` + path.
  * @internal
  */
 export function normalizeEntryArg(entry) {
@@ -194,6 +200,10 @@ export function normalizeEntryArg(entry) {
  * `SECURITY.md` § "CLI threat model" for the full rationale (and why we
  * are not vulnerable to the class of bug Snyk reported as CVE-2022-22984).
  *
+ * @param runtime - Host runtime to build the command for.
+ * @param entry - Entry file to run; validated and `./`-anchored before use.
+ * @returns The executable name and argv array to pass to `spawn({ shell: false })`.
+ * @throws Error via {@link assertSafeEntryPath} when the entry path is unsafe.
  * @since 0.3.0
  */
 export function buildDevCommand(runtime, entry) {
@@ -242,6 +252,10 @@ async function resolveDevEntry(entry) {
 /**
  * Parse a process-style argv (without the `node`/`daloy` prefix) into a
  * `{ command, opts }` pair. Throws on unknown flags or invalid enum values.
+ *
+ * @param argv - Arguments after the binary name, e.g. `["inspect", "--json", "./src/server.ts"]`.
+ * @returns The resolved command (default `"inspect"`) and parsed {@link CliOptions}.
+ * @throws Error on unknown `-`-prefixed flags, missing flag values, or invalid `--format`/`--runtime` values.
  */
 export function parseArgs(argv) {
     const opts = {
@@ -343,6 +357,10 @@ function readFlagValue(argv, index, flag) {
  * Execute the CLI against the supplied argv and {@link CliIO}. Does not read
  * `process.argv`, write to process stdio, or call `process.exit()` directly,
  * so tests can drive `inspect`/`dev`/`doctor` with in-memory stdio.
+ *
+ * @param argv - Process-style arguments (without the `node`/`daloy` prefix); see {@link parseArgs}.
+ * @param io - I/O hooks for stdout/stderr, module import, spawning, and file reads.
+ * @returns A {@link CliResult} whose `exitCode` the caller feeds to `process.exit()`.
  */
 export async function runCli(argv, io) {
     let parsed;
@@ -750,7 +768,8 @@ async function runDoctor(opts, io) {
                 message: `${missingBody.length} route(s) declare a 2xx response with no body schema, so ` +
                     `response field-level stripping (OWASP API3) is not applied: ${sample}` +
                     `${missingBody.length > 5 ? ", …" : ""}. Declare a response body schema so undeclared ` +
-                    "handler fields cannot leak, or ignore if the route intentionally returns no body.",
+                    "handler fields cannot leak, or set `acknowledgeNoResponseBodySchema: true` on routes " +
+                    "that intentionally return an opaque or body-less response.",
             });
         }
     }
@@ -826,6 +845,9 @@ async function runDev(opts, io) {
  * stable and self-describing so LLMs and SDK builders can consume it
  * without round-tripping through OpenAPI.
  *
+ * @param app - Loaded App whose route registry is dumped.
+ * @param opts - Parsed CLI options; `--tag` / `--method` filter the catalog.
+ * @returns JSON-serializable dump with `daloy.ai` version marker, `generatedAt`, and the `routes` array.
  * @since 0.14.0
  */
 export function buildAiDump(app, opts) {

package/dist/combine.d.ts

@@ -29,6 +29,8 @@ import type { Hooks, BaseContext } from "./types.js";
  * app.use(adminStack);
  * ```
  *
+ * @param layers Hook bundles to compose, executed in the order given.
+ * @returns A single merged {@link Hooks} bundle preserving all lifecycle phases.
  * @since 0.19.0
  */
 export declare function every(...layers: Hooks[]): Hooks;
@@ -61,6 +63,8 @@ export declare function every(...layers: Hooks[]): Hooks;
  * ));
  * ```
  *
+ * @param layers Candidate hook bundles; the first `beforeHandle` that passes wins.
+ * @returns A merged {@link Hooks} bundle with the OR-style `beforeHandle` strategy.
  * @since 0.19.0
  */
 export declare function some(...layers: Hooks[]): Hooks;
@@ -91,6 +95,10 @@ export type ExceptPredicate = string | string[] | ((ctx: BaseContext<any, any>)
  * exempted. Wrap each bundle with {@link except} individually when you
  * need to gate other phases.
  *
+ * @param when Paths or predicate ({@link ExceptPredicate}) that exempt a request.
+ * @param hooks The hook bundle whose `beforeHandle` is skipped on a match.
+ * @returns A {@link Hooks} bundle whose `beforeHandle` is gated by `when`.
+ * @throws Error at composition time if a string pattern does not start with `/`.
  * @since 0.19.0
  */
 export declare function except(when: ExceptPredicate, hooks: Hooks): Hooks;

package/dist/combine.js

@@ -28,6 +28,8 @@
  * app.use(adminStack);
  * ```
  *
+ * @param layers Hook bundles to compose, executed in the order given.
+ * @returns A single merged {@link Hooks} bundle preserving all lifecycle phases.
  * @since 0.19.0
  */
 export function every(...layers) {
@@ -62,6 +64,8 @@ export function every(...layers) {
  * ));
  * ```
  *
+ * @param layers Candidate hook bundles; the first `beforeHandle` that passes wins.
+ * @returns A merged {@link Hooks} bundle with the OR-style `beforeHandle` strategy.
  * @since 0.19.0
  */
 export function some(...layers) {
@@ -119,6 +123,10 @@ export function some(...layers) {
  * exempted. Wrap each bundle with {@link except} individually when you
  * need to gate other phases.
  *
+ * @param when Paths or predicate ({@link ExceptPredicate}) that exempt a request.
+ * @param hooks The hook bundle whose `beforeHandle` is skipped on a match.
+ * @returns A {@link Hooks} bundle whose `beforeHandle` is gated by `when`.
+ * @throws Error at composition time if a string pattern does not start with `/`.
  * @since 0.19.0
  */
 export function except(when, hooks) {

package/dist/compression.d.ts

@@ -121,6 +121,9 @@ export declare function _resetCompressionRuntimeProbeForTests(): void;
  * app.use(compression());
  * ```
  *
+ * @param opts Compression tuning ({@link CompressionOptions}); `minimumSize` defaults to `1024` bytes.
+ * @returns A {@link Hooks} bundle whose `onSend` compresses eligible response bodies.
+ * @throws TypeError if `compressLevel` is passed or `minimumSize` is not a finite non-negative integer.
  * @since 0.25.0
  */
 export declare function compression(opts?: CompressionOptions): Hooks;

package/dist/compression.js

@@ -281,6 +281,9 @@ async function compressBytes(bytes, encoding) {
  * app.use(compression());
  * ```
  *
+ * @param opts Compression tuning ({@link CompressionOptions}); `minimumSize` defaults to `1024` bytes.
+ * @returns A {@link Hooks} bundle whose `onSend` compresses eligible response bodies.
+ * @throws TypeError if `compressLevel` is passed or `minimumSize` is not a finite non-negative integer.
  * @since 0.25.0
  */
 export function compression(opts = {}) {

package/dist/config.d.ts

@@ -21,6 +21,7 @@ import { type StandardSchemaV1 } from "./schema.js";
  * dashboard, a startup probe, or a custom error renderer.
  */
 export declare class ConfigValidationError extends Error {
+    /** Every validation issue, as `{ key, message }` pairs (`key` is the dotted path, `"<root>"`/`"<source>"` for top-level failures). */
     readonly issues: ReadonlyArray<{
         key: string;
         message: string;
@@ -92,6 +93,9 @@ export interface DefineConfigOptions<S extends StandardSchemaV1> {
  * export const config = await defineConfig({ schema: Config });
  * ```
  *
+ * @param opts - Schema, source (default `"env"`), optional `transform`, and the stderr sink.
+ * @returns The validated, typed configuration object.
+ * @throws {ConfigValidationError} When the source cannot be read or the schema reports issues.
  * @since 0.20.0
  */
 export declare function defineConfig<S extends StandardSchemaV1>(opts: DefineConfigOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;

package/dist/config.js

@@ -21,6 +21,7 @@ import { validate } from "./schema.js";
  * dashboard, a startup probe, or a custom error renderer.
  */
 export class ConfigValidationError extends Error {
+    /** Every validation issue, as `{ key, message }` pairs (`key` is the dotted path, `"<root>"`/`"<source>"` for top-level failures). */
     issues;
     constructor(issues) {
         const summary = issues
@@ -90,6 +91,9 @@ function pathToKey(path) {
  * export const config = await defineConfig({ schema: Config });
  * ```
  *
+ * @param opts - Schema, source (default `"env"`), optional `transform`, and the stderr sink.
+ * @returns The validated, typed configuration object.
+ * @throws {ConfigValidationError} When the source cannot be read or the schema reports issues.
  * @since 0.20.0
  */
 export async function defineConfig(opts) {