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

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) {

package/dist/conn-info.d.ts

@@ -69,6 +69,9 @@ interface MutableConnInfo {
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
  * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
  * `app.fetch(request)`.
+ *
+ * @param request - Incoming request to tag (stored under a private symbol).
+ * @param info - Connection metadata gathered by the adapter.
  */
 export declare function setConnInfo(request: Request, info: ConnInfo): void;
 /**
@@ -76,6 +79,8 @@ export declare function setConnInfo(request: Request, info: ConnInfo): void;
  * `undefined` when the adapter does not expose connection metadata (e.g.
  * Cloudflare Workers without `cf` enabled).
  *
+ * @param request - Request previously tagged by {@link setConnInfo}.
+ * @returns The attached {@link ConnInfo}, or `undefined` when absent.
  * @since 0.24.0
  */
 export declare function getConnInfo(request: Request): ConnInfo | undefined;
@@ -83,6 +88,9 @@ export declare function getConnInfo(request: Request): ConnInfo | undefined;
  * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
  * during `new App({ behindProxy })`.
  *
+ * @param cfg - Proxy posture to validate; `undefined` is accepted as "unset".
+ * @throws Error when `hops` is not an integer in [0, 64], when `cidrs` is
+ *   empty or contains non-string entries, or when the shape is unrecognized.
  * @since 0.24.0
  */
 export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): void;
@@ -93,6 +101,10 @@ export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): v
  * `undefined` when the header is shorter than the configured hop count
  * (caller falls back to the immediate peer).
  *
+ * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
+ * @param hops - Declared number of trusted proxy hops (must be >= 1).
+ * @returns The client IP at the declared hop, or `undefined` when the chain
+ *   is too short or `hops < 1`.
  * @internal
  */
 export declare function pickForwardedForByHops(header: string | null, hops: number): string | undefined;
