counterfact 2.7.0 → 2.8.1

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/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/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) => ({

package/dist/server/scenario-registry.js

@@ -1,11 +1,37 @@
+/**
+ * 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);
     }

package/dist/server/tools.js

@@ -1,12 +1,33 @@
 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 = Object.entries(this.headers).find(([key]) => key.toLowerCase() === "accept")?.[1];
         if (acceptHeader === "" || acceptHeader === undefined) {
@@ -19,6 +40,12 @@ export class Tools {
                 (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);

package/dist/typescript-generator/code-generator.js

@@ -1,7 +1,23 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
 import { watch } from "chokidar";
+import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";
+import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { waitForEvent } from "../util/wait-for-event.js";
-import { generate } from "./generate.js";
+import { OperationCoder } from "./operation-coder.js";
+import { pruneRoutes } from "./prune.js";
+import { Repository } from "./repository.js";
+import { Specification } from "./specification.js";
+const debug = createDebug("counterfact:typescript-generator:generate");
+/**
+ * Orchestrates the code-generation pipeline and optional file-system watching.
+ *
+ * When {@link watch} is called, Counterfact watches the source OpenAPI document
+ * for changes and re-runs code generation automatically.  `"generate"` and
+ * `"failed"` events are emitted after each attempt.
+ */
 export class CodeGenerator extends EventTarget {
     openapiPath;
     destination;
@@ -13,15 +29,111 @@ export class CodeGenerator extends EventTarget {
         this.destination = destination;
         this.generateOptions = generateOptions;
     }
-    async generate() {
-        await generate(this.openapiPath, this.destination, this.generateOptions);
+    /**
+     * Initialises the `.cache` directory that holds compiled JS output.
+     *
+     * Creates a `.gitignore` file that excludes the `.cache` sub-directory and a
+     * `README.md` inside `.cache` that explains its purpose.
+     *
+     * @param destination - The root output directory.
+     */
+    async buildCacheDirectory(destination) {
+        const gitignorePath = nodePath.join(destination, ".gitignore");
+        const cacheReadmePath = nodePath.join(destination, ".cache", "README.md");
+        debug("ensuring the directory containing .gitgnore exists");
+        await ensureDirectoryExists(gitignorePath);
+        debug("creating the .gitignore file if it doesn't already exist");
+        if (!existsSync(gitignorePath)) {
+            await fs.writeFile(gitignorePath, ".cache\n", "utf8");
+        }
+        debug("creating the .cache/README.md file");
+        ensureDirectoryExists(cacheReadmePath);
+        await fs.writeFile(cacheReadmePath, "This directory contains compiled JS files from the paths directory. Do not edit these files directly.\n", "utf8");
+    }
+    /**
+     * Reads and returns the `#/paths` requirement from `specification`.
+     *
+     * Writes a diagnostic message to stderr and returns an empty set when the
+     * `paths` key is missing or cannot be read.
+     *
+     * @param specification - The loaded OpenAPI specification.
+     */
+    async getPathsFromSpecification(specification) {
+        try {
+            return specification.getRequirement("#/paths") ?? new Set();
+        }
+        catch (error) {
+            process.stderr.write(`Could not find #/paths in the specification.\n${error}\n`);
+            return undefined;
+        }
+    }
+    /**
+     * Runs the main code-generation pipeline once and resolves when complete.
+     *
+     * Loads the OpenAPI spec from `openapiPath`, optionally prunes defunct route
+     * files, registers all path operations as {@link OperationCoder} exports, and
+     * writes the resulting TypeScript files to `destination`.
+     *
+     * @param repository - Injectable repository instance; defaults to a fresh one
+     *   (primarily useful in tests).
+     */
+    async generate(repository = new Repository()) {
+        const { destination } = this;
+        debug("generating code from %s to %s", this.openapiPath, destination);
+        debug("initializing the .cache directory");
+        await this.buildCacheDirectory(destination);
+        debug("done initializing the .cache directory");
+        debug("creating specification from %s", this.openapiPath);
+        const specification = await Specification.fromFile(this.openapiPath);
+        debug("created specification: $o", specification);
+        debug("reading the #/paths from the specification");
+        const paths = await this.getPathsFromSpecification(specification);
+        debug("got %i paths", paths?.map?.length ?? 0);
+        if (this.generateOptions.prune && this.generateOptions.routes) {
+            debug("pruning defunct route files");
+            await pruneRoutes(destination, paths.map((_v, key) => key));
+            debug("done pruning");
+        }
+        const securityRequirement = specification.getRequirement("#/components/securitySchemes");
+        const securitySchemes = Object.values(securityRequirement?.data ?? {});
+        const HTTP_VERBS = new Set([
+            "get",
+            "put",
+            "post",
+            "delete",
+            "options",
+            "head",
+            "patch",
+            "trace",
+        ]);
+        paths.forEach((pathDefinition, key) => {
+            debug("processing path %s", key);
+            const path = key === "/" ? "/index" : key;
+            pathDefinition.forEach((operation, requestMethod) => {
+                if (!HTTP_VERBS.has(requestMethod)) {
+                    return;
+                }
+                repository
+                    .get(`routes${path}.ts`)
+                    .export(new OperationCoder(operation, requestMethod, securitySchemes));
+            });
+        });
+        debug("telling the repository to write the files to %s", destination);
+        await repository.writeFiles(destination, this.generateOptions);
+        debug("finished writing the files");
     }
+    /**
+     * Starts watching the OpenAPI document for changes.
+     *
+     * Has no effect when `openApiPath` is a URL (HTTP sources are not watched).
+     * Resolves once the watcher is ready.
+     */
     async watch() {
         if (this.openapiPath.startsWith("http")) {
             return;
         }
         this.watcher = watch(this.openapiPath, CHOKIDAR_OPTIONS).on("change", () => {
-            void generate(this.openapiPath, this.destination, this.generateOptions).then(() => {
+            void this.generate().then(() => {
                 this.dispatchEvent(new Event("generate"));
                 return true;
             }, () => {
@@ -31,6 +143,7 @@ export class CodeGenerator extends EventTarget {
         });
         await waitForEvent(this.watcher, "ready");
     }
+    /** Closes the file-system watcher. */
     async stopWatching() {
         await this.watcher?.close();
     }