@counterfact/generator 0.1.1

package/dist/schema-type-coder.js

@@ -0,0 +1,121 @@
+import { pathJoin } from "./forward-slash-path.js";
+import { buildJsDoc } from "./jsdoc.js";
+import { TypeCoder } from "./type-coder.js";
+import { Requirement } from "./requirement.js";
+export class SchemaTypeCoder extends TypeCoder {
+    names() {
+        return super.names(this.requirement.refUrl?.split("/").at(-1));
+    }
+    jsdoc() {
+        return buildJsDoc(this.requirement.data);
+    }
+    additionalPropertiesType(script) {
+        const { additionalProperties, properties } = this.requirement.data;
+        if (!additionalProperties.type) {
+            return "unknown";
+        }
+        if (Object.values(properties ?? {}).some((property) => property.type !== additionalProperties.type)) {
+            return "unknown";
+        }
+        const requirement = this.requirement.get("additionalProperties");
+        return new SchemaTypeCoder(requirement, this.version).write(script);
+    }
+    objectSchema(script) {
+        const { data } = this.requirement;
+        const typedData = data;
+        const properties = Object.keys(typedData.properties ?? {}).map((name) => {
+            const property = this.requirement.get("properties").get(name);
+            const propertyData = property.data;
+            const isRequired = typedData.required?.includes(name) || propertyData.required === true;
+            const optionalFlag = isRequired ? "" : "?";
+            const comment = buildJsDoc(property.data);
+            const commentPrefix = comment ? `\n${comment}` : "";
+            const propertyType = new SchemaTypeCoder(property, this.version).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${propertyType}`;
+        });
+        if (typedData.additionalProperties) {
+            properties.push(`[key: string]: ${this.additionalPropertiesType(script)}`);
+        }
+        return `{${properties.join(",")}}`;
+    }
+    arraySchema(script) {
+        return `Array<${new SchemaTypeCoder(this.requirement.get("items"), this.version).write(script)}>`;
+    }
+    writePrimitive(value) {
+        if (typeof value === "string") {
+            return `"${value}"`;
+        }
+        if (value === null) {
+            return "null";
+        }
+        return String(value);
+    }
+    writeType(script, type) {
+        if (Array.isArray(type)) {
+            return type
+                .map((item) => this.writeType(script, item))
+                .join(" | ");
+        }
+        if (typeof type !== "string") {
+            return "unknown";
+        }
+        if (type === "object") {
+            return this.objectSchema(script);
+        }
+        if (type === "array") {
+            return this.arraySchema(script);
+        }
+        if (type === "integer") {
+            return "number";
+        }
+        return type ?? "unknown";
+    }
+    writeGroup(script, { allOf, anyOf, oneOf, }) {
+        function matchingKey() {
+            if (allOf) {
+                return "allOf";
+            }
+            if (anyOf) {
+                return "anyOf";
+            }
+            return "oneOf";
+        }
+        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) {
+        return requirement.data
+            .map((item) => this.writePrimitive(item))
+            .join(" | ");
+    }
+    modulePath() {
+        return pathJoin("types", this.version, this.requirement.refUrl.replace(/^#\//u, "") + ".ts");
+    }
+    writeCode(script) {
+        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 });
+        }
+        if (this.requirement.has("enum")) {
+            return this.writeEnum(script, this.requirement.get("enum"));
+        }
+        if ((type === "string" && format === "binary") || type === "file") {
+            return "Uint8Array | string";
+        }
+        return this.writeType(script, type);
+    }
+}

package/dist/script.d.ts

@@ -0,0 +1,130 @@
+import type { Coder, ExportStatement } from "./coder.js";
+import type { Repository } from "./repository.js";
+interface ImportEntry {
+    isDefault: boolean;
+    isType: boolean;
+    name: string;
+    script: Script;
+}
+interface ExternalImportEntry {
+    isDefault?: boolean;
+    isType: boolean;
+    modulePath: string;
+}
+/**
+ * Represents a single TypeScript file being assembled by the code generator.
+ *
+ * A `Script` accumulates exports, imports, and external imports contributed by
+ * {@link Coder} instances.  Once all coders have resolved, {@link contents}
+ * formats the result with Prettier and returns the final source text.
+ *
+ * Scripts are created and retrieved through a {@link Repository} so that the
+ * same module path always maps to the same `Script` instance.
+ */
+export declare class Script {
+    repository: Repository;
+    comments: string[];
+    exports: Map<string, ExportStatement>;
+    versions: Map<string, Map<string, ExportStatement>>;
+    versionFormatters: Map<string, (versionCodes: Map<string, string>) => string>;
+    imports: Map<string, ImportEntry>;
+    externalImport: Map<string, ExternalImportEntry>;
+    cache: Map<string, string>;
+    typeCache: Map<string, string>;
+    path: string;
+    constructor(repository: Repository, path: string);
+    /**
+     * A `"../"` path fragment that points from this script's directory back to
+     * the repository root, used to resolve relative import paths.
+     */
+    get relativePathToBase(): string;
+    /**
+     * Picks the first name from `coder.names()` that is not already used as an
+     * import in this script, ensuring export/import name uniqueness.
+     *
+     * @param coder - The coder needing a name.
+     * @throws When all 100 candidate names are already taken.
+     */
+    firstUniqueName(coder: Coder): string;
+    /**
+     * Registers an export for `coder` in this script and returns the export name.
+     *
+     * If the same coder has already been exported (cache hit), the previously
+     * assigned name is returned without creating a duplicate.
+     *
+     * @param coder - The coder to export.
+     * @param isType - Emit `export type` instead of `export const`.
+     * @param isDefault - Emit `export default` instead of a named export.
+     * @returns The name under which the coder is exported.
+     */
+    export(coder: Coder, isType?: boolean, isDefault?: boolean): string;
+    exportDefault(coder: Coder, isType?: boolean): void;
+    /**
+     * Registers an import of `coder` from its owning module and returns the
+     * local alias used in this script.
+     *
+     * The coder is also exported from its home module as a side effect.
+     *
+     * @param coder - The coder to import.
+     * @param isType - Use a `import type` declaration.
+     * @param isDefault - Import the default export rather than a named export.
+     */
+    import(coder: Coder, isType?: boolean, isDefault?: boolean): string;
+    importType(coder: Coder): string;
+    importDefault(coder: Coder, isType?: boolean): string;
+    /**
+     * Registers an import from an external npm package or absolute module path
+     * (not managed by the repository).
+     *
+     * @param name - The local binding name.
+     * @param modulePath - The module specifier (e.g. `"counterfact-types/index"`).
+     * @param isType - Use a `import type` declaration.
+     * @returns `name` (for convenience in method chaining).
+     */
+    importExternal(name: string, modulePath: string, isType?: boolean): string;
+    /**
+     * Convenience wrapper that calls {@link importExternal} with `isType = true`.
+     */
+    importExternalType(name: string, modulePath: string): string;
+    /**
+     * Imports a type from the shared `counterfact-types/index.ts` module,
+     * resolving the path relative to this script's location in the repository.
+     *
+     * @param name - The type name to import (e.g. `"WideOperationArgument"`).
+     */
+    importSharedType(name: string): string;
+    /**
+     * 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: string): string;
+    exportType(coder: Coder): string;
+    /**
+     * 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: string, formatter: (versionCodes: Map<string, string>) => string): void;
+    declareVersion(coder: Coder, name: string): void;
+    /** `true` while at least one export promise is still pending. */
+    isInProgress(): boolean;
+    /** Returns a promise that resolves when all pending export promises settle. */
+    finished(): Promise<(Coder | undefined)[]>;
+    externalImportStatements(): string[];
+    importStatements(): string[];
+    exportStatements(): string[];
+    versionsTypeStatements(): string[];
+    /**
+     * Formats the fully assembled script source with Prettier and returns it.
+     *
+     * All pending export promises are awaited before formatting.
+     */
+    contents(): Promise<string>;
+}
+export {};

package/dist/script.js

@@ -0,0 +1,322 @@
+import createDebugger from "debug";
+import { format } from "prettier";
+import { escapePathForWindows } from "./windows-escape.js";
+import { pathJoin, pathRelative, pathDirname } from "./forward-slash-path.js";
+const debug = createDebugger("counterfact:typescript-generator:script");
+/**
+ * Represents a single TypeScript file being assembled by the code generator.
+ *
+ * A `Script` accumulates exports, imports, and external imports contributed by
+ * {@link Coder} instances.  Once all coders have resolved, {@link contents}
+ * formats the result with Prettier and returns the final source text.
+ *
+ * Scripts are created and retrieved through a {@link Repository} so that the
+ * same module path always maps to the same `Script` instance.
+ */
+export class Script {
+    repository;
+    comments;
+    exports;
+    versions;
+    versionFormatters;
+    imports;
+    externalImport;
+    cache;
+    typeCache;
+    path;
+    constructor(repository, path) {
+        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();
+        this.typeCache = new Map();
+        this.path = path;
+    }
+    /**
+     * A `"../"` path fragment that points from this script's directory back to
+     * the repository root, used to resolve relative import paths.
+     */
+    get relativePathToBase() {
+        return this.path
+            .split("/")
+            .slice(0, -1)
+            .map(() => "..")
+            .join("/");
+    }
+    /**
+     * Picks the first name from `coder.names()` that is not already used as an
+     * import in this script, ensuring export/import name uniqueness.
+     *
+     * @param coder - The coder needing a name.
+     * @throws When all 100 candidate names are already taken.
+     */
+    firstUniqueName(coder) {
+        for (const name of coder.names()) {
+            if (!this.imports.has(name)) {
+                return name;
+            }
+        }
+        throw new Error(`could not find a unique name for ${coder.id}`);
+    }
+    /**
+     * Registers an export for `coder` in this script and returns the export name.
+     *
+     * If the same coder has already been exported (cache hit), the previously
+     * assigned name is returned without creating a duplicate.
+     *
+     * @param coder - The coder to export.
+     * @param isType - Emit `export type` instead of `export const`.
+     * @param isDefault - Emit `export default` instead of a named export.
+     * @returns The name under which the coder is exported.
+     */
+    export(coder, isType = false, isDefault = false) {
+        const cacheKey = isDefault ? "default" : `${coder.id}:${isType}`;
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
+        const name = this.firstUniqueName(coder);
+        this.cache.set(cacheKey, name);
+        const exportStatement = {
+            beforeExport: coder.beforeExport(this.path),
+            done: false,
+            id: coder.id,
+            isDefault,
+            isType,
+            jsdoc: "",
+            typeDeclaration: coder.typeDeclaration(this.exports, this),
+        };
+        exportStatement.promise = coder
+            .delegate()
+            .then((availableCoder) => {
+            exportStatement.name = name;
+            exportStatement.code = availableCoder.write(this);
+            exportStatement.jsdoc = availableCoder.jsdoc();
+            return availableCoder;
+        })
+            .catch((error) => {
+            exportStatement.code = `{/* error creating export "${name}" for ${this.path}: ${error.stack} */}`;
+            exportStatement.error = error;
+            return undefined;
+        })
+            .finally(() => {
+            exportStatement.done = true;
+        });
+        this.exports.set(name, exportStatement);
+        return name;
+    }
+    exportDefault(coder, isType = false) {
+        this.export(coder, isType, true);
+    }
+    /**
+     * Registers an import of `coder` from its owning module and returns the
+     * local alias used in this script.
+     *
+     * The coder is also exported from its home module as a side effect.
+     *
+     * @param coder - The coder to import.
+     * @param isType - Use a `import type` declaration.
+     * @param isDefault - Import the default export rather than a named export.
+     */
+    import(coder, isType = false, isDefault = false) {
+        debug("import coder: %s", coder.id);
+        const modulePath = coder.modulePath();
+        const cacheKey = `${coder.id}@${modulePath}:${isType}:${isDefault}`;
+        debug("cache key: %s", cacheKey);
+        if (this.cache.has(cacheKey)) {
+            debug("cache hit: %s", cacheKey);
+            return this.cache.get(cacheKey);
+        }
+        debug("cache miss: %s", cacheKey);
+        const name = this.firstUniqueName(coder);
+        this.cache.set(cacheKey, name);
+        const scriptFromWhichToExport = this.repository.get(modulePath);
+        const exportedName = scriptFromWhichToExport.export(coder, isType, isDefault);
+        this.imports.set(name, {
+            isDefault,
+            isType,
+            name: exportedName,
+            script: scriptFromWhichToExport,
+        });
+        return name;
+    }
+    importType(coder) {
+        return this.import(coder, true);
+    }
+    importDefault(coder, isType = false) {
+        return this.import(coder, isType, true);
+    }
+    /**
+     * Registers an import from an external npm package or absolute module path
+     * (not managed by the repository).
+     *
+     * @param name - The local binding name.
+     * @param modulePath - The module specifier (e.g. `"counterfact-types/index"`).
+     * @param isType - Use a `import type` declaration.
+     * @returns `name` (for convenience in method chaining).
+     */
+    importExternal(name, modulePath, isType = false) {
+        this.externalImport.set(name, { isType, modulePath });
+        return name;
+    }
+    /**
+     * Convenience wrapper that calls {@link importExternal} with `isType = true`.
+     */
+    importExternalType(name, modulePath) {
+        return this.importExternal(name, modulePath, true);
+    }
+    /**
+     * Imports a type from the shared `counterfact-types/index.ts` module,
+     * resolving the path relative to this script's location in the repository.
+     *
+     * @param name - The type name to import (e.g. `"WideOperationArgument"`).
+     */
+    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) ||
+            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),
+            ...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}";`);
+    }
+    importStatements() {
+        return Array.from(this.imports, ([name, { isDefault, isType, script }]) => {
+            const resolvedPath = escapePathForWindows(pathRelative(pathDirname(this.path), script.path.replace(/\.ts$/u, ".js")));
+            return `import${isType ? " type" : ""} ${isDefault ? name : `{ ${name} }`} from "${resolvedPath.includes("../") ? "" : "./"}${resolvedPath}";`;
+        });
+    }
+    exportStatements() {
+        return Array.from(this.exports.values(), ({ beforeExport, code, isDefault, isType, jsdoc, name, typeDeclaration, }) => {
+            if (typeof code === "object" && code !== null && "raw" in code) {
+                return code.raw;
+            }
+            if (isDefault) {
+                return `${jsdoc}${beforeExport}export default ${code};`;
+            }
+            const keyword = isType ? "type" : "const";
+            const typeAnnotation = (typeDeclaration ?? "").length === 0
+                ? ""
+                : `:${typeDeclaration ?? ""}`;
+            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.
+     */
+    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/specification.d.ts

@@ -0,0 +1,40 @@
+import { Requirement } from "./requirement.js";
+/**
+ * Represents a fully dereferenced OpenAPI specification as a navigable tree
+ * of {@link Requirement} nodes.
+ *
+ * Use {@link Specification.fromFile} to load a spec from disk or a URL; the
+ * static method bundles external `$ref` references into a single in-memory
+ * object before constructing the tree.
+ */
+export declare class Specification {
+    cache: Map<string, Requirement>;
+    rootRequirement: Requirement;
+    constructor(rootRequirement?: Requirement);
+    /**
+     * 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 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 fromFile(urlOrPath: string, overlays?: readonly string[]): Promise<Specification>;
+    /**
+     * Returns the {@link Requirement} at `url` (a JSON Pointer such as
+     * `"#/paths"`).
+     *
+     * @param url - A JSON Pointer string (must start with `"#/"`).
+     */
+    getRequirement(url: string): Requirement;
+    /**
+     * 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.
+     */
+    load(urlOrPath: string, overlays?: readonly string[]): Promise<void>;
+}

package/dist/specification.js

@@ -0,0 +1,58 @@
+import { bundleOpenApiDocument } from "@counterfact/openapi";
+import createDebug from "debug";
+import { Requirement } from "./requirement.js";
+const debug = createDebug("counterfact:typescript-generator:specification");
+/**
+ * Represents a fully dereferenced OpenAPI specification as a navigable tree
+ * of {@link Requirement} nodes.
+ *
+ * Use {@link Specification.fromFile} to load a spec from disk or a URL; the
+ * static method bundles external `$ref` references into a single in-memory
+ * object before constructing the tree.
+ */
+export class Specification {
+    cache;
+    rootRequirement;
+    constructor(rootRequirement) {
+        this.cache = new Map();
+        if (rootRequirement) {
+            this.rootRequirement = rootRequirement;
+        }
+    }
+    /**
+     * 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 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, overlays = []) {
+        const specification = new Specification();
+        await specification.load(urlOrPath, overlays);
+        return specification;
+    }
+    /**
+     * Returns the {@link Requirement} at `url` (a JSON Pointer such as
+     * `"#/paths"`).
+     *
+     * @param url - A JSON Pointer string (must start with `"#/"`).
+     */
+    getRequirement(url) {
+        debug("getting requirement at %s", url);
+        return this.rootRequirement.select(url.slice(2));
+    }
+    /**
+     * 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, overlays = []) {
+        const document = (await bundleOpenApiDocument(urlOrPath, overlays));
+        this.rootRequirement = new Requirement(document, urlOrPath, this);
+    }
+}

package/dist/templates/counterfact-types/cookie-options.ts

@@ -0,0 +1,14 @@
+/**
+ * Options for setting an HTTP cookie on a response.
+ * These correspond to standard `Set-Cookie` attributes and are passed to the
+ * `.cookie()` method on the response builder.
+ */
+export interface CookieOptions {
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "lax" | "none" | "strict";
+  secure?: boolean;
+}