@@ -102,6 +114,10 @@ export declare function pickForwardedForByHops(header: string | null, hops: numb
  * available (the caller — rate-limit, ipRestriction, audit-log — must fail
  * closed rather than guess).
  *
+ * @param request - Incoming request whose client IP should be resolved.
+ * @param cfg - The app's `behindProxy` posture; `undefined` behaves as `"none"`.
+ * @returns The trusted client IP, or `undefined` when neither the peer
+ *   address nor a trusted `X-Forwarded-For` slot is available.
  * @since 0.24.0
  */
 export declare function resolveClientIp(request: Request, cfg: BehindProxyConfig | undefined): string | undefined;
@@ -110,11 +126,28 @@ export declare function resolveClientIp(request: Request, cfg: BehindProxyConfig
  * `undefined` rather than allocating a plain object so the IP cannot be
  * serialized into logs by accident.
  *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer address, or `undefined` when the adapter did
+ *   not attach connection metadata.
  * @since 0.24.0
  */
 export declare function readRemoteAddress(ctx: BaseContext<any, any>): string | undefined;
-/** @since 0.24.0 */
+/**
+ * Lazy accessor for `ctx.remotePort` (the immediate peer's TCP port).
+ *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer port, or `undefined` when the adapter did not
+ *   attach connection metadata.
+ * @since 0.24.0
+ */
 export declare function readRemotePort(ctx: BaseContext<any, any>): number | undefined;
-/** @internal Test-only helper. */
+/**
+ * Test-only helper that shallow-copies a {@link ConnInfo} into a mutable shape
+ * so tests can tweak fields without casting away `readonly`.
+ *
+ * @param info - Connection metadata to copy.
+ * @returns A mutable shallow copy of `info`.
+ * @internal
+ */
 export declare function _makeConnInfoForTests(info: ConnInfo): MutableConnInfo;
 export {};

package/dist/conn-info.js

@@ -23,6 +23,9 @@ const CONN_INFO_SYMBOL = Symbol.for("daloyjs.connInfo");
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
  * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
  * `app.fetch(request)`.
+ *
+ * @param request - Incoming request to tag (stored under a private symbol).
+ * @param info - Connection metadata gathered by the adapter.
  */
 export function setConnInfo(request, info) {
     request[CONN_INFO_SYMBOL] = info;
@@ -32,6 +35,8 @@ export function setConnInfo(request, info) {
  * `undefined` when the adapter does not expose connection metadata (e.g.
  * Cloudflare Workers without `cf` enabled).
  *
+ * @param request - Request previously tagged by {@link setConnInfo}.
+ * @returns The attached {@link ConnInfo}, or `undefined` when absent.
  * @since 0.24.0
  */
 export function getConnInfo(request) {
@@ -41,6 +46,9 @@ export function getConnInfo(request) {
  * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
  * during `new App({ behindProxy })`.
  *
+ * @param cfg - Proxy posture to validate; `undefined` is accepted as "unset".
+ * @throws Error when `hops` is not an integer in [0, 64], when `cidrs` is
+ *   empty or contains non-string entries, or when the shape is unrecognized.
  * @since 0.24.0
  */
 export function assertBehindProxy(cfg) {
@@ -76,6 +84,10 @@ export function assertBehindProxy(cfg) {
  * `undefined` when the header is shorter than the configured hop count
  * (caller falls back to the immediate peer).
  *
+ * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
+ * @param hops - Declared number of trusted proxy hops (must be >= 1).
+ * @returns The client IP at the declared hop, or `undefined` when the chain
+ *   is too short or `hops < 1`.
  * @internal
  */
 export function pickForwardedForByHops(header, hops) {
@@ -97,6 +109,10 @@ export function pickForwardedForByHops(header, hops) {
  * available (the caller — rate-limit, ipRestriction, audit-log — must fail
  * closed rather than guess).
  *
+ * @param request - Incoming request whose client IP should be resolved.
+ * @param cfg - The app's `behindProxy` posture; `undefined` behaves as `"none"`.
+ * @returns The trusted client IP, or `undefined` when neither the peer
+ *   address nor a trusted `X-Forwarded-For` slot is available.
  * @since 0.24.0
  */
 export function resolveClientIp(request, cfg) {
@@ -129,16 +145,33 @@ export function resolveClientIp(request, cfg) {
  * `undefined` rather than allocating a plain object so the IP cannot be
  * serialized into logs by accident.
  *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer address, or `undefined` when the adapter did
+ *   not attach connection metadata.
  * @since 0.24.0
  */
 export function readRemoteAddress(ctx) {
     return getConnInfo(ctx.request)?.remoteAddress;
 }
-/** @since 0.24.0 */
+/**
+ * Lazy accessor for `ctx.remotePort` (the immediate peer's TCP port).
+ *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer port, or `undefined` when the adapter did not
+ *   attach connection metadata.
+ * @since 0.24.0
+ */
 export function readRemotePort(ctx) {
     return getConnInfo(ctx.request)?.remotePort;
 }
-/** @internal Test-only helper. */
+/**
+ * Test-only helper that shallow-copies a {@link ConnInfo} into a mutable shape
+ * so tests can tweak fields without casting away `readonly`.
+ *
+ * @param info - Connection metadata to copy.
+ * @returns A mutable shallow copy of `info`.
+ * @internal
+ */
 export function _makeConnInfoForTests(info) {
     return { ...info };
 }

package/dist/contract.d.ts

@@ -44,6 +44,8 @@ export interface ContractTestOptions {
  * routes don't carry body schemas by accident, and that `meta.examples`
  * reference declared response statuses.
  *
+ * @param app The {@link App} whose registered routes are inspected.
+ * @param opts Check toggles ({@link ContractTestOptions}); `requireOperationId` defaults to `true`.
  * @returns A {@link ContractReport}. In CI, exit non-zero when `report.ok` is `false`.
  */
 export declare function runContractTests(app: App, opts?: ContractTestOptions): Promise<ContractReport>;

package/dist/contract.js

@@ -19,6 +19,8 @@ import { validate } from "./schema.js";
  * routes don't carry body schemas by accident, and that `meta.examples`
  * reference declared response statuses.
  *
+ * @param app The {@link App} whose registered routes are inspected.
+ * @param opts Check toggles ({@link ContractTestOptions}); `requireOperationId` defaults to `true`.
  * @returns A {@link ContractReport}. In CI, exit non-zero when `report.ok` is `false`.
  */
 export async function runContractTests(app, opts = {}) {

package/dist/cookie.d.ts

@@ -84,6 +84,11 @@ export declare function assertCookieAttributes(input: {
  * The value is URI-encoded so binary signature bytes and base64 padding
  * round-trip safely.
  *
+ * @param name Cookie name; `__Host-`/`__Secure-` prefixes are enforced by validation.
+ * @param value Cookie value; URI-encoded before serialization.
+ * @param attributes Cookie attributes. Defaults: `SameSite=Strict`, `Secure`, `HttpOnly`, `Path=/`.
+ * @returns A single `Set-Cookie` header value.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export declare function serializeCookie(name: string, value: string, attributes?: CookieAttributes): string;
@@ -92,6 +97,10 @@ export declare function serializeCookie(name: string, value: string, attributes?
  * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
  * intermediaries match the original cookie when deciding what to delete.
  *
+ * @param name Name of the cookie to clear.
+ * @param attributes Attributes of the original cookie; must match for deletion to apply.
+ * @returns A `Set-Cookie` header value with an empty value and `Max-Age=0`.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export declare function serializeClearCookie(name: string, attributes?: CookieAttributes): string;
@@ -118,6 +127,9 @@ export declare function serializeClearCookie(name: string, attributes?: CookieAt
  * parser-level guard is defense-in-depth for developers who customize the
  * cookie name or read other cookies through this helper.
  *
+ * @param header The raw `Cookie` request header, or `null`/`undefined` when absent.
+ * @param name Exact cookie name to read (case-sensitive).
+ * @returns The decoded cookie value, or `null` when absent or duplicated.
  * @since 0.27.0
  */
 export declare function readRequestCookie(header: string | null | undefined, name: string): string | null;

package/dist/cookie.js

@@ -96,6 +96,11 @@ export function assertCookieAttributes(input) {
  * The value is URI-encoded so binary signature bytes and base64 padding
  * round-trip safely.
  *
+ * @param name Cookie name; `__Host-`/`__Secure-` prefixes are enforced by validation.
+ * @param value Cookie value; URI-encoded before serialization.
+ * @param attributes Cookie attributes. Defaults: `SameSite=Strict`, `Secure`, `HttpOnly`, `Path=/`.
+ * @returns A single `Set-Cookie` header value.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export function serializeCookie(name, value, attributes = {}) {
@@ -125,6 +130,10 @@ export function serializeCookie(name, value, attributes = {}) {
  * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
  * intermediaries match the original cookie when deciding what to delete.
  *
+ * @param name Name of the cookie to clear.
+ * @param attributes Attributes of the original cookie; must match for deletion to apply.
+ * @returns A `Set-Cookie` header value with an empty value and `Max-Age=0`.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export function serializeClearCookie(name, attributes = {}) {
@@ -170,6 +179,9 @@ export function serializeClearCookie(name, attributes = {}) {
  * parser-level guard is defense-in-depth for developers who customize the
  * cookie name or read other cookies through this helper.
  *
+ * @param header The raw `Cookie` request header, or `null`/`undefined` when absent.
+ * @param name Exact cookie name to read (case-sensitive).
+ * @returns The decoded cookie value, or `null` when absent or duplicated.
  * @since 0.27.0
  */
 export function readRequestCookie(header, name) {

package/dist/dependency.d.ts

@@ -31,6 +31,7 @@ export interface DependencyOptions<TName extends string, TValue, TStateKey exten
 }
 /** Hooks bundle returned by {@link defineDependency} (carries metadata). */
 export interface DependencyHooks extends Hooks {
+    /** Non-enumerable dependency metadata (`name` + `dependsOn`) used for dedup and cycle checks. */
     readonly [DEPENDENCY_MARKER]: {
         readonly name: string;
         readonly dependsOn: readonly string[];
@@ -42,6 +43,9 @@ export interface DependencyHooks extends Hooks {
  * `ctx.state[stateKey]` (default `name`). Composing the same dependency
  * twice in one chain runs `resolve()` exactly once.
  *
+ * @param opts - Dependency `name`, optional `dependsOn` / `stateKey`, and the `resolve` function.
+ * @returns A {@link DependencyHooks} bundle to compose via `app.use()` / route hooks.
+ * @throws {Error} When `name` is empty or the dependency declares itself in `dependsOn` (cycle).
  * @since 0.24.0
  */
 export declare function defineDependency<TName extends string, TValue, TStateKey extends string = TName>(opts: DependencyOptions<TName, TValue, TStateKey>): DependencyHooks;

package/dist/dependency.js

@@ -21,6 +21,9 @@ const RESULTS_KEY = Symbol.for("daloyjs.dependency.results");
  * `ctx.state[stateKey]` (default `name`). Composing the same dependency
  * twice in one chain runs `resolve()` exactly once.
  *
+ * @param opts - Dependency `name`, optional `dependsOn` / `stateKey`, and the `resolve` function.
+ * @returns A {@link DependencyHooks} bundle to compose via `app.use()` / route hooks.
+ * @throws {Error} When `name` is empty or the dependency declares itself in `dependsOn` (cycle).
  * @since 0.24.0
  */
 export function defineDependency(opts) {

package/dist/discriminator.d.ts

@@ -27,6 +27,11 @@ export interface DiscriminatorObject {
  * Build an OpenAPI 3.1 Discriminator Object. Throws on an empty
  * `propertyName` so misconfigurations fail at boot rather than producing a
  * silently invalid spec.
+ *
+ * @param propertyName Name of the property that selects the variant schema.
+ * @param mapping Optional explicit discriminator-value-to-$ref map.
+ * @returns A {@link DiscriminatorObject} ready to embed in an OpenAPI schema.
+ * @throws TypeError if `propertyName` is not a non-empty string.
  */
 export declare function discriminator(propertyName: string, mapping?: Record<string, string>): DiscriminatorObject;
 /** Options for {@link discriminatedUnion}. */
@@ -68,6 +73,14 @@ export type DiscriminatedUnion<V extends Record<string, StandardSchemaV1>> = Sta
  * const Cat = z.object({ kind: z.literal("cat"), meow: z.boolean() });
  * const Dog = z.object({ kind: z.literal("dog"), bark: z.boolean() });
  * const Animal = discriminatedUnion("kind", { cat: Cat, dog: Dog });
+ *
+ * @param propertyName Discriminator property read off the incoming value.
+ * @param variants Map from discriminator value to variant schema. Only own
+ *   properties are consulted, so prototype names like `constructor` cannot
+ *   be abused to bypass variant lookup.
+ * @param opts Optional {@link DiscriminatedUnionOptions} (explicit `mapping`, `vendor`).
+ * @returns A {@link DiscriminatedUnion} usable as validator and OpenAPI emitter.
+ * @throws TypeError if `propertyName` is empty or `variants` has no entries.
  */
 export declare function discriminatedUnion<P extends string, V extends Record<string, StandardSchemaV1>>(propertyName: P, variants: V, opts?: DiscriminatedUnionOptions): DiscriminatedUnion<V>;
 export {};