counterfact 2.7.0 → 2.8.1

package/README.md

@@ -4,174 +4,19 @@
 
 <br>
 
-**Your backend isn't ready. Your frontend can't wait.**
-
-**Counterfact turns your OpenAPI spec into a live, stateful API you can program in TypeScript.**
-
-<br>
-
 ![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
 
 </div>
 
-This is a five-minute walkthrough. By the end, you’ll have a **stateful, type-safe, hot-reloading API simulator** running locally—and you’ll understand why it’s different from traditional mock servers.
-
-Built for frontend developers, test engineers, and AI agents that need a predictable API to work against.
+You've used mock servers. You know where they stop being useful: static responses, no shared state, no way to inject a failure mid-run, no control without restarting. Counterfact picks up where they leave off.
 
-
-
-## Minute 1 — Start the server
+Point it at an OpenAPI spec and it generates TypeScript handlers for every endpoint—type-safe, hot-reloading, sharing state across routes. A built-in REPL gives you a live control surface: seed data, trigger error conditions, proxy individual routes to a real backend, all on a running server. Whether you're a frontend developer waiting on a backend, a test engineer who needs clean reproducible state, or an AI agent that needs a stable API to work against, Counterfact is the simulator that doesn't plateau.
 
 ```sh
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
-> **Requires Node ≥ 22.0.0**
-
-That’s it.
-
-Counterfact reads your spec, generates a TypeScript handler for every endpoint, and starts a server at `http://localhost:3100`.
-
-Open `http://localhost:3100/counterfact/swagger/`.
-
-Every endpoint is already live, returning random, schema-valid responses. No code written yet.
-
-
-
-## Minute 2 — Make a route return real data
-
-Open the generated file for `GET /pet/{petId}`:
-
-```ts
-import type { HTTP_GET } from "../../types/paths/pet/{petId}.types.js";
-
-export const GET: HTTP_GET = ($) => $.response[200].random();
-```
-
-Replace `.random()` with your own logic:
-
-```ts
-export const GET: HTTP_GET = ($) => {
-  if ($.path.petId === 99) {
-    return $.response[404].text("Pet not found");
-  }
-  return $.response[200].json({
-    id: $.path.petId,
-    name: "Fluffy",
-    status: "available",
-    photoUrls: []
-  });
-};
-```
-
-Save the file. The server reloads instantly—no restart, no lost state.
-
-TypeScript enforces the contract. If your response doesn’t match the spec, you’ll know before you make the request. 
-
-## Minute 3 — Add state that survives across requests
-
-Real APIs have memory. Yours should too.
-
-Create `api/routes/_.context.ts`:
-
-```ts
-import type { Pet } from "../types/components/pet.types.js";
-
-export class Context {
-  private pets = new Map<number, Pet>();
-  private nextId = 1;
-
-  add(data: Omit<Pet, "id">): Pet {
-    const pet = { ...data, id: this.nextId++ };
-    this.pets.set(pet.id, pet);
-    return pet;
-  }
-
-  get(id: number): Pet | undefined { return this.pets.get(id); }
-  list(): Pet[] { return [...this.pets.values()]; }
-  remove(id: number): void { this.pets.delete(id); }
-}
-```
-
-Use it in your routes:
-
-```ts
-export const GET: HTTP_GET = ($) => $.response[200].json($.context.list());
-export const POST: HTTP_POST = ($) => $.response[200].json($.context.add($.body));
-```
-
-Now your API behaves like a real system:
-- POST creates data
-- GET returns it
-- DELETE removes it
-
-State survives hot reloads. Restarting resets everything—perfect for clean test runs.
-
-
-
-## Minute 4 — Control the system at runtime (REPL)
-
-This is where Counterfact becomes more than a mock.
-
-The built-in REPL lets you inspect and control the system while it’s running.
-
-Seed data:
-
-```
-⬣> context.add({ name: "Fluffy", status: "available", photoUrls: [] })
-⬣> context.add({ name: "Rex", status: "pending", photoUrls: [] })
-```
-
-Make requests:
-
-```
-⬣> client.get("/pet/1")
-```
-
-Simulate failures instantly:
-
-```
-⬣> context.rateLimitExceeded = true
-⬣> client.get("/pet/1")
-{ status: 429, body: "Too Many Requests" }
-```
-
-No HTTP scripts. No restarts. Just direct control.
-
-
-
-## Minute 5 — Proxy to the real backend
-
-When parts of your backend are ready, forward them through.
-
-Everything else stays simulated.
-
-```sh
-npx counterfact@latest openapi.yaml api --proxy-url https://api.example.com
-```
-
-Toggle paths live:
-
-```
-⬣> .proxy on /payments
-⬣> .proxy on /auth
-⬣> .proxy off
-```
-
-
-
-## What you just built
-
-In five minutes, you turned a static spec into a working system:
-
-- **Schema-valid responses** from the moment it starts
-- **Type-safe handlers** generated from your spec
-- **Shared state** across all routes
-- **Hot reloading** without losing that state
-- A **live control surface (REPL)** for runtime behavior
-- **Selective proxying** to real services
-
-
+> Requires Node ≥ 22.0.0
 
 ## Go deeper
 
@@ -189,4 +34,4 @@ In five minutes, you turned a static spec into a working system:
 
 [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
-</div>
+</div>

package/bin/counterfact.js

@@ -162,6 +162,14 @@ const { loadConfigFile } = await import(
   )
 );
 
+const { pathResolve } = await import(
+  resolve(
+    nativeTs
+      ? "../src/util/forward-slash-path.js"
+      : "../dist/util/forward-slash-path.js",
+  )
+);
+
 const DEFAULT_PORT = 3100;
 
 const debug = createDebug("counterfact:bin:counterfact");
@@ -314,9 +322,9 @@ async function main(source, destination) {
     source = options.spec;
   }
 
-  const destinationPath = nodePath.resolve(destination).replaceAll("\\", "/");
+  const destinationPath = pathResolve(destination);
 
-  const basePath = nodePath.resolve(destinationPath).replaceAll("\\", "/");
+  const basePath = pathResolve(destinationPath);
 
   // If no action-related option is provided, default to all options
 

package/dist/app.js

@@ -1,21 +1,33 @@
 import fs, { rm } from "node:fs/promises";
-import nodePath from "node:path";
 import { createHttpTerminator } from "http-terminator";
 import { startRepl as startReplServer } from "./repl/repl.js";
+import { createRouteFunction } from "./repl/route-builder.js";
 import { ContextRegistry } from "./server/context-registry.js";
 import { createKoaApp } from "./server/create-koa-app.js";
 import { Dispatcher } from "./server/dispatcher.js";
-import { koaMiddleware } from "./server/koa-middleware.js";
 import { loadOpenApiDocument } from "./server/load-openapi-document.js";
 import { ModuleLoader } from "./server/module-loader.js";
-import { OpenApiWatcher } from "./server/openapi-watcher.js";
 import { Registry } from "./server/registry.js";
 import { ScenarioRegistry } from "./server/scenario-registry.js";
 import { Transpiler } from "./server/transpiler.js";
 import { CodeGenerator } from "./typescript-generator/code-generator.js";
-import { writeApplyContextType } from "./typescript-generator/generate.js";
+import { ScenarioFileGenerator } from "./typescript-generator/scenario-file-generator.js";
 import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
+import { pathJoin } from "./util/forward-slash-path.js";
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
+export async function runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument) {
+    const indexModule = scenarioRegistry.getModule("index");
+    if (!indexModule || typeof indexModule["startup"] !== "function") {
+        return;
+    }
+    const scenario$ = {
+        context: contextRegistry.find("/"),
+        loadContext: (path) => contextRegistry.find(path),
+        route: createRouteFunction(config.port, "localhost", openApiDocument),
+        routes: {},
+    };
+    await indexModule["startup"](scenario$);
+}
 const allowedMethods = [
     "all",
     "head",
@@ -27,6 +39,16 @@ const allowedMethods = [
     "options",
 ];
 const mswHandlers = {};
+/**
+ * Dispatches a single MSW (Mock Service Worker) intercepted request to the
+ * matching Counterfact route handler registered via {@link createMswHandlers}.
+ *
+ * @param request - The intercepted request, including the HTTP method, path,
+ *   headers, query, body, and a `rawPath` that preserves the original URL
+ *   before base-path stripping.
+ * @returns The response produced by the matching handler, or a 404 object when
+ *   no handler has been registered for the given method and path.
+ */
 export async function handleMswRequest(request) {
     const { method, rawPath } = request;
     const handler = mswHandlers[`${method}:${rawPath}`];
@@ -36,15 +58,25 @@ export async function handleMswRequest(request) {
     console.warn(`No handler found for ${method} ${rawPath}`);
     return { error: `No handler found for ${method} ${rawPath}`, status: 404 };
 }
+/**
+ * Loads an OpenAPI document, registers all routes from it as MSW handlers, and
+ * returns the list of registered routes so callers (e.g. Vitest Browser mode)
+ * can mount them on their own request-interception layer.
+ *
+ * @param config - Counterfact configuration; `openApiPath` and `basePath` are
+ *   the most important fields for this function.
+ * @param ModuleLoaderClass - Injectable module-loader constructor, primarily
+ *   used in tests to substitute a test-friendly implementation.
+ * @returns An array of `{ method, path }` objects describing every registered
+ *   MSW handler.
+ */
 export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader) {
     // TODO: For some reason the Vitest Custom Commands needed by Vitest Browser mode fail on fs.readFile when they are called from the nested loadOpenApiDocument function.
     // If we "pre-read" the file here it works. This is a workaround to avoid the issue.
     await fs.readFile(config.openApiPath);
     const openApiDocument = await loadOpenApiDocument(config.openApiPath);
     const modulesPath = config.basePath;
-    const compiledPathsDirectory = nodePath
-        .join(modulesPath, ".cache")
-        .replaceAll("\\", "/");
+    const compiledPathsDirectory = pathJoin(modulesPath, ".cache");
     const registry = new Registry();
     const contextRegistry = new ContextRegistry();
     const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument, config);
@@ -67,47 +99,69 @@ export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader
     });
     return handlers;
 }
