counterfact 2.9.0 → 2.11.0

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;
@@ -53,7 +62,9 @@ export class Requirement {
         if (!this.has(key)) {
             return undefined;
         }
-        return new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
+        const child = new Requirement(this.data[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.

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

@@ -1,10 +1,11 @@
 import { printObject } from "./printers.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
+import { pathJoin } from "../util/forward-slash-path.js";
 export class ResponseTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     names() {
@@ -17,14 +18,14 @@ export class ResponseTypeCoder extends TypeCoder {
                 .map((content, mediaType) => [
                 mediaType,
                 `{ 
-            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
          }`,
             ]);
         }
         return this.openApi2MediaTypes.map((mediaType) => [
             mediaType,
             `{
-            schema: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            schema: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
          }`,
         ]);
     }
@@ -39,7 +40,7 @@ export class ResponseTypeCoder extends TypeCoder {
             .get("headers")
             .map((value, name) => [
             name,
-            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value).write(script)}}`,
+            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value, this.version).write(script)}}`,
         ]);
     }
     printHeaders(script, response) {
@@ -77,7 +78,7 @@ export class ResponseTypeCoder extends TypeCoder {
         return printObject(exampleNames.map((name) => [name, "unknown"]));
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"]}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"] + ".ts");
     }
     writeCode(script) {
         return `{

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

@@ -3,8 +3,8 @@ import { ResponseTypeCoder } from "./response-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ResponsesTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     typeForDefaultStatusCode(listedStatusCodes) {
@@ -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.openApi2MediaTypes).write(script),
-        ]));
+            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

@@ -13,7 +13,7 @@ export class SchemaCoder extends Coder {
     objectSchema(script) {
         const { properties, required } = this.requirement.data;
         const propertyLines = Object.keys(properties ?? {}).map((name) => {
-            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`));
+            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`), this.version);
             return `"${name}": ${schemaCoder.write(script)}`;
         });
         return `
@@ -27,7 +27,7 @@ export class SchemaCoder extends Coder {
     arraySchema(script) {
         return `{
         type: "array",     
-        items: ${new SchemaCoder(this.requirement.get("items")).write(script)}
+        items: ${new SchemaCoder(this.requirement.get("items"), this.version).write(script)}
       }`;
     }
     typeDeclaration(_namespace, script) {

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

@@ -1,5 +1,6 @@
 import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.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));
@@ -16,7 +17,7 @@ export class SchemaTypeCoder extends TypeCoder {
             return "unknown";
         }
         const requirement = this.requirement.get("additionalProperties");
-        return new SchemaTypeCoder(requirement).write(script);
+        return new SchemaTypeCoder(requirement, this.version).write(script);
     }
     objectSchema(script) {
         const { data } = this.requirement;
@@ -28,7 +29,8 @@ export class SchemaTypeCoder extends TypeCoder {
             const optionalFlag = isRequired ? "" : "?";
             const comment = buildJsDoc(property.data);
             const commentPrefix = comment ? `\n${comment}` : "";
-            return `${commentPrefix}"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(script)}`;
+            const propertyType = new SchemaTypeCoder(property, this.version).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${propertyType}`;
         });
         if (typedData.additionalProperties) {
             properties.push(`[key: string]: ${this.additionalPropertiesType(script)}`);
@@ -36,7 +38,7 @@ export class SchemaTypeCoder extends TypeCoder {
         return `{${properties.join(",")}}`;
     }
     arraySchema(script) {
-        return `Array<${new SchemaTypeCoder(this.requirement.get("items")).write(script)}>`;
+        return `Array<${new SchemaTypeCoder(this.requirement.get("items"), this.version).write(script)}>`;
     }
     writePrimitive(value) {
         if (typeof value === "string") {
@@ -79,7 +81,7 @@ 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)).write(script));
+        const types = items.map((_item, index) => new SchemaTypeCoder(this.requirement.get(key).get(index), this.version).write(script));
         return types.join(allOf ? " & " : " | ");
     }
     writeEnum(_script, requirement) {
@@ -88,7 +90,7 @@ export class SchemaTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"].replace(/^#\//u, "")}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"].replace(/^#\//u, "") + ".ts");
     }
     writeCode(script) {
         const { allOf, anyOf, oneOf, type, format } = this.requirement.data;

package/dist/typescript-generator/script.js

@@ -17,6 +17,8 @@ export class Script {
     repository;
     comments;
     exports;
+    versions;
+    versionFormatters;
     imports;
     externalImport;
     cache;
@@ -26,6 +28,8 @@ export class Script {
         this.repository = repository;
         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();
@@ -173,16 +177,77 @@ 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();
+        this.versions.set(name, versions);
+        if (versions.has(version)) {
+            return;
+        }
+        const versionStatement = {
+            beforeExport: "",
+            done: false,
+            id: coder.id,
+            isDefault: false,
+            isType: true,
+            jsdoc: "",
+            typeDeclaration: "",
+        };
+        versionStatement.promise = coder
+            .delegate()
+            .then((availableCoder) => {
+            versionStatement.code = availableCoder.write(this);
+            return availableCoder;
+        })
+            .catch((error) => {
+            versionStatement.code = `unknown /* error declaring version "${name}" (${version}) for ${this.path}: ${error.message} */`;
+            versionStatement.error = error;
+            return undefined;
+        })
+            .finally(() => {
+            versionStatement.done = true;
+        });
+        versions.set(version, versionStatement);
+    }
     /** `true` while at least one export promise is still pending. */
     isInProgress() {
-        return Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done);
+        return (Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done) ||
+            Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .some((versionStatement) => !versionStatement.done));
     }
     /** Returns a promise that resolves when all pending export promises settle. */
     finished() {
-        return Promise.all(Array.from(this.exports.values(), (value) => value.promise));
+        return Promise.all([
+            ...Array.from(this.exports.values(), (value) => value.promise),
+            ...Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .map((value) => value.promise),
+        ]);
     }
     externalImportStatements() {
         return Array.from(this.externalImport, ([name, { isDefault, isType, modulePath }]) => `import${isType ? " type" : ""} ${isDefault ? name : `{ ${name} }`} from "${modulePath}";`);
@@ -208,18 +273,49 @@ export class Script {
             return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
         });
     }
+    versionsTypeStatements() {
+        if (this.versions.size === 0) {
+            return [];
+        }
+        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.
      *
      * All pending export promises are awaited before formatting.
      */
-    contents() {
+    async contents() {
+        await this.finished();
         return format([
             this.comments.map((comment) => `// ${comment}`).join("\n"),
             this.comments.length > 0 ? "\n\n" : "",
             this.externalImportStatements().join("\n"),
             this.importStatements().join("\n"),
             "\n\n",
+            this.versionsTypeStatements().join("\n"),
+            this.versions.size > 0 ? "\n\n" : "",
             this.exportStatements().join("\n\n"),
         ].join(""), { parser: "typescript" });
     }

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

@@ -0,0 +1,57 @@
+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.",
+        "",
+        `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>>;",
+        "",
+        "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" });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.9.0",
+  "version": "2.11.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",