counterfact 2.10.0 → 2.12.0

package/dist/server/dispatcher.js

@@ -6,6 +6,23 @@ import { isExplodedObjectQueryParam, validateRequest, } from "./request-validato
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+/**
+ * Merges path-item-level and operation-level parameter arrays.
+ *
+ * Operation-level parameters take precedence when both arrays define a
+ * parameter with the same `name` and `in` location, per the OpenAPI
+ * specification.
+ */
+function mergeParameters(pathItemParams, operationParams) {
+    const map = new Map();
+    for (const p of pathItemParams) {
+        map.set(`${p.in}:${p.name}`, p);
+    }
+    for (const p of operationParams) {
+        map.set(`${p.in}:${p.name}`, p);
+    }
+    return [...map.values()];
+}
 /**
  * Parses the `Cookie` request header into a key/value map.
  *
@@ -91,12 +108,26 @@ export class Dispatcher {
     openApiDocument;
     fetch;
     config; // Add config property
-    constructor(registry, contextRegistry, openApiDocument, config) {
+    /**
+     * The version label for this dispatcher's spec (e.g. `"v1"`, `"v2"`).
+     * Empty string when running without a version.
+     */
+    version;
+    /**
+     * Ordered list of all version labels for the API group this dispatcher
+     * belongs to. The first entry is the oldest version. Used by
+     * `$.minVersion()` at runtime to determine if the current version is
+     * greater than or equal to a given minimum version.
+     */
+    versions;
+    constructor(registry, contextRegistry, openApiDocument, config, version = "", versions = []) {
         this.registry = registry;
         this.contextRegistry = contextRegistry;
         this.openApiDocument = openApiDocument;
         this.fetch = fetch;
         this.config = config;
+        this.version = version;
+        this.versions = versions;
     }
     parameterTypes(parameters) {
         const types = {
@@ -111,43 +142,74 @@ export class Dispatcher {
             return types;
         }
         for (const parameter of parameters) {
-            const type = parameter?.type;
+            // 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);
             }
         }
         return types;
     }
-    findOperation(path, method) {
-        if (this.openApiDocument) {
-            for (const key in this.openApiDocument.paths) {
-                if (key.toLowerCase() === path.toLowerCase()) {
-                    return this.openApiDocument.paths[key]?.[method.toLowerCase()];
-                }
+    findPathItem(path) {
+        if (!this.openApiDocument) {
+            return undefined;
+        }
+        for (const key in this.openApiDocument.paths) {
+            if (key.toLowerCase() === path.toLowerCase()) {
+                return this.openApiDocument.paths[key];
             }
         }
         return undefined;
     }
     /**
      * Resolves the OpenAPI operation for `path` and `method`, merging any
-     * top-level `produces` array from the document root into the operation.
+     * top-level `produces` array from the document root and any path-item-level
+     * `parameters` into the operation.
+     *
+     * Per the OpenAPI specification, parameters defined at the path item level
+     * are shared across all operations on that path. Operation-level parameters
+     * take precedence when both define a parameter with the same `name` and `in`.
      *
      * @param path - The matched route path (e.g. `"/pets/{petId}"`).
      * @param method - The HTTP method.
      * @returns The {@link OpenApiOperation} if found, or `undefined`.
      */
     operationForPathAndMethod(path, method) {
-        const operation = this.findOperation(path, method);
+        const pathItem = this.findPathItem(path);
+        if (pathItem === undefined) {
+            return undefined;
+        }
+        const normalizedMethod = method.toLowerCase();
+        const operation = pathItem[normalizedMethod] ??
+            pathItem.additionalOperations?.[method] ??
+            pathItem.additionalOperations?.[method.toUpperCase()] ??
+            pathItem.additionalOperations?.[normalizedMethod];
         if (operation === undefined) {
             return undefined;
         }
+        // Merge path-item-level parameters with operation-level parameters.
+        // Operation-level parameters take precedence on same name+in collision.
+        const pathItemParams = pathItem.parameters ?? [];
+        const operationParams = operation.parameters ?? [];
+        const mergedParameters = pathItemParams.length > 0
+            ? mergeParameters(pathItemParams, operationParams)
+            : operationParams.length > 0
+                ? operationParams
+                : undefined;
+        const mergedOperation = mergedParameters !== undefined
+            ? { ...operation, parameters: mergedParameters }
+            : operation;
         if (this.openApiDocument?.produces) {
             return {
                 produces: this.openApiDocument.produces,
-                ...operation,
+                ...mergedOperation,
             };
         }
-        return operation;
+        return mergedOperation;
     }
     normalizeResponse(response, acceptHeader) {
         if (response.content !== undefined) {
@@ -282,9 +344,22 @@ 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 }),
+            ...(this.version !== "" && {
+                version: this.version,
+                minVersion: (min) => {
+                    const currentIdx = this.versions.indexOf(this.version);
+                    const minIdx = this.versions.indexOf(min);
+                    if (currentIdx === -1 || minIdx === -1) {
+                        return false;
+                    }
+                    return currentIdx >= minIdx;
+                },
+            }),
         });
         if (response === undefined) {
             return {

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/admin-api-middleware.js

@@ -166,7 +166,7 @@ export function adminApiMiddleware(pathPrefix, registry, contextRegistry, config
                         port: config.port,
                         proxyUrl: config.proxyUrl,
                         prefix: config.prefix,
-                        startAdminApi: config.startAdminApi,
+                        startAdminApi: config.startAdminApi ?? false,
                         startRepl: config.startRepl,
                         startServer: config.startServer,
                         watch: config.watch,

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

@@ -22,12 +22,14 @@ const debug = createDebug("counterfact:typescript-generator:generate");
 export class CodeGenerator extends EventTarget {
     openapiPath;
     destination;
+    version;
     generateOptions;
     watcher;
-    constructor(openApiPath, destination, generateOptions) {
+    constructor(openApiPath, destination, generateOptions, version = "") {
         super();
         this.openapiPath = openApiPath;
         this.destination = destination;
+        this.version = version;
         this.generateOptions = generateOptions;
     }
     /**
@@ -107,16 +109,25 @@ 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, "", requestMethod, securitySchemes));
+                    .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
             });
         });
         debug("telling the repository to write the files to %s", destination);

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, } from "./operation-type-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 ($) => {
@@ -41,6 +55,14 @@ export class OperationCoder extends Coder {
     }
     typeDeclaration(_namespace, script) {
         const operationTypeCoder = new OperationTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
+        if (this.version !== "") {
+            // For versioned APIs: register this version's $-argument type on the
+            // shared script so that Script.versionsTypeStatements() can emit the
+            // merged handler type after all versions have been declared.
+            const versionedArgCoder = new VersionedArgTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
+            const sharedScript = script.repository.get(operationTypeCoder.modulePath());
+            sharedScript.declareVersion(versionedArgCoder, operationTypeCoder.getOperationBaseName());
+        }
         return script.importType(operationTypeCoder);
     }
     modulePath() {