counterfact 2.2.0 → 2.2.1

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.

package/bin/README.md

@@ -0,0 +1,43 @@
+# `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 |
+| `--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/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/index.ts

@@ -37,6 +37,7 @@ type OmitValueWhenNever<Base> = Pick<
 
 interface OpenApiResponse {
   content: { [key: MediaType]: OpenApiContent };
+  examples?: { [key: string]: unknown };
   headers: { [key: string]: OpenApiHeader };
   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>;
 }>;
@@ -252,6 +263,7 @@ interface OpenApiOperation {
 }
 
 interface WideResponseBuilder {
+  example: (name: string) => WideResponseBuilder;
   header: (body: unknown) => WideResponseBuilder;
   html: (body: unknown) => WideResponseBuilder;
   json: (body: unknown) => WideResponseBuilder;
@@ -274,6 +286,7 @@ interface WideOperationArgument {
 export type { COUNTERFACT_RESPONSE };
 
 export type {
+  ExampleNames,
   HttpStatusCode,
   MaybePromise,
   MediaType,

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

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.2.1",
   "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",