counterfact 2.11.0 → 2.12.0

package/README.md

@@ -4,7 +4,7 @@
 
 <br>
 
-![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)
+![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) ![Swagger 2.0](https://img.shields.io/badge/Swagger-2.0-85EA2D) ![OpenAPI 3.0-3.2](https://img.shields.io/badge/OpenAPI-3.x-6BA539)
 
 </div>
 
@@ -17,6 +17,7 @@ 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. 
+Supports Swagger 2.0 and OpenAPI 3.0, 3.1, and 3.2.
 - Type-safe TypeScript handlers for every endpoint  
 - Hot reloading as you edit  
 - Shared state across routes  

package/dist/cli/run.js

@@ -13,7 +13,7 @@ import { pathResolve } from "../util/forward-slash-path.js";
 import { loadConfigFile } from "../util/load-config-file.js";
 import { createIntroduction } from "./banner.js";
 import { checkForUpdates } from "./check-for-updates.js";
-import { isTelemetryEnabled, sendTelemetry } from "./telemetry.js";
+import { hashTelemetryLocation, isTelemetryEnabled, sendTelemetry, } from "./telemetry.js";
 const debug = createDebug("counterfact:cli:run");
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_PORT = 3100;
@@ -55,6 +55,35 @@ export function normalizeSpecOption(specOption) {
     }
     return undefined;
 }
+export function buildStartupTelemetryProperties(options, source, version, specs) {
+    const apiSources = specs?.map((spec) => spec.source) ?? [source];
+    const apiFileLocationHashes = apiSources
+        .filter((apiSource) => apiSource !== "_")
+        .map((apiSource) => hashTelemetryLocation(apiSource));
+    return {
+        alwaysFakeOptionals: Boolean(options.alwaysFakeOptionals),
+        apiFileLocationHashes,
+        buildCache: Boolean(options.buildCache),
+        generateRoutes: Boolean(options.generate) || Boolean(options.generateRoutes),
+        generateTypes: Boolean(options.generate) || Boolean(options.generateTypes),
+        mode: specs !== undefined
+            ? "multi-spec"
+            : source === "_"
+                ? "without-openapi"
+                : "single-spec",
+        openBrowser: Boolean(options.open),
+        port: options.port,
+        prune: Boolean(options.prune),
+        repl: Boolean(options.repl),
+        serve: Boolean(options.serve),
+        updateCheck: Boolean(options.updateCheck),
+        validateRequest: Boolean(options.validateRequest),
+        validateResponse: Boolean(options.validateResponse),
+        version,
+        watchRoutes: Boolean(options.watch) || Boolean(options.watchRoutes),
+        watchTypes: Boolean(options.watch) || Boolean(options.watchTypes),
+    };
+}
 /**
  * Builds the Commander program with all CLI options and the action handler.
  * Factored out of `runCli` so it is easy to test or extend.
@@ -116,6 +145,7 @@ function buildProgram(version, taglines) {
         debug("options: %o", options);
         debug("source: %s", source);
         debug("destination: %s", destination);
+        const startupTelemetryProperties = buildStartupTelemetryProperties(options, source, version, specs);
         const openBrowser = options.open;
         const url = `http://localhost:${options.port}${options.prefix}`;
         const guiUrl = `${url}/counterfact/`;
@@ -213,6 +243,7 @@ function buildProgram(version, taglines) {
             process.exit(1);
         }
         debug("started server");
+        sendTelemetry("counterfact_started", startupTelemetryProperties);
         await updateCheckPromise;
         if (config.startRepl) {
             startRepl();
@@ -300,10 +331,6 @@ export async function runCli(argv) {
     catch {
         taglines = ["counterfact — mock API server"];
     }
-    // Fire telemetry once on startup — fire-and-forget, never blocks.
-    if (isTelemetryEnabled()) {
-        sendTelemetry(version);
-    }
     debug("running counterfact CLI v%s", version);
     const program = buildProgram(version, taglines);
     await program.parseAsync(argv);

package/dist/cli/telemetry.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { PostHog } from "posthog-node";
 const POSTHOG_API_KEY = "phc_msXmBxiL8FVugNMLCx9bnPQGqfEMqmyBjnVkKhHkN3m7";
 const POSTHOG_HOST = "https://us.i.posthog.com";
@@ -15,24 +15,30 @@ export function isTelemetryEnabled() {
         return false;
     return true;
 }
+export function hashTelemetryLocation(location) {
+    return createHash("sha256").update(location).digest("hex");
+}
 /**
  * Fires a telemetry event to PostHog.  Fire-and-forget — never blocks
  * startup and never surfaces errors to the user.
  */
