counterfact 2.7.0 → 2.8.1

package/dist/typescript-generator/coder.js

@@ -1,30 +1,84 @@
 import { RESERVED_WORDS } from "./reserved-words.js";
+/**
+ * Base class for all code-generation helpers in the TypeScript generator.
+ *
+ * A `Coder` wraps a single {@link Requirement} node from the OpenAPI spec and
+ * knows how to emit TypeScript code for it.  Subclasses override
+ * {@link writeCode} to produce the actual source text.
+ *
+ * Coders are used by {@link Script} and {@link Repository} to lazily generate
+ * exports and imports, resolving `$ref` references through the
+ * {@link Specification} before writing.
+ */
 export class Coder {
     requirement;
     constructor(requirement) {
         this.requirement = requirement;
     }
+    /**
+     * A stable cache key for this coder, composed of the constructor name and
+     * either the `$ref` value (for references) or the requirement URL.
+     */
     get id() {
         if (this.requirement.isReference) {
             return `${this.constructor.name}@${this.requirement.data["$ref"]}`;
         }
         return `${this.constructor.name}@${this.requirement.url}`;
     }
+    /**
+     * Optional preamble emitted before the `export` keyword.
+     *
+     * Subclasses can return a string (e.g. a type alias) that must appear in the
+     * output before this coder's export statement.
+     *
+     * @param _path - The path of the script being written (unused in base class).
+     */
     beforeExport(_path) {
         return "";
     }
+    /**
+     * Returns a JSDoc comment block to be placed immediately before the export.
+     *
+     * Returns `""` by default; subclasses override this to surface OpenAPI
+     * metadata (description, summary, examples, etc.).
+     */
     jsdoc() {
         return "";
     }
+    /**
+     * Writes this coder's contribution to `script`.
+     *
+     * When the requirement is a `$ref`, delegates to {@link Script.import} so
+     * the reference target is exported from its own module.  Otherwise calls
+     * {@link writeCode}.
+     *
+     * @param script - The script being assembled.
+     * @returns The TypeScript source text for this coder's export value.
+     */
     write(script) {
         if (this.requirement.isReference) {
             return script.import(this);
         }
         return this.writeCode(script);
     }
+    /**
+     * Generates the TypeScript source text for this coder's value.
+     *
+     * This method is abstract — subclasses **must** override it.
+     *
+     * @param _script - The script being assembled.
+     * @throws Always — callers should never reach the base implementation.
+     */
     writeCode(_script) {
         throw new Error("write() is abstract and should be overwritten by a subclass");
     }
+    /**
+     * Resolves `$ref` references by returning the target coder.
+     *
+     * When this coder's requirement is not a reference, returns `this`.
+     * Otherwise loads the referenced requirement and wraps it in an instance of
+     * the same concrete coder class.
+     */
     async delegate() {
         if (!this.requirement.isReference) {
             return this;
@@ -32,6 +86,15 @@ export class Coder {
         const requirement = await this.requirement.reference();
         return new this.constructor(requirement);
     }
+    /**
+     * Generator that yields candidate export names for this coder.
+     *
+     * The first name is derived from the last path segment of the requirement
+     * URL, sanitised to be a valid TypeScript identifier.  Subsequent names have
+     * an incrementing numeric suffix to resolve collisions.
+     *
+     * @param rawName - Override the starting name (used by subclasses).
+     */
     *names(rawName = this.requirement.url.split("/").at(-1)) {
         const name = rawName
             .replace(/^\d/u, (digit) => `_${digit}`)
@@ -45,9 +108,22 @@ export class Coder {
             yield baseName + index;
         }
     }
+    /**
+     * Returns an optional TypeScript type annotation string to be placed between
+     * the export name and its value (`export const name: <type> = value`).
+     *
+     * Returns `""` by default.
+     */
     typeDeclaration(_namespace, _script) {
         return "";
     }
+    /**
+     * Returns the repository-relative path of the script where this coder's
+     * export should live when imported by another script.
+     *
+     * Subclasses override this to place type exports in `types/paths/…` and
+     * route exports in `routes/…`.
+     */
     modulePath() {
         return "did-not-override-coder-modulePath.ts";
     }

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

@@ -1,6 +1,16 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
 import { OperationTypeCoder, } from "./operation-type-coder.js";
+/**
+ * Generates the default route handler stub for a single OpenAPI operation.
+ *
+ * The generated stub calls `$.response[statusCode].random()` (or `.empty()`)
+ * for the first response defined in the spec.  It is only written when no
+ * handler file exists yet — users are expected to replace it with real logic.
+ *
+ * The corresponding TypeScript type is emitted by {@link OperationTypeCoder}
+ * into the `types/paths/…` tree.
+ */
 export class OperationCoder extends Coder {
     requestMethod;
     securitySchemes;
@@ -38,8 +48,6 @@ export class OperationCoder extends Coder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("routes", pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("routes", pathString)}.types.ts`;
     }
 }

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

@@ -1,4 +1,4 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
 import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
@@ -24,6 +24,15 @@ function sanitizeIdentifier(value) {
     }
     return result || "_";
 }
+/**
+ * Generates the TypeScript type for a single OpenAPI operation.
+ *
+ * The emitted type describes the function signature that a Counterfact route
+ * handler must satisfy, including strongly-typed `query`, `path`, `headers`,
+ * `cookie`, `body`, `context`, `response`, and `user` arguments.
+ *
+ * Output is written to `types/paths/<route>.types.ts`.
+ */
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
     securitySchemes;
@@ -35,6 +44,10 @@ export class OperationTypeCoder extends TypeCoder {
         this.requestMethod = requestMethod;
         this.securitySchemes = securitySchemes;
     }
+    /**
+     * Returns the base identifier for this operation, derived from its
+     * `operationId` (sanitised) or falling back to `HTTP_<METHOD>`.
+     */
     getOperationBaseName() {
         const operationId = this.requirement.get("operationId")?.data;
         return operationId
@@ -47,6 +60,19 @@ export class OperationTypeCoder extends TypeCoder {
     names() {
         return super.names(this.getOperationBaseName());
     }
+    /**
+     * Generates and exports a named parameter type (e.g. `ListPets_Query`) from
+     * `modulePath` and returns the exported type name.
+     *
+     * Returns `"never"` without creating an export when `inlineType` is
+     * `"never"`.
+     *
+     * @param script - The script being assembled.
+     * @param parameterKind - `"query"`, `"path"`, `"headers"`, or `"cookie"`.
+     * @param inlineType - The inline TypeScript type string to export.
+     * @param baseName - The base identifier prefix for the exported type name.
+     * @param modulePath - The repository-relative path of the type file.
+     */
     exportParameterType(script, parameterKind, inlineType, baseName, modulePath) {
         if (inlineType === "never") {
             return "never";
@@ -57,6 +83,11 @@ export class OperationTypeCoder extends TypeCoder {
         coder._modulePath = modulePath;
         return script.export(coder, true);
     }
+    /**
+     * Returns the union of all possible response type shapes for this operation.
+     *
+     * @param script - The script being assembled (used to resolve imports).
+     */
     responseTypes(script) {
         return this.requirement
             .get("responses")
@@ -96,10 +127,14 @@ export class OperationTypeCoder extends TypeCoder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("types/paths", pathString === "/" ? "/index" : pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("types/paths", pathString === "/" ? "/index" : pathString)}.types.ts`;
     }
+    /**
+     * Returns the TypeScript type for the `user` argument.
+     *
+     * When the operation is protected by HTTP Basic auth, the type is
+     * `{username?: string, password?: string}`.  Otherwise it is `"never"`.
+     */
     userType() {
         if (this.securitySchemes.some(({ scheme, type }) => type === "http" && scheme === "basic")) {
             return "{username?: string, password?: string}";

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

@@ -1,4 +1,4 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { buildJsDoc } from "./jsdoc.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
@@ -39,8 +39,6 @@ export class ParametersTypeCoder extends TypeCoder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("parameters", pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("parameters", pathString)}.types.ts`;
     }
 }

package/dist/typescript-generator/prune.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import nodePath from "node:path";
 import createDebug from "debug";
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 const debug = createDebug("counterfact:typescript-generator:prune");
 /**
  * Collects all .ts route files in a directory recursively.
@@ -87,7 +88,7 @@ export async function pruneRoutes(destination, openApiPaths) {
     debug("actual route files: %o", actualFiles);
     let prunedCount = 0;
     for (const file of actualFiles) {
-        const normalizedFile = file.replaceAll("\\", "/");
+        const normalizedFile = toForwardSlashPath(file);
         if (!expectedFiles.has(normalizedFile)) {
             const fullPath = nodePath.join(routesDir, file);
             debug("pruning %s", fullPath);

package/dist/typescript-generator/repository.js

@@ -4,17 +4,33 @@ import nodePath, { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
+import { toForwardSlashPath, pathJoin, pathRelative, pathDirname, } from "../util/forward-slash-path.js";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
 import { Script } from "./script.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 const debug = createDebug("counterfact:server:repository");
-const __dirname = dirname(fileURLToPath(import.meta.url)).replaceAll("\\", "/");
+const __dirname = toForwardSlashPath(dirname(fileURLToPath(import.meta.url)));
 debug("dirname is %s", __dirname);
+/**
+ * Collection of {@link Script} objects keyed by their repository-relative
+ * path.
+ *
+ * Coders call {@link get} to obtain (or create) the script where they should
+ * export their generated TypeScript.  After all coders have been registered,
+ * {@link writeFiles} waits for every script to finish and writes the output to
+ * disk.
+ */
 export class Repository {
     scripts;
     constructor() {
         this.scripts = new Map();
     }
+    /**
+     * Returns the {@link Script} for `path`, creating it if it does not yet
+     * exist.
+     *
+     * @param path - Repository-relative path (e.g. `"routes/pets.ts"`).
+     */
     get(path) {
         debug("getting script at %s", path);
         if (this.scripts.has(path)) {
@@ -26,12 +42,22 @@ export class Repository {
         this.scripts.set(path, script);
         return script;
     }
+    /** Waits until all scripts have resolved all of their pending export promises. */
     async finished() {
         while (Array.from(this.scripts.values()).some((script) => script.isInProgress())) {
             debug("waiting for %i scripts to finish", this.scripts.size);
             await Promise.all(Array.from(this.scripts.values(), (script) => script.finished()));
         }
     }
+    /**
+     * Copies the compiled `counterfact-types` directory from the Counterfact
+     * distribution into the generated output tree.
+     *
+     * Returns `false` when the source directory does not exist (e.g. running
+     * from source without a prior build).
+     *
+     * @param destination - The root of the generated output tree.
+     */
     async copyCoreFiles(destination) {
         const sourcePath = nodePath.join(__dirname, "../../dist/server/counterfact-types");
         const destinationPath = nodePath.join(destination, "counterfact-types");
@@ -40,13 +66,23 @@ export class Repository {
         }
         return fs.cp(sourcePath, destinationPath, { recursive: true });
     }
+    /**
+     * Waits for all scripts to finish, then writes each one to disk.
+     *
+     * Route files (`routes/…`) are never overwritten if they already exist on
+     * disk, preserving user edits.  Type files (`types/…`) are always
+     * overwritten.
+     *
+     * @param destination - Absolute path to the output root directory.
+     * @param options - Controls which artefacts are written.
+     */
     async writeFiles(destination, { routes, types }) {
         debug("waiting for %i or more scripts to finish before writing files", this.scripts.size);
         await this.finished();
         debug("all %i scripts are finished", this.scripts.size);
         const writeFiles = Array.from(this.scripts.entries(), async ([path, script]) => {
             const contents = await script.contents();
-            const fullPath = escapePathForWindows(nodePath.join(destination, path).replaceAll("\\", "/"));
+            const fullPath = escapePathForWindows(pathJoin(destination, path));
             await ensureDirectoryExists(fullPath);
             const shouldWriteRoutes = routes && path.startsWith("routes");
             const shouldWriteTypes = types && !path.startsWith("routes");
@@ -70,37 +106,57 @@ export class Repository {
             await this.createDefaultContextFile(destination);
         }
     }
+    /**
+     * Creates the default `routes/_.context.ts` file if it does not already
+     * exist.
+     *
+     * @param destination - Absolute path to the output root directory.
+     */
     async createDefaultContextFile(destination) {
         const contextFilePath = nodePath.join(destination, "routes", "_.context.ts");
         if (existsSync(contextFilePath)) {
             return;
         }
         await ensureDirectoryExists(contextFilePath);
-        await fs.writeFile(contextFilePath, `/**
-* This is the default context for Counterfact.
-*
-* It defines the context object in the REPL 
-* and the $.context object in the code.
-*
-* Add properties and methods to suit your needs.
-* 
-* See https://counterfact.dev/docs/usage.html#working-with-state-the-codecontextcode-object-and-codecontexttscode
-*/
-export class Context {
+        await fs.writeFile(contextFilePath, `import type { Context$ } from "../types/_.context.js";
+
+/**
+ * This is the default context for Counterfact.
+ *
+ * It defines the context object in the REPL
+ * and the $.context object in the code.
+ *
+ * Add properties and methods to suit your needs.
+ *
+ * See https://github.com/counterfact/api-simulator/blob/main/docs/features/state.md
+ */
 
+export class Context {
+  constructor($: Context$) {
+    void $;
+  }
 }
 `);
     }
+    /**
+     * Returns the path of the `_.context.ts` file that is nearest to `path` in
+     * the directory hierarchy, relative to the script's output directory.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path of the script being generated.
+     */
     findContextPath(destination, path) {
-        return nodePath
-            .relative(nodePath.join(destination, nodePath.dirname(path)), this.nearestContextFile(destination, path))
-            .replaceAll("\\", "/");
+        return pathRelative(nodePath.join(destination, nodePath.dirname(path)), this.nearestContextFile(destination, path));
     }
+    /**
+     * Walks up the directory tree from `path` to find the nearest
+     * `_.context.ts` file, falling back to `routes/_.context.ts` at the root.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path to start from.
+     */
     nearestContextFile(destination, path) {
-        const directory = nodePath
-            .dirname(path)
-            .replaceAll("\\", "/")
-            .replace("types/paths", "routes");
+        const directory = pathDirname(path).replace("types/paths", "routes");
         const candidate = nodePath.join(destination, directory, "_.context.ts");
         if (directory.length <= 1) {
             // No _context.ts was found so import the one that should be in the root

package/dist/typescript-generator/requirement.js

@@ -1,3 +1,11 @@
+/**
+ * A node in the dereferenced OpenAPI spec tree.
+ *
+ * A `Requirement` wraps a raw JSON object (`data`) together with its location
+ * (`url`, a JSON Pointer) and a back-reference to the owning
+ * {@link Specification}.  Navigation methods (`get`, `select`, `find`, …)
+ * transparently follow `$ref` pointers.
+ */
 export class Requirement {
     data;
     url;
@@ -7,18 +15,36 @@ export class Requirement {
         this.url = url;
         this.specification = specification;
     }
+    /** `true` when this node is a JSON Reference (`$ref`) rather than inline data. */
     get isReference() {
         return this.data["$ref"] !== undefined;
     }
+    /**
+     * Resolves the `$ref` and returns the target {@link Requirement}.
+     *
+     * @throws When `isReference` is `false` or the specification is not set.
+     */
     reference() {
         return this.specification.getRequirement(this.data["$ref"]);
     }
+    /**
+     * Returns `true` when this node has a child property named `item`.
+     *
+     * Transparently follows `$ref` references.
+     *
+     * @param item - The property key to check.
+     */
     has(item) {
         if (this.isReference) {
             return this.reference().has(item);
         }
         return item in this.data;
     }
+    /**
+     * Returns the child {@link Requirement} for `item`, or `undefined`.
+     *
+     * @param item - The property key (string) or array index (number).
+     */
     get(item) {
         if (this.isReference) {
             return this.reference().get(item);
@@ -29,6 +55,16 @@ export class Requirement {
         }
         return new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
     }
+    /**
+     * Navigates to a descendant node using a slash-delimited JSON Pointer path.
+     *
+     * Tilde-escaped characters (`~0` → `~`, `~1` → `/`) and percent-encoded
+     * characters are unescaped during traversal.
+     *
+     * @param path - A slash-delimited path (e.g. `"responses/200/content"`).
+     * @returns The target {@link Requirement}, or `undefined` if the path does
+     *   not exist.
+     */
     select(path) {
         const parts = path
             .split("/")
@@ -54,19 +90,42 @@ export class Requirement {
         }
         return result;
     }
+    /**
+     * Iterates over all child properties and calls `callback` with each child
+     * requirement and its key.
+     *
+     * @param callback - Called for each child with `(child, key)`.
+     */
     forEach(callback) {
         Object.keys(this.data).forEach((key) => {
             callback(this.select(this.escapeJsonPointer(key)), key);
         });
     }
+    /**
+     * Maps over all child properties and returns the collected results.
+     *
+     * @param callback - Transformation function called with `(child, key)`.
+     */
     map(callback) {
         const result = [];
         this.forEach((value, key) => result.push(callback(value, key)));
         return result;
     }
+    /**
+     * Maps and flattens over all child properties.
+     *
+     * @param callback - Transformation function that may return a value or an
+     *   array of values.
+     */
     flatMap(callback) {
         return this.map(callback).flat();
     }
+    /**
+     * Returns the first child for which `callback` returns `true`, or
+     * `undefined` when nothing matches.
+     *
+     * @param callback - Predicate called with `(child, key)`.
+     */
     find(callback) {
         let result;
         this.forEach((value, key) => {
@@ -76,11 +135,21 @@ export class Requirement {
         });
         return result;
     }
+    /**
+     * Escapes a JSON Pointer token: `~` → `~0`, `/` → `~1`.
+     *
+     * @param value - The token to escape.
+     */
     escapeJsonPointer(value) {
         if (typeof value !== "string")
             return value;
         return value.replaceAll("~", "~0").replaceAll("/", "~1");
     }
+    /**
+     * Unescapes a JSON Pointer token: `~1` → `/`, `~0` → `~`.
+     *
+     * @param pointer - The token to unescape.
+     */
     unescapeJsonPointer(pointer) {
         if (typeof pointer !== "string")
             return pointer;