counterfact 2.6.0 → 2.7.0

package/README.md

@@ -4,227 +4,189 @@
 
 <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)
+**Your backend isn't ready. Your frontend can't wait.**
 
-</div>
+**Counterfact turns your OpenAPI spec into a live, stateful API you can program in TypeScript.**
 
----
+<br>
 
-**Counterfact instantly turns an [OpenAPI/Swagge](https://www.openapis.org) spec into a live, working API you can run locally.**
+![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)
 
-Instead of waiting for a backend—or wiring up brittle mocks—it generates a server where every endpoint is backed by TypeScript code. Responses are valid by default, but fully customizable, and the system is stateful, interactive, and hot-reloading.
+</div>
 
-It’s not just a mock server.
+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.
 
-It’s a controllable API environment you can shape in real time.
+Built for frontend developers, test engineers, and AI agents that need a predictable API to work against.
 
-> Built by Patrick McElhaney · Currently available for the right opportunity → https://patrickmcelhaney.org
 
----
 
-## Quick Start
+## Minute 1 — Start the server
 
 ```sh
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
-That's it. Counterfact reads your OpenAPI spec, generates TypeScript route files in `api/`, and starts a mock server — all in one command. Point it at your own spec instead of the Petstore whenever you're ready.
-
-> **Requires Node ≥ 17.0.0**
+> **Requires Node ≥ 22.0.0**
 
----
+That’s it.
 
-## Features
+Counterfact reads your spec, generates a TypeScript handler for every endpoint, and starts a server at `http://localhost:3100`.
 
-- ⚡ **Zero config** — one command to generate and start a simulated api
-- 🔒 **Type-safe by default** — route handlers are typed directly from your OpenAPI spec
-- 🔄 **Hot reload** — edit route files while the server is running; state is preserved
-- 🧠 **State management** — POST data and GET it back; share state across routes with context objects
-- 🖥 **Live REPL** — inspect and modify server state from your terminal without touching files
-- 🔀 **Hybrid proxy** — route some paths to the real API while mocking others
-- 🎲 **Smart random data** — uses OpenAPI examples and schema metadata to generate realistic responses
-- 📖 **Built-in Swagger UI** — browse and test your mock API in a browser automatically
-- 🔌 **Middleware support** — add custom middleware with `_.middleware.ts` files
+Open `http://localhost:3100/counterfact/swagger/`.
 
----
+Every endpoint is already live, returning random, schema-valid responses. No code written yet.
 
-## How It Works
 
-1. **Generate** — Counterfact reads your OpenAPI spec and creates a `routes/` directory with a `.ts` file for each path, plus a `types/` directory with fully typed request/response interfaces.
-2. **Customize** — Edit the route files to return exactly the data your frontend needs. The full power of TypeScript is at your disposal.
-3. **Run** — The server hot-reloads on every save. No restart, no lost state.
 
----
+## Minute 2 — Make a route return real data
 
-## Examples
-
-### Zero effort: random responses out of the box
-
-Generated route files return random, schema-valid responses immediately — no editing required.
+Open the generated file for `GET /pet/{petId}`:
 
 ```ts
-// mock-api/routes/store/order/{orderID}.ts
-import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
+import type { HTTP_GET } from "../../types/paths/pet/{petId}.types.js";
 
-export const GET: HTTP_GET = ($) => {
-  return $.response[200].random();
-};
+export const GET: HTTP_GET = ($) => $.response[200].random();
 ```
 
-### Typed custom responses
-
-Replace `.random()` with `.json()` to return specific data. TypeScript (via your IDE's autocomplete) guides you to a valid response.
+Replace `.random()` with your own logic:
 
 ```ts
-import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
-import type { HTTP_DELETE } from "../../../types/paths/store/order/{orderId}.types.js";
-
 export const GET: HTTP_GET = ($) => {
-  const orders: Record<number, Order> = {
-    1: { petId: 100, status: "placed" },
-    2: { petId: 999, status: "approved" },
-    3: { petId: 1234, status: "delivered" },
-  };
-
-  const order = orders[$.path.orderID];
-  if (order === undefined) return $.response[404];
-  return $.response[200].json(order);
-};
-
-export const DELETE: HTTP_DELETE = ($) => {
-  return $.response[200];
+  if ($.path.petId === 99) {
+    return $.response[404].text("Pet not found");
+  }
+  return $.response[200].json({
+    id: $.path.petId,
+    name: "Fluffy",
+    status: "available",
+    photoUrls: []
+  });
 };
 ```
 
-### Returning named examples
+Save the file. The server reloads instantly—no restart, no lost state.
 
-If your OpenAPI spec defines named examples, use `.example(name)` to return a specific one. The name is autocompleted and type-checked from your spec:
+TypeScript enforces the contract. If your response doesn’t match the spec, you’ll know before you make the request. 
 
-```ts
-export const GET: HTTP_GET = ($) => {
-  return $.response[200].example("successResponse");
-};
-```
+## Minute 3 — Add state that survives across requests
 
-### State management with plain old objects
+Real APIs have memory. Yours should too.
 
-Use a `_.context.ts` file to share in-memory state across routes. POST data and GET it back, just like a real API.
+Create `api/routes/_.context.ts`:
 
 ```ts
-// mock-api/routes/_.context.ts
+import type { Pet } from "../types/components/pet.types.js";
+
 export class Context {
-  pets: Pet[] = [];
+  private pets = new Map<number, Pet>();
+  private nextId = 1;
 
-  addPet(pet: Pet) {
-    const id = this.pets.length;
-    this.pets.push({ ...pet, id });
-    return this.pets[id];
+  add(data: Omit<Pet, "id">): Pet {
+    const pet = { ...data, id: this.nextId++ };
+    this.pets.set(pet.id, pet);
+    return pet;
   }
 
-  getPetById(id: number) {
-    return this.pets[id];
-  }
+  get(id: number): Pet | undefined { return this.pets.get(id); }
+  list(): Pet[] { return [...this.pets.values()]; }
+  remove(id: number): void { this.pets.delete(id); }
 }
 ```
 
-```ts
-// mock-api/routes/pet.ts
-export const POST: HTTP_POST = ($) => {
-  return $.response[200].json($.context.addPet($.body));
-};
+Use it in your routes:
 
-// mock-api/routes/pet/{petId}.ts
-export const GET: HTTP_GET = ($) => {
-  const pet = $.context.getPetById($.path.petId);
-  if (!pet) return $.response[404].text(`Pet ${$.path.petId} not found.`);
-  return $.response[200].json(pet);
-};
+```ts
+export const GET: HTTP_GET = ($) => $.response[200].json($.context.list());
+export const POST: HTTP_POST = ($) => $.response[200].json($.context.add($.body));
 ```
 
-You can also interact with the context object using a REPL. It's like DevTools on the server side. (See "Live REPL" below.)
+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.
 
----
 
-## Key Capabilities
 
-### 🔄 Hot Reload
+## Minute 4 — Control the system at runtime (REPL)
 
-Save a route file and the server picks it up instantly — no restart, no lost state. Your in-memory context survives every reload.
+This is where Counterfact becomes more than a mock.
 
-### 🖥 Live REPL
+The built-in REPL lets you inspect and control the system while it’s running.
 
-The REPL gives you a JavaScript prompt connected directly to your running server. Inspect state, trigger edge cases, or adjust proxy settings without touching a file.
+Seed data:
 
 ```
-⬣> context.pets.length
-3
-⬣> context.addPet({ name: "Fluffy", photoUrls: [] })
-⬣> client.get("/pet/3")
-⬣> .proxy on /payments    # forward /payments to the real API
-⬣> .proxy off             # stop all proxying
+⬣> context.add({ name: "Fluffy", status: "available", photoUrls: [] })
+⬣> context.add({ name: "Rex", status: "pending", photoUrls: [] })
 ```
 
-### 🔀 Hybrid Proxy
+Make requests:
 
-Mock the paths that aren't ready yet while forwarding everything else to the real backend. See [Proxying](./docs/usage.md#proxy-peek-a-boo-) for details.
+```
+⬣> client.get("/pet/1")
+```
 
-```sh
-npx counterfact@latest openapi.yaml mock-api --proxy-url https://api.example.com
+Simulate failures instantly:
+
+```
+⬣> context.rateLimitExceeded = true
+⬣> client.get("/pet/1")
+{ status: 429, body: "Too Many Requests" }
 ```
 
-### 🔒 Type Safety
+No HTTP scripts. No restarts. Just direct control.
 
-Every route handler is typed to match your OpenAPI spec. When the spec changes, regenerating the types surfaces any mismatches at compile time — before they become bugs.
 
-```ts
-export const GET: HTTP_GET = ($) => {
-  return $.response[200]
-    .header("x-request-id", $.headers["x-request-id"])
-    .json({
-      id: $.path.userId,
-    });
-};
-```
 
----
+## Minute 5 — Proxy to the real backend
+
+When parts of your backend are ready, forward them through.
 
-## CLI Reference
+Everything else stays simulated.
 
 ```sh
-npx counterfact@latest [openapi.yaml] [destination] [options]
+npx counterfact@latest openapi.yaml api --proxy-url https://api.example.com
 ```
 
-| Option              | Description                                 |
-| ------------------- | ------------------------------------------- |
-| `--port <number>`   | Server port (default: `3100`)               |
-| `-o, --open`        | Open browser automatically                  |
-| `-g, --generate`    | Generate route and type files               |
-| `-w, --watch`       | Generate and watch for spec changes         |
-| `-s, --serve`       | Start the mock server                       |
-| `-r, --repl`        | Start the interactive REPL                  |
-| `--spec <path>`     | Path or URL to the OpenAPI document         |
-| `--proxy-url <url>` | Forward all requests to this URL by default |
-| `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
-| `--no-validate-request` | Disable request validation against the OpenAPI spec |
+Toggle paths live:
+
+```
+⬣> .proxy on /payments
+⬣> .proxy on /auth
+⬣> .proxy off
+```
 
-Run `npx counterfact@latest --help` for the full list of options.
 
----
 
-## About the Author
+## What you just built
 
-Counterfact came out of a pattern I kept seeing: teams are slowed down more by coordination than by code.
+In five minutes, you turned a static spec into a working system:
 
-I’ve spent 25+ years building software and improving how engineering organizations operate across large enterprises, regulated industries, and complex systems. Most of that time, the real constraint wasn’t technology—it was dependency and coordination.
+- **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
 
-Counterfact is one way of removing that friction.
 
-I’m currently available — not for long.
 
-→ https://patrickmcelhaney.org
+## Go deeper
+
+| | |
+|---|---|
+| [Getting started](./docs/getting-started.md) | Detailed walkthrough with state, REPL, and proxy |
+| [Usage](./docs/usage.md) | Feature index: routes, context, REPL, proxy, middleware, and more |
+| [Patterns](./docs/patterns/index.md) | Failures, latency, AI sandboxes, integration tests |
+| [Reference](./docs/reference.md) | `$` API, CLI flags, architecture |
+| [How it compares](./docs/comparison.md) | json-server, WireMock, Prism, Microcks, MSW |
+| [FAQ](./docs/faq.md) | State, types, regeneration |
+| [Petstore example](https://github.com/counterfact/example-petstore) | Full working example |
 
 <div align="center" markdown="1">
 
-[Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
+[Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
-</div>
+</div>

package/bin/README.md

@@ -18,11 +18,13 @@ npx counterfact@latest openapi.yaml ./api [options]
 │     counterfact.js         │
 │                            │
 │  1. Parse args (Commander) │
-│  2. Resolve paths          │
-│  3. Build Config object    │
-│  4. Run migrations if      │
+│  2. Load counterfact.yaml  │
+│  3. Merge config + args    │
+│  4. Resolve paths          │
+│  5. Build Config object    │
+│  6. Run migrations if      │
 │     old layout detected    │
-│  5. Call start(config)     │
+│  7. Call start(config)     │
 │     from src/app.ts        │
 └────────────────────────────┘
 ```
@@ -42,5 +44,23 @@ npx counterfact@latest openapi.yaml ./api [options]
 | `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
 | `--no-update-check` | Disable the npm update check on startup |
 | `--no-validate-request` | Disable request validation against the OpenAPI spec |
+| `--config <path>` | Path to a `counterfact.yaml` config file (default: `counterfact.yaml` in the current directory) |
 
 Run `npx counterfact@latest --help` to see the full option list.
+
+### Config File
+
+Any CLI option can also be specified in a `counterfact.yaml` file in the current working directory. Command-line options always take precedence.
+
+```yaml
+# counterfact.yaml
+spec: ./openapi.yaml
+port: 8080
+serve: true
+repl: true
+watch: true
+proxy-url: https://api.example.com
+prefix: /api/v1
+```
+
+Use `--config <path>` to load a config file from a non-default location.

package/bin/counterfact.js

@@ -41,7 +41,9 @@ import { PostHog } from "posthog-node";
 
 const MIN_NODE_VERSION = 17;
 
-if (Number.parseInt(process.versions.node.split("."), 10) < MIN_NODE_VERSION) {
+if (
+  Number.parseInt(process.versions.node.split(".")[0], 10) < MIN_NODE_VERSION
+) {
   process.stdout.write(
     `Counterfact works with Node version ${MIN_NODE_VERSION}+. You are running version ${process.version}`,
   );
@@ -152,6 +154,13 @@ const { updateRouteTypes } = await import(
       : "../dist/migrate/update-route-types.js",
   )
 );
+const { loadConfigFile } = await import(
+  resolve(
+    nativeTs
+      ? "../src/util/load-config-file.js"
+      : "../dist/util/load-config-file.js",
+  )
+);
 
 const DEFAULT_PORT = 3100;
 
@@ -269,6 +278,31 @@ async function main(source, destination) {
       ? Promise.resolve()
       : checkForUpdates(CURRENT_VERSION);
 
+  // Load the config file (counterfact.yaml by default, or --config <path>).
+  // CLI options always take precedence over config file settings.
+  const configFilePath = nodePath.resolve(options.config ?? "counterfact.yaml");
+  const fileConfig = await loadConfigFile(
+    configFilePath,
+    options.config !== undefined,
+  );
+  debug("fileConfig: %o", fileConfig);
+
+  // Apply config file values for any option that was not explicitly set on the
+  // command line (i.e. its source is "default" or it was never defined).
+  for (const [key, value] of Object.entries(fileConfig)) {
+    const optionSource = program.getOptionValueSource(key);
+
+    if (optionSource !== "cli") {
+      options[key] = value;
+    }
+  }
+
+  // If the config file specifies a destination and none was given on the CLI,
+  // use it (destination has no Commander option — it's a positional argument).
+  if (fileConfig.destination !== undefined && destination === ".") {
+    destination = String(fileConfig.destination);
+  }
+
   // --spec takes precedence over the positional [openapi.yaml] argument.
   // When --spec is provided, the [openapi.yaml] positional slot shifts to
   // become the [destination] argument (so `counterfact --spec api.yaml ./api`
@@ -343,6 +377,7 @@ async function main(source, destination) {
     startServer: options.serve,
     buildCache: options.buildCache || false,
     validateRequests: options.validateRequest !== false,
+    validateResponses: options.validateResponse !== false,
 
     watch: {
       routes: options.watch || options.watchRoutes,
@@ -550,5 +585,13 @@ program
     "--no-validate-request",
     "disable request validation against the OpenAPI spec",
   )
+  .option(
+    "--no-validate-response",
+    "disable response validation against the OpenAPI spec",
+  )
+  .option(
+    "--config <path>",
+    "path to a counterfact.yaml config file (default: counterfact.yaml in the current directory)",
+  )
   .action(main)
   .parse(process.argv);

package/dist/app.js

@@ -1,19 +1,21 @@
 import fs, { rm } from "node:fs/promises";
 import nodePath from "node:path";
-import { dereference } from "@apidevtools/json-schema-ref-parser";
-import createDebug from "debug";
 import { createHttpTerminator } from "http-terminator";
 import { startRepl as startReplServer } from "./repl/repl.js";
 import { ContextRegistry } from "./server/context-registry.js";
 import { createKoaApp } from "./server/create-koa-app.js";
-import { Dispatcher, } from "./server/dispatcher.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 { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
-const debug = createDebug("counterfact:app");
+export { loadOpenApiDocument } from "./server/load-openapi-document.js";
 const allowedMethods = [
     "all",
     "head",
@@ -24,16 +26,6 @@ const allowedMethods = [
     "patch",
     "options",
 ];
-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 mswHandlers = {};
 export async function handleMswRequest(request) {
     const { method, rawPath } = request;
@@ -86,15 +78,20 @@ export async function counterfact(config) {
     }
     const registry = new Registry();
     const contextRegistry = new ContextRegistry();
+    const scenarioRegistry = new ScenarioRegistry();
     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);
+    const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry, nodePath.join(modulesPath, "scenarios").replaceAll("\\", "/"), scenarioRegistry);
+    contextRegistry.addEventListener("context-changed", () => {
+        void writeApplyContextType(modulesPath);
+    });
     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)) {
@@ -105,6 +102,7 @@ export async function counterfact(config) {
         }
         let httpTerminator;
         if (startServer) {
+            await openApiWatcher.watch();
             if (!nativeTs) {
                 await transpiler.watch();
             }
@@ -127,6 +125,7 @@ export async function counterfact(config) {
                 await codeGenerator.stopWatching();
                 await transpiler.stopWatching();
                 await moduleLoader.stopWatching();
+                await openApiWatcher.stopWatching();
                 await httpTerminator?.terminate();
             },
         };
@@ -138,6 +137,6 @@ export async function counterfact(config) {
         registry,
         start,
         startRepl: () => startReplServer(contextRegistry, registry, config, undefined, // use the default print function (stdout)
-        openApiDocument),
+        openApiDocument, scenarioRegistry),
     };
 }

package/dist/counterfact-types/cookie-options.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/counterfact-response.js

@@ -0,0 +1,7 @@
+/**
+ * A unique symbol used as a brand for the `COUNTERFACT_RESPONSE` type.
+ * This prevents arbitrary objects from being accidentally treated as a
+ * completed response value.
+ */
+const counterfactResponse = Symbol("Counterfact Response");
+export {};

package/dist/counterfact-types/example-names.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/example.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/generic-response-builder.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/http-status-code.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/if-has-key.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/index.js

@@ -1,2 +1 @@
-const counterfactResponse = Symbol("Counterfact Response");
 export {};

package/dist/counterfact-types/maybe-promise.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/media-type.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/omit-all.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/omit-value-when-never.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/open-api-content.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/open-api-operation.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/open-api-parameters.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/open-api-response.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/random-function.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/response-builder-factory.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/response-builder.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/wide-operation-argument.js

@@ -0,0 +1 @@
+export {};

package/dist/counterfact-types/wide-response-builder.js

@@ -0,0 +1 @@
+export {};