counterfact 2.2.0 → 2.3.0

package/README.md

@@ -96,6 +96,16 @@ export const DELETE: HTTP_DELETE = ($) => {
 };
 ```
 
+### Returning named examples
+
+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:
+
+```ts
+export const GET: HTTP_GET = ($) => {
+  return $.response[200].example("successResponse");
+};
+```
+
 ### State management with plain old objects
 
 Use a `_.context.ts` file to share in-memory state across routes. POST data and GET it back, just like a real API.
@@ -192,6 +202,7 @@ npx counterfact@latest [openapi.yaml] [destination] [options]
 | `-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`)           |
 

package/bin/README.md

@@ -0,0 +1,44 @@
+# `bin/` — CLI Entry Point
+
+This directory contains the executable script that is run when a developer invokes `npx counterfact` (or `counterfact` after a global install).
+
+## Files
+
+| File | Description |
+|---|---|
+| `counterfact.js` | Parses command-line arguments with [Commander](https://github.com/tj/commander.js), validates inputs, and calls `counterfact()` from `src/app.ts` to start the server, code generator, file watcher, and/or REPL |
+
+## How It Works
+
+```
+npx counterfact openapi.yaml ./api [options]
+        │
+        ▼
+┌────────────────────────────┐
+│     counterfact.js         │
+│                            │
+│  1. Parse args (Commander) │
+│  2. Resolve paths          │
+│  3. Build Config object    │
+│  4. Run migrations if      │
+│     old layout detected    │
+│  5. Call start(config)     │
+│     from src/app.ts        │
+└────────────────────────────┘
+```
+
+### Key CLI Options
+
+| Option | Description |
+|---|---|
+| `--port <number>` | HTTP server port (default: `3100`) |
+| `-o, --open` | Open the dashboard in a browser after startup |
+| `-g, --generate` | Generate route and type files from the OpenAPI spec |
+| `-w, --watch` | Re-generate whenever the spec changes |
+| `-s, --serve` | Start the HTTP server |
+| `-r, --repl` | Start the interactive REPL |
+| `--spec <path>` | Path or URL to the OpenAPI document (alternative to positional argument) |
+| `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
+| `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
+
+Run `npx counterfact --help` to see the full option list.

package/bin/counterfact.js

@@ -102,11 +102,20 @@ async function main(source, destination) {
 
   const options = program.opts();
 
+  // --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`
+  // works the same as `counterfact api.yaml ./api`).
+  if (options.spec) {
+    if (source !== "_") {
+      destination = source;
+    }
+    source = options.spec;
+  }
+
   const args = process.argv;
 
-  const destinationPath = nodePath
-    .join(process.cwd(), destination)
-    .replaceAll("\\", "/");
+  const destinationPath = nodePath.resolve(destination).replaceAll("\\", "/");
 
   const basePath = nodePath.resolve(destinationPath).replaceAll("\\", "/");
 
@@ -155,6 +164,8 @@ async function main(source, destination) {
         options.watch ||
         options.watchTypes ||
         options.buildCache,
+
+      prune: Boolean(options.prune),
     },
 
     openApiPath: source,
@@ -326,5 +337,13 @@ program
     "--always-fake-optionals",
     "random responses will include optional fields",
   )
+  .option(
+    "--prune",
+    "remove route files that no longer exist in the OpenAPI spec",
+  )
+  .option(
+    "--spec <string>",
+    "path or URL to OpenAPI document (alternative to the positional [openapi.yaml] argument)",
+  )
   .action(main)
   .parse(process.argv);

package/dist/client/README.md

