counterfact 2.6.0 → 2.8.1

package/dist/server/module-tree.js

@@ -1,6 +1,20 @@
 function isDirectory(test) {
     return test !== undefined;
 }
+/**
+ * Trie-based tree that maps URL path segments to route-handler modules.
+ *
+ * Each node in the tree represents one URL segment.  Segments whose names are
+ * wrapped in curly braces (e.g. `{petId}`) are treated as wildcards and can
+ * match any value in that position.
+ *
+ * The tree supports:
+ * - **Exact matches** — literal URL segments take precedence over wildcards.
+ * - **Wildcard matches** — `{param}` segments capture the matched value as a
+ *   path variable.
+ * - **Ambiguous-wildcard detection** — when multiple wildcards exist at the
+ *   same level the match is flagged as `ambiguous` and an error is logged.
+ */
 export class ModuleTree {
     root = {
         directories: new Map(),
@@ -58,6 +72,12 @@ export class ModuleTree {
             }
         }
     }
+    /**
+     * Registers a module at the given URL pattern.
+     *
+     * @param url - The route URL pattern (e.g. `"/pets/{petId}"`).
+     * @param module - The route-handler module to associate with the URL.
+     */
     add(url, module) {
         this.addModuleToDirectory(this.root, url.split("/").slice(1), module);
     }
@@ -75,6 +95,11 @@ export class ModuleTree {
         }
         this.removeModuleFromDirectory(directory.directories.get(segment.toLowerCase()), remainingSegments);
     }
+    /**
+     * Removes the module registered at `url`.
+     *
+     * @param url - The route URL pattern to deregister.
+     */
     remove(url) {
         const segments = url.split("/").slice(1);
         this.removeModuleFromDirectory(this.root, segments);
@@ -168,9 +193,20 @@ export class ModuleTree {
         }
         return wildcardMatches[0];
     }
+    /**
+     * Finds the best-matching module for `url` and `method`.
+     *
+     * Traverses the trie, preferring exact matches over wildcards at each
+     * segment.  Returns `undefined` when no match is found.
+     *
+     * @param url - The incoming request URL.
+     * @param method - The HTTP method (used to validate wildcard matches).
+     * @returns A {@link Match} object, or `undefined` when nothing matches.
+     */
     match(url, method) {
         return this.matchWithinDirectory(this.root, url.split("/").slice(1), {}, "", method);
     }
