counterfact 2.9.0 → 2.11.0

package/dist/server/dispatcher.js

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

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

package/dist/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/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;
     }
     /**
@@ -116,7 +118,7 @@ export class CodeGenerator extends EventTarget {
                 }
                 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

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

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

@@ -1,6 +1,6 @@
 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";
 /**
  * Generates the default route handler stub for a single OpenAPI operation.
  *
@@ -14,9 +14,9 @@ import { OperationTypeCoder, } from "./operation-type-coder.js";
 export class OperationCoder extends Coder {
     requestMethod;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -40,7 +40,15 @@ export class OperationCoder extends Coder {
     }`;
     }
     typeDeclaration(_namespace, script) {
-        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.requestMethod, this.securitySchemes);
+        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
+        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() {

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

@@ -8,6 +8,7 @@ import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.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,13 +33,21 @@ 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;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -79,7 +88,7 @@ export class OperationTypeCoder extends TypeCoder {
         }
         const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
         const typeName = `${baseName}_${capitalize(parameterKind)}`;
-        const coder = new ParameterExportTypeCoder(this.requirement, typeName, inlineType, parameterKind);
+        const coder = new ParameterExportTypeCoder(this.requirement, this.version, typeName, inlineType, parameterKind);
         coder._modulePath = modulePath;
         return script.export(coder, true);
     }
@@ -99,7 +108,7 @@ export class OperationTypeCoder extends TypeCoder {
                 return response.get("content").map((content, contentType) => `{  
               status: ${status}, 
               contentType?: "${contentType}",
-              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
             }`);
             }
             if (response.has("schema")) {
@@ -111,7 +120,7 @@ export class OperationTypeCoder extends TypeCoder {
                         .map((contentType) => `{
             status: ${status},
             contentType?: "${contentType}",
-            body?: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            body?: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
           }`)
                         .join(" | ");
                 }
@@ -141,18 +150,61 @@ 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 queryType = new ParametersTypeCoder(parameters, "query").write(script);
-        const pathType = new ParametersTypeCoder(parameters, "path").write(script);
-        const headersType = new ParametersTypeCoder(parameters, "header").write(script);
-        const cookieType = new ParametersTypeCoder(parameters, "cookie").write(script);
+        const 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);
+        const cookieType = new ParametersTypeCoder(parameters, this.version, "cookie").write(script);
         const bodyRequirement = (this.requirement.get("consumes") ??
             this.requirement.specification?.rootRequirement?.get("consumes"))
             ? parameters
@@ -161,19 +213,121 @@ export class OperationTypeCoder extends TypeCoder {
             : this.requirement.select("requestBody/content/application~1json/schema");
         const bodyType = bodyRequirement === undefined
             ? "never"
-            : new SchemaTypeCoder(bodyRequirement).write(script);
-        const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), (this.requirement.get("produces")?.data ??
+            : new SchemaTypeCoder(bodyRequirement, this.version).write(script);
+        const openApi2MediaTypes = (this.requirement.get("produces")?.data ??
             this.requirement.specification?.rootRequirement?.get("produces")
-                ?.data)).write(script);
+                ?.data);
+        const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), this.version, openApi2MediaTypes).write(script);
         const proxyType = "(url: string) => COUNTERFACT_RESPONSE";
         const delayType = "(milliseconds: number, maxMilliseconds?: number) => Promise<void>";
-        // Get the base name for this operation and export parameter types
-        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<${this.responseTypes(script)} | { status: 415, contentType: "text/plain", body: string } | COUNTERFACT_RESPONSE | { ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE }>`;
+        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} }>`;
+    }
+    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/parameter-export-type-coder.js

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

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

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