@@ -0,0 +1,14 @@
+# `src/client/` — Built-in UI Templates
+
+This directory contains [Handlebars](https://handlebarsjs.com/) (`.hbs`) templates that are rendered by `page-middleware.ts` to produce the browser-facing pages bundled with Counterfact.
+
+## Files
+
+| File | Description |
+|---|---|
+| `index.html.hbs` | Template for the Counterfact dashboard (`/counterfact/`); lists registered routes and shows server status |
+| `rapi-doc.html.hbs` | Template for the interactive API documentation page (`/counterfact/swagger/`); embeds the [RapiDoc](https://rapidocweb.com/) viewer and adds VSCode "open file" links |
+
+## How It Works
+
+When a request arrives for `/counterfact/` or `/counterfact/swagger/`, `page-middleware.ts` compiles the appropriate template with runtime data (routes, port, base path, etc.) and sends the resulting HTML to the browser. No build step is required; templates are rendered on the fly.

package/dist/server/counterfact-types/OpenApiHeader.ts

@@ -1,3 +1,4 @@
 export interface OpenApiHeader {
-  schema: unknown;
+  required?: boolean;
+  schema: { [key: string]: unknown };
 }

package/dist/server/counterfact-types/index.ts

@@ -37,7 +37,8 @@ type OmitValueWhenNever<Base> = Pick<
 
 interface OpenApiResponse {
   content: { [key: MediaType]: OpenApiContent };
-  headers: { [key: string]: OpenApiHeader };
+  examples?: { [key: string]: unknown };
+  headers: { [key: string]: { schema: unknown } };
   requiredHeaders: string;
 }
 
@@ -105,9 +106,16 @@ type RandomFunction<Response extends OpenApiResponse> = <
   Header extends string & keyof Response["headers"],
 >() => COUNTERFACT_RESPONSE;
 
+type ExampleNames<Response extends OpenApiResponse> = Response extends {
+  examples: infer E;
+}
+  ? keyof E & string
+  : never;
+
 interface ResponseBuilder {
   [status: number | `${number} ${string}`]: ResponseBuilder;
   content?: { body: unknown; type: string }[];
+  example: (name: string) => ResponseBuilder;
   header: (name: string, value: string) => ResponseBuilder;
   headers: { [name: string]: string };
   html: (body: unknown) => ResponseBuilder;
@@ -143,6 +151,9 @@ export type GenericResponseBuilderInner<
   random: [keyof Response["content"]] extends [never]
     ? never
     : RandomFunction<Response>;
+  example: [ExampleNames<Response>] extends [never]
+    ? never
+    : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
   text: MaybeShortcut<["text/plain"], Response>;
   xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
 }>;
@@ -246,12 +257,16 @@ interface OpenApiOperation {
         };
       };
       examples?: { [key: string]: unknown };
+      headers?: {
+        [name: string]: OpenApiHeader;
+      };
       schema?: { [key: string]: unknown };
     };
   };
 }
 
 interface WideResponseBuilder {
+  example: (name: string) => WideResponseBuilder;
   header: (body: unknown) => WideResponseBuilder;
   html: (body: unknown) => WideResponseBuilder;
   json: (body: unknown) => WideResponseBuilder;
@@ -274,6 +289,7 @@ interface WideOperationArgument {
 export type { COUNTERFACT_RESPONSE };
 
 export type {
+  ExampleNames,
   HttpStatusCode,
   MaybePromise,
   MediaType,

package/dist/server/module-loader.js

@@ -110,10 +110,28 @@ export class ModuleLoader extends EventTarget {
             if (basename(pathName).startsWith("_.context.") &&
                 isContextModule(endpoint)) {
                 const loadContext = (path) => this.contextRegistry.find(path);
+                const contextDir = nodePath.dirname(unescapePathForWindows(pathName));
+                const readJson = async (relativePath) => {
+                    const absolutePath = nodePath.resolve(contextDir, relativePath);
+                    let content;
+                    try {
+                        content = await fs.readFile(absolutePath, "utf8");
+                    }
+                    catch {
+                        throw new Error(`readJson: could not read file at "${absolutePath}" (resolved from "${relativePath}" relative to "${contextDir}")`);
+                    }
+                    try {
+                        return JSON.parse(content);
+                    }
+                    catch {
+                        throw new Error(`readJson: file at "${absolutePath}" does not contain valid JSON`);
+                    }
+                };
                 this.contextRegistry.update(directory, 
                 // @ts-expect-error TS says Context has no constructable signatures but that's not true?
                 new endpoint.Context({
                     loadContext,
+                    readJson,
                 }));
                 return;
             }

package/dist/server/registry.js

@@ -37,7 +37,7 @@ export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
     constructor() {
-        this.middlewares.set("/", ($, respondTo) => respondTo($));
+        this.middlewares.set("", ($, respondTo) => respondTo($));
     }
     get routes() {
         return this.moduleTree.routes;
@@ -46,7 +46,7 @@ export class Registry {
         this.moduleTree.add(url, module);
     }
     addMiddleware(url, callback) {
-        this.middlewares.set(url, callback);
+        this.middlewares.set(url === "/" ? "" : url, callback);
     }
     remove(url) {
         this.moduleTree.remove(url);
@@ -111,11 +111,10 @@ export class Registry {
             };
             const middlewares = this.middlewares;
             function recurse(path, respondTo) {
+                debug("recursing path", path);
                 if (path === null)
                     return respondTo;
-                const nextPath = path === "/" || path === ""
-                    ? null
-                    : path.slice(0, path.lastIndexOf("/")) || "/";
+                const nextPath = path === "" ? null : path.slice(0, path.lastIndexOf("/"));
                 const middleware = middlewares.get(path);
                 if (middleware !== undefined) {
                     return recurse(nextPath, ($) => middleware($, respondTo));

package/dist/server/response-builder.js

@@ -63,6 +63,24 @@ export function createResponseBuilder(operation, config) {
                     ],
                 };
             },
+            example(name) {
+                if (operation.produces) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                if (response?.content === undefined) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const { content } = response;
+                return {
+                    ...this,
+                    content: Object.keys(content).map((type) => ({
+                        body: convertToXmlIfNecessary(type, content[type]?.examples?.[name]?.value, content[type]?.schema),
+                        type,
+                    })),
+                };
+            },
             random() {
                 if (config?.alwaysFakeOptionals) {
                     JSONSchemaFaker.option("alwaysFakeOptionals", true);
@@ -78,6 +96,12 @@ export function createResponseBuilder(operation, config) {
                     return unknownStatusCodeResponse(this.status);
                 }
                 const { content } = response;
+                const generatedHeaders = {};
+                for (const [name, header] of Object.entries(response.headers ?? {})) {
+                    if (header.required && !(name in (this.headers ?? {}))) {
+                        generatedHeaders[name] = JSONSchemaFaker.generate(header.schema ?? { type: "string" });
+                    }
+                }
                 return {
                     ...this,
                     content: Object.keys(content).map((type) => ({
@@ -86,6 +110,10 @@ export function createResponseBuilder(operation, config) {
                             : JSONSchemaFaker.generate(content[type]?.schema ?? { type: "object" }), content[type]?.schema),
                         type,
                     })),
+                    headers: {
+                        ...generatedHeaders,
+                        ...this.headers,
+                    },
                 };
             },
             randomLegacy() {

package/dist/typescript-generator/generate.js

@@ -5,6 +5,7 @@ import nodePath from "node:path";
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.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");
@@ -41,6 +42,11 @@ export async function generate(source, destination, generateOptions, repository
     debug("reading the #/paths from the specification");
     const paths = await getPathsFromSpecification(specification);
     debug("got %i paths", paths.size);
+    if (generateOptions.prune && generateOptions.routes) {
+        debug("pruning defunct route files");
+        await pruneRoutes(destination, paths.keys());
+        debug("done pruning");
+    }
     const securityRequirement = specification.getRequirement("#/components/securitySchemes");
     const securitySchemes = Object.values(securityRequirement?.data ?? {});
     paths.forEach((pathDefinition, key) => {

package/dist/typescript-generator/prune.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import createDebug from "debug";
+const debug = createDebug("counterfact:typescript-generator:prune");
+/**
+ * Collects all .ts route files in a directory recursively.
+ * Context files (_.context.ts) are excluded.
+ * @param {string} routesDir - Path to routes directory
+ * @param {string} currentPath - Current subdirectory being processed (relative to routesDir)
+ * @returns {Promise<string[]>} - Array of relative paths (using forward slashes)
+ */
+async function collectRouteFiles(routesDir, currentPath = "") {
+    const files = [];
+    try {
+        const fullDir = currentPath
+            ? nodePath.join(routesDir, currentPath)
+            : routesDir;
+        const entries = await fs.readdir(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = currentPath
+                ? `${currentPath}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory()) {
+                files.push(...(await collectRouteFiles(routesDir, relativePath)));
+            }
+            else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    return files;
+}
+/**
+ * Recursively removes empty directories under rootDir, but not rootDir itself.
+ * @param {string} dir - Directory to check
+ * @param {string} rootDir - Root directory that should never be removed
+ */
+async function removeEmptyDirectories(dir, rootDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await removeEmptyDirectories(nodePath.join(dir, entry.name), rootDir);
+        }
+    }
+    if (nodePath.resolve(dir) === nodePath.resolve(rootDir)) {
+        return;
+    }
+    const remaining = await fs.readdir(dir);
+    if (remaining.length === 0) {
+        await fs.rmdir(dir);
+        debug("removed empty directory: %s", dir);
+    }
+}
+/**
+ * Converts an OpenAPI path to the expected route file path (relative to routesDir).
+ * e.g. "/pet/{id}" -> "pet/{id}.ts", "/" -> "index.ts"
+ * @param {string} openApiPath
+ * @returns {string}
+ */
+function openApiPathToRouteFile(openApiPath) {
+    const filePath = openApiPath === "/" ? "index" : openApiPath.slice(1);
+    return `${filePath}.ts`;
+}
+/**
+ * Prunes route files that no longer correspond to any path in the OpenAPI spec.
+ * Context files (_.context.ts) are never pruned.
+ * @param {string} destination - Base destination directory (contains the routes/ sub-directory)
+ * @param {Iterable<string>} openApiPaths - Iterable of OpenAPI path strings (e.g. "/pet/{id}")
+ * @returns {Promise<number>} - Number of files removed
+ */
+export async function pruneRoutes(destination, openApiPaths) {
+    const routesDir = nodePath.join(destination, "routes");
+    const expectedFiles = new Set(Array.from(openApiPaths).map(openApiPathToRouteFile));
+    debug("expected route files: %o", Array.from(expectedFiles));
+    const actualFiles = await collectRouteFiles(routesDir);
+    debug("actual route files: %o", actualFiles);
+    let prunedCount = 0;
+    for (const file of actualFiles) {
+        const normalizedFile = file.replaceAll("\\", "/");
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(routesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(routesDir, routesDir);
+    debug("pruned %d files", prunedCount);
+    return prunedCount;
+}

package/dist/typescript-generator/response-type-coder.js

@@ -52,6 +52,25 @@ export class ResponseTypeCoder extends TypeCoder {
             .map(({ name }) => `"${name}"`);
         return requiredHeaders.length === 0 ? "never" : requiredHeaders.join(" | ");
     }
+    buildExamplesObjectType(response) {
+        if (!response.has("content")) {
+            return "{}";
+        }
+        const exampleNames = [];
+        response.get("content").forEach((content) => {
+            if (content.has("examples")) {
+                content.get("examples").forEach((_, name) => {
+                    if (!exampleNames.includes(name)) {
+                        exampleNames.push(name);
+                    }
+                });
+            }
+        });
+        if (exampleNames.length === 0) {
+            return "{}";
+        }
+        return printObject(exampleNames.map((name) => [name, "unknown"]));
+    }
     modulePath() {
         return `types/${this.requirement.data.$ref}.ts`;
     }
@@ -60,6 +79,7 @@ export class ResponseTypeCoder extends TypeCoder {
           headers: ${this.printHeaders(script, this.requirement)};
           requiredHeaders: ${this.printRequiredHeaders(this.requirement)};
           content: ${this.printContentObjectType(script, this.requirement)};
+          examples: ${this.buildExamplesObjectType(this.requirement)};
         }`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds — with stateful routes, hot reload, and REPL support.",
   "type": "module",
   "main": "./dist/app.js",
@@ -87,7 +87,7 @@
     "@types/debug": "^4.1.12",
     "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
-    "@types/koa": "3.0.1",
+    "@types/koa": "3.0.2",
     "@types/koa-bodyparser": "4.3.13",
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",