counterfact 2.9.0 → 2.10.0

package/README.md

@@ -1,34 +1,57 @@
 <div align="center" markdown="1">
 
-<img src="./counterfact.svg" alt="Counterfact" border=0>
+<h1><img src="./counterfact.svg" alt="Counterfact" border=0></h1>
 
 <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/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
+![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) ![friction 0%](https://img.shields.io/badge/friction-0%25-brightgreen)
 
 </div>
 
-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.
+<div align="center" markdown="1">
+<h2>Mock servers work—until you need state, failures, or control mid-run.</h2>
+</div
+
+Static responses aren’t enough. There’s no shared state. You can’t inject failures. You can’t test real workflows.<br>
+Mock servers make it easy to get started, but hard to keep going.<br>
+Counterfact is an API simulator without those limits. 
+
+Point it at an [OpenAPI](https://www.openapis.org) document and get a live, stateful API in seconds. 
+- Type-safe TypeScript handlers for every endpoint  
+- Hot reloading as you edit  
+- Shared state across routes  
+- **A built-in REPL to control behavior at runtime**  
+- Optional proxying to real backends
+
+Flexbile for humans. Stable for [AI agents](https://github.com/counterfact/api-simulator/blob/main/docs/patterns/ai-assisted-implementation.md).
+
+You’re in control—without restarting.
+
+For a *frontend developer* waiting on a backend,<br>
+a *test engineer* who needs clean, reproducible state,<br>
+or an *AI agent* that needs a stable API
+
+Real enough to be useful. Fake enough to be usable.
+
 
-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.
+## Try it now 
 
 ```sh
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
+> Starts a local server with a live REPL to inspect and control API behavior  
 > Requires Node ≥ 22.0.0
 
 ## 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 |
+- [Getting started](./docs/getting-started.md) – Detailed walkthrough with state, REPL, and proxy  
+- [Patterns](./docs/patterns/index.md) – How Counterfact transforms your workflow  
+- [Example repo](https://github.com/counterfact/example-petstore) – Using Counterfact to implement the Swagger Petstore  
+- [How it compares](./docs/comparison.md) – json-server, WireMock, Prism, Microcks, MSW  
+- [Usage](./docs/usage.md) – Explore features and how to use them  
+- [Reference](./docs/reference.md) – `$` API, CLI flags, architecture  
+- [FAQ](./docs/faq.md) – State, types, regeneration  
 
 <div align="center" markdown="1">
 

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

@@ -67,7 +67,7 @@ async function buildTypeNameMapping(specification) {
                     return;
                 }
                 // Create the type coder to get the correct type name
-                const typeCoder = new OperationTypeCoder(operation, requestMethod, securitySchemes);
+                const typeCoder = new OperationTypeCoder(operation, "", requestMethod, securitySchemes);
                 // Get the type name (first from the names generator)
                 const typeName = typeCoder.names().next().value;
                 methodMap.set(requestMethod.toUpperCase(), typeName);

package/dist/server/counterfact-types/generic-response-builder.ts

@@ -157,8 +157,7 @@ export type GenericResponseBuilder<
   : object extends OmitValueWhenNever<Omit<Response, "examples">>
     ? COUNTERFACT_RESPONSE
     : keyof OmitValueWhenNever<Omit<Response, "examples">> extends "headers"
-      ? {
-          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
+      ? COUNTERFACT_RESPONSE & {
           header: HeaderFunction<Response>;
         }
       : GenericResponseBuilderInner<Response>;

package/dist/server/counterfact-types/open-api-parameters.ts

@@ -5,12 +5,15 @@
  * argument object.
  */
 export interface OpenApiParameters {
+  explode?: boolean;
   in: "body" | "cookie" | "formData" | "header" | "path" | "query";
   name: string;
   required?: boolean;
   schema?: {
     [key: string]: unknown;
+    properties?: Record<string, unknown>;
     type?: string;
   };
+  style?: string;
   type?: "string" | "number" | "integer" | "boolean";
 }

package/dist/server/dispatcher.js

@@ -2,7 +2,7 @@ import { mediaTypes } from "@hapi/accept";
 import createDebugger from "debug";
 import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
-import { validateRequest } from "./request-validator.js";
+import { isExplodedObjectQueryParam, validateRequest, } from "./request-validator.js";
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
@@ -36,6 +36,45 @@ function parseCookies(cookieHeader) {
     }
     return cookies;
 }
+/**
+ * Gathers exploded object query parameters back into a nested object under the
+ * parameter's own name.
+ *
+ * Per OpenAPI 3.x, a query parameter of type `object` with `style: form` and
+ * `explode: true` (both defaults for query params) is serialised as individual
+ * query parameters — one per object property.  This function reconstructs the
+ * object so that the route handler can access `$.query.<paramName>` rather than
+ * only the individual flat parameters.
+ *
+ * Properties that are "claimed" by an object parameter are removed from the
+ * top-level map and placed under the parameter name. Unclaimed keys remain at
+ * the top level.
+ *
+ * @param query - The raw parsed query-string map from the HTTP request.
+ * @param parameters - The OpenAPI parameter definitions for the current operation.
+ * @returns A new map with exploded object parameters reconstructed as nested objects.
+ */
+export function collectExplodedObjectParams(query, parameters) {
+    const result = { ...query };
+    for (const parameter of parameters) {
+        if (!isExplodedObjectQueryParam(parameter))
+            continue;
+        const properties = parameter.schema?.properties;
+        if (!properties)
+            continue;
+        const obj = {};
+        for (const key of Object.keys(properties)) {
+            if (key in result) {
+                obj[key] = result[key];
+                delete result[key];
+            }
+        }
+        if (Object.keys(obj).length > 0) {
+            result[parameter.name] = obj;
+        }
+    }
+    return result;
+}
 /**
  * Core HTTP request dispatcher.
  *
@@ -208,6 +247,9 @@ export class Dispatcher {
                 };
             }
         }
+        // Reconstruct exploded object query parameters so that `$.query.<name>`
+        // contains the assembled object instead of only the individual flat keys.
+        const processedQuery = collectExplodedObjectParams(query, operation?.parameters ?? []);
         const continuousDistribution = (min, max) => {
             return min + Math.random() * (max - min);
         };
@@ -238,7 +280,8 @@ export class Dispatcher {
                     status: fetchResponse.status,
                 };
             },
-            query,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- object params are reconstructed and typed by generated route types
+            query: processedQuery,
             // @ts-expect-error - Might be pushing the limits of what TypeScript can do here
             response: createResponseBuilder(operation ?? { responses: {} }, this.config), // Pass config
             tools: new Tools({ headers }),

package/dist/server/request-validator.js

@@ -4,10 +4,51 @@ const ajv = new Ajv({
     strict: false,
     coerceTypes: false,
 });
+/**
+ * Returns `true` when a query parameter should be serialized as exploded form
+ * style — meaning its object properties appear as individual query parameters
+ * instead of being passed under the parameter's own name.
+ *
+ * Per OpenAPI 3.x: for `in: query`, the default `style` is `form` and the
+ * default `explode` for `form` is `true`.  An object-type parameter with these
+ * defaults (or with them set explicitly) uses exploded form serialization.
+ */
+export function isExplodedObjectQueryParam(parameter) {
+    if (parameter.in !== "query")
+        return false;
+    const schema = parameter.schema;
+    if (!schema)
+        return false;
+    // Must be an object type (explicit type or implied by presence of properties)
+    const isObjectType = schema.type === "object" || schema.properties !== undefined;
+    if (!isObjectType)
+        return false;
+    // style must be "form" (the default for query params) or unset
+    if (parameter.style !== undefined && parameter.style !== "form")
+        return false;
+    // explode must not be explicitly false (default for form style is true)
+    if (parameter.explode === false)
+        return false;
+    return true;
+}
 function findMissingRequired(parameters, location, values) {
     return parameters
         .filter((p) => p.in === location && p.required === true)
-        .filter((p) => !(p.name in values) || values[p.name] === undefined)
+        .filter((p) => {
+        // For exploded object query params the individual properties appear as
+        // separate query parameters, so we check for those instead of the name.
+        if (location === "query" && isExplodedObjectQueryParam(p)) {
+            const properties = p.schema?.properties;
+            if (!properties) {
+                // Free-form object with no declared properties: treat as always
+                // satisfied — we cannot know which keys belong to the parameter.
+                return false;
+            }
+            // The parameter is "missing" only when none of its properties are present.
+            return !Object.keys(properties).some((key) => key in values);
+        }
+        return !(p.name in values) || values[p.name] === undefined;
+    })
         .map((p) => `${location} parameter '${p.name}' is required`);
 }
 export function validateRequest(operation, request) {

package/dist/typescript-generator/code-generator.js

@@ -116,7 +116,7 @@ export class CodeGenerator extends EventTarget {
                 }
                 repository
                     .get(`routes${path}.ts`)
-                    .export(new OperationCoder(operation, requestMethod, securitySchemes));
+                    .export(new OperationCoder(operation, "", requestMethod, securitySchemes));
             });
         });
         debug("telling the repository to write the files to %s", destination);

package/dist/typescript-generator/coder.js

@@ -12,8 +12,10 @@ import { RESERVED_WORDS } from "./reserved-words.js";
  */
 export class Coder {
     requirement;
-    constructor(requirement) {
+    version;
+    constructor(requirement, version = "") {
         this.requirement = requirement;
+        this.version = version;
     }
     /**
      * A stable cache key for this coder, composed of the constructor name and
@@ -84,7 +86,7 @@ export class Coder {
             return this;
         }
         const requirement = await this.requirement.reference();
-        return new this.constructor(requirement);
+        return new this.constructor(requirement, this.version);
     }
     /**
      * Generator that yields candidate export names for this coder.

package/dist/typescript-generator/operation-coder.js

@@ -14,9 +14,9 @@ import { OperationTypeCoder, } from "./operation-type-coder.js";
 export class OperationCoder extends Coder {
     requestMethod;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -40,7 +40,7 @@ export class OperationCoder extends Coder {
     }`;
     }
     typeDeclaration(_namespace, script) {
-        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.requestMethod, this.securitySchemes);
+        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
         return script.importType(operationTypeCoder);
     }
     modulePath() {

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

@@ -36,9 +36,9 @@ function sanitizeIdentifier(value) {
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -79,7 +79,7 @@ export class OperationTypeCoder extends TypeCoder {
         }
         const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
         const typeName = `${baseName}_${capitalize(parameterKind)}`;
-        const coder = new ParameterExportTypeCoder(this.requirement, typeName, inlineType, parameterKind);
+        const coder = new ParameterExportTypeCoder(this.requirement, this.version, typeName, inlineType, parameterKind);
         coder._modulePath = modulePath;
         return script.export(coder, true);
     }
@@ -99,7 +99,7 @@ export class OperationTypeCoder extends TypeCoder {
                 return response.get("content").map((content, contentType) => `{  
               status: ${status}, 
               contentType?: "${contentType}",
-              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
             }`);
             }
             if (response.has("schema")) {
@@ -111,7 +111,7 @@ export class OperationTypeCoder extends TypeCoder {
                         .map((contentType) => `{
             status: ${status},
             contentType?: "${contentType}",
-            body?: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            body?: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
           }`)
                         .join(" | ");
                 }
@@ -149,10 +149,10 @@ export class OperationTypeCoder extends TypeCoder {
         script.importSharedType("COUNTERFACT_RESPONSE");
         const contextTypeImportName = script.importExternalType("Context", CONTEXT_FILE_TOKEN);
         const parameters = this.requirement.get("parameters");
-        const queryType = new ParametersTypeCoder(parameters, "query").write(script);
-        const pathType = new ParametersTypeCoder(parameters, "path").write(script);
-        const headersType = new ParametersTypeCoder(parameters, "header").write(script);
-        const cookieType = new ParametersTypeCoder(parameters, "cookie").write(script);
+        const queryType = new ParametersTypeCoder(parameters, this.version, "query").write(script);
+        const pathType = new ParametersTypeCoder(parameters, this.version, "path").write(script);
+        const headersType = new ParametersTypeCoder(parameters, this.version, "header").write(script);
+        const cookieType = new ParametersTypeCoder(parameters, this.version, "cookie").write(script);
         const bodyRequirement = (this.requirement.get("consumes") ??
             this.requirement.specification?.rootRequirement?.get("consumes"))
             ? parameters
@@ -161,10 +161,11 @@ export class OperationTypeCoder extends TypeCoder {
             : this.requirement.select("requestBody/content/application~1json/schema");
         const bodyType = bodyRequirement === undefined
             ? "never"
-            : new SchemaTypeCoder(bodyRequirement).write(script);
-        const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), (this.requirement.get("produces")?.data ??
+            : new SchemaTypeCoder(bodyRequirement, this.version).write(script);
+        const openApi2MediaTypes = (this.requirement.get("produces")?.data ??
             this.requirement.specification?.rootRequirement?.get("produces")
-                ?.data)).write(script);
+                ?.data);
+        const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), this.version, openApi2MediaTypes).write(script);
         const proxyType = "(url: string) => COUNTERFACT_RESPONSE";
         const delayType = "(milliseconds: number, maxMilliseconds?: number) => Promise<void>";
         // Get the base name for this operation and export parameter types
@@ -174,6 +175,6 @@ export class OperationTypeCoder extends TypeCoder {
         const pathTypeName = this.exportParameterType(script, "path", pathType, baseName, modulePath);
         const headersTypeName = this.exportParameterType(script, "headers", headersType, baseName, modulePath);
         const cookieTypeName = this.exportParameterType(script, "cookie", cookieType, baseName, modulePath);
-        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<${this.responseTypes(script)} | { status: 415, contentType: "text/plain", body: string } | COUNTERFACT_RESPONSE | { ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE }>`;
+        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<COUNTERFACT_RESPONSE>`;
     }
 }

