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

package/dist/middleware.d.ts

@@ -78,16 +78,38 @@ export interface CspDirectivesOptions {
 }
 /** Options for {@link secureHeaders}. Every field can be disabled with `false`. */
 export interface SecureHeadersOptions {
+    /**
+     * `Content-Security-Policy` value: a raw header string, a
+     * {@link CspDirectivesOptions} object (enables nonces / Trusted Types),
+     * or `false` to omit. Defaults to
+     * `"default-src 'self'; frame-ancestors 'none'"`.
+     */
     contentSecurityPolicy?: string | false | CspDirectivesOptions;
+    /**
+     * `Strict-Transport-Security` settings (`maxAgeSeconds` in seconds).
+     * Defaults to `{ maxAgeSeconds: 31536000, includeSubDomains: true }`.
+     */
     hsts?: {
         maxAgeSeconds: number;
         includeSubDomains?: boolean;
         preload?: boolean;
     } | false;
+    /**
+     * `X-Frame-Options` value. Defaults to `"DENY"`. Disabling it with
+     * `false` while the CSP also lacks `frame-ancestors` throws at
+     * construction time (clickjacking guard).
+     */
     frameOptions?: "DENY" | "SAMEORIGIN" | false;
+    /** `Referrer-Policy` value. Defaults to `"no-referrer"`. */
     referrerPolicy?: string | false;
+    /**
+     * `Permissions-Policy` value. Defaults to
+     * `"camera=(), microphone=(), geolocation=(), clipboard-write=()"`.
+     */
     permissionsPolicy?: string | false;
+    /** `Cross-Origin-Opener-Policy` value. Defaults to `"same-origin"`. */
     crossOriginOpenerPolicy?: string | false;
+    /** `Cross-Origin-Resource-Policy` value. Defaults to `"same-origin"`. */
     crossOriginResourcePolicy?: string | false;
     /**
      * `Cross-Origin-Embedder-Policy` (COEP). Off by default because
@@ -101,7 +123,12 @@ export interface SecureHeadersOptions {
      * @since 0.37.0
      */
     crossOriginEmbedderPolicy?: "require-corp" | "credentialless" | "unsafe-none" | false;
+    /** Emit `X-Content-Type-Options: nosniff`. Defaults to `true`. */
     noSniff?: boolean;
+    /**
+     * Emit `X-XSS-Protection: 0` (disables the legacy XSS auditor, per
+     * modern guidance). Defaults to `false` (header omitted).
+     */
     xssProtection?: boolean;
     /**
      * Reporting API endpoint declarations rendered as the
@@ -165,6 +192,11 @@ export declare const SECURE_HEADERS_MARKER: unique symbol;
  * {@link SecureHeadersOptions} for the full list). Pass `false` for any
  * field to disable that header; handler-set headers always win.
  *
+ * @param opts - Per-header overrides. Pass `false` to disable a header.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with
+ * {@link SECURE_HEADERS_MARKER}.
+ * @throws {Error} When `frameOptions: false` is combined with a CSP that has
+ * no `frame-ancestors` directive (would disable every clickjacking defense).
  * @since 0.1.0
  */
 export declare function secureHeaders(opts?: SecureHeadersOptions): Hooks;
@@ -286,11 +318,30 @@ export declare const CSRF_HOOK_MARKER: unique symbol;
 export type CorsOriginAllow = (origin: string) => boolean;
 /** Options for {@link cors}. */
 export interface CorsOptions {
+    /**
+     * Allowed cross-origin caller(s): a single origin string, an array of
+     * origins, or a predicate. `"*"` is rejected with `credentials: true`
+     * and refused at boot on production `secureDefaults` apps.
+     */
     origin: string | string[] | ((origin: string) => boolean);
+    /**
+     * Verbs advertised on preflight (`Access-Control-Allow-Methods`).
+     * Defaults to `["GET", "HEAD", "POST"]`. `"*"` is rejected.
+     */
     methods?: string[];
+    /**
+     * Request headers advertised on preflight (`Access-Control-Allow-Headers`).
+     * Defaults to `["content-type", "authorization"]`.
+     */
     allowedHeaders?: string[];
+    /** Response headers exposed to browser JS (`Access-Control-Expose-Headers`). None by default. */
     exposedHeaders?: string[];
+    /**
+     * Emit `Access-Control-Allow-Credentials: true`. Defaults to `false`.
+     * Cannot be combined with a wildcard `origin`.
+     */
     credentials?: boolean;
+    /** Preflight cache lifetime in seconds (`Access-Control-Max-Age`). Defaults to `600`. */
     maxAgeSeconds?: number;
 }
 /**
@@ -327,6 +378,11 @@ export declare function cors(opts: CorsOptions): Hooks;
  * (`@daloyjs/core/rate-limit-redis`).
  */
 export interface RateLimitStore {
+    /**
+     * Record one request for `key` in the window of `windowMs` milliseconds
+     * and return the updated `count` plus the window's absolute reset time
+     * (`resetMs`, epoch milliseconds).
+     */
     hit(key: string, windowMs: number): Promise<{
         count: number;
         resetMs: number;
@@ -437,6 +493,9 @@ export interface LoginThrottleOptions {
  * same `groupId`) across related routes so an attacker cannot bypass the limit
  * by rotating between password, OTP, and reset endpoints.
  *
+ * @param opts - Throttle tuning (see {@link LoginThrottleOptions}); every field has a safe default.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`.
+ * @throws {Error} When `windowMs`/`max` are not positive integers or the delay options are negative.
  * @since 0.23.0
  */
 export declare function loginThrottle(opts?: LoginThrottleOptions): Hooks;
@@ -627,6 +686,11 @@ export interface CsrfOptions {
  *   allowedOrigins: ["https://app.example.com"],
  * }));
  * ```
+ *
+ * @param opts - Strategy, cookie/header names, and cookie attributes (see {@link CsrfOptions}).
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with {@link CSRF_HOOK_MARKER}.
+ * @throws {Error} When `strategy` is unknown or the cookie name/attributes are invalid
+ * (e.g. `__Host-` prefix without `secure: true`, `path: "/"`, and no `domain`).
  */
 export declare function csrf(opts?: CsrfOptions): Hooks;
 /** Options for {@link basicAuth}. */
@@ -723,6 +787,10 @@ export declare const REQUIRE_SCOPES_HOOK_MARKER: unique symbol;
  * });
  * ```
  *
+ * @param scopes - Required scope strings; must be non-empty and free of RFC 6749 illegal characters.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`,
+ * stamped with {@link REQUIRE_SCOPES_HOOK_MARKER}.
+ * @throws {Error} When `scopes` is empty or contains a non-string, empty, or illegal-character scope.
  * @since 0.21.0
  */
 export declare function requireScopes(scopes: readonly string[]): Hooks;

package/dist/middleware.js

@@ -148,6 +148,11 @@ export const SECURE_HEADERS_MARKER = Symbol.for("daloyjs.middleware.secureHeader
  * {@link SecureHeadersOptions} for the full list). Pass `false` for any
  * field to disable that header; handler-set headers always win.
  *
+ * @param opts - Per-header overrides. Pass `false` to disable a header.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with
+ * {@link SECURE_HEADERS_MARKER}.
+ * @throws {Error} When `frameOptions: false` is combined with a CSP that has
+ * no `frame-ancestors` directive (would disable every clickjacking defense).
  * @since 0.1.0
  */
 export function secureHeaders(opts = {}) {
@@ -706,6 +711,9 @@ function wait(ms) {
  * same `groupId`) across related routes so an attacker cannot bypass the limit
  * by rotating between password, OTP, and reset endpoints.
  *
+ * @param opts - Throttle tuning (see {@link LoginThrottleOptions}); every field has a safe default.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`.
+ * @throws {Error} When `windowMs`/`max` are not positive integers or the delay options are negative.
  * @since 0.23.0
  */
 export function loginThrottle(opts = {}) {
@@ -912,6 +920,11 @@ function csrfCookieAttributes(opts) {
  *   allowedOrigins: ["https://app.example.com"],
  * }));
  * ```
+ *
+ * @param opts - Strategy, cookie/header names, and cookie attributes (see {@link CsrfOptions}).
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`, stamped with {@link CSRF_HOOK_MARKER}.
+ * @throws {Error} When `strategy` is unknown or the cookie name/attributes are invalid
+ * (e.g. `__Host-` prefix without `secure: true`, `path: "/"`, and no `domain`).
  */
 export function csrf(opts = {}) {
     const strategy = opts.strategy ?? "double-submit";
@@ -1191,6 +1204,10 @@ function readUserScopes(user) {
  * });
  * ```
  *
+ * @param scopes - Required scope strings; must be non-empty and free of RFC 6749 illegal characters.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`,
+ * stamped with {@link REQUIRE_SCOPES_HOOK_MARKER}.
+ * @throws {Error} When `scopes` is empty or contains a non-string, empty, or illegal-character scope.
  * @since 0.21.0
  */
 export function requireScopes(scopes) {

package/dist/mtls.d.ts

@@ -84,6 +84,9 @@ export type ClientCertificateSource = ClientCertificate | undefined | (() => Cli
  * Pass a thunk to defer the read until {@link getClientCertificate} is first
  * called; the resolved value is cached back onto the request.
  *
+ * @param request The incoming request to stash the certificate on.
+ * @param source The certificate, a lazy thunk producing one, or `undefined`
+ *   when the connection presented no client certificate.
  * @since 0.37.0
  */
 export declare function setClientCertificate(request: Request, source: ClientCertificateSource): void;
@@ -93,6 +96,8 @@ export declare function setClientCertificate(request: Request, source: ClientCer
  * adapter does not expose TLS peer info). If a lazy thunk was stashed, it is
  * resolved once and the result cached.
  *
+ * @param request The request previously seen by {@link setClientCertificate}.
+ * @returns The attached certificate, or `undefined` when none was presented.
  * @since 0.37.0
  */
 export declare function getClientCertificate(request: Request): ClientCertificate | undefined;
@@ -104,12 +109,19 @@ export declare function getClientCertificate(request: Request): ClientCertificat
  * @since 0.37.0
  */
 export interface PeerCertificateLike {
+    /** Subject RDN attributes keyed by short name (e.g. `CN`, `O`). */
     subject?: Record<string, string | string[]> | null;
+    /** Issuer RDN attributes keyed by short name. */
     issuer?: Record<string, string | string[]> | null;
+    /** Validity start as a Node-formatted date string. */
     valid_from?: string;
+    /** Validity end as a Node-formatted date string. */
     valid_to?: string;
+    /** SHA-256 fingerprint, colon-delimited hex as Node emits it. */
     fingerprint256?: string;
+    /** Certificate serial number as a hex string. */
     serialNumber?: string;
+    /** Subject Alternative Names rendered as `DNS:a, IP Address:1.2.3.4, ...`. */
     subjectaltname?: string;
 }
 /**
@@ -120,6 +132,9 @@ export interface PeerCertificateLike {
  * @param raw - The structured peer-certificate object from the TLS socket.
  * @param verified - Whether the socket reported `authorized === true` (the
  *   chain was verified against the configured CA).
+ * @returns The normalized certificate, or `undefined` when `raw` is missing
+ *   or carries no identifying fields (no subject, issuer, fingerprint, or
+ *   serial).
  * @since 0.37.0
  */
 export declare function normalizePeerCertificate(raw: PeerCertificateLike | null | undefined, verified: boolean): ClientCertificate | undefined;
@@ -131,8 +146,10 @@ export declare function normalizePeerCertificate(raw: PeerCertificateLike | null
  * and is the one returned. Because Envoy only emits XFCC for connections it
  * mutually authenticated, the result is marked `verified: true`.
  *
- * Returns `undefined` for an empty or unparseable header.
- *
+ * @param headerValue Raw XFCC header value; `null`/`undefined` are tolerated.
+ * @returns The certificate parsed from the first XFCC element, or `undefined`
+ *   for an empty or unparseable header. Only trust this header behind a proxy
+ *   you control that strips client-supplied XFCC.
  * @since 0.37.0
  */
 export declare function parseForwardedClientCert(headerValue: string | null | undefined): ClientCertificate | undefined;

package/dist/mtls.js

@@ -36,6 +36,9 @@ const CLIENT_CERT_SYMBOL = Symbol.for("daloyjs.clientCertificate");
  * Pass a thunk to defer the read until {@link getClientCertificate} is first
  * called; the resolved value is cached back onto the request.
  *
+ * @param request The incoming request to stash the certificate on.
+ * @param source The certificate, a lazy thunk producing one, or `undefined`
+ *   when the connection presented no client certificate.
  * @since 0.37.0
  */
 export function setClientCertificate(request, source) {
@@ -47,6 +50,8 @@ export function setClientCertificate(request, source) {
  * adapter does not expose TLS peer info). If a lazy thunk was stashed, it is
  * resolved once and the result cached.
  *
+ * @param request The request previously seen by {@link setClientCertificate}.
+ * @returns The attached certificate, or `undefined` when none was presented.
  * @since 0.37.0
  */
 export function getClientCertificate(request) {
@@ -67,6 +72,9 @@ export function getClientCertificate(request) {
  * @param raw - The structured peer-certificate object from the TLS socket.
  * @param verified - Whether the socket reported `authorized === true` (the
  *   chain was verified against the configured CA).
+ * @returns The normalized certificate, or `undefined` when `raw` is missing
+ *   or carries no identifying fields (no subject, issuer, fingerprint, or
+ *   serial).
  * @since 0.37.0
  */
 export function normalizePeerCertificate(raw, verified) {
@@ -205,8 +213,10 @@ function cnFromDN(dn) {
  * and is the one returned. Because Envoy only emits XFCC for connections it
  * mutually authenticated, the result is marked `verified: true`.
  *
- * Returns `undefined` for an empty or unparseable header.
- *
+ * @param headerValue Raw XFCC header value; `null`/`undefined` are tolerated.
+ * @returns The certificate parsed from the first XFCC element, or `undefined`
+ *   for an empty or unparseable header. Only trust this header behind a proxy
+ *   you control that strips client-supplied XFCC.
  * @since 0.37.0
  */
 export function parseForwardedClientCert(headerValue) {

package/dist/multipart.d.ts

@@ -114,6 +114,7 @@ export type UploadedFile = Blob & {
  * emit `format: binary`/`byte` accordingly.
  */
 export interface FileFieldSchema<Output = UploadedFile> extends StandardSchemaV1<unknown, Output> {
+    /** Resolved {@link FileFieldOptions} (with `format` defaulted) stamped on the schema for OpenAPI generation. */
     readonly [FILE_FIELD_MARKER]: Required<Pick<FileFieldOptions, "format">> & FileFieldOptions;
 }
 /**
@@ -122,13 +123,26 @@ export interface FileFieldSchema<Output = UploadedFile> extends StandardSchemaV1
  * Use inside a `multipartObject({...})` body schema, or directly inside any
  * Standard-Schema-compatible object schema (Zod, Valibot, ...). DaloyJS
  * keeps the underlying `File` reference so handlers can stream the body.
+ *
+ * @param options - Field constraints with `optional: true`; `null`/`undefined` values pass through.
+ * @returns A {@link FileFieldSchema} whose output may be `null`/`undefined`.
  */
 export declare function fileField(options: FileFieldOptions & {
     optional: true;
 }): FileFieldSchema<UploadedFile | null | undefined>;
-/** Validator for a required single uploaded `File`/`Blob` field. */
+/**
+ * Validator for a required single uploaded `File`/`Blob` field.
+ *
+ * @param options - Field constraints (`maxBytes`, `accept`, `filename`, `magicBytes`, ...).
+ * @returns A {@link FileFieldSchema} that rejects missing or non-file values.
+ */
 export declare function fileField(options?: FileFieldOptions): FileFieldSchema<UploadedFile>;
-/** Type-only check used by the OpenAPI generator. */
+/**
+ * Type-only check used by the OpenAPI generator.
+ *
+ * @param s - Candidate value to test for the `FILE_FIELD_MARKER` key.
+ * @returns `true` when `s` is a {@link fileField}-produced schema.
+ */
 export declare function isFileFieldSchema(s: unknown): s is FileFieldSchema;
 /** Options for {@link multipartObject}. */
 export interface MultipartObjectOptions {
@@ -154,15 +168,38 @@ interface MultipartSchema<S extends MultipartShape> extends StandardSchemaV1<Rec
  * body. Each entry in `shape` validates one form field by name. File fields
  * should use {@link fileField}; non-file fields can use any Standard-Schema
  * validator (`z.string()`, `v.number()`, ...).
+ *
+ * @param shape - Record mapping form-field names to per-field validators.
+ * @param options - `strict: true` rejects undeclared extra fields. Defaults
+ *   to `{ strict: false }` (extras pass through unvalidated).
+ * @returns A marker-carrying schema the OpenAPI generator renders as
+ *   `multipart/form-data`; validation issues are prefixed with the field name.
  */
 export declare function multipartObject<S extends MultipartShape>(shape: S, options?: MultipartObjectOptions): MultipartSchema<S>;
-/** Type-only check used by the OpenAPI generator and request-body parser. */
+/**
+ * Type-only check used by the OpenAPI generator and request-body parser.
+ *
+ * @param s - Candidate value to test for the `MULTIPART_SCHEMA_MARKER` key.
+ * @returns `true` when `s` is a {@link multipartObject}-produced schema.
+ */
 export declare function isMultipartObjectSchema(s: unknown): s is MultipartSchema<MultipartShape>;
-/** Internal: pull the multipart shape so the OpenAPI generator can walk it. */
+/**
+ * Internal: pull the multipart shape so the OpenAPI generator can walk it.
+ *
+ * @param s - Candidate schema value.
+ * @returns The `{ shape, strict }` config stored under the multipart marker,
+ *   or `undefined` when `s` is not a {@link multipartObject} schema.
+ */
 export declare function getMultipartShape(s: unknown): {
     shape: MultipartShape;
     strict: boolean;
 } | undefined;
-/** Internal: read the file-field options used for OpenAPI documentation. */
+/**
+ * Internal: read the file-field options used for OpenAPI documentation.
+ *
+ * @param s - Candidate schema value.
+ * @returns The resolved {@link FileFieldOptions} stored under the file-field
+ *   marker, or `undefined` when `s` is not a {@link fileField} schema.
+ */
 export declare function getFileFieldOptions(s: unknown): (Required<Pick<FileFieldOptions, "format">> & FileFieldOptions) | undefined;
 export {};

package/dist/multipart.js

@@ -233,7 +233,15 @@ async function verifyMagicBytes(file, signatures) {
     }
     return undefined;
 }
-/** Shared implementation for the `fileField` overloads above. */
+/**
+ * Shared implementation for the `fileField` overloads above.
+ *
+ * @param options - Field constraints; `format` defaults to `"binary"`, and
+ *   the scriptable-image guard defaults to on whenever `magicBytes` is set.
+ * @returns The marker-carrying {@link FileFieldSchema} validator.
+ * @throws Error at construction when `magicBytes` config is malformed (bad
+ *   offset, empty/out-of-range bytes, or `true` without a sniffable `accept`).
+ */
 export function fileField(options = {}) {
     const opts = {
         ...options,
@@ -312,7 +320,12 @@ export function fileField(options = {}) {
     };
     return schema;
 }
-/** Type-only check used by the OpenAPI generator. */
+/**
+ * Type-only check used by the OpenAPI generator.
+ *
+ * @param s - Candidate value to test for the `FILE_FIELD_MARKER` key.
+ * @returns `true` when `s` is a {@link fileField}-produced schema.
+ */
 export function isFileFieldSchema(s) {
     return !!s && typeof s === "object" && FILE_FIELD_MARKER in s;
 }
@@ -321,6 +334,12 @@ export function isFileFieldSchema(s) {
  * body. Each entry in `shape` validates one form field by name. File fields
  * should use {@link fileField}; non-file fields can use any Standard-Schema
  * validator (`z.string()`, `v.number()`, ...).
+ *
+ * @param shape - Record mapping form-field names to per-field validators.
+ * @param options - `strict: true` rejects undeclared extra fields. Defaults
+ *   to `{ strict: false }` (extras pass through unvalidated).
+ * @returns A marker-carrying schema the OpenAPI generator renders as
+ *   `multipart/form-data`; validation issues are prefixed with the field name.
  */
 export function multipartObject(shape, options = {}) {
     const strict = options.strict ?? false;
@@ -368,17 +387,34 @@ export function multipartObject(shape, options = {}) {
     };
     return schema;
 }
-/** Type-only check used by the OpenAPI generator and request-body parser. */
+/**
+ * Type-only check used by the OpenAPI generator and request-body parser.
+ *
+ * @param s - Candidate value to test for the `MULTIPART_SCHEMA_MARKER` key.
+ * @returns `true` when `s` is a {@link multipartObject}-produced schema.
+ */
 export function isMultipartObjectSchema(s) {
     return !!s && typeof s === "object" && MULTIPART_SCHEMA_MARKER in s;
 }
-/** Internal: pull the multipart shape so the OpenAPI generator can walk it. */
+/**
+ * Internal: pull the multipart shape so the OpenAPI generator can walk it.
+ *
+ * @param s - Candidate schema value.
+ * @returns The `{ shape, strict }` config stored under the multipart marker,
+ *   or `undefined` when `s` is not a {@link multipartObject} schema.
+ */
 export function getMultipartShape(s) {
     if (!isMultipartObjectSchema(s))
         return undefined;
     return s[MULTIPART_SCHEMA_MARKER];
 }
-/** Internal: read the file-field options used for OpenAPI documentation. */
+/**
+ * Internal: read the file-field options used for OpenAPI documentation.
+ *
+ * @param s - Candidate schema value.
+ * @returns The resolved {@link FileFieldOptions} stored under the file-field
+ *   marker, or `undefined` when `s` is not a {@link fileField} schema.
+ */
 export function getFileFieldOptions(s) {
     if (!isFileFieldSchema(s))
         return undefined;

package/dist/openapi.d.ts

@@ -38,14 +38,23 @@ export interface SecuritySchemeMap {
  * (no execution path on the producer side).
  */
 export interface WebhookDefinition {
+    /** HTTP method the producer uses when delivering the webhook. */
     method: HttpMethod;
+    /** Stable operation id for codegen. Omitted from the document when unset. */
     operationId?: string;
+    /** Short one-line summary shown in docs UIs. */
     summary?: string;
+    /** Longer CommonMark description of the webhook operation. */
     description?: string;
+    /** Tags used to group the operation in docs UIs. */
     tags?: string[];
+    /** Mark the webhook operation as deprecated in the document. */
     deprecated?: boolean;
+    /** Request schemas (body, headers, ...) the producer sends. Same shape as route `request`. */
     request?: RequestSchemas;
+    /** Map of status code to response schema the consumer is expected to return. */
     responses: ResponsesMap;
+    /** Security requirement(s) documented on the webhook operation (e.g. a signature scheme). */
     auth?: AuthSpec;
     /**
      * Optional OpenAPI 3.1 callbacks attached to this webhook operation.
@@ -112,16 +121,13 @@ export interface OpenAPIOptions {
  */
 export declare function generateOpenAPI(app: App, options: OpenAPIOptions): Record<string, unknown>;
 /**
- * Serialize an OpenAPI document (or any JSON-safe object) as YAML 1.2.
- *
- * Pure function with no runtime dependency. Output is the canonical form
- * consumed by Swagger UI's `/swagger.yaml` style endpoints.
+ * Serialize an OpenAPI document (from {@link generateOpenAPI}) — or any
+ * JSON-safe object — to YAML 1.2 using a minimal built-in emitter. Pure
+ * transform with no runtime dependency; output is the form consumed by
+ * `/swagger.yaml`-style endpoints and build-time artifacts.
  *
+ * @param doc - JSON-safe object to serialize (typically the generated document).
+ * @returns The YAML text, without a leading newline.
  * @since 0.13.1
  */
-/**
- * Serialize an OpenAPI document (from {@link generateOpenAPI}) to YAML using a
- * minimal built-in emitter. No external dependencies; suitable for build-time
- * artifacts. Reads/writes nothing; pure transform.
- */
 export declare function openapiToYAML(doc: Record<string, unknown>): string;

package/dist/openapi.js

@@ -485,18 +485,15 @@ function yamlEmit(value, indent) {
     return ` ${yamlScalar(value)}\n`;
 }
 /**
- * Serialize an OpenAPI document (or any JSON-safe object) as YAML 1.2.
- *
- * Pure function with no runtime dependency. Output is the canonical form
- * consumed by Swagger UI's `/swagger.yaml` style endpoints.
+ * Serialize an OpenAPI document (from {@link generateOpenAPI}) — or any
+ * JSON-safe object — to YAML 1.2 using a minimal built-in emitter. Pure
+ * transform with no runtime dependency; output is the form consumed by
+ * `/swagger.yaml`-style endpoints and build-time artifacts.
  *
+ * @param doc - JSON-safe object to serialize (typically the generated document).
+ * @returns The YAML text, without a leading newline.
  * @since 0.13.1
  */
-/**
- * Serialize an OpenAPI document (from {@link generateOpenAPI}) to YAML using a
- * minimal built-in emitter. No external dependencies; suitable for build-time
- * artifacts. Reads/writes nothing; pure transform.
- */
 export function openapiToYAML(doc) {
     const result = yamlEmit(doc, "");
     return result.startsWith("\n") ? result.slice(1) : result;

package/dist/rate-limit-redis.d.ts

@@ -50,10 +50,12 @@ import type { RateLimitStore } from "./middleware.js";
  * required by the bundled script.
  */
 export interface RedisCommands {
+    /** Run a Lua script atomically with the given `KEYS` / `ARGV` and return the raw Redis reply. */
     eval(script: string, keys: string[], args: string[]): Promise<unknown>;
 }
 /** Options accepted by {@link redisRateLimitStore}. */
 export interface RedisRateLimitStoreOptions {
+    /** Redis transport (see {@link ioredisAdapter} / {@link nodeRedisAdapter} for common clients). */
     client: RedisCommands;
     /**
      * Optional namespace prefix for every Redis key. Defaults to `"daloy:rl:"`.
@@ -83,6 +85,11 @@ export interface RedisRateLimitStoreOptions {
  * abuse-sensitive limiters in front of auth, password-reset, or other
  * credential endpoints, pass `onError: () => "fail-closed"` so a Redis
  * outage rejects rather than silently disables the limit.
+ *
+ * @param opts - Redis client, key prefix, and error policy; see
+ *   {@link RedisRateLimitStoreOptions}.
+ * @returns A {@link RateLimitStore} whose `hit()` atomically increments the
+ *   windowed counter in Redis and reports `{ count, resetMs }`.
  */
 export declare function redisRateLimitStore(opts: RedisRateLimitStoreOptions): RateLimitStore;
 /**
@@ -90,19 +97,31 @@ export declare function redisRateLimitStore(opts: RedisRateLimitStoreOptions): R
  * takes `(script, numKeys, ...keysAndArgs)` is used.
  */
 export interface IoredisLike {
+    /** ioredis-style `EVAL`: script, number of keys, then keys and args flattened. */
     eval(script: string, numKeys: number, ...keysAndArgs: string[]): Promise<unknown>;
 }
-/** Wrap an [`ioredis`](https://github.com/redis/ioredis) client. */
+/**
+ * Wrap an [`ioredis`](https://github.com/redis/ioredis) client.
+ *
+ * @param client - Connected ioredis instance (only its `eval` is used).
+ * @returns A {@link RedisCommands} transport for {@link redisRateLimitStore}.
+ */
 export declare function ioredisAdapter(client: IoredisLike): RedisCommands;
 /**
  * Shape of a `node-redis` v4+ client we care about. The v4 `eval` takes an
  * options object instead of variadic arguments.
  */
 export interface NodeRedisLike {
+    /** node-redis v4+ `EVAL`: script plus a `{ keys, arguments }` options object. */
     eval(script: string, options: {
         keys: string[];
         arguments: string[];
     }): Promise<unknown>;
 }
-/** Wrap a [`node-redis`](https://github.com/redis/node-redis) v4+ client. */
+/**
+ * Wrap a [`node-redis`](https://github.com/redis/node-redis) v4+ client.
+ *
+ * @param client - Connected node-redis v4+ instance (only its `eval` is used).
+ * @returns A {@link RedisCommands} transport for {@link redisRateLimitStore}.
+ */
 export declare function nodeRedisAdapter(client: NodeRedisLike): RedisCommands;

package/dist/rate-limit-redis.js

@@ -84,6 +84,11 @@ function toNumber(value) {
  * abuse-sensitive limiters in front of auth, password-reset, or other
  * credential endpoints, pass `onError: () => "fail-closed"` so a Redis
  * outage rejects rather than silently disables the limit.
+ *
+ * @param opts - Redis client, key prefix, and error policy; see
+ *   {@link RedisRateLimitStoreOptions}.
+ * @returns A {@link RateLimitStore} whose `hit()` atomically increments the
+ *   windowed counter in Redis and reports `{ count, resetMs }`.
  */
 export function redisRateLimitStore(opts) {
     const prefix = opts.prefix ?? "daloy:rl:";
@@ -106,7 +111,12 @@ export function redisRateLimitStore(opts) {
         },
     };
 }
-/** Wrap an [`ioredis`](https://github.com/redis/ioredis) client. */
+/**
+ * Wrap an [`ioredis`](https://github.com/redis/ioredis) client.
+ *
+ * @param client - Connected ioredis instance (only its `eval` is used).
+ * @returns A {@link RedisCommands} transport for {@link redisRateLimitStore}.
+ */
 export function ioredisAdapter(client) {
     return {
         eval(script, keys, args) {
@@ -114,7 +124,12 @@ export function ioredisAdapter(client) {
         },
     };
 }
-/** Wrap a [`node-redis`](https://github.com/redis/node-redis) v4+ client. */
+/**
+ * Wrap a [`node-redis`](https://github.com/redis/node-redis) v4+ client.
+ *
+ * @param client - Connected node-redis v4+ instance (only its `eval` is used).
+ * @returns A {@link RedisCommands} transport for {@link redisRateLimitStore}.
+ */
 export function nodeRedisAdapter(client) {
     return {
         eval(script, keys, args) {

package/dist/safe-redirect.d.ts

@@ -47,7 +47,9 @@
 export type SafeRedirectBlockReason = "empty-target" | "invalid-control-characters" | "protocol-relative" | "backslash-path" | "path-not-allowed" | "origin-not-allowed" | "scheme-not-allowed" | "parse-failed";
 /** Thrown when {@link safeRedirect} refuses a candidate URL and no `fallback` is configured. */
 export declare class OpenRedirectBlockedError extends Error {
+    /** Machine-readable {@link SafeRedirectBlockReason} explaining the refusal. */
     readonly reason: SafeRedirectBlockReason;
+    /** The candidate URL that was refused, verbatim. */
     readonly target: string;
     constructor(reason: SafeRedirectBlockReason, target: string);
 }
@@ -88,6 +90,10 @@ export interface SafeRedirectOptions {
  *
  * @param target - User-supplied URL candidate (path or absolute URL).
  * @param options - Allowlist + response configuration.
+ * @returns A redirect `Response` (default `303`) with `Location` set to the
+ *   validated target (or the `fallback`) and `Cache-Control: no-store`.
+ * @throws {TypeError} for a non-redirect `status` or malformed
+ *   `allowedPaths` / `allowedOrigins` / `fallback` entries.
  *
  * @since 0.35.0
  */

package/dist/safe-redirect.js

@@ -45,7 +45,9 @@
  */
 /** Thrown when {@link safeRedirect} refuses a candidate URL and no `fallback` is configured. */
 export class OpenRedirectBlockedError extends Error {
+    /** Machine-readable {@link SafeRedirectBlockReason} explaining the refusal. */
     reason;
+    /** The candidate URL that was refused, verbatim. */
     target;
     constructor(reason, target) {
         super(`safeRedirect: refused redirect (${reason})`);
@@ -148,6 +150,10 @@ function hasEncodedProtocolRelativePrefix(value) {
  *
  * @param target - User-supplied URL candidate (path or absolute URL).
  * @param options - Allowlist + response configuration.
+ * @returns A redirect `Response` (default `303`) with `Location` set to the
+ *   validated target (or the `fallback`) and `Cache-Control: no-store`.
+ * @throws {TypeError} for a non-redirect `status` or malformed
+ *   `allowedPaths` / `allowedOrigins` / `fallback` entries.
  *
  * @since 0.35.0
  */