-export function sendTelemetry(version) {
+export function sendTelemetry(event, properties = {}) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
     const telemetryKey = process.env["POSTHOG_API_KEY"] ?? POSTHOG_API_KEY;
     const telemetryHost = process.env["POSTHOG_HOST"] ?? POSTHOG_HOST;
     try {
         const posthog = new PostHog(telemetryKey, { host: telemetryHost });
         posthog.capture({
             distinctId: randomUUID(),
-            event: "counterfact_started",
+            event,
             properties: {
-                version,
                 nodeVersion: process.version,
                 platform: process.platform,
                 arch: process.arch,
                 source: "counterfact-cli",
+                ...properties,
             },
         });
         posthog.flush().catch(() => {

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

@@ -14,6 +14,7 @@ const HTTP_METHODS = [
     "PATCH",
     "HEAD",
     "OPTIONS",
+    "QUERY",
 ];
 // Pre-compile regex patterns derived from HTTP_METHODS
 const HTTP_METHOD_ALTERNATION = HTTP_METHODS.join("|");

package/dist/msw.js

@@ -14,6 +14,7 @@ const allowedMethods = [
     "delete",
     "patch",
     "options",
+    "query",
 ];
 const mswHandlers = {};
 /**

package/dist/repl/repl.js

@@ -1,4 +1,5 @@
 import repl from "node:repl";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { RawHttpClient } from "./raw-http-client.js";
 import { createRouteFunction } from "./route-builder.js";
 function printToStdout(line) {
@@ -258,6 +259,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         : undefined);
     replServer.defineCommand("counterfact", {
         action() {
+            sendTelemetry("repl_command_used", { command: "counterfact" });
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");
             print("Except that it's connected to the running server, which you can access with the following globals:");
             print("");
@@ -274,6 +276,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     });
     replServer.defineCommand("proxy", {
         action(text) {
+            sendTelemetry("repl_command_used", { command: "proxy" });
             if (text === "help" || text === "") {
                 print(".proxy [on|off] - turn the proxy on/off at the root level");
                 print(".proxy [on|off] <path-prefix> - turn the proxy on for a path");
@@ -313,6 +316,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         : {};
     replServer.defineCommand("scenario", {
         async action(text) {
+            sendTelemetry("repl_command_used", { command: "scenario" });
             const trimmedText = text.trim();
             const parsedArgs = trimmedText.split(/\s+/u).filter(Boolean);
             const usage = isMultiApi

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

@@ -2,9 +2,13 @@
  * Represents a named example defined in an OpenAPI document.
  * Examples can be referenced by route handlers via the `.example(name)` method
  * on the response builder.
+ *
+ * OpenAPI 3.2 adds `dataValue` as a structured alternative to `value`.
+ * When present, `dataValue` is preferred over `value`.
  */
 export interface Example {
+  dataValue?: unknown;
   description: string;
   summary: string;
-  value: unknown;
+  value?: unknown;
 }

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

@@ -130,6 +130,10 @@ export type GenericResponseBuilderInner<
     : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
   text: MaybeShortcut<["text/plain"], Response>;
   xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
+  stream: MaybeShortcut<
+    ["text/event-stream", "application/jsonl", "application/json-seq"],
+    Response
+  >;
 }>;
 
 /**

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

@@ -6,7 +6,14 @@
  */
 export interface OpenApiParameters {
   explode?: boolean;
-  in: "body" | "cookie" | "formData" | "header" | "path" | "query";
+  in:
+    | "body"
+    | "cookie"
+    | "formData"
+    | "header"
+    | "path"
+    | "query"
+    | "querystring";
   name: string;
   required?: boolean;
   schema?: {

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

@@ -26,6 +26,11 @@ export interface ResponseBuilder {
   random: () => MaybePromise<ResponseBuilder>;
   randomLegacy: () => MaybePromise<ResponseBuilder>;
   status?: number;
+  stream: (iterable: AsyncIterable<unknown>) => {
+    body: AsyncIterable<unknown>;
+    contentType: string;
+    status?: number;
+  };
   text: (body: unknown) => ResponseBuilder;
   xml: (body: unknown) => ResponseBuilder;
 }

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

@@ -23,4 +23,5 @@ export interface WideResponseBuilder {
   random: () => MaybePromise<WideResponseBuilder>;
   text: (body: unknown) => WideResponseBuilder;
   xml: (body: unknown) => WideResponseBuilder;
+  stream: (body: AsyncIterable<unknown>) => WideResponseBuilder;
 }

package/dist/server/dispatcher.js

@@ -142,6 +142,11 @@ export class Dispatcher {
             return types;
         }
         for (const parameter of parameters) {
+            // querystring parameters represent the entire query string as a single
+            // typed object; they are not individually coerced by name.
+            if (parameter.in === "querystring") {
+                continue;
+            }
             const type = parameter?.type ?? parameter?.schema?.type;
             if (type !== undefined) {
                 types[parameter.in].set(parameter.name, type === "integer" ? "number" : type);
@@ -178,7 +183,11 @@ export class Dispatcher {
         if (pathItem === undefined) {
             return undefined;
         }
-        const operation = pathItem[method.toLowerCase()];
+        const normalizedMethod = method.toLowerCase();
+        const operation = pathItem[normalizedMethod] ??
+            pathItem.additionalOperations?.[method] ??
+            pathItem.additionalOperations?.[method.toUpperCase()] ??
+            pathItem.additionalOperations?.[normalizedMethod];
         if (operation === undefined) {
             return undefined;
         }
@@ -335,6 +344,8 @@ export class Dispatcher {
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- object params are reconstructed and typed by generated route types
             query: processedQuery,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- typed by generated route types; entire query string as a single object
+            querystring: 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/json-to-xml.js

@@ -22,19 +22,44 @@ function xmlEscape(xmlString) {
         }
     });
 }
+function resolveNodeType(schema) {
+    if (schema?.xml?.nodeType !== undefined) {
+        return schema.xml.nodeType;
+    }
+    if (schema?.xml?.attribute || schema?.attribute) {
+        return "attribute";
+    }
+    return "element";
+}
 function objectToXml(json, schema, name) {
     const xml = [];
     const attributes = [];
     Object.entries(json).forEach(([key, value]) => {
         const properties = schema?.properties?.[key];
-        if (properties?.attribute) {
-            attributes.push(` ${key}="${xmlEscape(String(value))}"`);
-        }
-        else {
-            xml.push(jsonToXml(value, properties, key));
+        const nodeType = resolveNodeType(properties);
+        const xmlName = properties?.xml?.name ?? key;
+        switch (nodeType) {
+            case "attribute": {
+                attributes.push(` ${xmlName}="${xmlEscape(String(value))}"`);
+                break;
+            }
+            case "text": {
+                xml.push(xmlEscape(String(value)));
+                break;
+            }
+            case "cdata": {
+                xml.push(`<![CDATA[${String(value)}]]>`);
+                break;
+            }
+            case "none": {
+                break;
+            }
+            default: {
+                xml.push(jsonToXml(value, properties, key));
+            }
         }
     });
-    return `<${name}${attributes.join("")}>${String(xml.join(""))}</${name}>`;
+    return `<${name}${attributes.join("")}>${xml.join("")}</${name}>`;
 }
 /**
  * Converts a JSON value to an XML string using optional OpenAPI `xml` schema
@@ -52,7 +77,7 @@ export function jsonToXml(json, schema, keyName = "root") {
         const items = json
             .map((item) => jsonToXml(item, schema?.items, name))
             .join("");
-        if (schema?.xml?.wrapped) {
+        if (schema?.xml?.wrapped || schema?.xml?.nodeType === "element") {
             return `<${name}>${items}</${name}>`;
         }
         return items;

package/dist/server/module-loader.js

@@ -11,6 +11,7 @@ import { FileDiscovery } from "./file-discovery.js";
 import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { toForwardSlashPath, pathDirname, pathRelative, } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
@@ -74,6 +75,10 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             const parts = nodePath.parse(pathName.replace(this.basePath, ""));
+            sendTelemetry("file_change_detected", {
+                changeType: eventName,
+                fileType: this.isContextFile(pathName) ? "context" : "route",
+            });
             const url = unescapePathForWindows(toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(/\/+/gu, "/"));
             if (eventName === "unlink") {
                 this.registry.remove(url);

package/dist/server/openapi-document.js

@@ -2,6 +2,7 @@ import { watch } from "chokidar";
 import createDebug from "debug";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
 import { waitForEvent } from "../util/wait-for-event.js";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 const debug = createDebug("counterfact:server:openapi-document");
 /**
@@ -49,6 +50,10 @@ export class OpenApiDocument extends EventTarget {
             return;
         }
         this.watcher = watch(this.source, CHOKIDAR_OPTIONS).on("change", () => {
+            sendTelemetry("file_change_detected", {
+                changeType: "change",
+                fileType: "openapi",
+            });
             void (async () => {
                 try {
                     await this.load();

package/dist/server/registry.js

@@ -1,7 +1,7 @@
 import createDebugger from "debug";
 import { ModuleTree } from "./module-tree.js";
 const debug = createDebugger("counterfact:server:registry");
-const ALL_HTTP_METHODS = [
+const DEFAULT_HTTP_METHODS = [
     "DELETE",
     "GET",
     "HEAD",
@@ -9,6 +9,7 @@ const ALL_HTTP_METHODS = [
     "PATCH",
     "POST",
     "PUT",
+    "QUERY",
     "TRACE",
 ];
 /**
@@ -60,6 +61,7 @@ function castParameters(parameters = {}, parameterTypes = new Map()) {
 export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
+    methodNames = new Set(DEFAULT_HTTP_METHODS);
     constructor() {
         this.middlewares.set("", ($, respondTo) => respondTo($));
     }
@@ -75,6 +77,9 @@ export class Registry {
      */
     add(url, module) {
         this.moduleTree.add(url, module);
+        for (const methodName of Object.keys(module)) {
+            this.methodNames.add(methodName.toUpperCase());
+        }
     }
     /**
      * Registers a middleware function that wraps every handler under `url`.
@@ -102,8 +107,20 @@ export class Registry {
      * @param method - HTTP method (e.g. `"GET"`).
      * @param url - The request URL.
      */
+    methodFromModule(module, method) {
+        if (module === undefined) {
+            return undefined;
+        }
+        return (module[method] ??
+            module[method.toUpperCase()] ??
+            module[method.toLowerCase()]);
+    }
     exists(method, url) {
-        return Boolean(this.handler(url, method).module?.[method]);
+        return (this.methodFromModule(this.handler(url, method).module, method) !==
+            undefined);
+    }
+    methodsForPath(url) {
+        return [...this.methodNames].filter((method) => this.methodFromModule(this.moduleTree.match(url, method)?.module, method) !== undefined);
     }
     /**
      * Finds the best-matching module and extracts path-variable bindings for a
@@ -133,7 +150,7 @@ export class Registry {
      * @param excludeMethod - The method to exclude from the check.
      */
     pathExistsWithAnyMethod(url, excludeMethod) {
-        return ALL_HTTP_METHODS.filter((method) => method !== excludeMethod).some((method) => this.moduleTree.match(url, method) !== undefined);
+        return this.methodsForPath(url).some((method) => method.toUpperCase() !== excludeMethod.toUpperCase());
     }
     /**
      * Returns a comma-separated list of HTTP methods that have a registered
@@ -143,7 +160,7 @@ export class Registry {
      * @param url - The request URL.
      */
     allowedMethods(url) {
-        return ALL_HTTP_METHODS.filter((method) => Boolean(this.moduleTree.match(url, method)?.module?.[method])).join(", ");
+        return this.methodsForPath(url).join(", ");
     }
     /**
      * Returns an async function that executes the registered handler for
@@ -169,7 +186,7 @@ export class Registry {
                 status: 500,
             });
         }
-        const execute = handler.module?.[httpRequestMethod];
+        const execute = this.methodFromModule(handler.module, httpRequestMethod);
         if (!execute) {
             debug(`Could not find a ${httpRequestMethod} method matching ${url}\n`);
             return () => ({

package/dist/server/response-builder.js

@@ -1,5 +1,6 @@
 import { generate } from "json-schema-faker";
 import { jsonToXml } from "./json-to-xml.js";
+import { STREAMING_CONTENT_TYPES } from "../typescript-generator/streaming-content-types.js";
 const DEFAULT_GENERATE_OPTIONS = {
     useExamplesValue: true,
     minItems: 0,
@@ -154,10 +155,16 @@ export function createResponseBuilder(operation, config) {
                 }
                 return {
                     ...this,
-                    content: Object.keys(content).map((type) => ({
-                        body: convertToXmlIfNecessary(type, content[type]?.examples?.[name]?.value, content[type]?.schema),
-                        type,
-                    })),
+                    content: Object.keys(content).map((type) => {
+                        const example = content[type]?.examples?.[name];
+                        const body = example !== undefined && "dataValue" in example
+                            ? example.dataValue
+                            : example?.value;
+                        return {
+                            body: convertToXmlIfNecessary(type, body, content[type]?.schema),
+                            type,
+                        };
+                    }),
                 };
             },
             async random() {
@@ -188,7 +195,9 @@ export function createResponseBuilder(operation, config) {
                     ...this,
                     content: await Promise.all(Object.keys(content).map(async (type) => ({
                         body: convertToXmlIfNecessary(type, content[type]?.examples
-                            ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => example.value))
+                            ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => "dataValue" in example
+                                ? example.dataValue
+                                : example.value))
                             : await generate((content[type]?.schema ?? {
                                 type: "object",
                             }), generateOptions), content[type]?.schema),
@@ -217,6 +226,19 @@ export function createResponseBuilder(operation, config) {
                     })),
                 };
             },
+            stream(iterable) {
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                const contentTypes = Object.keys(response?.content ?? {});
+                const contentType = contentTypes.find((ct) => STREAMING_CONTENT_TYPES.has(ct)) ??
+                    "text/event-stream";
+                return {
+                    body: iterable,
+                    contentType,
+                    headers: this.headers,
+                    status: this.status,
+                };
+            },
             status: Number.parseInt(statusCode, 10),
             text(body) {
                 return this.match("text/plain", body);

package/dist/server/web-server/create-koa-app.js

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import createDebug from "debug";
 import Koa from "koa";
 import bodyParser from "koa-bodyparser";
@@ -53,7 +54,8 @@ export function createKoaApp({ runners, config, }) {
         if (ctx.body !== null &&
             ctx.body !== undefined &&
             typeof ctx.body === "object" &&
-            !Buffer.isBuffer(ctx.body)) {
+            !Buffer.isBuffer(ctx.body) &&
+            !(ctx.body instanceof Readable)) {
             ctx.body = JSON.stringify(ctx.body, null, 2);
             ctx.type = "application/json";
         }

package/dist/server/web-server/openapi-middleware.js

@@ -24,6 +24,7 @@ export function openapiMiddleware(pathPrefix, document) {
         const openApiDocument = (await bundle(document.path));
         openApiDocument.servers ??= [];
         openApiDocument.servers.unshift({
+            name: "Counterfact",
             description: "Counterfact",
             url: document.baseUrl,
         });

package/dist/server/web-server/routes-middleware.js

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import createDebug from "debug";
 import koaProxy from "koa-proxies";
 import { isProxyEnabledForPath } from "../is-proxy-enabled-for-path.js";
@@ -19,6 +20,36 @@ const HEADERS_TO_DROP = new Set([
     "trailer",
     "trailers",
 ]);
+/**
+ * SSE/JSONL/JSON-seq formatter map. Each entry maps a content-type to the
+ * function that serialises a single stream item into the wire format.
+ */
+const STREAMING_FORMATTERS = {
+    "text/event-stream": (item) => `data: ${JSON.stringify(item)}\n\n`,
+    "application/json-seq": (item) => `\x1e${JSON.stringify(item)}\n`,
+};
+function defaultStreamFormatter(item) {
+    return `${JSON.stringify(item)}\n`;
+}
+function isAsyncIterable(value) {
+    return (value !== null &&
+        value !== undefined &&
+        typeof value === "object" &&
+        Symbol.asyncIterator in value);
+}
+/**
+ * Converts an `AsyncIterable` to a Node.js `Readable` stream, serialising
+ * each item according to the given content type.
+ */
+function asyncIterableToReadable(iterable, contentType) {
+    const formatter = STREAMING_FORMATTERS[contentType] ?? defaultStreamFormatter;
+    async function* generate() {
+        for await (const item of iterable) {
+            yield formatter(item);
+        }
+    }
+    return Readable.from(generate());
+}
 function addCors(ctx, allowedMethods, headers) {
     // Always append CORS headers, reflecting back the headers requested if any
     ctx.set("Access-Control-Allow-Origin", headers?.origin ?? "*");
@@ -92,7 +123,18 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
             rawBody: method === "HEAD" || method === "GET" ? undefined : rawBody,
             req: { path: "", ...ctx.req },
         });
-        ctx.body = response.body;
+        if (isAsyncIterable(response.body)) {
+            const contentType = response.contentType ?? "application/jsonl";
+            ctx.type = contentType;
+            ctx.body = asyncIterableToReadable(response.body, contentType);
+            if (contentType === "text/event-stream") {
+                ctx.set("Cache-Control", "no-cache");
+                ctx.set("X-Accel-Buffering", "no");
+            }
+        }
+        else {
+            ctx.body = response.body;
+        }
         if (response.contentType !== undefined &&
             response.contentType !== "unknown/unknown") {
             ctx.type = response.contentType;

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

@@ -109,13 +109,22 @@ export class CodeGenerator extends EventTarget {
             "patch",
             "trace",
         ]);
+        const operationMethodsForPath = (pathDefinition) => pathDefinition.flatMap((operation, requestMethod) => {
+            if (requestMethod === "additionalOperations") {
+                return operation.map((additionalOperation, additionalMethod) => [
+                    additionalOperation,
+                    additionalMethod.toLowerCase(),
+                ]);
+            }
+            if (!HTTP_VERBS.has(requestMethod)) {
+                return [];
+            }
+            return [[operation, requestMethod]];
+        });
         paths.forEach((pathDefinition, key) => {
             debug("processing path %s", key);
             const path = key === "/" ? "/index" : key;
-            pathDefinition.forEach((operation, requestMethod) => {
-                if (!HTTP_VERBS.has(requestMethod)) {
-                    return;
-                }
+            operationMethodsForPath(pathDefinition).forEach(([operation, requestMethod]) => {
                 repository
                     .get(`routes${path}.ts`)
                     .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));

package/dist/typescript-generator/coder.js

@@ -23,7 +23,7 @@ export class Coder {
      */
     get id() {
         if (this.requirement.isReference) {
-            return `${this.constructor.name}@${this.requirement.data["$ref"]}`;
+            return `${this.constructor.name}@${this.requirement.refUrl}`;
         }
         return `${this.constructor.name}@${this.requirement.url}`;
     }

package/dist/typescript-generator/jsdoc.js

@@ -3,14 +3,18 @@
  * Returns an empty string if there is no relevant metadata.
  */
 export function buildJsDoc(data) {
+    if (typeof data !== "object" || data === null) {
+        return "";
+    }
+    const record = data;
     const lines = [];
-    const description = data["description"];
-    const summary = data["summary"];
-    const example = data["example"];
-    const examples = data["examples"];
-    const defaultValue = data["default"];
-    const format = data["format"];
-    const deprecated = data["deprecated"];
+    const description = record["description"];
+    const summary = record["summary"];
+    const example = record["example"];
+    const examples = record["examples"];
+    const defaultValue = record["default"];
+    const format = record["format"];
+    const deprecated = record["deprecated"];
     const mainText = description ?? summary;
     if (mainText) {
         // Escape */ to prevent prematurely closing the JSDoc block

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

@@ -1,6 +1,7 @@
 import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
 import { OperationTypeCoder, VersionedArgTypeCoder, } from "./operation-type-coder.js";
+import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 /**
  * Generates the default route handler stub for a single OpenAPI operation.
  *
@@ -33,6 +34,19 @@ export class OperationCoder extends Coder {
             !("content" in firstResponse || "schema" in firstResponse)) {
             return `async ($) => {
         return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}].empty();
+      }`;
+        }
+        // Detect streaming responses (OpenAPI 3.2 itemSchema)
+        const content = firstResponse.content;
+        const hasStreamingContent = content !== undefined &&
+            Object.keys(content).some((ct) => STREAMING_CONTENT_TYPES.has(ct) &&
+                content[ct]?.itemSchema !== undefined);
+        if (hasStreamingContent) {
+            return `async ($) => {
+        async function* items() {
+          // yield items here
+        }
+        return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}].stream(items());
       }`;
         }
         return `async ($) => {

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

@@ -7,6 +7,7 @@ import { READ_ONLY_COMMENTS } from "./read-only-comments.js";
 import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
+import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 import { TypeCoder } from "./type-coder.js";
 import { Requirement } from "./requirement.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
@@ -105,11 +106,23 @@ export class OperationTypeCoder extends TypeCoder {
                 ? "number | undefined"
                 : Number.parseInt(responseCode, 10);
             if (response.has("content")) {
-                return response.get("content").map((content, contentType) => `{  
+                return response.get("content").map((content, contentType) => {
+                    let bodyType;
+                    if (content.has("itemSchema") &&
+                        STREAMING_CONTENT_TYPES.has(contentType)) {
+                        bodyType = `AsyncIterable<${new SchemaTypeCoder(content.get("itemSchema"), this.version).write(script)}>`;
+                    }
+                    else {
+                        bodyType = content.has("schema")
+                            ? new SchemaTypeCoder(content.get("schema"), this.version).write(script)
+                            : "unknown";
+                    }
+                    return `{  
               status: ${status}, 
               contentType?: "${contentType}",
-              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
-            }`);
+              body?: ${bodyType}
+            }`;
+                });
             }
             if (response.has("schema")) {
                 const producesReq = this.requirement?.get("produces") ??
@@ -224,8 +237,15 @@ 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);
+        // OpenAPI 3.2 querystring parameter: the entire query string treated as a
+        // single typed object (similar to requestBody for query strings).
+        const querystringParam = parameters?.find((parameter) => parameter.get("in")?.data === "querystring");
+        const querystringType = querystringParam?.has("schema") === true
+            ? new SchemaTypeCoder(querystringParam.get("schema"), this.version).write(script)
+            : "never";
+        const querystringTypeName = this.exportParameterType(script, "querystring", querystringType, baseName, modulePath);
         const versionLiteralType = this.version !== "" ? `"${this.version}"` : "never";
-        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}, version: ${versionLiteralType} }>`;
+        return `OmitValueWhenNever<{ query: ${queryTypeName}, querystring: ${querystringTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType}, version: ${versionLiteralType} }>`;
     }
     writeCode(script) {
         script.comments = READ_ONLY_COMMENTS;

package/dist/typescript-generator/requirement.js

@@ -26,7 +26,19 @@ export class Requirement {
     }
     /** `true` when this node is a JSON Reference (`$ref`) rather than inline data. */
     get isReference() {
-        return this.data["$ref"] !== undefined;
+        return (typeof this.data === "object" &&
+            this.data !== null &&
+            this.data["$ref"] !== undefined);
+    }
+    /**
+     * When this node is a JSON Reference, returns the raw `$ref` URL string.
+     * Returns `undefined` for non-reference (inline) nodes.
+     */
+    get refUrl() {
+        if (typeof this.data !== "object" || this.data === null) {
+            return undefined;
+        }
+        return this.data["$ref"];
     }
     /**
      * Resolves the `$ref` and returns the target {@link Requirement}.
@@ -34,7 +46,7 @@ export class Requirement {
      * @throws When `isReference` is `false` or the specification is not set.
      */
     reference() {
-        return this.specification.getRequirement(this.data["$ref"]);
+        return this.specification.getRequirement(this.refUrl);
     }
     /**
      * Returns `true` when this node has a child property named `item`.
@@ -47,6 +59,9 @@ export class Requirement {
         if (this.isReference) {
             return this.reference().has(item);
         }
+        if (typeof this.data !== "object" || this.data === null) {
+            return false;
+        }
         return item in this.data;
     }
     /**
@@ -62,7 +77,11 @@ export class Requirement {
         if (!this.has(key)) {
             return undefined;
         }
-        const child = new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
+        if (typeof this.data !== "object" || this.data === null) {
+            return undefined;
+        }
+        const objectData = this.data;
+        const child = new Requirement(objectData[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
         child.parent = this;
         return child;
     }
@@ -108,6 +127,9 @@ export class Requirement {
      * @param callback - Called for each child with `(child, key)`.
      */
     forEach(callback) {
+        if (typeof this.data !== "object" || this.data === null) {
+            return;
+        }
         Object.keys(this.data).forEach((key) => {
             callback(this.select(this.escapeJsonPointer(key)), key);
         });

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

@@ -1,5 +1,6 @@
 import { printObject } from "./printers.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
+import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 import { TypeCoder } from "./type-coder.js";
 import { pathJoin } from "../util/forward-slash-path.js";
 export class ResponseTypeCoder extends TypeCoder {
@@ -9,18 +10,30 @@ export class ResponseTypeCoder extends TypeCoder {
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     names() {
-        return super.names(this.requirement.data["$ref"].split("/").at(-1));
+        return super.names(this.requirement.refUrl.split("/").at(-1));
     }
     buildContentObjectType(script, response) {
         if (response.has("content")) {
             return response
                 .get("content")
-                .map((content, mediaType) => [
-                mediaType,
-                `{ 
-            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
+                .map((content, mediaType) => {
+                let schemaType;
+                if (content.has("itemSchema") &&
+                    STREAMING_CONTENT_TYPES.has(mediaType)) {
+                    schemaType = `AsyncIterable<${new SchemaTypeCoder(content.get("itemSchema"), this.version).write(script)}>`;
+                }
+                else {
+                    schemaType = content.has("schema")
+                        ? new SchemaTypeCoder(content.get("schema"), this.version).write(script)
+                        : "unknown";
+                }
+                return [
+                    mediaType,
+                    `{ 
+            schema:  ${schemaType}
          }`,
-            ]);
+                ];
+            });
         }
         return this.openApi2MediaTypes.map((mediaType) => [
             mediaType,
@@ -78,7 +91,7 @@ export class ResponseTypeCoder extends TypeCoder {
         return printObject(exampleNames.map((name) => [name, "unknown"]));
     }
     modulePath() {
-        return pathJoin("types", this.version, this.requirement.data["$ref"] + ".ts");
+        return pathJoin("types", this.version, this.requirement.refUrl + ".ts");
     }
     writeCode(script) {
         return `{

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

@@ -8,7 +8,7 @@ function scrubSchema(schema) {
 }
 export class SchemaCoder extends Coder {
     names() {
-        return super.names(`${this.requirement.data["$ref"].split("/").at(-1)}Schema`);
+        return super.names(`${this.requirement.refUrl.split("/").at(-1)}Schema`);
     }
     objectSchema(script) {
         const { properties, required } = this.requirement.data;
@@ -34,7 +34,7 @@ export class SchemaCoder extends Coder {
         return script.importExternalType("JSONSchema6", "json-schema");
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"]}.ts`;
+        return `types/${this.requirement.refUrl}.ts`;
     }
     writeCode(script) {
         const { type } = this.requirement.data;

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

@@ -1,9 +1,10 @@
 import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.js";
+import { Requirement } from "./requirement.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));
+        return super.names(this.requirement.refUrl?.split("/").at(-1));
     }
     jsdoc() {
         return buildJsDoc(this.requirement.data);
@@ -82,6 +83,14 @@ 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), this.version).write(script));
+        // Include the default schema from discriminator.defaultMapping (OpenAPI 3.2)
+        if (!allOf) {
+            const { discriminator } = this.requirement.data;
+            if (discriminator?.defaultMapping) {
+                const defaultRequirement = new Requirement({ $ref: discriminator.defaultMapping }, "", this.requirement.specification);
+                types.push(new SchemaTypeCoder(defaultRequirement, this.version).write(script));
+            }
+        }
         return types.join(allOf ? " & " : " | ");
     }
     writeEnum(_script, requirement) {
@@ -90,10 +99,14 @@ export class SchemaTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        return pathJoin("types", this.version, this.requirement.data["$ref"].replace(/^#\//u, "") + ".ts");
+        return pathJoin("types", this.version, this.requirement.refUrl.replace(/^#\//u, "") + ".ts");
     }
     writeCode(script) {
-        const { allOf, anyOf, oneOf, type, format } = this.requirement.data;
+        const { allOf, anyOf, oneOf, type, format, itemSchema } = this.requirement
+            .data;
+        if (itemSchema) {
+            return `AsyncIterable<${new SchemaTypeCoder(this.requirement.get("itemSchema"), this.version).write(script)}>`;
+        }
         if (allOf ?? anyOf ?? oneOf) {
             return this.writeGroup(script, { allOf, anyOf, oneOf });
         }

package/dist/typescript-generator/specification.js

@@ -49,7 +49,9 @@ export class Specification {
      */
     async load(urlOrPath) {
         try {
-            this.rootRequirement = new Requirement((await bundle(urlOrPath)), urlOrPath, this);
+            this.rootRequirement = new Requirement((await bundle(urlOrPath, {
+                resolve: { http: { safeUrlResolver: false } },
+            })), urlOrPath, this);
         }
         catch (error) {
             const details = error instanceof Error ? error.message : String(error);

package/dist/typescript-generator/streaming-content-types.js

@@ -0,0 +1,16 @@
+/**
+ * Content types that represent sequential/streaming media in OpenAPI 3.2.
+ *
+ * When a Media Type Object uses `itemSchema` together with one of these content
+ * types, the generated TypeScript body type is `AsyncIterable<T>` rather than
+ * a plain schema type.  On the server side, returning an `AsyncIterable` for
+ * one of these content types causes Counterfact to stream each item in the
+ * appropriate wire format.
+ */
+export const STREAMING_CONTENT_TYPES = new Set([
+    "text/event-stream",
+    "application/jsonl",
+    "application/x-ndjson",
+    "application/ndjson",
+    "application/json-seq",
+]);

package/dist/typescript-generator/versions-ts-generator.js

@@ -30,6 +30,7 @@ export async function generateVersionsTsContent(versions) {
     const source = [
         "// This file is auto-generated by Counterfact. Do not edit.",
         "",
+        '/** Union of all version strings declared for this API group (e.g. `"v1" | "v2" | "v3"`). */',
         `export type Versions = ${versionsUnion};`,
         "",
         "/**",
@@ -42,6 +43,30 @@ export async function generateVersionsTsContent(versions) {
         "",
         "type VersionMap = Partial<Record<Versions, object>>;",
         "",
+        "/**",
+        " * The type of the `$` argument in a versioned route handler.",
+        " *",
+        " * @typeParam T - A map from version string to the `$`-arg type for that version",
+        " *   (e.g. `{ v1: $v1Type; v2: $v2Type }`). Generated by Counterfact from the spec.",
+        " * @typeParam V - The union of currently active version keys; defaults to all keys of `T`.",
+        " *",
+        " * An instance of `Versioned<T, V>` exposes:",
+        " * - All properties of the intersection `T[V]` (request data, response builders, etc.)",
+        ' * - `version` — the version string for the current request (e.g. `"v2"`).',
+        " * - `minVersion(min)` — type predicate that returns `true` when the current version",
+        " *   is at or after `min` in the declared version order and narrows `$` accordingly.",
+        " *",
+        " * @example",
+        " * ```ts",
+        " * export const GET: HTTP_GET = ($) => {",
+        ' *   if ($.minVersion("v2")) {',
+        " *     // $ is now typed as the v2+ arg — v2-only fields are available",
+        " *     return $.response[200].json({ id: $.path.id, extra: $.body.extra });",
+        " *   }",
+        " *   return $.response[200].json({ id: $.path.id });",
+        " * };",
+        " * ```",
+        " */",
         "export type Versioned<",
         "  T extends VersionMap,",
         "  V extends keyof T & Versions = keyof T & Versions,",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.11.0",
+  "version": "2.12.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",
@@ -78,17 +78,16 @@
     "go:petstore2": "yarn build && yarn counterfact  https://petstore.swagger.io/v2/swagger.json out",
     "go:example": "yarn build && node ./bin/counterfact.js ./test/fixtures/openapi/example.yaml out",
     "go:multiple-apis": "yarn build && node ./bin/counterfact.js --config ./test/fixtures/config/multiple-apis.yaml",
-    "counterfact": "./bin/counterfact.js",
-    "postinstall": "patch-package"
+    "counterfact": "./bin/counterfact.js"
   },
   "devDependencies": {
-    "@changesets/cli": "2.30.0",
+    "@changesets/cli": "2.31.0",
     "@eslint/js": "10.0.1",
-    "@jest/globals": "^30.3.0",
-    "@swc/core": "1.15.24",
+    "@jest/globals": "30.4.1",
+    "@swc/core": "1.15.33",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
-    "@types/debug": "^4.1.12",
+    "@types/debug": "4.1.13",
     "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
     "@types/koa": "3.0.2",
@@ -96,26 +95,26 @@
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",
     "@types/node": "22",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
+    "@typescript-eslint/eslint-plugin": "8.59.3",
+    "@typescript-eslint/parser": "8.59.3",
     "copyfiles": "2.4.1",
-    "eslint": "10.2.0",
+    "eslint": "10.3.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-etc": "2.0.3",
     "eslint-plugin-file-progress": "4.0.0",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-jest": "29.15.1",
+    "eslint-plugin-jest": "29.15.2",
     "eslint-plugin-jest-dom": "5.5.0",
-    "eslint-plugin-n": "^17.24.0",
+    "eslint-plugin-n": "18.0.1",
     "eslint-plugin-no-explicit-type-exports": "0.12.1",
     "eslint-plugin-prettier": "5.5.5",
-    "eslint-plugin-promise": "^7.2.1",
-    "eslint-plugin-regexp": "^3.0.0",
-    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-promise": "7.3.0",
+    "eslint-plugin-regexp": "3.1.0",
+    "eslint-plugin-security": "4.0.0",
     "eslint-plugin-unused-imports": "4.4.1",
     "husky": "9.1.7",
-    "jest": "30.3.0",
+    "jest": "30.4.2",
     "jest-retries": "1.0.1",
     "node-mocks-http": "1.17.2",
     "rimraf": "6.1.3",
@@ -124,17 +123,17 @@
     "using-temporary-files": "2.2.1"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "13.0.5",
+    "@apidevtools/json-schema-ref-parser": "15.3.5",
     "@hapi/accept": "6.0.3",
     "@types/json-schema": "7.0.15",
-    "ajv": "8.18.0",
+    "ajv": "8.20.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
     "debug": "4.4.3",
-    "fs-extra": "11.3.4",
+    "fs-extra": "11.3.5",
     "http-terminator": "3.2.0",
     "js-yaml": "4.1.1",
-    "json-schema-faker": "0.6.0",
+    "json-schema-faker": "0.6.1",
     "jsonwebtoken": "9.0.3",
     "koa": "3.2.0",
     "koa-bodyparser": "4.4.1",
@@ -142,13 +141,12 @@
     "koa2-swagger-ui": "5.12.0",
     "node-fetch": "3.3.2",
     "open": "11.0.0",
-    "patch-package": "8.0.1",
-    "posthog-node": "^5.28.11",
-    "precinct": "12.2.0",
-    "prettier": "3.8.1",
+    "posthog-node": "5.34.1",
+    "precinct": "12.3.2",
+    "prettier": "3.8.3",
     "recast": "0.23.11",
-    "tsx": "^4.20.3",
-    "typescript": "6.0.2"
+    "tsx": "4.21.0",
+    "typescript": "6.0.3"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
   "resolutions": {