counterfact 2.10.0 → 2.12.0

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

@@ -7,7 +7,9 @@ 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
 function sanitizeIdentifier(value) {
     // Treat any run of non-identifier characters as a camelCase separator
@@ -32,6 +34,14 @@ function sanitizeIdentifier(value) {
  * `cookie`, `body`, `context`, `response`, and `user` arguments.
  *
  * Output is written to `types/paths/<route>.types.ts`.
+ *
+ * **Versioned APIs**: when `version` is non-empty this coder emits only a
+ * sentinel `{raw: ""}` export (suppressing the normal flat type) and
+ * registers a formatter on the shared script so that
+ * {@link Script.versionsTypeStatements} can later emit the merged
+ * `HTTP_<METHOD>_$_Versions` map and the `HTTP_<METHOD>` handler type.
+ * Each version's `$`-argument type is emitted to
+ * `types/<version>/paths/<path>.types.ts` by {@link VersionedArgTypeCoder}.
  */
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
@@ -96,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") ??
@@ -141,14 +163,57 @@ export class OperationTypeCoder extends TypeCoder {
         }
         return "never";
     }
-    writeCode(script) {
-        script.comments = READ_ONLY_COMMENTS;
+    /**
+     * Returns the effective parameters for this operation by merging path-item-level
+     * parameters with operation-level parameters. Per the OpenAPI specification,
+     * operation-level parameters override path-item-level parameters that share
+     * the same `name` and `in` location.
+     *
+     * Uses `this.requirement.parent` (the path item requirement) to access
+     * path-item-level parameters directly, without URL string parsing.
+     *
+     * When the parent is not set (e.g. in unit tests that construct requirements
+     * directly), only the operation-level parameters are returned.
+     */
+    getEffectiveParameters() {
+        const operationParams = this.requirement.get("parameters");
+        const pathItemParams = this.requirement.parent?.get("parameters");
+        if (!pathItemParams) {
+            return operationParams;
+        }
+        if (!operationParams) {
+            return pathItemParams;
+        }
+        // Merge using a Map keyed on `${in}:${name}`.
+        // Path-level params are added first; operation-level overrides them.
+        const pathData = pathItemParams.data;
+        const opData = operationParams.data;
+        const map = new Map();
+        for (const p of pathData) {
+            map.set(`${p.in}:${p.name}`, p);
+        }
+        for (const p of opData) {
+            map.set(`${p.in}:${p.name}`, p);
+        }
+        return new Requirement([...map.values()], this.requirement.url, this.requirement.specification);
+    }
+    /**
+     * Builds the `OmitValueWhenNever<{…}>` dollar-argument type body and sets
+     * up all required shared-type imports on `script`.
+     *
+     * This helper is reused by both {@link writeCode} (non-versioned) and
+     * {@link VersionedArgTypeCoder.writeCode} (per-version file).
+     *
+     * @param script - The script to write imports and parameter-type exports into.
+     * @param baseName - Identifier prefix used for named parameter-type exports.
+     * @param modulePath - Repository-relative path for parameter-type exports.
+     */
+    buildDollarArgType(script, baseName, modulePath) {
         const xType = script.importSharedType("WideOperationArgument");
         script.importSharedType("OmitValueWhenNever");
-        script.importSharedType("MaybePromise");
         script.importSharedType("COUNTERFACT_RESPONSE");
         const contextTypeImportName = script.importExternalType("Context", CONTEXT_FILE_TOKEN);
-        const parameters = this.requirement.get("parameters");
+        const parameters = this.getEffectiveParameters();
         const queryType = new ParametersTypeCoder(parameters, this.version, "query").write(script);
         const pathType = new ParametersTypeCoder(parameters, this.version, "path").write(script);
         const headersType = new ParametersTypeCoder(parameters, this.version, "header").write(script);
@@ -168,13 +233,121 @@ export class OperationTypeCoder extends TypeCoder {
         const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), this.version, openApi2MediaTypes).write(script);
         const proxyType = "(url: string) => COUNTERFACT_RESPONSE";
         const delayType = "(milliseconds: number, maxMilliseconds?: number) => Promise<void>";
-        // Get the base name for this operation and export parameter types
-        const baseName = this.getOperationBaseName();
-        const modulePath = this.modulePath();
         const queryTypeName = this.exportParameterType(script, "query", queryType, baseName, modulePath);
         const pathTypeName = this.exportParameterType(script, "path", pathType, baseName, modulePath);
         const headersTypeName = this.exportParameterType(script, "headers", headersType, baseName, modulePath);
         const cookieTypeName = this.exportParameterType(script, "cookie", cookieType, baseName, modulePath);
-        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<COUNTERFACT_RESPONSE>`;
+        // 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}, 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;
+        if (this.version !== "") {
+            // Versioned case: suppress the normal flat export and register a
+            // formatter so that Script.versionsTypeStatements() can emit the
+            // merged HTTP_<METHOD>_$_Versions + HTTP_<METHOD> types after all
+            // versions have been declared via declareVersion().
+            const versionedType = script.importVersionsType("Versioned");
+            const maybePromiseType = script.importSharedType("MaybePromise");
+            const counterfactResponseType = script.importSharedType("COUNTERFACT_RESPONSE");
+            const baseName = this.getOperationBaseName();
+            script.setVersionFormatter(baseName, (versionCodes) => {
+                const versionsTypeName = `${baseName}_$_Versions`;
+                const versionMap = Array.from(versionCodes, ([v, code]) => `"${v}": ${code}`).join("; ");
+                return [
+                    `type ${versionsTypeName} = { ${versionMap} };`,
+                    `export type ${baseName} = ($: ${versionedType}<${versionsTypeName}>) => ${maybePromiseType}<${counterfactResponseType}>;`,
+                ].join("\n");
+            });
+            // Return a raw-empty sentinel so exportStatements() emits nothing for
+            // this export entry.  The real export is produced by
+            // versionsTypeStatements().
+            return { raw: "" };
+        }
+        // Non-versioned case: existing flat-type output.
+        // Import in the same order as the original writeCode so that the emitted
+        // import block is identical to the pre-refactor output (snapshot-safe).
+        script.importSharedType("WideOperationArgument");
+        script.importSharedType("OmitValueWhenNever");
+        script.importSharedType("MaybePromise");
+        script.importSharedType("COUNTERFACT_RESPONSE");
+        const baseName = this.getOperationBaseName();
+        const modulePath = this.modulePath();
+        const dollarArgType = this.buildDollarArgType(script, baseName, modulePath);
+        return `($: ${dollarArgType}) => MaybePromise<COUNTERFACT_RESPONSE>`;
+    }
+}
+/**
+ * Emits a per-version `$`-argument type to
+ * `types/<version>/paths/<path>.types.ts`.
+ *
+ * When called from a *different* script (e.g. the shared
+ * `types/paths/…` script via `Script.declareVersion`), `write()` delegates to
+ * `script.importType(this)` so that the type is written to the per-version
+ * file and an import is added to the calling script.
+ *
+ * Only the `OmitValueWhenNever<{…}>` type body is emitted — the
+ * function-wrapper `($: Versioned<…>) => MaybePromise<COUNTERFACT_RESPONSE>`
+ * is assembled by the shared script's `versionsTypeStatements()`.
+ */
+export class VersionedArgTypeCoder extends OperationTypeCoder {
+    /**
+     * Include the version in the cache key so v1 and v2 coders are treated as
+     * distinct exports even when they share the same requirement URL.
+     */
+    get id() {
+        return `${super.id}:${this.version}`;
+    }
+    /**
+     * The per-version `$`-argument type is emitted to
+     * `types/<version>/paths/<path>.types.ts`, not to the shared path.
+     */
+    modulePath() {
+        const pathString = this.requirement.url
+            .split("/")
+            .at(-2)
+            .replaceAll("~1", "/");
+        return `${pathJoin(`types/${this.version}/paths`, pathString === "/" ? "/index" : pathString)}.types.ts`;
+    }
+    /**
+     * Names are version-qualified (e.g. `HTTP_GET_$_v1`) so that importing
+     * multiple versions into the shared script requires no aliasing.
+     */
+    *names() {
+        const baseName = `${this.getOperationBaseName()}_$_${sanitizeIdentifier(this.version)}`;
+        yield baseName;
+        let index = 1;
+        const MAX = 100;
+        while (index < MAX) {
+            index += 1;
+            yield `${baseName}${index}`;
+        }
+    }
+    /**
+     * When called from the per-version file itself, generate the actual type.
+     * When called from any other script (e.g. the shared file), export to the
+     * per-version file and import the result back into that script.
+     */
+    write(script) {
+        if (script.path === this.modulePath()) {
+            return this.writeCode(script);
+        }
+        return script.importType(this);
+    }
+    /**
+     * Generates the `OmitValueWhenNever<{…}>` dollar-argument type and writes
+     * it to the per-version script.
+     */
+    writeCode(script) {
+        script.comments = READ_ONLY_COMMENTS;
+        const baseName = this.getOperationBaseName();
+        return this.buildDollarArgType(script, baseName, this.modulePath());
     }
 }

package/dist/typescript-generator/requirement.js

@@ -10,6 +10,15 @@ export class Requirement {
     data;
     url;
     specification;
+    /**
+     * The requirement that produced this one via a `get()` call, or `undefined`
+     * for root requirements that were constructed directly.
+     *
+     * For path-traversal purposes this is the "logical" parent: when a `$ref` is
+     * followed, the parent is the resolved reference target rather than the
+     * `$ref` node itself.
+     */
+    parent;
     constructor(data, url = "", specification = undefined) {
         this.data = data;
         this.url = url;
@@ -17,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}.
@@ -25,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`.
@@ -38,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;
     }
     /**
@@ -53,7 +77,13 @@ export class Requirement {
         if (!this.has(key)) {
             return undefined;
         }
-        return 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;
     }
     /**
      * Navigates to a descendant node using a slash-delimited JSON Pointer path.
@@ -97,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/responses-type-coder.js

@@ -21,10 +21,16 @@ export class ResponsesTypeCoder extends TypeCoder {
         return statusCode;
     }
     buildResponseObjectType(script) {
-        return printObjectWithoutQuotes(this.requirement.map((response, responseCode) => [
+        const entries = this.requirement.map((response, responseCode) => [
             this.normalizeStatusCode(responseCode),
             new ResponseTypeCoder(response, this.version, this.openApi2MediaTypes).write(script),
-        ]));
+        ]);
+        const explicitEntries = entries.filter(([key]) => !key.startsWith("["));
+        const mappedEntries = entries.filter(([key]) => key.startsWith("["));
+        if (explicitEntries.length > 0 && mappedEntries.length > 0) {
+            return `${printObjectWithoutQuotes(explicitEntries)} & ${printObjectWithoutQuotes(mappedEntries)}`;
+        }
+        return printObjectWithoutQuotes(entries);
     }
     writeCode(script) {
         script.importSharedType("ResponseBuilderFactory");

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/script.js

@@ -18,6 +18,7 @@ export class Script {
     comments;
     exports;
     versions;
+    versionFormatters;
     imports;
     externalImport;
     cache;
@@ -28,6 +29,7 @@ export class Script {
         this.comments = [];
         this.exports = new Map();
         this.versions = new Map();
+        this.versionFormatters = new Map();
         this.imports = new Map();
         this.externalImport = new Map();
         this.cache = new Map();
@@ -175,9 +177,30 @@ export class Script {
     importSharedType(name) {
         return this.importExternal(name, pathJoin(this.relativePathToBase, "counterfact-types/index.ts"), true);
     }
+    /**
+     * Imports a type from the generated `types/versions.ts` module,
+     * resolving the path relative to this script's location in the repository.
+     *
+     * @param name - The type name to import (e.g. `"Versioned"`).
+     */
+    importVersionsType(name) {
+        return this.importExternal(name, pathJoin(this.relativePathToBase, "types/versions.ts"), true);
+    }
     exportType(coder) {
         return this.export(coder, true);
     }
+    /**
+     * Registers a formatter function for the merged versioned type emitted under
+     * `name` by {@link versionsTypeStatements}.
+     *
+     * When a formatter is present for a name, `versionsTypeStatements` delegates
+     * the entire type declaration to it instead of generating the default
+     * `Versions` object type.  The formatter receives a `Map<version, importAlias>`
+     * and must return the complete TypeScript source for that operation type.
+     */
+    setVersionFormatter(name, formatter) {
+        this.versionFormatters.set(name, formatter);
+    }
     declareVersion(coder, name) {
         const version = coder.version;
         const versions = this.versions.get(name) ?? new Map();
@@ -254,11 +277,29 @@ export class Script {
         if (this.versions.size === 0) {
             return [];
         }
-        const names = Array.from(this.versions, ([name, versions]) => {
-            const mappedVersions = Array.from(versions, ([version, versionStatement]) => `"${version}": ${versionStatement.code}`);
-            return `"${name}": { ${mappedVersions.join(", ")} }`;
-        });
-        return [`export type Versions = { ${names.join(", ")} };`];
+        const statements = [];
+        const unformatted = [];
+        for (const [name, versions] of this.versions) {
+            const formatter = this.versionFormatters.get(name);
+            if (formatter) {
+                const versionCodes = new Map(Array.from(versions, ([version, stmt]) => [
+                    version,
+                    stmt.code,
+                ]));
+                statements.push(formatter(versionCodes));
+            }
+            else {
+                unformatted.push([name, versions]);
+            }
+        }
+        if (unformatted.length > 0) {
+            const names = unformatted.map(([name, versions]) => {
+                const mappedVersions = Array.from(versions, ([version, versionStatement]) => `"${version}": ${versionStatement.code}`);
+                return `"${name}": { ${mappedVersions.join(", ")} }`;
+            });
+            statements.push(`export type Versions = { ${names.join(", ")} };`);
+        }
+        return statements;
     }
     /**
      * Formats the fully assembled script source with Prettier and returns it.

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

@@ -0,0 +1,82 @@
+import { format } from "prettier";
+/**
+ * Builds the `VersionsGTE` map: for each version V at index i,
+ * maps V to all versions at indices >= i (i.e. V and all later-declared
+ * versions, where "later" means "newer").
+ */
+function buildVersionsGTE(versions) {
+    const result = new Map();
+    versions.forEach((version, index) => {
+        result.set(version, versions.slice(index));
+    });
+    return result;
+}
+/**
+ * Generates the TypeScript source text for `types/versions.ts`.
+ *
+ * Returns an empty string when `versions` is empty.
+ * The returned string is formatted with Prettier.
+ *
+ * @param versions - Ordered list of unique, non-empty version strings.
+ *   The first entry is the oldest version.
+ */
+export async function generateVersionsTsContent(versions) {
+    if (versions.length === 0) {
+        return "";
+    }
+    const versionsUnion = versions.map((v) => `"${v}"`).join(" | ");
+    const versionsGTE = buildVersionsGTE(versions);
+    const versionsGTEBody = Array.from(versionsGTE, ([v, gte]) => `  "${v}": ${gte.map((g) => `"${g}"`).join(" | ")};`).join("\n");
+    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};`,
+        "",
+        "/**",
+        " * Maps each version to the set of versions that are greater than or equal to it.",
+        " * Used by `Versioned.minVersion()` to narrow which versions a handler must support.",
+        " */",
+        "export type VersionsGTE = {",
+        versionsGTEBody,
+        "};",
+        "",
+        "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,",
+        "> = T[V] & {",
+        "  version: V;",
+        "  minVersion<M extends keyof T & Versions>(",
+        "    min: M,",
+        "  ): this is Versioned<T, Extract<V, VersionsGTE[M]>>;",
+        "};",
+        "",
+    ].join("\n");
+    return format(source, { parser: "typescript" });
+}