package/dist/typescript-generator/parameter-export-type-coder.js

@@ -4,8 +4,8 @@ export class ParameterExportTypeCoder extends TypeCoder {
     _typeCode;
     _parameterKind;
     _modulePath;
-    constructor(requirement, typeName, typeCode, parameterKind) {
-        super(requirement);
+    constructor(requirement, version, typeName, typeCode, parameterKind) {
+        super(requirement, version);
         this._typeName = typeName;
         this._typeCode = typeCode;
         this._parameterKind = parameterKind;

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

@@ -4,8 +4,8 @@ import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ParametersTypeCoder extends TypeCoder {
     placement;
-    constructor(requirement, placement) {
-        super(requirement);
+    constructor(requirement, version = "", placement = "") {
+        super(requirement, version);
         this.placement = placement;
     }
     names() {
@@ -26,7 +26,7 @@ export class ParametersTypeCoder extends TypeCoder {
                 : parameter;
             const comment = buildJsDoc(parameter.data);
             const commentPrefix = comment ? `\n${comment}` : "";
-            const typeString = new SchemaTypeCoder(schema).write(script);
+            const typeString = new SchemaTypeCoder(schema, this.version).write(script);
             return `${commentPrefix}"${name}"${optionalFlag}: ${typeString}`;
         });
         if (typeDefinitions.length === 0) {

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

@@ -1,10 +1,11 @@
 import { printObject } from "./printers.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
+import { pathJoin } from "../util/forward-slash-path.js";
 export class ResponseTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     names() {
@@ -17,14 +18,14 @@ export class ResponseTypeCoder extends TypeCoder {
                 .map((content, mediaType) => [
                 mediaType,
                 `{ 
-            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
          }`,
             ]);
         }
         return this.openApi2MediaTypes.map((mediaType) => [
             mediaType,
             `{
-            schema: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            schema: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
          }`,
         ]);
     }
@@ -39,7 +40,7 @@ export class ResponseTypeCoder extends TypeCoder {
             .get("headers")
             .map((value, name) => [
             name,
-            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value).write(script)}}`,
+            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value, this.version).write(script)}}`,
         ]);
     }
     printHeaders(script, response) {
@@ -77,7 +78,7 @@ export class ResponseTypeCoder extends TypeCoder {
         return printObject(exampleNames.map((name) => [name, "unknown"]));
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"]}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"] + ".ts");
     }
     writeCode(script) {
         return `{

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

@@ -3,8 +3,8 @@ import { ResponseTypeCoder } from "./response-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ResponsesTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     typeForDefaultStatusCode(listedStatusCodes) {
@@ -23,7 +23,7 @@ export class ResponsesTypeCoder extends TypeCoder {
     buildResponseObjectType(script) {
         return printObjectWithoutQuotes(this.requirement.map((response, responseCode) => [
             this.normalizeStatusCode(responseCode),
-            new ResponseTypeCoder(response, this.openApi2MediaTypes).write(script),
+            new ResponseTypeCoder(response, this.version, this.openApi2MediaTypes).write(script),
         ]));
     }
     writeCode(script) {

package/dist/typescript-generator/schema-coder.js

@@ -13,7 +13,7 @@ export class SchemaCoder extends Coder {
     objectSchema(script) {
         const { properties, required } = this.requirement.data;
         const propertyLines = Object.keys(properties ?? {}).map((name) => {
-            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`));
+            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`), this.version);
             return `"${name}": ${schemaCoder.write(script)}`;
         });
         return `
@@ -27,7 +27,7 @@ export class SchemaCoder extends Coder {
     arraySchema(script) {
         return `{
         type: "array",     
-        items: ${new SchemaCoder(this.requirement.get("items")).write(script)}
+        items: ${new SchemaCoder(this.requirement.get("items"), this.version).write(script)}
       }`;
     }
     typeDeclaration(_namespace, script) {

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

@@ -1,5 +1,6 @@
 import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.js";
+import { pathJoin } from "../util/forward-slash-path.js";
 export class SchemaTypeCoder extends TypeCoder {
     names() {
         return super.names(this.requirement.data["$ref"]?.split("/").at(-1));
@@ -16,7 +17,7 @@ export class SchemaTypeCoder extends TypeCoder {
             return "unknown";
         }
         const requirement = this.requirement.get("additionalProperties");
-        return new SchemaTypeCoder(requirement).write(script);
+        return new SchemaTypeCoder(requirement, this.version).write(script);
     }
     objectSchema(script) {
         const { data } = this.requirement;
@@ -28,7 +29,8 @@ export class SchemaTypeCoder extends TypeCoder {
             const optionalFlag = isRequired ? "" : "?";
             const comment = buildJsDoc(property.data);
             const commentPrefix = comment ? `\n${comment}` : "";
-            return `${commentPrefix}"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(script)}`;
+            const propertyType = new SchemaTypeCoder(property, this.version).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${propertyType}`;
         });
         if (typedData.additionalProperties) {
             properties.push(`[key: string]: ${this.additionalPropertiesType(script)}`);
@@ -36,7 +38,7 @@ export class SchemaTypeCoder extends TypeCoder {
         return `{${properties.join(",")}}`;
     }
     arraySchema(script) {
-        return `Array<${new SchemaTypeCoder(this.requirement.get("items")).write(script)}>`;
+        return `Array<${new SchemaTypeCoder(this.requirement.get("items"), this.version).write(script)}>`;
     }
     writePrimitive(value) {
         if (typeof value === "string") {
@@ -79,7 +81,7 @@ export class SchemaTypeCoder extends TypeCoder {
         }
         const key = matchingKey();
         const items = (allOf ?? anyOf ?? oneOf);
-        const types = items.map((_item, index) => new SchemaTypeCoder(this.requirement.get(key).get(index)).write(script));
+        const types = items.map((_item, index) => new SchemaTypeCoder(this.requirement.get(key).get(index), this.version).write(script));
         return types.join(allOf ? " & " : " | ");
     }
     writeEnum(_script, requirement) {
@@ -88,7 +90,7 @@ export class SchemaTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"].replace(/^#\//u, "")}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"].replace(/^#\//u, "") + ".ts");
     }
     writeCode(script) {
         const { allOf, anyOf, oneOf, type, format } = this.requirement.data;

package/dist/typescript-generator/script.js

@@ -17,6 +17,7 @@ export class Script {
     repository;
     comments;
     exports;
+    versions;
     imports;
     externalImport;
     cache;
@@ -26,6 +27,7 @@ export class Script {
         this.repository = repository;
         this.comments = [];
         this.exports = new Map();
+        this.versions = new Map();
         this.imports = new Map();
         this.externalImport = new Map();
         this.cache = new Map();
@@ -176,13 +178,53 @@ export class Script {
     exportType(coder) {
         return this.export(coder, true);
     }
+    declareVersion(coder, name) {
+        const version = coder.version;
+        const versions = this.versions.get(name) ?? new Map();
+        this.versions.set(name, versions);
+        if (versions.has(version)) {
+            return;
+        }
+        const versionStatement = {
+            beforeExport: "",
+            done: false,
+            id: coder.id,
+            isDefault: false,
+            isType: true,
+            jsdoc: "",
+            typeDeclaration: "",
+        };
+        versionStatement.promise = coder
+            .delegate()
+            .then((availableCoder) => {
+            versionStatement.code = availableCoder.write(this);
+            return availableCoder;
+        })
+            .catch((error) => {
+            versionStatement.code = `unknown /* error declaring version "${name}" (${version}) for ${this.path}: ${error.message} */`;
+            versionStatement.error = error;
+            return undefined;
+        })
+            .finally(() => {
+            versionStatement.done = true;
+        });
+        versions.set(version, versionStatement);
+    }
     /** `true` while at least one export promise is still pending. */
     isInProgress() {
-        return Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done);
+        return (Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done) ||
+            Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .some((versionStatement) => !versionStatement.done));
     }
     /** Returns a promise that resolves when all pending export promises settle. */
     finished() {
-        return Promise.all(Array.from(this.exports.values(), (value) => value.promise));
+        return Promise.all([
+            ...Array.from(this.exports.values(), (value) => value.promise),
+            ...Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .map((value) => value.promise),
+        ]);
     }
     externalImportStatements() {
         return Array.from(this.externalImport, ([name, { isDefault, isType, modulePath }]) => `import${isType ? " type" : ""} ${isDefault ? name : `{ ${name} }`} from "${modulePath}";`);
@@ -208,18 +250,31 @@ export class Script {
             return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
         });
     }
+    versionsTypeStatements() {
+        if (this.versions.size === 0) {
+            return [];
+        }
+        const names = Array.from(this.versions, ([name, versions]) => {
+            const mappedVersions = Array.from(versions, ([version, versionStatement]) => `"${version}": ${versionStatement.code}`);
+            return `"${name}": { ${mappedVersions.join(", ")} }`;
+        });
+        return [`export type Versions = { ${names.join(", ")} };`];
+    }
     /**
      * Formats the fully assembled script source with Prettier and returns it.
      *
      * All pending export promises are awaited before formatting.
      */
-    contents() {
+    async contents() {
+        await this.finished();
         return format([
             this.comments.map((comment) => `// ${comment}`).join("\n"),
             this.comments.length > 0 ? "\n\n" : "",
             this.externalImportStatements().join("\n"),
             this.importStatements().join("\n"),
             "\n\n",
+            this.versionsTypeStatements().join("\n"),
+            this.versions.size > 0 ? "\n\n" : "",
             this.exportStatements().join("\n\n"),
         ].join(""), { parser: "typescript" });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.9.0",
+  "version": "2.10.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",