@schmock/core 2.4.1 → 2.6.0

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

package/dist/history.d.ts

@@ -0,0 +1,56 @@
+/** What history records about the request, captured before any hook runs. */
+export interface RequestHistorySnapshot {
+    readonly query: Record<string, string>;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+}
+/** A matched request as it is committed to history. */
+interface RequestHistoryEntry {
+    /** The history generation the request was admitted under. */
+    readonly generation: symbol;
+    readonly method: Schmock.HttpMethod;
+    /** The namespace-stripped, normalized path the route matched. */
+    readonly path: string;
+    readonly params: Record<string, string>;
+    readonly snapshot: RequestHistorySnapshot;
+    readonly response: Schmock.Response;
+}
+/**
+ * The mock's request log and its spy API.
+ *
+ * Every read returns deep copies, so a caller can never corrupt the records.
+ * A request is recorded only under the history generation it was admitted
+ * with: `startGeneration()` ends the current one, so a request still in
+ * flight when history is reset cannot write into the new log.
+ */
+export declare class RequestHistory {
+    #private;
+    /**
+     * @param limit `maxHistorySize`: FIFO bound on the number of records,
+     *   `0` disables history, `undefined` keeps every record.
+     * @throws SchmockError `INVALID_CONFIG` when the limit is not a
+     *   non-negative integer.
+     */
+    constructor(limit: number | undefined);
+    /** The token an admitted request captures and records under. */
+    get generation(): symbol;
+    /**
+     * Copy what the CLIENT sent, before any plugin or the generator gets the
+     * live objects and can edit them. `undefined` when history is disabled.
+     */
+    snapshotRequest(request: RequestHistorySnapshot): RequestHistorySnapshot | undefined;
+    /** Record a matched request, unless its history generation has ended. */
+    record(entry: RequestHistoryEntry): void;
+    /**
+     * Start a new generation: a request admitted before it can no longer
+     * record. The records themselves stay until `clear()`.
+     */
+    startGeneration(): void;
+    /** Drop every record. */
+    clear(): void;
+    history(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord[];
+    called(method?: Schmock.HttpMethod, path?: string): boolean;
+    callCount(method?: Schmock.HttpMethod, path?: string): number;
+    lastRequest(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord | undefined;
+}
+export {};

package/dist/history.js

@@ -0,0 +1,151 @@
+import { canonicalizePath, normalizePath } from "./constants.js";
+import { SchmockError } from "./errors.js";
+import { snapshotNormalizedBody, snapshotValue } from "./snapshot.js";
+/**
+ * Reject a history limit that cannot bound anything.
+ *
+ * A negative limit used to read as "unbounded" and a fractional one evicted a
+ * fractional number of records, so a typo silently disabled the cap instead of
+ * failing. `Number.isInteger` also rejects NaN and Infinity. `0` stays valid
+ * and keeps meaning "history disabled".
+ */
+function assertValidHistoryLimit(limit) {
+    if (limit === undefined)
+        return;
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new SchmockError(`Invalid maxHistorySize: ${String(limit)}. Expected a non-negative integer (0 disables history).`, "INVALID_CONFIG", { maxHistorySize: limit });
+    }
+}
+function cloneRecord(r) {
+    return {
+        method: r.method,
+        path: r.path,
+        params: { ...r.params },
+        query: { ...r.query },
+        headers: { ...r.headers },
+        body: snapshotValue(r.body),
+        timestamp: r.timestamp,
+        response: {
+            status: r.response.status,
+            body: snapshotNormalizedBody(r.response.body),
+        },
+    };
+}
+/**
+ * History stores the canonical request path — percent-encoded and
+ * trailing-slash-normalized exactly as `handle()` produced it — so a spy
+ * filter must be put into the same form before it is compared, or the very
+ * string the caller passed to `handle()` would not match its own record.
+ * `canonicalizePath` is idempotent, so an already-encoded filter keeps
+ * matching and both spellings work.
+ */
+function historyMatcher(method, path) {
+    const wanted = path === undefined ? undefined : normalizePath(canonicalizePath(path));
+    return (r) => (!method || r.method === method) && (!wanted || r.path === wanted);
+}
+/**
+ * The mock's request log and its spy API.
+ *
+ * Every read returns deep copies, so a caller can never corrupt the records.
+ * A request is recorded only under the history generation it was admitted
+ * with: `startGeneration()` ends the current one, so a request still in
+ * flight when history is reset cannot write into the new log.
+ */
+export class RequestHistory {
+    #records = [];
+    #generation = Symbol("schmock.history.generation");
+    #limit;
+    /**
+     * @param limit `maxHistorySize`: FIFO bound on the number of records,
+     *   `0` disables history, `undefined` keeps every record.
+     * @throws SchmockError `INVALID_CONFIG` when the limit is not a
+     *   non-negative integer.
+     */
+    constructor(limit) {
+        assertValidHistoryLimit(limit);
+        this.#limit = limit;
+    }
+    /** The token an admitted request captures and records under. */
+    get generation() {
+        return this.#generation;
+    }
+    /**
+     * Copy what the CLIENT sent, before any plugin or the generator gets the
+     * live objects and can edit them. `undefined` when history is disabled.
+     */
+    snapshotRequest(request) {
+        if (this.#limit === 0)
+            return undefined;
+        return {
+            query: { ...request.query },
+            headers: { ...request.headers },
+            body: snapshotValue(request.body),
+        };
+    }
+    /** Record a matched request, unless its history generation has ended. */
+    record(entry) {
+        if (entry.generation !== this.#generation || this.#limit === 0)
+            return;
+        const limit = this.#limit;
+        this.#records.push({
+            method: entry.method,
+            path: entry.path,
+            params: { ...entry.params },
+            query: entry.snapshot.query,
+            headers: entry.snapshot.headers,
+            body: entry.snapshot.body,
+            timestamp: Date.now(),
+            response: {
+                status: entry.response.status,
+                body: snapshotNormalizedBody(entry.response.body),
+            },
+        });
+        // The constructor already rejected a limit that is not a non-negative
+        // integer, so a plain comparison is enough here.
+        if (limit !== undefined && this.#records.length > limit) {
+            this.#records.splice(0, this.#records.length - limit);
+        }
+    }
+    /**
+     * Start a new generation: a request admitted before it can no longer
+     * record. The records themselves stay until `clear()`.
+     */
+    startGeneration() {
+        this.#generation = Symbol("schmock.history.generation");
+    }
+    /** Drop every record. */
+    clear() {
+        this.#records = [];
+    }
+    history(method, path) {
+        if (method || path) {
+            return this.#records
+                .filter(historyMatcher(method, path))
+                .map((r) => cloneRecord(r));
+        }
+        return this.#records.map((r) => cloneRecord(r));
+    }
+    called(method, path) {
+        if (method || path) {
+            return this.#records.some(historyMatcher(method, path));
+        }
+        return this.#records.length > 0;
+    }
+    callCount(method, path) {
+        if (method || path) {
+            return this.#records.filter(historyMatcher(method, path)).length;
+        }
+        return this.#records.length;
+    }
+    lastRequest(method, path) {
+        if (method || path) {
+            const filtered = this.#records.filter(historyMatcher(method, path));
+            const last = filtered[filtered.length - 1];
+            // FIX 2.3: return a deep clone so callers cannot corrupt internal history
+            return last ? cloneRecord(last) : undefined;
+        }
+        const last = this.#records[this.#records.length - 1];
+        // FIX 2.3: return a deep clone so callers cannot corrupt internal history
+        return last ? cloneRecord(last) : undefined;
+    }
+}

package/dist/http-helpers.d.ts

@@ -15,7 +15,7 @@ interface ResponseWritable {
     writeHead(status: number, headers: Record<string, string>): this;
     end(body?: string | Uint8Array): this;
 }
-export type HttpIngressErrorCode = "MALFORMED_JSON" | "PAYLOAD_TOO_LARGE";
+export type HttpIngressErrorCode = "MALFORMED_JSON" | "JSON_TOO_DEEP" | "MALFORMED_MULTIPART" | "PAYLOAD_TOO_LARGE";
 /** An HTTP client error raised while collecting an incoming request body. */
 export declare class HttpIngressError extends Error {
     readonly status: 400 | 413;
@@ -29,15 +29,20 @@ export declare class HttpIngressError extends Error {
 export declare function parseNodeHeaders(req: RequestWithHeaders): Record<string, string>;
 /**
  * Extract query parameters from a URL as a flat Record<string, string>.
+ * A repeated key resolves to its LAST value; every adapter follows this rule.
  */
 export declare function parseNodeQuery(url: URL): Record<string, string>;
+/** Default body size limit: 10 MB */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
 /**
  * Collect and parse the request body from a Node.js IncomingMessage.
- * Returns parsed JSON for application/json and +json media types, otherwise the
- * raw string.
+ * The body takes the shape the fetch interceptor gives it: parsed JSON for
+ * application/json and +json, an object for urlencoded forms, a string for
+ * text/*, FormData for multipart/*, and an ArrayBuffer for anything else.
  * Returns undefined for empty bodies.
  * @param req - Node.js IncomingMessage
- * @param headers - Parsed request headers
+ * @param headers - Parsed request headers; content-length and content-type
+ *   are looked up case-insensitively
  * @param maxBodySize - Maximum body size in bytes (default: 10 MB)
  */
 export declare function collectBody(req: BodyReadable, headers: Record<string, string>, maxBodySize?: number): Promise<unknown>;
@@ -68,5 +73,105 @@ export declare function writeSchmockResponse(res: ResponseWritable, response: Sc
  * request finishes, goes idle, or exhausts the grace cap.
  */
 export declare function writeRejectedSchmockResponse(req: RejectedRequestReadable, res: RejectedResponseWritable, response: Schmock.Response, extraHeaders?: Record<string, string>): void;
+/** The parts of a Node.js IncomingMessage `serveNodeRequest` uses. */
+type NodeRequest = RequestWithHeaders & BodyReadable & RejectedRequestReadable & {
+    readonly headers: {
+        readonly host?: string;
+    };
+    readonly method?: string;
+    readonly url?: string;
+    once(event: "aborted", listener: () => void): unknown;
+    off(event: "aborted", listener: () => void): unknown;
+};
+/** The parts of a Node.js ServerResponse `serveNodeRequest` uses. */
+type NodeResponse = RejectedResponseWritable & {
+    readonly headersSent: boolean;
+    shouldKeepAlive: boolean;
+    destroy(error?: Error): unknown;
+    off(event: "close", listener: () => void): unknown;
+};
+/**
+ * The request `serveNodeRequest` accepts: the parts of a Node.js
+ * IncomingMessage it uses. Structural, so a request typed by any `@types/node`
+ * copy fits.
+ */
+export type NodeRequestLike = NodeRequest;
+/**
+ * The response `serveNodeRequest` writes to: the parts of a Node.js
+ * ServerResponse it uses. Structural, so a response typed by any
+ * `@types/node` copy fits.
+ */
+export type NodeResponseLike = NodeResponse;
+/** What `serveNodeRequest` tells `extraHeaders` about the response it writes. */
+export interface ServeNodeResponseContext {
+    /**
+     * `true` for an error answer `serveNodeRequest` writes itself, `false` for
+     * the response `handle` produced.
+     */
+    readonly isError: boolean;
+    /** The request pathname, or `undefined` when the request did not parse. */
+    readonly path: string | undefined;
+}
+/**
+ * How `serveNodeRequest` answers a failed request. The body is the JSON
+ * `{ "error": message, "code": code }`.
+ */
+export interface HttpErrorReply {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    /** Headers the answer carries besides its content type (a 405's `allow`). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface ServeNodeRequestOptions {
+    /** Routes the parsed request: `mock.handle`, or a request admission's `handle`. */
+    readonly handle: Schmock.MockRequestHandler;
+    /**
+     * Largest request body accepted, in bytes. A larger one is answered 413 and
+     * the connection is closed. Defaults to 10 MB, the limit `mock.listen()`
+     * applies.
+     */
+    readonly maxBodySize?: number;
+    /**
+     * Answer a request from its verb and path alone, before its body is read.
+     * Return a response to send it as is (through `extraHeaders`, like any
+     * answer from `handle`), or `undefined` to read the body and call `handle`.
+     * A throw is answered like a `handle` failure.
+     *
+     * For answers that never depend on the body — a CORS preflight, an
+     * authorization refusal — so an oversized, malformed or stalled upload
+     * cannot delay or replace them.
+     */
+    readonly answerBeforeBody?: (method: Schmock.HttpMethod, path: string) => Schmock.Response | undefined;
+    /**
+     * Headers written over every response for this request (CORS headers, for
+     * example), replacing any case variant of the same name.
+     */
+    readonly extraHeaders?: (context: ServeNodeResponseContext) => Record<string, string> | undefined;
+    /**
+     * Choose the answer for an error. Return `undefined` for the default: 400
+     * for a request that does not parse, 405 with `allow` for a method Schmock
+     * does not route, the ingress status for a body error (400, or 413 over
+     * `maxBodySize`), and 500 `SERVER_ERROR` with the error's message otherwise.
+     */
+    readonly classifyError?: (error: unknown) => HttpErrorReply | undefined;
+}
+/**
+ * Serve one Node.js request through a mock: the bridge `mock.listen()` runs,
+ * usable with any `http.createServer` callback.
+ *
+ * It rejects a request without a parseable Host header or target (400) and a
+ * method Schmock does not route (405, with `allow`), gives `answerBeforeBody`
+ * the chance to answer without the body, then parses headers, query and body
+ * (400 for a malformed JSON or multipart body, 413 over `maxBodySize`, 10 MB
+ * by default) and calls `handle` with an abort signal that fires when the
+ * client goes away. Every failure is answered as `{ error, code }` JSON; an
+ * ingress failure also closes the connection, and a 413 is flushed while the
+ * client may still be uploading so it can read it.
+ *
+ * The returned promise never rejects. It settles once the response has been
+ * handed to Node, which is when per-request resources (a request admission)
+ * can be released.
+ */
+export declare function serveNodeRequest(req: NodeRequest, res: NodeResponse, options: ServeNodeRequestOptions): Promise<void>;
 export {};
-//# sourceMappingURL=http-helpers.d.ts.map