counterfact 2.5.1 → 2.7.0

package/dist/repl/raw-http-client.js

@@ -11,8 +11,8 @@ const colors = {
     blue: "\x1b[34m",
 };
 function isLikelyJson(headersBlock, body) {
-    const m = headersBlock.match(/^content-type:\s*([^\r\n;]+)/im);
-    const ct = (m?.[1] ?? "").toLowerCase();
+    const m = headersBlock.match(/^content-type:\s*(?<contentType>[^\r\n;]+)/im);
+    const ct = (m?.groups?.["contentType"] ?? "").toLowerCase();
     if (ct.includes("application/json") || ct.includes("+json"))
         return true;
     const s = body.trim();
@@ -30,7 +30,7 @@ function highlightJson(text) {
         return text;
     }
     const pretty = JSON.stringify(obj, null, 2);
-    return pretty.replace(/("(?:\\.|[^"\\])*")(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (match, str, colon, boolOrNull) => {
+    return pretty.replace(/(?<str>"(?:\\.|[^"\\])*")(?<colon>\s*:)?|\b(?<boolOrNull>true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (match, str, colon, boolOrNull) => {
         if (str) {
             if (colon)
                 return `${colors.blue}${str}${colors.reset}${colon}`;
@@ -60,31 +60,31 @@ export class RawHttpClient {
         this.port = port;
     }
     get(path, headers = {}) {
-        this.#send("GET", path, "", headers);
+        return this.#send("GET", path, "", headers);
     }
     head(path, headers = {}) {
-        this.#send("HEAD", path, "", headers);
+        return this.#send("HEAD", path, "", headers);
     }
     post(path, body = "", headers = {}) {
-        this.#send("POST", path, body, headers);
+        return this.#send("POST", path, body, headers);
     }
     put(path, body = "", headers = {}) {
-        this.#send("PUT", path, body, headers);
+        return this.#send("PUT", path, body, headers);
     }
     delete(path, headers = {}) {
-        this.#send("DELETE", path, "", headers);
+        return this.#send("DELETE", path, "", headers);
     }
     connect(path, headers = {}) {
-        this.#send("CONNECT", path, "", headers);
+        return this.#send("CONNECT", path, "", headers);
     }
     options(path, headers = {}) {
-        this.#send("OPTIONS", path, "", headers);
+        return this.#send("OPTIONS", path, "", headers);
     }
     trace(path, headers = {}) {
-        this.#send("TRACE", path, "", headers);
+        return this.#send("TRACE", path, "", headers);
     }
     patch(path, body = "", headers = {}) {
-        this.#send("PATCH", path, body, headers);
+        return this.#send("PATCH", path, body, headers);
     }
     #send(method, path, bodyAsStringOrObject, headers) {
         const requestNumber = ++this.requestNumber;
@@ -146,9 +146,9 @@ export class RawHttpClient {
         const lines = head.split("\r\n");
         const statusLine = lines[0] ?? "";
         let statusColor = colors.green;
-        const match = statusLine.match(/HTTP\/\d+\.\d+\s+(\d+)/);
+        const match = statusLine.match(/HTTP\/\d+\.\d+\s+(?<statusCode>\d+)/);
         if (match) {
-            const code = Number(match[1]);
+            const code = Number(match.groups?.["statusCode"]);
             if (code >= 400)
                 statusColor = colors.red;
             else if (code >= 300)

package/dist/repl/repl.js

@@ -1,11 +1,74 @@
 import repl from "node:repl";
 import { RawHttpClient } from "./raw-http-client.js";
+import { createRouteFunction } from "./route-builder.js";
 function printToStdout(line) {
     process.stdout.write(`${line}\n`);
 }
-export function createCompleter(registry, fallback) {
+const ROUTE_BUILDER_METHODS = [
+    "body(",
+    "headers(",
+    "help(",
+    "method(",
+    "missing(",
+    "path(",
+    "query(",
+    "ready(",
+    "send(",
+];
+/**
+ * Creates a tab-completion function for the REPL.
+ *
+ * @param registry - The route registry used to complete path arguments for `route()` and `client.*()` calls.
+ * @param fallback - Optional fallback completer (e.g. the Node.js built-in completer) invoked when no custom completion matches.
+ * @param scenarioRegistry - When provided, enables tab completion for `.apply` commands by enumerating
+ *   exported function names and file-key prefixes from the loaded scenario modules.
+ */
+export function createCompleter(registry, fallback, scenarioRegistry) {
     return (line, callback) => {
-        const match = line.match(/client\.(?:get|post|put|patch|delete)\("(?<partial>[^"]*)$/u);
+        // Check for .apply completion: .apply <partial>
+        const applyMatch = line.match(/^\.apply\s+(?<partial>\S*)$/u);
+        if (applyMatch) {
+            const partial = applyMatch.groups?.["partial"] ?? "";
+            if (scenarioRegistry !== undefined) {
+                const slashIdx = partial.lastIndexOf("/");
+                if (slashIdx === -1) {
+                    // No slash: complete exports from "index" key + top-level file prefixes
+                    const indexFunctions = scenarioRegistry.getExportedFunctionNames("index");
+                    const fileKeys = scenarioRegistry
+                        .getFileKeys()
+                        .filter((k) => k !== "index");
+                    const topLevelPrefixes = [
+                        ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
+                    ];
+                    const allOptions = [...indexFunctions, ...topLevelPrefixes];
+                    const matches = allOptions.filter((c) => c.startsWith(partial));
+                    callback(null, [matches, partial]);
+                }
+                else {
+                    // Has slash: complete exports from the named file key
+                    const fileKey = partial.slice(0, slashIdx);
+                    const funcPartial = partial.slice(slashIdx + 1);
+                    const functions = scenarioRegistry.getExportedFunctionNames(fileKey);
+                    const matches = functions
+                        .filter((e) => e.startsWith(funcPartial))
+                        .map((e) => `${fileKey}/${e}`);
+                    callback(null, [matches, partial]);
+                }
+            }
+            else {
+                callback(null, [[], partial]);
+            }
+            return;
+        }
+        // Check for RouteBuilder method completion: route("..."). or chained calls
+        const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
+        if (builderMatch) {
+            const partial = builderMatch.groups?.["partial"] ?? "";
+            const matches = ROUTE_BUILDER_METHODS.filter((m) => m.startsWith(partial));
+            callback(null, [matches, partial]);
+            return;
+        }
+        const match = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
         if (!match) {
             if (fallback) {
                 fallback(line, callback);
@@ -21,7 +84,7 @@ export function createCompleter(registry, fallback) {
         callback(null, [matches, partial]);
     };
 }
-export function startRepl(contextRegistry, registry, config, print = printToStdout) {
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -65,7 +128,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     const builtinCompleter = replServer.completer;
     // completer is typed as readonly in @types/node but is writable at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    replServer.completer = createCompleter(registry, builtinCompleter);
+    replServer.completer = createCompleter(registry, builtinCompleter, scenarioRegistry);
     replServer.defineCommand("counterfact", {
         action() {
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");
@@ -73,6 +136,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             print("");
             print("- loadContext('/some/path'): to access the context object for a given path");
             print("- context: the root context ( same as loadContext('/') )");
+            print("- route('/some/path'): create a request builder for the given path");
             print("");
             print("For more information, see https://counterfact.dev/docs/usage.html");
             print("");
@@ -107,5 +171,56 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     replServer.context.context = replServer.context.loadContext("/");
     replServer.context.client = new RawHttpClient("localhost", config.port);
     replServer.context.RawHttpClient = RawHttpClient;
+    replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
+    replServer.context.routes = {};
+    replServer.defineCommand("apply", {
+        async action(text) {
+            const parts = text.trim().split("/").filter(Boolean);
+            if (parts.length === 0) {
+                print("usage: .apply <path>");
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            if (parts.some((part) => part === ".." || part === ".")) {
+                print("Error: Path must not contain '.' or '..' segments");
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const functionName = parts[parts.length - 1] ?? "";
+            const fileKey = parts.length === 1 ? "index" : parts.slice(0, -1).join("/");
+            const module = scenarioRegistry?.getModule(fileKey);
+            if (module === undefined) {
+                print(`Error: Could not find scenario file "${fileKey}"`);
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const fn = module[functionName];
+            if (typeof fn !== "function") {
+                print(`Error: "${functionName}" is not a function exported from "${fileKey}"`);
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            try {
+                const applyContext = {
+                    context: replServer.context["context"],
+                    loadContext: replServer.context["loadContext"],
+                    route: replServer.context["route"],
+                    routes: replServer.context["routes"],
+                };
+                await fn(applyContext);
+                print(`Applied ${text.trim()}`);
+            }
+            catch (error) {
+                print(`Error: ${String(error)}`);
+            }
+            this.clearBufferedCommand();
+            this.displayPrompt();
+        },
+        help: 'apply a scenario script (".apply <path>" calls the named export from scenarios/)',
+    });
     return replServer;
 }

package/dist/repl/route-builder.js

@@ -0,0 +1,270 @@
+import { RawHttpClient } from "./raw-http-client.js";
+export class RouteBuilder {
+    routePath;
+    _body;
+    _headerParams;
+    _host;
+    _method;
+    _openApiDocument;
+    _pathParams;
+    _port;
+    _queryParams;
+    _operation;
+    constructor(routePath, options) {
+        this.routePath = routePath;
+        this._method = options.method;
+        this._pathParams = options.pathParams ?? {};
+        this._queryParams = options.queryParams ?? {};
+        this._headerParams = options.headerParams ?? {};
+        this._body = options.body;
+        this._port = options.port;
+        this._host = options.host ?? "localhost";
+        this._openApiDocument = options.openApiDocument;
+        this._operation = this._resolveOperation();
+    }
+    _resolveOperation() {
+        if (!this._openApiDocument || !this._method)
+            return undefined;
+        const method = this._method.toLowerCase();
+        const normalizedPath = this.routePath.toLowerCase();
+        for (const key of Object.keys(this._openApiDocument.paths)) {
+            if (key.toLowerCase() === normalizedPath) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return this._openApiDocument.paths[key][method];
+            }
+        }
+        return undefined;
+    }
+    clone(overrides) {
+        return new RouteBuilder(this.routePath, {
+            body: "body" in overrides ? overrides.body : this._body,
+            headerParams: overrides.headerParams ?? this._headerParams,
+            host: this._host,
+            method: overrides.method ?? this._method,
+            openApiDocument: this._openApiDocument,
+            pathParams: overrides.pathParams ?? this._pathParams,
+            port: this._port,
+            queryParams: overrides.queryParams ?? this._queryParams,
+        });
+    }
+    method(method) {
+        return this.clone({ method: method.toUpperCase() });
+    }
+    path(params) {
+        return this.clone({ pathParams: { ...this._pathParams, ...params } });
+    }
+    query(params) {
+        return this.clone({ queryParams: { ...this._queryParams, ...params } });
+    }
+    headers(params) {
+        return this.clone({ headerParams: { ...this._headerParams, ...params } });
+    }
+    body(body) {
+        return this.clone({ body });
+    }
+    getOperation() {
+        return this._operation;
+    }
+    ready() {
+        if (!this._method)
+            return false;
+        return this.missing() === undefined;
+    }
+    missing() {
+        const operation = this.getOperation();
+        if (!operation?.parameters)
+            return undefined;
+        const missingParams = {};
+        for (const param of operation.parameters) {
+            if (!param.required)
+                continue;
+            const paramType = param.type ?? param.schema?.type ?? "string";
+            const paramInfo = {
+                description: param.description,
+                name: param.name,
+                type: paramType,
+            };
+            if (param.in === "path" && !(param.name in this._pathParams)) {
+                missingParams.path = [...(missingParams.path ?? []), paramInfo];
+            }
+            else if (param.in === "query" && !(param.name in this._queryParams)) {
+                missingParams.query = [...(missingParams.query ?? []), paramInfo];
+            }
+            else if (param.in === "header" && !(param.name in this._headerParams)) {
+                missingParams.header = [...(missingParams.header ?? []), paramInfo];
+            }
+        }
+        if (Object.keys(missingParams).length === 0)
+            return undefined;
+        return missingParams;
+    }
+    help() {
+        const method = this._method ?? "[no method set]";
+        const operation = this.getOperation();
+        const lines = [];
+        lines.push(`${method} ${this.routePath}`);
+        if (operation?.summary) {
+            lines.push("");
+            lines.push("Summary:");
+            lines.push(`  ${operation.summary}`);
+        }
+        if (operation?.description) {
+            lines.push("");
+            lines.push("Description:");
+            lines.push(`  ${operation.description}`);
+        }
+        if (operation?.parameters && operation.parameters.length > 0) {
+            const pathParams = operation.parameters.filter((p) => p.in === "path");
+            const queryParams = operation.parameters.filter((p) => p.in === "query");
+            const headerParams = operation.parameters.filter((p) => p.in === "header");
+            if (pathParams.length > 0) {
+                lines.push("");
+                lines.push("Path Parameters:");
+                for (const p of pathParams) {
+                    const paramType = p.type ?? p.schema?.type ?? "string";
+                    const required = p.required ? "required" : "optional";
+                    lines.push(`  ${p.name} (${paramType}, ${required})`);
+                    if (p.description)
+                        lines.push(`    Description: ${p.description}`);
+                    if (p.enum)
+                        lines.push(`    Allowed values: ${p.enum.join(" | ")}`);
+                }
+            }
+            if (queryParams.length > 0) {
+                lines.push("");
+                lines.push("Query Parameters:");
+                for (const p of queryParams) {
+                    const paramType = p.type ?? p.schema?.type ?? "string";
+                    const required = p.required ? "required" : "optional";
+                    lines.push(`  ${p.name} (${paramType}, ${required})`);
+                    if (p.description)
+                        lines.push(`    Description: ${p.description}`);
+                    const enumValues = p.enum ?? p.schema?.enum;
+                    if (enumValues)
+                        lines.push(`    Allowed values: ${enumValues.join(" | ")}`);
+                }
+            }
+            if (headerParams.length > 0) {
+                lines.push("");
+                lines.push("Headers:");
+                for (const p of headerParams) {
+                    const paramType = p.type ?? p.schema?.type ?? "string";
+                    const required = p.required ? "required" : "optional";
+                    lines.push(`  ${p.name} (${paramType}, ${required})`);
+                    if (p.description)
+                        lines.push(`    Description: ${p.description}`);
+                }
+            }
+        }
+        if (operation?.responses) {
+            lines.push("");
+            lines.push("Responses:");
+            for (const [status, response] of Object.entries(operation.responses)) {
+                lines.push(`  ${status}`);
+                if (response.description) {
+                    lines.push(`    Description: ${response.description}`);
+                }
+            }
+        }
+        return lines.join("\n");
+    }
+    async send() {
+        if (!this._method) {
+            throw new Error('No HTTP method set. Use .method("get") to set the method.');
+        }
+        const missing = this.missing();
+        if (missing) {
+            const lines = [
+                "Cannot execute request.",
+                "",
+                "Missing required parameters:",
+            ];
+            if (missing.path) {
+                lines.push("  path:");
+                for (const p of missing.path) {
+                    lines.push(`    - ${p.name} (${p.type ?? "string"})`);
+                }
+            }
+            if (missing.query) {
+                lines.push("  query:");
+                for (const p of missing.query) {
+                    lines.push(`    - ${p.name} (${p.type ?? "string"})`);
+                }
+            }
+            if (missing.header) {
+                lines.push("  header:");
+                for (const p of missing.header) {
+                    lines.push(`    - ${p.name} (${p.type ?? "string"})`);
+                }
+            }
+            throw new Error(lines.join("\n"));
+        }
+        // Build URL with path parameters substituted
+        let url = this.routePath;
+        for (const [key, value] of Object.entries(this._pathParams)) {
+            url = url.replaceAll(`{${key}}`, String(value));
+        }
+        // Append query string
+        const queryEntries = Object.entries(this._queryParams);
+        if (queryEntries.length > 0) {
+            const qs = new URLSearchParams(queryEntries.map(([k, v]) => [k, String(v)])).toString();
+            url = `${url}?${qs}`;
+        }
+        const client = new RawHttpClient(this._host, this._port);
+        const headers = Object.fromEntries(Object.entries(this._headerParams).map(([k, v]) => [k, String(v)]));
+        const method = this._method.toLowerCase();
+        switch (method) {
+            case "get":
+                return client.get(url, headers);
+            case "head":
+                return client.head(url, headers);
+            case "delete":
+                return client.delete(url, headers);
+            case "options":
+                return client.options(url, headers);
+            case "trace":
+                return client.trace(url, headers);
+            case "post":
+                return client.post(url, this._body, headers);
+            case "put":
+                return client.put(url, this._body, headers);
+            case "patch":
+                return client.patch(url, this._body, headers);
+            default:
+                throw new Error(`Unsupported HTTP method: ${this._method}`);
+        }
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        const method = this._method ?? "[no method set]";
+        const operation = this.getOperation();
+        const lines = [];
+        lines.push(`${method} ${this.routePath}`);
+        if (operation?.parameters) {
+            const pathParams = operation.parameters.filter((p) => p.in === "path");
+            const queryParams = operation.parameters.filter((p) => p.in === "query");
+            if (pathParams.length > 0) {
+                lines.push("");
+                lines.push("Path:");
+                for (const p of pathParams) {
+                    const value = this._pathParams[p.name];
+                    lines.push(`  ${p.name}: ${value !== undefined ? String(value) : "[missing]"}`);
+                }
+            }
+            if (queryParams.length > 0) {
+                lines.push("");
+                lines.push("Query:");
+                for (const p of queryParams) {
+                    const value = this._queryParams[p.name];
+                    const label = p.required ? "[missing]" : "[optional]";
+                    lines.push(`  ${p.name}: ${value !== undefined ? String(value) : label}`);
+                }
+            }
+        }
+        lines.push("");
+        lines.push(`Ready: ${this.ready()}`);
+        return lines.join("\n");
+    }
+}
+export function createRouteFunction(port, host, openApiDocument) {
+    return (routePath) => new RouteBuilder(routePath, { host, openApiDocument, port });
+}

package/dist/server/config.js

@@ -1 +1 @@
-export const DUMMY_EXPORT_FOR_TEST_COVERAGE = 1;
+export {};

package/dist/server/context-registry.js

@@ -1,15 +1,40 @@
-import cloneDeep from "lodash/cloneDeep.js";
 export class Context {
     constructor() { }
 }
 export function parentPath(path) {
     return String(path.split("/").slice(0, -1).join("/")) || "/";
 }
-export class ContextRegistry {
+/**
+ * Deep-clones an object for caching purposes.
+ * Plain objects and class instances have their own enumerable properties
+ * recursively cloned (preserving the prototype chain). Functions are copied
+ * by reference since they are not structurally comparable data.
+ */
+function cloneForCache(value) {
+    if (value === null || typeof value === "function") {
+        return value;
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(cloneForCache);
+    }
+    const proto = Object.getPrototypeOf(value);
+    const clone = proto !== null && proto !== Object.prototype
+        ? Object.create(proto)
+        : {};
+    for (const key of Object.keys(value)) {
+        clone[key] = cloneForCache(value[key]);
+    }
+    return clone;
+}
+export class ContextRegistry extends EventTarget {
     entries = new Map();
     cache = new Map();
     seen = new Set();
     constructor() {
+        super();
         this.add("/", {});
     }
     getContextIgnoreCase(map, key) {
@@ -23,7 +48,22 @@ export class ContextRegistry {
     }
     add(path, context) {
         this.entries.set(path, context);
-        this.cache.set(path, cloneDeep(context));
+        this.cache.set(path, cloneForCache(context));
+        this.dispatchEvent(new Event("context-changed"));
+    }
+    /**
+     * Removes the context entry for the given path and dispatches a
+     * "context-changed" event so that listeners (e.g. the scenario-context type
+     * generator) can regenerate type files in response to the removal.
+     *
+     * @param path - The route path whose context entry should be deleted
+     *   (e.g. "/pets").
+     */
+    remove(path) {
+        this.entries.delete(path);
+        this.cache.delete(path);
+        this.seen.delete(path);
+        this.dispatchEvent(new Event("context-changed"));
     }
     find(path) {
         return (this.getContextIgnoreCase(this.entries, path) ??
@@ -45,7 +85,7 @@ export class ContextRegistry {
             }
         }
         Object.setPrototypeOf(context, Object.getPrototypeOf(updatedContext));
-        this.cache.set(path, cloneDeep(updatedContext));
+        this.cache.set(path, cloneForCache(updatedContext));
     }
     getAllPaths() {
         return Array.from(this.entries.keys());

package/dist/server/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;
+}

package/dist/server/counterfact-types/counterfact-response.ts

@@ -0,0 +1,15 @@
+/**
+ * A unique symbol used as a brand for the `COUNTERFACT_RESPONSE` type.
+ * This prevents arbitrary objects from being accidentally treated as a
+ * completed response value.
+ */
+const counterfactResponse = Symbol("Counterfact Response");
+
+/**
+ * The terminal value type returned by the fluent response builder once all
+ * required fields (body, headers, etc.) have been provided. When a route
+ * handler returns this type, Counterfact treats the response as complete.
+ */
+export type COUNTERFACT_RESPONSE = {
+  [counterfactResponse]: typeof counterfactResponse;
+};

package/dist/server/counterfact-types/example-names.ts

@@ -0,0 +1,13 @@
+import type { OpenApiResponse } from "./open-api-response.js";
+
+/**
+ * Extracts the union of named example keys defined on an OpenAPI response.
+ * Resolves to `never` when the response has no named examples.
+ * Used to constrain the argument to the `.example(name)` method on the
+ * response builder.
+ */
+export type ExampleNames<Response extends OpenApiResponse> = Response extends {
+  examples: infer E;
+}
+  ? keyof E & string
+  : never;

package/dist/server/counterfact-types/example.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents a named example defined in an OpenAPI document.
+ * Examples can be referenced by route handlers via the `.example(name)` method
+ * on the response builder.
+ */
+export interface Example {
+  description: string;
+  summary: string;
+  value: unknown;
+}