counterfact 2.7.0 → 2.9.0

package/dist/server/dispatcher.js

@@ -6,6 +6,15 @@ import { validateRequest } from "./request-validator.js";
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+/**
+ * Parses the `Cookie` request header into a key/value map.
+ *
+ * Duplicate keys are silently dropped (first occurrence wins) and values are
+ * percent-decoded where possible.
+ *
+ * @param cookieHeader - The raw `Cookie` header string.
+ * @returns A record mapping cookie name to decoded value.
+ */
 function parseCookies(cookieHeader) {
     const cookies = {};
     for (const part of cookieHeader.split(";")) {
@@ -27,6 +36,16 @@ function parseCookies(cookieHeader) {
     }
     return cookies;
 }
+/**
+ * Core HTTP request dispatcher.
+ *
+ * Receives incoming requests from the Koa middleware layer, matches them
+ * against the {@link Registry}, optionally validates the request and response
+ * against the OpenAPI spec, and invokes the matching route-handler function.
+ *
+ * Content-negotiation (Accept header handling) is performed before returning
+ * the response so the caller always receives the most appropriate content type.
+ */
 export class Dispatcher {
     registry;
     contextRegistry;
@@ -70,6 +89,14 @@ export class Dispatcher {
         }
         return undefined;
     }
+    /**
+     * Resolves the OpenAPI operation for `path` and `method`, merging any
+     * top-level `produces` array from the document root into the operation.
+     *
+     * @param path - The matched route path (e.g. `"/pets/{petId}"`).
+     * @param method - The HTTP method.
+     * @returns The {@link OpenApiOperation} if found, or `undefined`.
+     */
     operationForPathAndMethod(path, method) {
         const operation = this.findOperation(path, method);
         if (operation === undefined) {
@@ -108,6 +135,16 @@ export class Dispatcher {
                 "unknown/unknown",
         };
     }
+    /**
+     * Picks the best matching content entry from a multi-type response using the
+     * request's `Accept` header preferences.
+     *
+     * @param acceptHeader - The value of the `Accept` request header.
+     * @param content - Array of `{ type, body }` objects representing all
+     *   available content-type variants.
+     * @returns The first entry whose MIME type satisfies the accept preferences,
+     *   or `undefined` when none match.
+     */
     selectContent(acceptHeader, content) {
         const preferredMediaTypes = mediaTypes(acceptHeader);
         for (const mediaType of preferredMediaTypes) {
@@ -132,6 +169,15 @@ export class Dispatcher {
         }
         return false;
     }
+    /**
+     * Main request handler.
+     *
+     * Orchestrates base-path stripping, route matching, request validation,
+     * handler invocation, content negotiation, and response validation.
+     *
+     * @param request - The incoming request descriptor.
+     * @returns A promise that resolves to a {@link CounterfactResponseObject}.
+     */
     async request({ auth, body, headers = {}, method, path, query, rawBody, req, }) {
         debug(`request: ${method} ${path}`);
         debug(`headers: ${JSON.stringify(headers)}`);

package/dist/server/file-discovery.js

@@ -1,32 +1,44 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- discovery walks directories rooted at basePath and uses Dirent-provided names. */
+import { toForwardSlashPath, pathJoin } from "../util/forward-slash-path.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 const JS_EXTENSIONS = new Set(["cjs", "cts", "js", "mjs", "mts", "ts"]);
+/**
+ * Recursively discovers JavaScript/TypeScript source files under a base
+ * directory.
+ *
+ * Only files with one of the following extensions are returned:
+ * `js`, `mjs`, `cjs`, `ts`, `mts`, `cts`.
+ */
 export class FileDiscovery {
     basePath;
     constructor(basePath) {
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
     }
+    /**
+     * Returns an array of absolute file paths for all JS/TS files found
+     * recursively under `basePath/directory`.
+     *
+     * @param directory - Sub-directory relative to `basePath` to start from.
+     *   Defaults to `""` (the base path itself).
+     * @throws When `basePath/directory` does not exist.
+     */
     async findFiles(directory = "") {
-        const fullDir = nodePath
-            .join(this.basePath, directory)
-            .replaceAll("\\", "/");
+        const fullDir = pathJoin(this.basePath, directory);
         if (!existsSync(fullDir)) {
             throw new Error(`Directory does not exist ${fullDir}`);
         }
         const entries = await fs.readdir(fullDir, { withFileTypes: true });
         const results = await Promise.all(entries.map(async (entry) => {
             if (entry.isDirectory()) {
-                return this.findFiles(nodePath.join(directory, entry.name).replaceAll("\\", "/"));
+                return this.findFiles(pathJoin(directory, entry.name));
             }
             const extension = entry.name.split(".").at(-1);
             if (!JS_EXTENSIONS.has(extension ?? "")) {
                 return [];
             }
-            const fullPath = nodePath
-                .join(this.basePath, directory, entry.name)
-                .replaceAll("\\", "/");
+            const fullPath = pathJoin(this.basePath, directory, entry.name);
             return [escapePathForWindows(fullPath)];
         }));
         return results.flat();

package/dist/server/is-proxy-enabled-for-path.js

@@ -1,3 +1,15 @@
+/**
+ * Determines whether a given request path should be forwarded to the upstream
+ * proxy.
+ *
+ * The check walks up the path hierarchy until it either finds an explicit
+ * `proxyPaths` entry or reaches the root (in which case the proxy is
+ * considered disabled).
+ *
+ * @param path - The request path to check (e.g. `"/pets/1"`).
+ * @param config - Object containing the `proxyPaths` map.
+ * @returns `true` when the request should be proxied.
+ */
 export function isProxyEnabledForPath(path, config) {
     if (config.proxyPaths.has(path)) {
         return config.proxyPaths.get(path) ?? false;

package/dist/server/json-to-xml.js

@@ -36,6 +36,16 @@ function objectToXml(json, schema, name) {
     });
     return `<${name}${attributes.join("")}>${String(xml.join(""))}</${name}>`;
 }
+/**
+ * Converts a JSON value to an XML string using optional OpenAPI `xml` schema
+ * hints (element names, attributes, wrapping).
+ *
+ * @param json - The value to serialise.
+ * @param schema - Optional JSON Schema with an `xml` hint block.
+ * @param keyName - Fallback XML element name when the schema does not provide
+ *   one.  Defaults to `"root"`.
+ * @returns A well-formed XML string.
+ */
 export function jsonToXml(json, schema, keyName = "root") {
     const name = schema?.xml?.name ?? keyName;
     if (Array.isArray(json)) {

package/dist/server/load-openapi-document.js

@@ -1,13 +1,6 @@
-import { dereference } from "@apidevtools/json-schema-ref-parser";
-import createDebug from "debug";
-const debug = createDebug("counterfact:server:load-openapi-document");
+import { OpenApiDocument } from "./openapi-document.js";
 export async function loadOpenApiDocument(source) {
-    try {
-        return (await dereference(source));
-    }
-    catch (error) {
-        debug("could not load OpenAPI document from %s: %o", source, error);
-        const details = error instanceof Error ? error.message : String(error);
-        throw new Error(`Could not load the OpenAPI spec from "${source}".\n${details}`, { cause: error });
-    }
+    const document = new OpenApiDocument(source);
+    await document.load();
+    return document;
 }

package/dist/server/module-dependency-graph.js

@@ -2,6 +2,14 @@ import { dirname, resolve } from "node:path";
 import createDebug from "debug";
 import precinct from "precinct";
 const debug = createDebug("counterfact:server:module-dependency-graph");
+/**
+ * Tracks which route files depend on shared modules so that when a shared
+ * module changes, all dependent route files can be reloaded.
+ *
+ * Dependency edges are extracted using [precinct](https://npm.im/precinct)'s
+ * static analysis and are stored as a reverse map (`dependency → Set<dependent
+ * files>`).
+ */
 export class ModuleDependencyGraph {
     dependents = new Map();
     loadDependencies(path) {
@@ -18,6 +26,14 @@ export class ModuleDependencyGraph {
             group.delete(path);
         });
     }
+    /**
+     * (Re-)indexes the dependency edges for `path`, replacing any previously
+     * recorded edges.
+     *
+     * Only relative imports are tracked; node_modules dependencies are ignored.
+     *
+     * @param path - Absolute path of the file to analyse.
+     */
     load(path) {
         this.clearDependents(path);
         for (const dependency of this.loadDependencies(path)) {
@@ -31,6 +47,15 @@ export class ModuleDependencyGraph {
             this.dependents.get(key)?.add(path);
         }
     }
+    /**
+     * Returns the transitive set of files that (directly or indirectly) import
+     * `path`.
+     *
+     * Uses a BFS traversal so each dependent is returned exactly once.
+     *
+     * @param path - Absolute path of the changed dependency.
+     * @returns A `Set` of absolute paths of all dependent files.
+     */
     dependentsOf(path) {
         const marked = new Set();
         const dependents = new Set();

package/dist/server/module-loader.js

@@ -1,6 +1,7 @@
 import { once } from "node:events";
 import fs from "node:fs/promises";
-import nodePath, { basename, dirname } from "node:path";
+import nodePath, { basename } from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- readJson resolves paths against the current context directory before file access. */
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
@@ -10,9 +11,23 @@ import { FileDiscovery } from "./file-discovery.js";
 import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { toForwardSlashPath, pathDirname, pathRelative, } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
 const debug = createDebug("counterfact:server:module-loader");
+/**
+ * Watches the compiled routes directory and dynamically loads/reloads route
+ * modules, context files, and middleware as files are added, changed, or
+ * removed.
+ *
+ * Loaded modules are registered in the {@link Registry} (route handlers) or
+ * the {@link ContextRegistry} (context files).  An optional
+ * {@link ScenarioRegistry} receives scenario modules loaded from a separate
+ * `scenarios/` directory.
+ *
+ * Emits DOM-style events (`"add"`, `"remove"`) so callers can react to module
+ * lifecycle changes.
+ */
 export class ModuleLoader extends EventTarget {
     basePath;
     registry;
@@ -28,19 +43,29 @@ export class ModuleLoader extends EventTarget {
     };
     constructor(basePath, registry, contextRegistry = new ContextRegistry(), scenariosPath, scenarioRegistry) {
         super();
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
         this.registry = registry;
         this.contextRegistry = contextRegistry;
-        this.scenariosPath = scenariosPath?.replaceAll("\\", "/");
+        this.scenariosPath =
+            scenariosPath === undefined
+                ? undefined
+                : toForwardSlashPath(scenariosPath);
         this.scenarioRegistry = scenarioRegistry;
         this.fileDiscovery = new FileDiscovery(this.basePath);
     }
+    /**
+     * Starts watching the routes directory (and optionally the scenarios
+     * directory) for file-system changes, loading or reloading modules on
+     * `"add"` and `"change"` events and deregistering them on `"unlink"`.
+     *
+     * Resolves once the initial directory scan is complete.
+     */
     async watch() {
         this.watcher = watch(this.basePath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
             const JS_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
             if (!JS_EXTENSIONS.some((extension) => pathNameOriginal.endsWith(`.${extension}`)))
                 return;
-            const pathName = pathNameOriginal.replaceAll("\\", "/");
+            const pathName = toForwardSlashPath(pathNameOriginal);
             if (pathName.includes("$.context") && eventName === "add") {
                 process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md\n\n\n`);
                 return;
@@ -49,14 +74,12 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             const parts = nodePath.parse(pathName.replace(this.basePath, ""));
-            const url = unescapePathForWindows(`/${parts.dir}/${parts.name}`
-                .replaceAll("\\", "/")
-                .replaceAll(/\/+/gu, "/"));
+            const url = unescapePathForWindows(toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(/\/+/gu, "/"));
             if (eventName === "unlink") {
                 this.registry.remove(url);
                 this.dispatchEvent(new Event("remove"));
                 if (this.isContextFile(pathName)) {
-                    this.contextRegistry.remove(unescapePathForWindows(parts.dir).replaceAll("\\", "/") || "/");
+                    this.contextRegistry.remove(unescapePathForWindows(toForwardSlashPath(parts.dir)) || "/");
                 }
                 return;
             }
@@ -75,7 +98,7 @@ export class ModuleLoader extends EventTarget {
                     return;
                 if (!["add", "change", "unlink"].includes(eventName))
                     return;
-                const pathName = pathNameOriginal.replaceAll("\\", "/");
+                const pathName = toForwardSlashPath(pathNameOriginal);
                 if (eventName === "unlink") {
                     const fileKey = this.scenarioFileKey(pathName);
                     this.scenarioRegistry?.remove(fileKey);
@@ -86,6 +109,7 @@ export class ModuleLoader extends EventTarget {
             await once(this.scenariosWatcher, "ready");
         }
     }
+    /** Closes both file-system watchers (routes and scenarios). */
     async stopWatching() {
         await this.watcher?.close();
         await this.scenariosWatcher?.close();
@@ -93,6 +117,12 @@ export class ModuleLoader extends EventTarget {
     isContextFile(pathName) {
         return basename(pathName).startsWith("_.context.");
     }
+    /**
+     * Performs a one-shot load of all modules found under `directory` (relative
+     * to the configured base path) and all scenario files.
+     *
+     * @param directory - Sub-directory to load, defaults to the root (`""`).
+     */
     async load(directory = "") {
         const files = await this.fileDiscovery.findFiles(directory);
         await Promise.all(files.map((file) => this.loadEndpoint(file)));
@@ -115,12 +145,10 @@ export class ModuleLoader extends EventTarget {
         }
     }
     scenarioFileKey(pathName) {
-        const normalizedScenariosPath = (this.scenariosPath ?? "").replaceAll("\\", "/");
-        const directory = dirname(pathName.slice(normalizedScenariosPath.length)).replaceAll("\\", "/");
+        const normalizedScenariosPath = toForwardSlashPath(this.scenariosPath ?? "");
+        const directory = pathDirname(pathName.slice(normalizedScenariosPath.length));
         const name = nodePath.parse(basename(pathName)).name;
-        const url = unescapePathForWindows(`/${nodePath.join(directory, name)}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"));
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, name)}`).replaceAll(/\/+/gu, "/"));
         return url.slice(1); // strip leading "/"
     }
     async loadScenarioFile(pathName) {
@@ -142,10 +170,8 @@ export class ModuleLoader extends EventTarget {
     }
     async loadEndpoint(pathName) {
         debug("importing module: %s", pathName);
-        const directory = dirname(pathName.slice(this.basePath.length)).replaceAll("\\", "/");
-        const url = unescapePathForWindows(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"));
+        const directory = pathDirname(pathName.slice(this.basePath.length));
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`).replaceAll(/\/+/gu, "/"));
         debug(`loading pathName from dependencyGraph: ${pathName}`);
         this.dependencyGraph.load(pathName);
         try {
@@ -159,9 +185,14 @@ export class ModuleLoader extends EventTarget {
             if (importError !== undefined) {
                 const isSyntaxError = importError instanceof SyntaxError ||
                     String(importError).startsWith("SyntaxError:");
-                const displayPath = nodePath
-                    .relative(process.cwd(), unescapePathForWindows(pathName))
-                    .replaceAll("\\", "/");
+                const displayPath = pathRelative(process.cwd(), unescapePathForWindows(pathName));
+                if (this.isContextFile(pathName)) {
+                    const warning = isSyntaxError
+                        ? `Warning: There is a syntax error in the context file: ${displayPath}`
+                        : `Warning: There was an error loading the context file: ${displayPath}`;
+                    process.stdout.write(`\n${warning}\n`);
+                    return;
+                }
                 const message = isSyntaxError
                     ? `There is a syntax error in the route file: ${displayPath}`
                     : `There was an error loading the route file: ${displayPath}`;

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