@schmock/core 2.4.1 → 2.5.0

package/dist/constants.d.ts

@@ -9,6 +9,10 @@ export declare function markResponseException<T extends ResponseLike>(response:
 export declare function getResponseException(response: ResponseLike): Error | undefined;
 export declare const HTTP_METHODS: readonly HttpMethod[];
 export declare function isHttpMethod(method: string): method is HttpMethod;
+/**
+ * Uppercase `method` and narrow it to an {@link HttpMethod}.
+ * @throws InvalidHttpMethodError (code `INVALID_HTTP_METHOD`) for any other verb
+ */
 export declare function toHttpMethod(method: string): HttpMethod;
 export declare function normalizePath(path: string): string;
 /**
@@ -25,6 +29,28 @@ export declare function normalizePath(path: string): string;
  * spelling is preferable to silently rewriting the caller's path.
  */
 export declare function canonicalizePath(path: string): string;
+/**
+ * Parse a `baseUrl` or namespace into its origin and canonical path prefix.
+ *
+ * - "/api/"                → { origin: null, path: "/api" }
+ * - "api"                  → { origin: null, path: "/api" }
+ * - "https://x.com/api/v1" → { origin: "https://x.com", path: "/api/v1" }
+ * - "https://x.com"        → { origin: "https://x.com", path: "" }
+ *
+ * The path is canonicalized like request paths are (so "/café" and
+ * "/caf%C3%A9" are one prefix), gains a leading slash when it has none, and
+ * loses one trailing slash. A value containing "://" that is not a valid URL
+ * is read as a path.
+ */
+export declare function parsePathPrefix(prefix: string): Schmock.PathPrefix;
+/**
+ * Whether `path` lies under the prefix, on a segment boundary: "/api" matches
+ * "/api" and "/api/users" but never "/apiv2". `path` is canonicalized first,
+ * so a raw or an encoded spelling of the same path match alike. Only the path
+ * is compared; checking `prefix.origin` against the request's origin is the
+ * caller's job.
+ */
+export declare function matchPathPrefix(prefix: Schmock.PathPrefix, path: string): boolean;
 /**
  * Decode a single captured path parameter.
  *
@@ -54,11 +80,16 @@ export declare function isRouteNotFound(response: {
  * Check if a value is a status tuple: [status, body] or [status, body, headers]
  * Guards against misinterpreting numeric arrays like [1, 2, 3] as tuples.
  *
+ * Only the length and the status are checked, so the third element is typed
+ * `unknown`: a caller that reads it as headers must check it is a string
+ * record first (core's response parser rejects anything else with
+ * INVALID_RESPONSE). Rejecting such a tuple here instead would make the parser
+ * treat `[200, "x", null]` as plain array data and answer 200.
+ *
  * Known ambiguity: a length-2 numeric array whose first element happens to
  * be in the HTTP-status range (e.g. [200, 300] as legitimate data) is
  * indistinguishable from a status tuple by shape alone. Prefer the explicit
  * status() helper or return an object response when the data could collide.
  */
-export declare function isStatusTuple(value: unknown): value is [number, unknown] | [number, unknown, Record<string, string>];
+export declare function isStatusTuple(value: unknown): value is [number, unknown] | [number, unknown, unknown];
 export {};
-//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -1,3 +1,4 @@
+import { InvalidHttpMethodError } from "./errors.js";
 export const ROUTE_NOT_FOUND_CODE = "ROUTE_NOT_FOUND";
 const RESPONSE_ORIGIN = Symbol.for("@schmock/core.response-origin");
 function setResponseOrigin(response, origin) {
@@ -44,10 +45,14 @@ export const HTTP_METHODS = [
 export function isHttpMethod(method) {
     return HTTP_METHODS.includes(method);
 }
+/**
+ * Uppercase `method` and narrow it to an {@link HttpMethod}.
+ * @throws InvalidHttpMethodError (code `INVALID_HTTP_METHOD`) for any other verb
+ */
 export function toHttpMethod(method) {
     const upper = method.toUpperCase();
     if (!isHttpMethod(upper)) {
-        throw new Error(`Invalid HTTP method: "${method}"`);
+        throw new InvalidHttpMethodError(method);
     }
     return upper;
 }
@@ -72,6 +77,13 @@ const PATH_ENCODED_ASCII = new Set([
     "}",
 ]);
 const PERCENT_TRIPLET = /^%[0-9A-Fa-f]{2}$/;
+/**
+ * Paths made only of characters the loop below copies unchanged: printable
+ * ASCII minus {@link PATH_ENCODED_ASCII} and minus `%`, which always takes the
+ * loop so a lowercase triplet is still uppercased. `&-;` starts after `%`
+ * (0x25) on purpose.
+ */
+const ALREADY_CANONICAL_PATH = /^[!$&-;=@-\]_a-z|~]*$/;
 /** UTF-8 for U+FFFD, the URL parser's substitute for a lone surrogate. */
 const ENCODED_REPLACEMENT_CHARACTER = "%EF%BF%BD";
 /**
@@ -88,6 +100,10 @@ const ENCODED_REPLACEMENT_CHARACTER = "%EF%BF%BD";
  * spelling is preferable to silently rewriting the caller's path.
  */
 export function canonicalizePath(path) {
+    // Fast path for the common case, which runs on every request: nothing to
+    // encode and no percent triplet to uppercase.
+    if (ALREADY_CANONICAL_PATH.test(path))
+        return path;
     let result = "";
     for (let index = 0; index < path.length;) {
         if (path[index] === "%" &&
@@ -115,6 +131,56 @@ export function canonicalizePath(path) {
     }
     return result;
 }
+/**
+ * The one trailing-slash rule for a path prefix: a single trailing slash is
+ * dropped, so "/api/" and "/api" are the same prefix, and the root "/" becomes
+ * "" (matches every path).
+ */
+function trimPrefixPath(canonicalPath) {
+    return canonicalPath === "/" ? "" : canonicalPath.replace(/\/$/, "");
+}
+/**
+ * Parse a `baseUrl` or namespace into its origin and canonical path prefix.
+ *
+ * - "/api/"                → { origin: null, path: "/api" }
+ * - "api"                  → { origin: null, path: "/api" }
+ * - "https://x.com/api/v1" → { origin: "https://x.com", path: "/api/v1" }
+ * - "https://x.com"        → { origin: "https://x.com", path: "" }
+ *
+ * The path is canonicalized like request paths are (so "/café" and
+ * "/caf%C3%A9" are one prefix), gains a leading slash when it has none, and
+ * loses one trailing slash. A value containing "://" that is not a valid URL
+ * is read as a path.
+ */
+export function parsePathPrefix(prefix) {
+    if (prefix.includes("://")) {
+        try {
+            const url = new URL(prefix);
+            return {
+                origin: url.origin,
+                path: trimPrefixPath(canonicalizePath(url.pathname)),
+            };
+        }
+        catch {
+            // Not a URL after all: read it as a path below.
+        }
+    }
+    const rooted = prefix.startsWith("/") ? prefix : `/${prefix}`;
+    return { origin: null, path: trimPrefixPath(canonicalizePath(rooted)) };
+}
+/**
+ * Whether `path` lies under the prefix, on a segment boundary: "/api" matches
+ * "/api" and "/api/users" but never "/apiv2". `path` is canonicalized first,
+ * so a raw or an encoded spelling of the same path match alike. Only the path
+ * is compared; checking `prefix.origin` against the request's origin is the
+ * caller's job.
+ */
+export function matchPathPrefix(prefix, path) {
+    if (prefix.path === "")
+        return true;
+    const canonicalPath = canonicalizePath(path);
+    return (canonicalPath === prefix.path || canonicalPath.startsWith(`${prefix.path}/`));
+}
 /**
  * Decode a single captured path parameter.
  *
@@ -162,6 +228,12 @@ export function isRouteNotFound(response) {
  * Check if a value is a status tuple: [status, body] or [status, body, headers]
  * Guards against misinterpreting numeric arrays like [1, 2, 3] as tuples.
  *
+ * Only the length and the status are checked, so the third element is typed
+ * `unknown`: a caller that reads it as headers must check it is a string
+ * record first (core's response parser rejects anything else with
+ * INVALID_RESPONSE). Rejecting such a tuple here instead would make the parser
+ * treat `[200, "x", null]` as plain array data and answer 200.
+ *
  * Known ambiguity: a length-2 numeric array whose first element happens to
  * be in the HTTP-status range (e.g. [200, 300] as legitimate data) is
  * indistinguishable from a status tuple by shape alone. Prefer the explicit

package/dist/debug-logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Debug logger that respects debug mode configuration
+ */
+export declare class DebugLogger {
+    private enabled;
+    constructor(enabled?: boolean);
+    log(category: string, message: string, data?: unknown): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+}

package/dist/debug-logger.js

@@ -0,0 +1,31 @@
+/**
+ * Debug logger that respects debug mode configuration
+ */
+export class DebugLogger {
+    enabled;
+    constructor(enabled = false) {
+        this.enabled = enabled;
+    }
+    log(category, message, data) {
+        if (!this.enabled)
+            return;
+        const timestamp = new Date().toISOString();
+        const prefix = `[${timestamp}] [SCHMOCK:${category.toUpperCase()}]`;
+        if (data) {
+            console.log(`${prefix} ${message}`, data);
+        }
+        else {
+            console.log(`${prefix} ${message}`);
+        }
+    }
+    time(label) {
+        if (!this.enabled)
+            return;
+        console.time(`[SCHMOCK] ${label}`);
+    }
+    timeEnd(label) {
+        if (!this.enabled)
+            return;
+        console.timeEnd(`[SCHMOCK] ${label}`);
+    }
+}

package/dist/delay.d.ts

@@ -0,0 +1,12 @@
+type ResponseDelay = number | [number, number];
+/**
+ * Apply configured response delay: the route's own when set, the mock's
+ * otherwise. Supports both fixed delays and random delays within a range. An
+ * abort ends the wait with the signal's reason.
+ */
+export declare function applyResponseDelay(input: {
+    routeDelay?: ResponseDelay;
+    globalDelay?: ResponseDelay;
+    signal?: AbortSignal;
+}): Promise<void>;
+export {};

package/dist/delay.js

@@ -0,0 +1,37 @@
+import { throwIfAborted } from "./abort.js";
+/**
+ * Apply configured response delay: the route's own when set, the mock's
+ * otherwise. Supports both fixed delays and random delays within a range. An
+ * abort ends the wait with the signal's reason.
+ */
+export async function applyResponseDelay(input) {
+    const { signal } = input;
+    const effectiveDelay = input.routeDelay ?? input.globalDelay;
+    if (!effectiveDelay) {
+        throwIfAborted(signal);
+        return;
+    }
+    const configuredMs = Array.isArray(effectiveDelay)
+        ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
+            effectiveDelay[0]
+        : effectiveDelay;
+    const ms = Math.max(0, configuredMs);
+    throwIfAborted(signal);
+    await new Promise((resolve, reject) => {
+        const finish = () => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        };
+        const abort = () => {
+            clearTimeout(timer);
+            try {
+                throwIfAborted(signal);
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}

package/dist/errors.d.ts

@@ -42,6 +42,14 @@ export declare class InvalidResponseError extends SchmockError {
 export declare class PluginError extends SchmockError {
     constructor(pluginName: string, error: Error);
 }
+/**
+ * Error thrown by `toHttpMethod` for a string that is not one of the HTTP
+ * methods Schmock routes (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`,
+ * `OPTIONS`), compared case-insensitively.
+ */
+export declare class InvalidHttpMethodError extends SchmockError {
+    constructor(method: string);
+}
 /**
  * Error thrown when route definition is invalid
  */
@@ -62,8 +70,11 @@ export declare class SchemaGenerationError extends SchmockError {
 }
 /**
  * Error thrown when resource limits are exceeded
+ *
+ * @param path - Optional location of the breach (for example the schema path
+ *   `$.properties.items`). When given it is appended to the message and added
+ *   to the context; without it both keep their original shape.
  */
 export declare class ResourceLimitError extends SchmockError {
-    constructor(resource: string, limit: number, actual?: number);
+    constructor(resource: string, limit: number, actual?: number, path?: string);
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -94,6 +94,19 @@ export class PluginError extends SchmockError {
         this.name = "PluginError";
     }
 }
+/**
+ * Error thrown by `toHttpMethod` for a string that is not one of the HTTP
+ * methods Schmock routes (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`,
+ * `OPTIONS`), compared case-insensitively.
+ */
+export class InvalidHttpMethodError extends SchmockError {
+    constructor(method) {
+        super(`Invalid HTTP method: "${method}"`, "INVALID_HTTP_METHOD", {
+            method,
+        });
+        this.name = "InvalidHttpMethodError";
+    }
+}
 /**
  * Error thrown when route definition is invalid
  */
@@ -123,10 +136,16 @@ export class SchemaGenerationError extends SchmockError {
 }
 /**
  * Error thrown when resource limits are exceeded
+ *
+ * @param path - Optional location of the breach (for example the schema path
+ *   `$.properties.items`). When given it is appended to the message and added
+ *   to the context; without it both keep their original shape.
  */
 export class ResourceLimitError extends SchmockError {
-    constructor(resource, limit, actual) {
-        super(`Resource limit exceeded for ${resource}: limit=${limit}${actual ? `, actual=${actual}` : ""}`, "RESOURCE_LIMIT_ERROR", { resource, limit, actual });
+    constructor(resource, limit, actual, path) {
+        super(`Resource limit exceeded for ${resource}: limit=${limit}${actual ? `, actual=${actual}` : ""}${path === undefined ? "" : ` at ${path}`}`, "RESOURCE_LIMIT_ERROR", path === undefined
+            ? { resource, limit, actual }
+            : { resource, limit, actual, path });
         this.name = "ResourceLimitError";
     }
 }

package/dist/events.d.ts

@@ -0,0 +1,17 @@
+import type { DebugLogger } from "./debug-logger.js";
+/**
+ * The mock's lifecycle event listeners.
+ *
+ * Every listener receives one frozen snapshot of the event, so a listener
+ * cannot edit what the next one (or the request) sees. A listener that throws
+ * or rejects is logged and never reaches the request.
+ */
+export declare class MockEvents {
+    #private;
+    constructor(logger: DebugLogger);
+    on<E extends Schmock.SchmockEvent>(event: E, listener: (data: Schmock.SchmockEventMap[E]) => void): void;
+    off<E extends Schmock.SchmockEvent>(event: E, listener: (data: Schmock.SchmockEventMap[E]) => void): void;
+    emit<E extends Schmock.SchmockEvent>(event: E, data: Schmock.SchmockEventMap[E]): void;
+    /** Remove every listener. */
+    clear(): void;
+}

package/dist/events.js

@@ -0,0 +1,58 @@
+import { errorMessage } from "./errors.js";
+import { isThenable } from "./plugin-hooks.js";
+/**
+ * The mock's lifecycle event listeners.
+ *
+ * Every listener receives one frozen snapshot of the event, so a listener
+ * cannot edit what the next one (or the request) sees. A listener that throws
+ * or rejects is logged and never reaches the request.
+ */
+export class MockEvents {
+    // biome-ignore lint/complexity/noBannedTypes: internal storage for event listeners with varying signatures
+    #listeners = new Map();
+    #logger;
+    constructor(logger) {
+        this.#logger = logger;
+    }
+    on(event, listener) {
+        let set = this.#listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.#listeners.set(event, set);
+        }
+        set.add(listener);
+    }
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+    }
+    emit(event, data) {
+        const set = this.#listeners.get(event);
+        if (!set)
+            return;
+        const snapshot = { ...data };
+        if ("headers" in data) {
+            snapshot.headers = Object.freeze({ ...data.headers });
+        }
+        if ("params" in data) {
+            snapshot.params = Object.freeze({ ...data.params });
+        }
+        const eventData = Object.freeze(snapshot);
+        for (const listener of [...set]) {
+            try {
+                const listenerResult = listener(eventData);
+                if (isThenable(listenerResult)) {
+                    void Promise.resolve(listenerResult).catch((error) => {
+                        this.#logger.log("event", `${event} listener rejected: ${errorMessage(error)}`);
+                    });
+                }
+            }
+            catch (error) {
+                this.#logger.log("event", `${event} listener failed: ${errorMessage(error)}`);
+            }
+        }
+    }
+    /** Remove every listener. */
+    clear() {
+        this.#listeners.clear();
+    }
+}

package/dist/generations.d.ts

@@ -0,0 +1,43 @@
+/** One period of the mock between two resets. */
+export interface RequestGeneration {
+    activeAdmissions: number;
+    /** Set once retired: the plugins it still owes an uninstall. */
+    retiredPlugins?: readonly Schmock.Plugin[];
+}
+type Uninstall = (plugins: readonly Schmock.Plugin[]) => void;
+/**
+ * The mock's request generations. `reset()` retires the current one, but the
+ * plugins it had installed are uninstalled only once its last in-flight
+ * request settles, so no admitted request loses its plugins mid-flight.
+ */
+export declare class RequestGenerations {
+    #private;
+    constructor(uninstall: Uninstall);
+    /**
+     * Whether a request's generation is still the live one. Only its requests
+     * emit lifecycle events and record history.
+     */
+    isCurrent(generation: RequestGeneration): boolean;
+    /** Count one more in-flight request in the current generation. */
+    admit(): RequestGeneration;
+    /**
+     * Count a request out. The last one out of a retired generation runs the
+     * uninstall that generation owes.
+     */
+    release(generation: RequestGeneration): void;
+    /** Start a new generation; the previous one is returned for `retire()`. */
+    advance(): RequestGeneration;
+    /**
+     * Retire a generation that owes `plugins` an uninstall: at once when no
+     * request of it is in flight, otherwise when its last request settles.
+     */
+    retire(generation: RequestGeneration, plugins: readonly Schmock.Plugin[]): void;
+    /**
+     * Run the uninstall a retired generation still owes this plugin object, now,
+     * before it is installed again. Left to the retired generation, it would run
+     * when that generation's last request settles — after the new install() —
+     * and tear down the live installation.
+     */
+    uninstallBeforeReinstall(plugin: Schmock.Plugin): void;
+}
+export {};

package/dist/generations.js

@@ -0,0 +1,75 @@
+/**
+ * The mock's request generations. `reset()` retires the current one, but the
+ * plugins it had installed are uninstalled only once its last in-flight
+ * request settles, so no admitted request loses its plugins mid-flight.
+ */
+export class RequestGenerations {
+    #current = { activeAdmissions: 0 };
+    /** Retired generations whose uninstall waits for in-flight requests. */
+    #retired = new Set();
+    #uninstall;
+    constructor(uninstall) {
+        this.#uninstall = uninstall;
+    }
+    /**
+     * Whether a request's generation is still the live one. Only its requests
+     * emit lifecycle events and record history.
+     */
+    isCurrent(generation) {
+        return generation === this.#current;
+    }
+    /** Count one more in-flight request in the current generation. */
+    admit() {
+        const generation = this.#current;
+        generation.activeAdmissions += 1;
+        return generation;
+    }
+    /**
+     * Count a request out. The last one out of a retired generation runs the
+     * uninstall that generation owes.
+     */
+    release(generation) {
+        generation.activeAdmissions -= 1;
+        if (generation.activeAdmissions === 0 &&
+            generation.retiredPlugins !== undefined) {
+            const plugins = generation.retiredPlugins;
+            generation.retiredPlugins = undefined;
+            this.#retired.delete(generation);
+            this.#uninstall(plugins);
+        }
+    }
+    /** Start a new generation; the previous one is returned for `retire()`. */
+    advance() {
+        const previous = this.#current;
+        this.#current = { activeAdmissions: 0 };
+        return previous;
+    }
+    /**
+     * Retire a generation that owes `plugins` an uninstall: at once when no
+     * request of it is in flight, otherwise when its last request settles.
+     */
+    retire(generation, plugins) {
+        generation.retiredPlugins = plugins;
+        if (generation.activeAdmissions === 0) {
+            generation.retiredPlugins = undefined;
+            this.#uninstall(plugins);
+            return;
+        }
+        this.#retired.add(generation);
+    }
+    /**
+     * Run the uninstall a retired generation still owes this plugin object, now,
+     * before it is installed again. Left to the retired generation, it would run
+     * when that generation's last request settles — after the new install() —
+     * and tear down the live installation.
+     */
+    uninstallBeforeReinstall(plugin) {
+        for (const generation of this.#retired) {
+            const pending = generation.retiredPlugins;
+            if (!pending?.includes(plugin))
+                continue;
+            generation.retiredPlugins = pending.filter((retired) => retired !== plugin);
+            this.#uninstall([plugin]);
+        }
+    }
+}

package/dist/headers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Header names whose value is a credential, in lowercase. Debug logs replace
+ * their values with "[redacted]" (see {@link redactHeaders}) and keep the name,
+ * so a log still shows the header was sent. The CLI's admin history masks the
+ * same set.
+ */
+export declare const SENSITIVE_HEADER_NAMES: ReadonlySet<string>;
+/**
+ * Look a header up by name, ignoring case. Response headers keep the casing a
+ * route gave them, so `headers["content-type"]` can miss a `Content-Type`.
+ * @returns the first matching value, or `undefined`
+ */
+export declare function getHeader(headers: Readonly<Record<string, string>> | undefined, name: string): string | undefined;
+/**
+ * Whether a header of that name is present, ignoring case, whatever its value.
+ * Unlike `getHeader(...) !== undefined`, a key present with a non-string value
+ * counts, so the response normalizer still gets to reject that value.
+ */
+export declare function hasHeader(headers: Readonly<Record<string, unknown>>, name: string): boolean;
+/**
+ * Replace the value of every {@link SENSITIVE_HEADER_NAMES} header with
+ * "[redacted]", matching names case-insensitively.
+ *
+ * Copy-on-write: the input is never mutated, and when nothing is sensitive the
+ * same object is returned.
+ */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;

package/dist/headers.js

@@ -0,0 +1,57 @@
+/**
+ * Header names whose value is a credential, in lowercase. Debug logs replace
+ * their values with "[redacted]" (see {@link redactHeaders}) and keep the name,
+ * so a log still shows the header was sent. The CLI's admin history masks the
+ * same set.
+ */
+export const SENSITIVE_HEADER_NAMES = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-schmock-admin-token",
+]);
+const REDACTED_HEADER_VALUE = "[redacted]";
+/**
+ * Look a header up by name, ignoring case. Response headers keep the casing a
+ * route gave them, so `headers["content-type"]` can miss a `Content-Type`.
+ * @returns the first matching value, or `undefined`
+ */
+export function getHeader(headers, name) {
+    if (headers === undefined)
+        return undefined;
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted)
+            return headers[key];
+    }
+    return undefined;
+}
+/**
+ * Whether a header of that name is present, ignoring case, whatever its value.
+ * Unlike `getHeader(...) !== undefined`, a key present with a non-string value
+ * counts, so the response normalizer still gets to reject that value.
+ */
+export function hasHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === wanted);
+}
+/**
+ * Replace the value of every {@link SENSITIVE_HEADER_NAMES} header with
+ * "[redacted]", matching names case-insensitively.
+ *
+ * Copy-on-write: the input is never mutated, and when nothing is sensitive the
+ * same object is returned.
+ */
+export function redactHeaders(headers) {
+    let redacted;
+    for (const name of Object.keys(headers)) {
+        if (!SENSITIVE_HEADER_NAMES.has(name.toLowerCase()))
+            continue;
+        redacted ??= { ...headers };
+        redacted[name] = REDACTED_HEADER_VALUE;
+    }
+    return redacted ?? headers;
+}

package/dist/helpers.d.ts

@@ -1,10 +1,10 @@
-export declare function notFound(message?: string | object): [number, object];
-export declare function badRequest(message?: string | object): [number, object];
-export declare function unauthorized(message?: string | object): [number, object];
-export declare function forbidden(message?: string | object): [number, object];
-export declare function serverError(message?: string | object): [number, object];
-export declare function created(body: object): [number, object];
-export declare function noContent(): [number, null];
+export declare function notFound(message?: string | object): [404, object];
+export declare function badRequest(message?: string | object): [400, object];
+export declare function unauthorized(message?: string | object): [401, object];
+export declare function forbidden(message?: string | object): [403, object];
+export declare function serverError(message?: string | object): [500, object];
+export declare function created(body: object): [201, object];
+export declare function noContent(): [204, null];
 /**
  * Slice `items` into a page envelope.
  *
@@ -12,7 +12,6 @@ export declare function noContent(): [number, null];
  * page 1 and a page size of 10) so a fractional, negative, NaN or infinite
  * option can never produce a nonsensical slice or a negative `totalPages`. The
  * returned envelope always echoes the NORMALIZED values, so it is internally
- * consistent with `data`.
+ * consistent with `data`. `items` is only read, so a readonly array is fine.
  */
-export declare function paginate<T>(items: T[], options?: Schmock.PaginateOptions): Schmock.PaginatedResponse<T>;
-//# sourceMappingURL=helpers.d.ts.map
+export declare function paginate<T>(items: readonly T[], options?: Schmock.PaginateOptions): Schmock.PaginatedResponse<T>;

package/dist/helpers.js

@@ -1,4 +1,7 @@
 /// <reference path="../schmock.d.ts" />
+// Each helper returns its literal status (`[404, object]`, not
+// `[number, object]`), as docs/api.md documents: a literal tuple is still
+// assignable to `[number, object]`, and callers can destructure a typed status.
 export function notFound(message = "Not Found") {
     const body = typeof message === "string" ? { message } : message;
     return [404, body];
@@ -39,7 +42,7 @@ function positiveInteger(value, fallback) {
  * page 1 and a page size of 10) so a fractional, negative, NaN or infinite
  * option can never produce a nonsensical slice or a negative `totalPages`. The
  * returned envelope always echoes the NORMALIZED values, so it is internally
- * consistent with `data`.
+ * consistent with `data`. `items` is only read, so a readonly array is fine.
  */
 export function paginate(items, options = {}) {
     const page = positiveInteger(options.page, 1);