counterfact 2.11.0 → 2.14.0

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

@@ -1,5 +1,6 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
 import createDebug from "debug";
+import { applyOverlays } from "../util/apply-overlay.js";
 import { Requirement } from "./requirement.js";
 const debug = createDebug("counterfact:typescript-generator:specification");
 /**
@@ -23,12 +24,14 @@ export class Specification {
      * Loads the OpenAPI document at `urlOrPath`, bundles all external `$ref`
      * references, and returns a fully initialised {@link Specification}.
      *
-     * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @param urlOrPath   - A local file path or HTTP(S) URL.
+     * @param overlays    - Optional ordered list of overlay file paths/URLs to
+     *   apply after loading the document.
      * @throws When the document cannot be found or parsed.
      */
-    static async fromFile(urlOrPath) {
+    static async fromFile(urlOrPath, overlays = []) {
         const specification = new Specification();
-        await specification.load(urlOrPath);
+        await specification.load(urlOrPath, overlays);
         return specification;
     }
     /**
@@ -42,14 +45,22 @@ export class Specification {
         return this.rootRequirement.select(url.slice(2));
     }
     /**
-     * Loads (or reloads) the specification from `urlOrPath`.
+     * Loads (or reloads) the specification from `urlOrPath`, then applies any
+     * overlay files listed in `overlays` in order.
      *
      * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @param overlays  - Optional ordered list of overlay file paths/URLs.
      * @throws When the document cannot be found or parsed.
      */
-    async load(urlOrPath) {
+    async load(urlOrPath, overlays = []) {
         try {
-            this.rootRequirement = new Requirement((await bundle(urlOrPath)), urlOrPath, this);
+            const document = (await bundle(urlOrPath, {
+                resolve: { http: { safeUrlResolver: false } },
+            }));
+            if (overlays.length > 0) {
+                await applyOverlays(document, overlays);
+            }
+            this.rootRequirement = new Requirement(document, 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/dist/util/apply-overlay.js

@@ -0,0 +1,119 @@
+import { load as loadYaml } from "js-yaml";
+import { JSONPath } from "jsonpath-plus";
+import { readFile } from "./read-file.js";
+/**
+ * Deeply merges `source` into `target`, overwriting scalar values and
+ * recursively merging plain objects.  Arrays and non-plain-object values in
+ * `source` always overwrite the corresponding entry in `target`.
+ */
+function deepMerge(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        // Guard against prototype pollution attacks.
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            continue;
+        }
+        if (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof target[key] === "object" &&
+            target[key] !== null &&
+            !Array.isArray(target[key])) {
+            deepMerge(target[key], value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+}
+/**
+ * Applies a list of overlay actions to `document` in place.
+ *
+ * Each action may either:
+ * - **update**: deep-merge the `action.update` object into every node matched
+ *   by the JSONPath `action.target`.
+ * - **remove**: delete every node matched by `action.target` from its parent.
+ *
+ * @param document - The OpenAPI document object to mutate.
+ * @param actions  - The ordered list of overlay actions to apply.
+ */
+export function applyOverlayActions(document, actions) {
+    for (const action of actions) {
+        const results = JSONPath({
+            path: action.target,
+            json: document,
+            resultType: "all",
+        });
+        if (action.remove === true) {
+            // Iterate in reverse so that removing by numeric index doesn't shift
+            // subsequent items in the same parent array.
+            for (const result of [...results].reverse()) {
+                const { parent, parentProperty } = result;
+                if (Array.isArray(parent)) {
+                    parent.splice(Number(parentProperty), 1);
+                }
+                else {
+                    delete parent[String(parentProperty)];
+                }
+            }
+        }
+        else if (action.update !== undefined) {
+            for (const result of results) {
+                if (typeof result.value === "object" &&
+                    result.value !== null &&
+                    !Array.isArray(result.value)) {
+                    deepMerge(result.value, action.update);
+                }
+            }
+        }
+    }
+}
+/**
+ * Loads and parses an overlay file (YAML or JSON), validates that it looks
+ * like a valid OpenAPI overlay document, and returns the parsed object.
+ *
+ * @param overlayPath - Path or URL to the overlay file.
+ * @throws When the file cannot be read, parsed, or does not contain an
+ *   `overlay` version field and an `actions` array.
+ */
+export async function loadOverlay(overlayPath) {
+    let content;
+    try {
+        content = await readFile(overlayPath);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read overlay file "${overlayPath}".\n${details}`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = loadYaml(content);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not parse overlay file "${overlayPath}".\n${details}`, { cause: error });
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("overlay" in parsed) ||
+        !("actions" in parsed) ||
+        !Array.isArray(parsed.actions)) {
+        throw new Error(`"${overlayPath}" does not appear to be a valid OpenAPI overlay file. ` +
+            `Expected an object with "overlay" and "actions" fields.`);
+    }
+    return parsed;
+}
+/**
+ * Applies all overlays listed in `overlayPaths` to `document` in order.
+ *
+ * Each overlay is loaded from disk (or a URL), parsed, and its actions are
+ * applied sequentially.  The document is mutated in place.
+ *
+ * @param document      - The OpenAPI document object to mutate.
+ * @param overlayPaths  - Ordered list of paths/URLs to overlay files.
+ */
+export async function applyOverlays(document, overlayPaths) {
+    for (const overlayPath of overlayPaths) {
+        const overlay = await loadOverlay(overlayPath);
+        applyOverlayActions(document, overlay.actions);
+    }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "counterfact",
-  "version": "2.11.0",
+  "version": "2.14.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",
   "exports": {
     ".": {
-      "import": "./dist/app.js"
+      "import": "./dist/app.js",
+      "types": "./dist/server/types.d.ts"
     }
   },
   "types": "./dist/server/types.d.ts",
@@ -78,44 +79,43 @@
     "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.40",
     "@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",
+    "@types/koa": "3.0.3",
     "@types/koa-bodyparser": "4.3.13",
     "@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.60.0",
+    "@typescript-eslint/parser": "8.60.0",
     "copyfiles": "2.4.1",
-    "eslint": "10.2.0",
+    "eslint": "10.4.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,31 +124,31 @@
     "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.2",
+    "jsonpath-plus": "10.4.0",
     "jsonwebtoken": "9.0.3",
-    "koa": "3.2.0",
+    "koa": "3.2.1",
     "koa-bodyparser": "4.4.1",
     "koa-proxies": "0.12.4",
     "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.35.5",
+    "precinct": "13.0.0",
+    "prettier": "3.8.3",
     "recast": "0.23.11",
-    "tsx": "^4.20.3",
-    "typescript": "6.0.2"
+    "tsx": "4.22.3",
+    "typescript": "6.0.3"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
   "resolutions": {