+    /** Returns all registered routes sorted alphabetically by path. */
     get routes() {
         const routes = [];
         function traverse(directory, path) {

package/dist/server/openapi-document.js

@@ -0,0 +1,69 @@
+import { watch } from "chokidar";
+import createDebug from "debug";
+import { dereference } from "@apidevtools/json-schema-ref-parser";
+import { waitForEvent } from "../util/wait-for-event.js";
+import { CHOKIDAR_OPTIONS } from "./constants.js";
+const debug = createDebug("counterfact:server:openapi-document");
+/**
+ * Represents a loaded OpenAPI document. Knows the location of its source
+ * file, can read the file and initialize itself, can watch for file-system
+ * changes, and dispatches a `"reload"` event (via `EventTarget`) whenever
+ * the document is reloaded from disk.
+ */
+export class OpenApiDocument extends EventTarget {
+    /** The path or URL of the OpenAPI source file. */
+    source;
+    basePath;
+    paths = {};
+    produces;
+    watcher;
+    constructor(source) {
+        super();
+        this.source = source;
+    }
+    /**
+     * Reads the source file and populates the document's properties.
+     * Must be called at least once before the document data is accessible.
+     */
+    async load() {
+        try {
+            const data = (await dereference(this.source));
+            this.basePath = data.basePath;
+            this.paths = data.paths;
+            this.produces = data.produces;
+        }
+        catch (error) {
+            debug("could not load OpenAPI document from %s: %o", this.source, error);
+            const details = error instanceof Error ? error.message : String(error);
+            throw new Error(`Could not load the OpenAPI spec from "${this.source}".\n${details}`, { cause: error });
+        }
+    }
+    /**
+     * Starts watching the source file for changes. When a change is detected
+     * the document reloads itself and dispatches a `"reload"` event.
+     *
+     * Has no effect when the source is `"_"` or a remote URL.
+     */
+    async watch() {
+        if (this.source === "_" || this.source.startsWith("http")) {
+            return;
+        }
+        this.watcher = watch(this.source, CHOKIDAR_OPTIONS).on("change", () => {
+            void (async () => {
+                try {
+                    await this.load();
+                    debug("reloaded OpenAPI document from %s", this.source);
+                    this.dispatchEvent(new Event("reload"));
+                }
+                catch (error) {
+                    debug("failed to reload OpenAPI document from %s: %o", this.source, error);
+                }
+            })();
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    /** Stops watching the source file. */
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}

package/dist/server/openapi-middleware.js

@@ -1,16 +1,45 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
 import { dump } from "js-yaml";
-export function openapiMiddleware(openApiPath, url) {
+/**
+ * Returns a Koa middleware that serves bundled OpenAPI documents as YAML.
+ *
+ * When `documents` has exactly one entry the document is served at
+ * `/counterfact/openapi` (backward-compatible behaviour).
+ *
+ * When `documents` has more than one entry each document is served at
+ * `/counterfact/openapi/{id}` where `id` comes from the corresponding entry.
+ *
+ * Every served document is augmented with a `servers` entry (OpenAPI 3.x) and
+ * a `host` field (OpenAPI 2.x / Swagger) so that the Swagger UI can send
+ * requests to the running Counterfact instance.
+ *
+ * @param documents - Array of document descriptors. Each entry must provide
+ *   `path` (file path or URL to the source OpenAPI document) and `baseUrl`
+ *   (the base URL to inject, e.g. `"//localhost:3100/api"`). An optional `id`
+ *   string is used to build the per-document URL when more than one document
+ *   is present.
+ * @returns A Koa middleware function.
+ */
+export function openapiMiddleware(documents) {
     return async (ctx, next) => {
-        if (ctx.URL.pathname === "/counterfact/openapi") {
-            const openApiDocument = (await bundle(openApiPath));
+        let matched;
+        if (documents.length === 1) {
+            if (ctx.URL.pathname === "/counterfact/openapi") {
+                matched = documents[0];
+            }
+        }
+        else {
+            matched = documents.find((doc) => ctx.URL.pathname === `/counterfact/openapi/${doc.id}`);
+        }
+        if (matched) {
+            const openApiDocument = (await bundle(matched.path));
             openApiDocument.servers ??= [];
             openApiDocument.servers.unshift({
                 description: "Counterfact",
-                url,
+                url: matched.baseUrl,
             });
             // OpenApi 2 support:
-            openApiDocument.host = url;
+            openApiDocument.host = matched.baseUrl;
             ctx.body = dump(openApiDocument);
             return;
         }

package/dist/server/openapi-watcher.js

@@ -0,0 +1,35 @@
+import { watch } from "chokidar";
+import createDebug from "debug";
+import { waitForEvent } from "../util/wait-for-event.js";
+import { CHOKIDAR_OPTIONS } from "./constants.js";
+import { loadOpenApiDocument } from "./load-openapi-document.js";
+const debug = createDebug("counterfact:server:openapi-watcher");
+export class OpenApiWatcher {
+    openApiPath;
+    dispatcher;
+    watcher;
+    constructor(openApiPath, dispatcher) {
+        this.openApiPath = openApiPath;
+        this.dispatcher = dispatcher;
+    }
+    async watch() {
+        if (this.openApiPath === "_" || this.openApiPath.startsWith("http")) {
+            return;
+        }
+        this.watcher = watch(this.openApiPath, CHOKIDAR_OPTIONS).on("change", () => {
+            void (async () => {
+                try {
+                    this.dispatcher.openApiDocument = await loadOpenApiDocument(this.openApiPath);
+                    debug("reloaded OpenAPI document from %s", this.openApiPath);
+                }
+                catch (error) {
+                    debug("failed to reload OpenAPI document from %s: %o", this.openApiPath, error);
+                }
+            })();
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}

package/dist/server/registry.js

@@ -11,6 +11,16 @@ const ALL_HTTP_METHODS = [
     "PUT",
     "TRACE",
 ];
+/**
+ * Casts a string URL/header/query parameter value to the type declared in the
+ * OpenAPI spec.
+ *
+ * @param value - The raw parameter value (may already be the correct type when
+ *   the HTTP framework has pre-parsed it).
+ * @param type - The OpenAPI primitive type string (`"integer"`, `"number"`,
+ *   `"boolean"`, or anything else to leave as a string).
+ * @returns The value coerced to the appropriate JavaScript type.
+ */
 function castParameter(value, type) {
     if (typeof value !== "string") {
         return value;
@@ -26,6 +36,13 @@ function castParameter(value, type) {
     }
     return value;
 }
+/**
+ * Applies {@link castParameter} to every value in a parameters map.
+ *
+ * @param parameters - Key/value map of raw parameter values.
+ * @param parameterTypes - Map from parameter name to its OpenAPI type string.
+ * @returns A new object with the same keys and cast values.
+ */
 function castParameters(parameters = {}, parameterTypes = new Map()) {
     const copy = {};
     Object.entries(parameters).forEach(([key, value]) => {
@@ -33,27 +50,70 @@ function castParameters(parameters = {}, parameterTypes = new Map()) {
     });
     return copy;
 }
+/**
+ * Central route registry that maps URL patterns to route-handler modules.
+ *
+ * Routes are stored in a {@link ModuleTree} that supports wildcard path
+ * segments (e.g. `{petId}`). The registry also maintains an ordered chain of
+ * middleware functions that wrap every route handler execution.
+ */
 export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
     constructor() {
         this.middlewares.set("", ($, respondTo) => respondTo($));
     }
+    /** Returns all registered routes as a flat array of `{ path, methods }` objects. */
     get routes() {
         return this.moduleTree.routes;
     }
+    /**
+     * Registers (or replaces) the module for a URL pattern.
+     *
+     * @param url - The URL pattern (e.g. `/pets/{petId}`).
+     * @param module - The route-handler module exposing HTTP-method functions.
+     */
     add(url, module) {
         this.moduleTree.add(url, module);
     }
+    /**
+     * Registers a middleware function that wraps every handler under `url`.
+     *
+     * Middleware receives `($, respondTo)` where `respondTo` is the next handler
+     * in the chain. Setting `url` to `"/"` makes the middleware global.
+     *
+     * @param url - The path prefix at which this middleware applies.
+     * @param callback - The middleware function.
+     */
     addMiddleware(url, callback) {
         this.middlewares.set(url === "/" ? "" : url, callback);
     }
+    /**
+     * Removes the module registered at `url`.
+     *
+     * @param url - The URL pattern to deregister.
+     */
     remove(url) {
         this.moduleTree.remove(url);
     }
+    /**
+     * Returns `true` when a handler for `method` is registered at `url`.
+     *
+     * @param method - HTTP method (e.g. `"GET"`).
+     * @param url - The request URL.
+     */
     exists(method, url) {
         return Boolean(this.handler(url, method).module?.[method]);
     }
+    /**
+     * Finds the best-matching module and extracts path-variable bindings for a
+     * given URL and HTTP method.
+     *
+     * @param url - The incoming request URL.
+     * @param method - The HTTP method.
+     * @returns An object with `module`, `path` (variable bindings),
+     *   `matchedPath`, and `ambiguous` flag.
+     */
     handler(url, method) {
         const match = this.moduleTree.match(url, method);
         return {
@@ -63,12 +123,41 @@ export class Registry {
             path: match?.pathVariables ?? {},
         };
     }
+    /**
+     * Returns `true` when the URL matches a registered module for at least one
+     * HTTP method other than `excludeMethod`.
+     *
+     * Used to decide whether to respond with 405 Method Not Allowed.
+     *
+     * @param url - The request URL.
+     * @param excludeMethod - The method to exclude from the check.
+     */
     pathExistsWithAnyMethod(url, excludeMethod) {
         return ALL_HTTP_METHODS.filter((method) => method !== excludeMethod).some((method) => this.moduleTree.match(url, method) !== undefined);
     }
+    /**
+     * Returns a comma-separated list of HTTP methods that have a registered
+     * handler at `url`.  Used to populate the `Allow` response header for 405
+     * responses.
+     *
+     * @param url - The request URL.
+     */
     allowedMethods(url) {
         return ALL_HTTP_METHODS.filter((method) => Boolean(this.moduleTree.match(url, method)?.module?.[method])).join(", ");
     }
+    /**
+     * Returns an async function that executes the registered handler for
+     * `httpRequestMethod` at `url`, wrapped by all applicable middleware.
+     *
+     * Path, query, and header parameter values are cast to their declared types
+     * before being forwarded to the handler.  The returned function always
+     * resolves to a {@link CounterfactResponseObject}.
+     *
+     * @param httpRequestMethod - The HTTP method to look up.
+     * @param url - The incoming request URL (before path-variable substitution).
+     * @param parameterTypes - Optional maps from parameter name to OpenAPI type
+     *   for each of `header`, `path`, and `query`.
+     */
     endpoint(httpRequestMethod, url, parameterTypes = {}) {
         const handler = this.handler(url, httpRequestMethod);
         debug("handler for %s: %o", url, handler);

package/dist/server/request-validator.js

@@ -1,7 +1,7 @@
 import Ajv from "ajv";
 const ajv = new Ajv({
     allErrors: true,
-    unknownFormats: "ignore",
+    strict: false,
     coerceTypes: false,
 });
 function findMissingRequired(parameters, location, values) {
@@ -30,9 +30,7 @@ export function validateRequest(operation, request) {
             const valid = ajv.validate(schema, request.body);
             if (!valid && ajv.errors) {
                 for (const error of ajv.errors) {
-                    const path = error.instancePath ??
-                        error.dataPath ??
-                        "";
+                    const path = error.instancePath ?? "";
                     errors.push(`body${path} ${error.message ?? "is invalid"}`);
                 }
             }
@@ -47,9 +45,7 @@ export function validateRequest(operation, request) {
         const valid = ajv.validate(bodyParam.schema, request.body);
         if (!valid && ajv.errors) {
             for (const error of ajv.errors) {
-                const path = error.instancePath ??
-                    error.dataPath ??
-                    "";
+                const path = error.instancePath ?? "";
                 errors.push(`body${path} ${error.message ?? "is invalid"}`);
             }
         }

package/dist/server/response-builder.js

@@ -56,6 +56,21 @@ function unknownStatusCodeResponse(statusCode) {
         status: 500,
     };
 }
+/**
+ * Creates the `$.response` builder proxy made available to route handlers.
+ *
+ * The proxy maps HTTP status codes to a fluent builder object.  Example usage
+ * in a route handler:
+ *
+ * ```ts
+ * return $.response[200].json({ id: 1, name: "Fluffy" });
+ * ```
+ *
+ * @param operation - The OpenAPI operation descriptor used for schema-driven
+ *   random generation and example resolution.
+ * @param config - Server configuration (e.g. `alwaysFakeOptionals`).
+ * @returns A {@link ResponseBuilder} proxy keyed by HTTP status code.
+ */
 export function createResponseBuilder(operation, config) {
     return new Proxy({}, {
         get: (target, statusCode) => ({
@@ -112,6 +127,9 @@ export function createResponseBuilder(operation, config) {
                     ],
                 };
             },
+            empty() {
+                return { ...this, content: undefined };
+            },
             example(name) {
                 if (operation.produces) {
                     return unknownStatusCodeResponse(this.status);

package/dist/server/response-validator.js

@@ -0,0 +1,58 @@
+import Ajv from "ajv";
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+});
+export function validateResponse(operation, response) {
+    if (!operation) {
+        return { errors: [], valid: true };
+    }
+    const errors = [];
+    const statusKey = response.status !== undefined ? String(response.status) : undefined;
+    const responseSpec = (statusKey !== undefined ? operation.responses[statusKey] : undefined) ??
+        operation.responses.default;
+    if (!responseSpec) {
+        return { errors: [], valid: true };
+    }
+    const specHeaders = responseSpec.headers ?? {};
+    const actualHeaders = response.headers ?? {};
+    for (const [name, headerSpec] of Object.entries(specHeaders)) {
+        const actualValue = actualHeaders[name] ?? actualHeaders[name.toLowerCase()];
+        if (headerSpec.required === true && actualValue === undefined) {
+            errors.push(`response header '${name}' is required`);
+            continue;
+        }
+        if (actualValue !== undefined && headerSpec.schema !== undefined) {
+            const coercedValue = typeof actualValue === "string"
+                ? coerceHeaderValue(actualValue, headerSpec.schema)
+                : actualValue;
+            const valid = ajv.validate(headerSpec.schema, coercedValue);
+            if (!valid && ajv.errors) {
+                for (const error of ajv.errors) {
+                    const path = error.instancePath ?? "";
+                    errors.push(`response header '${name}'${path} ${error.message ?? "is invalid"}`);
+                }
+            }
+        }
+    }
+    return {
+        errors,
+        valid: errors.length === 0,
+    };
+}
+function coerceHeaderValue(value, schema) {
+    const type = schema.type;
+    if (type === "integer" || type === "number") {
+        const num = Number(value);
+        return Number.isNaN(num) ? value : num;
+    }
+    if (type === "boolean") {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+        return value;
+    }
+    return value;
+}

package/dist/server/scenario-registry.js

@@ -0,0 +1,55 @@
+/**
+ * Registry of loaded scenario modules.
+ *
+ * Scenario modules are plain JavaScript/TypeScript files that export named
+ * functions.  Each module is keyed by a slash-delimited path relative to the
+ * `scenarios/` directory (e.g. `"index"`, `"sub/reset"`).
+ *
+ * The registry is used by the REPL's `.scenario` command and by tab-completion
+ * to enumerate available scenarios and their exported function names.
+ */
+export class ScenarioRegistry {
+    modules = new Map();
+    /**
+     * Registers (or replaces) a scenario module.
+     *
+     * @param key - Slash-delimited file key (e.g. `"index"`, `"auth/setup"`).
+     * @param module - The module's exported values.
+     */
+    add(key, module) {
+        this.modules.set(key, module);
+    }
+    /**
+     * Removes the scenario module for `key`.
+     *
+     * @param key - The file key to remove.
+     */
+    remove(key) {
+        this.modules.delete(key);
+    }
+    /**
+     * Returns the module for `fileKey`, or `undefined` if not registered.
+     *
+     * @param fileKey - The file key to look up.
+     */
+    getModule(fileKey) {
+        return this.modules.get(fileKey);
+    }
+    /**
+     * Returns the names of all exported functions for the given file key.
+     * Used for tab completion.
+     */
+    getExportedFunctionNames(fileKey) {
+        const module = this.modules.get(fileKey);
+        if (!module)
+            return [];
+        return Object.keys(module).filter((k) => typeof module[k] === "function");
+    }
+    /**
+     * Returns all loaded file keys (e.g. "index", "myscript", "sub/script").
+     * Used for tab completion to enumerate available scenario files.
+     */
+    getFileKeys() {
+        return [...this.modules.keys()];
+    }
+}

package/dist/server/tools.js

@@ -1,24 +1,51 @@
 import { generate } from "json-schema-faker";
+/**
+ * A collection of utility helpers made available to route handlers via
+ * `$.tools`.
+ *
+ * Provides random selection, content-type acceptance checking, and
+ * schema-based random data generation.
+ */
 export class Tools {
     headers;
     constructor({ headers = {}, } = {}) {
         this.headers = headers;
     }
+    /**
+     * Returns a randomly selected element from `array`.
+     *
+     * @param array - The array to pick from.
+     * @returns A random element.
+     */
     oneOf(array) {
         return array[Math.floor(Math.random() * array.length)];
     }
+    /**
+     * Returns `true` when the request's `Accept` header is compatible with
+     * `contentType`.
+     *
+     * A missing or empty `Accept` header is treated as `*/*` (accepts anything).
+     *
+     * @param contentType - The MIME type to check (e.g. `"application/json"`).
+     */
     accepts(contentType) {
-        const acceptHeader = this.headers.Accept;
+        const acceptHeader = Object.entries(this.headers).find(([key]) => key.toLowerCase() === "accept")?.[1];
         if (acceptHeader === "" || acceptHeader === undefined) {
             return true;
         }
         const acceptTypes = String(acceptHeader).split(",");
         return acceptTypes.some((acceptType) => {
-            const [type, subtype] = acceptType.split("/");
+            const [type, subtype] = acceptType.trim().split("/");
             return ((type === "*" || type === contentType.split("/")[0]) &&
                 (subtype === "*" || subtype === contentType.split("/")[1]));
         });
     }
+    /**
+     * Generates a random value that satisfies `schema` using json-schema-faker.
+     *
+     * @param schema - A JSON Schema object.
+     * @returns A promise that resolves to a generated value.
+     */
     randomFromSchema(schema) {
         return generate(schema, { useExamplesValue: true, fillProperties: false });
     }

package/dist/server/transpiler.js

@@ -1,14 +1,25 @@
 // Stryker disable all
 import { once } from "node:events";
 import fs from "node:fs/promises";
-import nodePath from "node:path";
 import { watch as chokidarWatch } from "chokidar";
 import createDebug from "debug";
 import ts from "typescript";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
+import { toForwardSlashPath, pathJoin } from "../util/forward-slash-path.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 import { convertFileExtensionsToCjs } from "./convert-js-extensions-to-cjs.js";
 const debug = createDebug("counterfact:server:transpiler");
+/**
+ * Watches TypeScript source files in `sourcePath` and compiles them to
+ * JavaScript in `destinationPath` using the TypeScript compiler API.
+ *
+ * Used when the runtime cannot execute TypeScript natively (i.e. Node.js
+ * without the `--experimental-strip-types` flag).  Each file is compiled
+ * independently (no type-checking) for maximum speed.
+ *
+ * Emits DOM-style events: `"write"` after a successful transpile, `"delete"`
+ * after a source file is removed, and `"error"` on write or compilation errors.
+ */
 export class Transpiler extends EventTarget {
     sourcePath;
     destinationPath;
@@ -23,6 +34,11 @@ export class Transpiler extends EventTarget {
     get extension() {
         return this.moduleKind.toLowerCase() === "commonjs" ? ".cjs" : ".js";
     }
+    /**
+     * Starts the file-system watcher and transpiles all existing files in the
+     * source path.  Resolves once the initial scan and all pending transpiles
+     * are complete.
+     */
     async watch() {
         debug("transpiler: watch");
         this.watcher = chokidarWatch(this.sourcePath, {
@@ -36,11 +52,10 @@ export class Transpiler extends EventTarget {
             const JS_EXTENSIONS = ["js", "mjs", "ts", "mts"];
             if (!JS_EXTENSIONS.some((extension) => sourcePathOriginal.endsWith(`.${extension}`)))
                 return;
-            const sourcePath = sourcePathOriginal.replaceAll("\\", "/");
-            const destinationPath = sourcePath
+            const sourcePath = toForwardSlashPath(sourcePathOriginal);
+            const destinationPath = toForwardSlashPath(sourcePath
                 .replace(this.sourcePath, this.destinationPath)
-                .replaceAll("\\", "/")
-                .replace(".ts", this.extension);
+                .replace(".ts", this.extension));
             if (["add", "change"].includes(eventName)) {
                 transpiles.push(this.transpileFile(eventName, sourcePath, destinationPath));
             }
@@ -61,6 +76,7 @@ export class Transpiler extends EventTarget {
         await once(this.watcher, "ready");
         await Promise.all(transpiles);
     }
+    /** Closes the file-system watcher. */
     async stopWatching() {
         await this.watcher?.close();
     }
@@ -81,11 +97,9 @@ export class Transpiler extends EventTarget {
             }
         }
         const result = transpileOutput.outputText;
-        const fullDestination = nodePath
-            .join(sourcePath
+        const fullDestination = pathJoin(sourcePath
             .replace(this.sourcePath, this.destinationPath)
-            .replace(".ts", this.extension))
-            .replaceAll("\\", "/");
+            .replace(".ts", this.extension));
         const resultWithTransformedFileExtensions = convertFileExtensionsToCjs(result);
         try {
             await fs.writeFile(fullDestination, resultWithTransformedFileExtensions);