+/**
+ * Creates and configures a full Counterfact server instance.
+ *
+ * Sets up the route registry, context registry, scenario registry, code
+ * generator, transpiler, module loader, Koa application, and OpenAPI watcher.
+ * The returned object exposes handles for starting the server, stopping it, and
+ * launching the interactive REPL.
+ *
+ * @param config - Runtime configuration (port, paths, feature flags, etc.).
+ * @returns An object containing the configured sub-systems and two entry-point
+ *   functions:
+ *   - `start(options)` — generates/watches code and optionally starts the HTTP
+ *     server; returns a `stop()` handle.
+ *   - `startRepl()` — launches the interactive Node.js REPL connected to the
+ *     live server state.
+ */
 export async function counterfact(config) {
     const modulesPath = config.basePath;
     const nativeTs = await runtimeCanExecuteErasableTs();
-    const compiledPathsDirectory = nodePath
-        .join(modulesPath, nativeTs ? "routes" : ".cache")
-        .replaceAll("\\", "/");
+    const compiledPathsDirectory = pathJoin(modulesPath, nativeTs ? "routes" : ".cache");
     if (!nativeTs) {
         await rm(compiledPathsDirectory, { force: true, recursive: true });
     }
     const registry = new Registry();
     const contextRegistry = new ContextRegistry();
     const scenarioRegistry = new ScenarioRegistry();
+    const scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
     const codeGenerator = new CodeGenerator(config.openApiPath, config.basePath, config.generate);
     const openApiDocument = config.openApiPath === "_"
         ? undefined
         : await loadOpenApiDocument(config.openApiPath);
     const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument, config);
-    const transpiler = new Transpiler(nodePath.join(modulesPath, "routes").replaceAll("\\", "/"), compiledPathsDirectory, "commonjs");
-    const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry, nodePath.join(modulesPath, "scenarios").replaceAll("\\", "/"), scenarioRegistry);
-    contextRegistry.addEventListener("context-changed", () => {
-        void writeApplyContextType(modulesPath);
+    const transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
+    const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry, pathJoin(modulesPath, "scenarios"), scenarioRegistry);
+    const koaApp = createKoaApp({
+        config,
+        contextRegistry,
+        dispatcher,
+        registry,
     });
-    const middleware = koaMiddleware(dispatcher, config);
-    const koaApp = createKoaApp(registry, middleware, config, contextRegistry);
-    const openApiWatcher = new OpenApiWatcher(config.openApiPath, dispatcher);
     async function start(options) {
         const { generate, startServer, watch, buildCache } = options;
         if (config.openApiPath !== "_" && (generate.routes || generate.types)) {
             await codeGenerator.generate();
         }
+        if (generate.types) {
+            await scenarioFileGenerator.generate();
+        }
         if (config.openApiPath !== "_" && (watch.routes || watch.types)) {
             await codeGenerator.watch();
         }
+        if (watch.types) {
+            await scenarioFileGenerator.watch();
+        }
         let httpTerminator;
         if (startServer) {
-            await openApiWatcher.watch();
+            await openApiDocument?.watch();
             if (!nativeTs) {
                 await transpiler.watch();
             }
             await moduleLoader.load();
             await moduleLoader.watch();
+            await runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument);
             const server = koaApp.listen({
                 port: config.port,
             });
@@ -123,9 +177,10 @@ export async function counterfact(config) {
         return {
             async stop() {
                 await codeGenerator.stopWatching();
+                await scenarioFileGenerator.stopWatching();
                 await transpiler.stopWatching();
                 await moduleLoader.stopWatching();
-                await openApiWatcher.stopWatching();
+                await openApiDocument?.stopWatching();
                 await httpTerminator?.terminate();
             },
         };
@@ -133,7 +188,6 @@ export async function counterfact(config) {
     return {
         contextRegistry,
         koaApp,
-        koaMiddleware: middleware,
         registry,
         start,
         startRepl: () => startReplServer(contextRegistry, registry, config, undefined, // use the default print function (stdout)

package/dist/migrate/update-route-types.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import createDebug from "debug";
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { OperationTypeCoder, } from "../typescript-generator/operation-type-coder.js";
 import { Specification } from "../typescript-generator/specification.js";
 const debug = createDebug("counterfact:migrate:update-route-types");
@@ -180,9 +181,7 @@ async function processRouteDirectory(routesDir, currentPath, mapping) {
             }
             else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
                 // Process TypeScript route files (skip context files)
-                const routePath = relativePath
-                    .replace(/\.ts$/, "")
-                    .replaceAll("\\", "/");
+                const routePath = toForwardSlashPath(relativePath.replace(/\.ts$/, ""));
                 const methodMap = mapping.get(routePath);
                 if (methodMap) {
                     const wasUpdated = await updateRouteFile(absolutePath, methodMap);

package/dist/repl/raw-http-client.js

@@ -51,6 +51,16 @@ function stringifyBody(body) {
     }
     return JSON.stringify(body);
 }
+/**
+ * A minimal HTTP/1.1 client that communicates over a raw TCP socket.
+ *
+ * Used in the Counterfact REPL (`client.*`) to send requests to the local mock
+ * server and pretty-print the request and response to `stdout` with ANSI
+ * colours.
+ *
+ * Unlike `fetch` or Axios, `RawHttpClient` does not buffer or parse the
+ * response — the raw HTTP response string is returned from every method.
+ */
 export class RawHttpClient {
     host;
     port;
@@ -59,30 +69,39 @@ export class RawHttpClient {
         this.host = host;
         this.port = port;
     }
+    /** Sends a `GET` request and returns the raw HTTP response string. */
     get(path, headers = {}) {
         return this.#send("GET", path, "", headers);
     }
+    /** Sends a `HEAD` request and returns the raw HTTP response string. */
     head(path, headers = {}) {
         return this.#send("HEAD", path, "", headers);
     }
+    /** Sends a `POST` request with `body` and returns the raw HTTP response string. */
     post(path, body = "", headers = {}) {
         return this.#send("POST", path, body, headers);
     }
+    /** Sends a `PUT` request with `body` and returns the raw HTTP response string. */
     put(path, body = "", headers = {}) {
         return this.#send("PUT", path, body, headers);
     }
+    /** Sends a `DELETE` request and returns the raw HTTP response string. */
     delete(path, headers = {}) {
         return this.#send("DELETE", path, "", headers);
     }
+    /** Sends a `CONNECT` request and returns the raw HTTP response string. */
     connect(path, headers = {}) {
         return this.#send("CONNECT", path, "", headers);
     }
+    /** Sends an `OPTIONS` request and returns the raw HTTP response string. */
     options(path, headers = {}) {
         return this.#send("OPTIONS", path, "", headers);
     }
+    /** Sends a `TRACE` request and returns the raw HTTP response string. */
     trace(path, headers = {}) {
         return this.#send("TRACE", path, "", headers);
     }
+    /** Sends a `PATCH` request with `body` and returns the raw HTTP response string. */
     patch(path, body = "", headers = {}) {
         return this.#send("PATCH", path, body, headers);
     }

package/dist/repl/repl.js

@@ -20,13 +20,13 @@ const ROUTE_BUILDER_METHODS = [
  *
  * @param registry - The route registry used to complete path arguments for `route()` and `client.*()` calls.
  * @param fallback - Optional fallback completer (e.g. the Node.js built-in completer) invoked when no custom completion matches.
- * @param scenarioRegistry - When provided, enables tab completion for `.apply` commands by enumerating
+ * @param scenarioRegistry - When provided, enables tab completion for `.scenario` commands by enumerating
  *   exported function names and file-key prefixes from the loaded scenario modules.
  */
 export function createCompleter(registry, fallback, scenarioRegistry) {
     return (line, callback) => {
-        // Check for .apply completion: .apply <partial>
-        const applyMatch = line.match(/^\.apply\s+(?<partial>\S*)$/u);
+        // Check for .scenario completion: .scenario <partial>
+        const applyMatch = line.match(/^\.scenario\s+(?<partial>\S*)$/u);
         if (applyMatch) {
             const partial = applyMatch.groups?.["partial"] ?? "";
             if (scenarioRegistry !== undefined) {
@@ -84,6 +84,25 @@ export function createCompleter(registry, fallback, scenarioRegistry) {
         callback(null, [matches, partial]);
     };
 }
+/**
+ * Launches the interactive Counterfact REPL.
+ *
+ * The REPL is a standard Node.js REPL augmented with:
+ * - `context` / `loadContext(path)` globals wired to the {@link ContextRegistry}.
+ * - `client` — a {@link RawHttpClient} pre-configured for `localhost`.
+ * - `route(path)` — creates a {@link RouteBuilder} for the given path.
+ * - `.counterfact` — help command.
+ * - `.proxy` — proxy configuration command.
+ * - `.scenario` — runs a named scenario function from the scenarios directory.
+ *
+ * @param contextRegistry - The live context registry.
+ * @param registry - The route registry (used for tab completion).
+ * @param config - Server configuration.
+ * @param print - Output function; defaults to writing to `stdout`.
+ * @param openApiDocument - Optional OpenAPI document for tab completion.
+ * @param scenarioRegistry - Optional scenario registry for `.scenario` support.
+ * @returns The configured Node.js REPL server instance.
+ */
 export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
@@ -123,7 +142,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         }
     }
     const replServer = repl.start({
-        prompt: "⬣> ",
+        prompt: "\x1b[38;2;0;113;181m⬣> \x1b[0m",
     });
     const builtinCompleter = replServer.completer;
     // completer is typed as readonly in @types/node but is writable at runtime
@@ -173,11 +192,11 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     replServer.context.RawHttpClient = RawHttpClient;
     replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
     replServer.context.routes = {};
-    replServer.defineCommand("apply", {
+    replServer.defineCommand("scenario", {
         async action(text) {
             const parts = text.trim().split("/").filter(Boolean);
             if (parts.length === 0) {
-                print("usage: .apply <path>");
+                print("usage: .scenario <path>");
                 this.clearBufferedCommand();
                 this.displayPrompt();
                 return;
@@ -220,7 +239,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             this.clearBufferedCommand();
             this.displayPrompt();
         },
-        help: 'apply a scenario script (".apply <path>" calls the named export from scenarios/)',
+        help: 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
     });
     return replServer;
 }

package/dist/repl/route-builder.js

@@ -1,4 +1,17 @@
 import { RawHttpClient } from "./raw-http-client.js";
+/**
+ * Immutable fluent builder for constructing and sending HTTP requests from the
+ * Counterfact REPL.
+ *
+ * Each builder method returns a **new** `RouteBuilder` instance with the
+ * updated field — the original is never mutated.  When all required parameters
+ * are set, call {@link send} to execute the request.
+ *
+ * ```ts
+ * // Inside the REPL:
+ * route("/pets/{petId}").method("get").path({ petId: 1 }).send();
+ * ```
+ */
 export class RouteBuilder {
     routePath;
     _body;
@@ -47,29 +60,63 @@ export class RouteBuilder {
             queryParams: overrides.queryParams ?? this._queryParams,
         });
     }
+    /**
+     * Returns a new builder with the HTTP method set.
+     *
+     * @param method - HTTP method name (case-insensitive, e.g. `"get"`, `"POST"`).
+     */
     method(method) {
         return this.clone({ method: method.toUpperCase() });
     }
+    /**
+     * Returns a new builder with additional path parameters merged in.
+     *
+     * @param params - Key/value map of path variable names to values.
+     */
     path(params) {
         return this.clone({ pathParams: { ...this._pathParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional query parameters merged in.
+     *
+     * @param params - Key/value map of query parameter names to values.
+     */
     query(params) {
         return this.clone({ queryParams: { ...this._queryParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional request headers merged in.
+     *
+     * @param params - Key/value map of header names to values.
+     */
     headers(params) {
         return this.clone({ headerParams: { ...this._headerParams, ...params } });
     }
+    /**
+     * Returns a new builder with the request body set.
+     *
+     * @param body - The request body (will be serialised to JSON or sent as-is).
+     */
     body(body) {
         return this.clone({ body });
     }
     getOperation() {
         return this._operation;
     }
+    /**
+     * Returns `true` when a method is set and no required parameters are
+     * missing.
+     */
     ready() {
         if (!this._method)
             return false;
         return this.missing() === undefined;
     }
+    /**
+     * Returns a {@link MissingParams} object describing all required parameters
+     * that have not yet been set, or `undefined` when nothing is missing (or
+     * when the operation has no parameters).
+     */
     missing() {
         const operation = this.getOperation();
         if (!operation?.parameters)
@@ -98,6 +145,10 @@ export class RouteBuilder {
             return undefined;
         return missingParams;
     }
+    /**
+     * Returns a human-readable help string describing the operation, its
+     * parameters, and the expected responses.
+     */
     help() {
         const method = this._method ?? "[no method set]";
         const operation = this.getOperation();
@@ -168,6 +219,13 @@ export class RouteBuilder {
         }
         return lines.join("\n");
     }
+    /**
+     * Executes the HTTP request and returns the parsed response body.
+     *
+     * @throws When no HTTP method has been set.
+     * @throws When required parameters are missing.
+     * @throws When an unsupported HTTP method is used.
+     */
     async send() {
         if (!this._method) {
             throw new Error('No HTTP method set. Use .method("get") to set the method.');
@@ -265,6 +323,16 @@ export class RouteBuilder {
         return lines.join("\n");
     }
 }
+/**
+ * Creates a factory function that constructs a {@link RouteBuilder} for a
+ * given route path, pre-configured with the server's host, port, and OpenAPI
+ * document.
+ *
+ * @param port - The port the Counterfact server is listening on.
+ * @param host - The server hostname (default `"localhost"`).
+ * @param openApiDocument - Optional OpenAPI document for parameter introspection.
+ * @returns A function `(routePath: string) => RouteBuilder`.
+ */
 export function createRouteFunction(port, host, openApiDocument) {
     return (routePath) => new RouteBuilder(routePath, { host, openApiDocument, port });
 }

package/dist/server/constants.js

@@ -1,3 +1,11 @@
+/**
+ * Default options passed to every chokidar watcher in Counterfact.
+ *
+ * - `ignoreInitial: true` — suppresses the initial `"add"` events emitted for
+ *   files already present when the watcher starts.
+ * - `usePolling: true` on Windows — chokidar's native FSEvents are unreliable
+ *   on Windows; polling is more reliable there.
+ */
 export const CHOKIDAR_OPTIONS = {
     ignoreInitial: true,
     usePolling: process.platform === "win32",