counterfact 2.5.0 → 2.6.0

package/dist/repl/repl.js

@@ -1,11 +1,31 @@
 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`);
 }
+const ROUTE_BUILDER_METHODS = [
+    "body(",
+    "headers(",
+    "help(",
+    "method(",
+    "missing(",
+    "path(",
+    "query(",
+    "ready(",
+    "send(",
+];
 export function createCompleter(registry, fallback) {
     return (line, callback) => {
-        const match = line.match(/client\.(?:get|post|put|patch|delete)\("(?<partial>[^"]*)$/u);
+        // 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 +41,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) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -73,6 +93,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 +128,6 @@ 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);
     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,10 +1,34 @@
-import cloneDeep from "lodash/cloneDeep.js";
 export class Context {
     constructor() { }
 }
 export function parentPath(path) {
     return String(path.split("/").slice(0, -1).join("/")) || "/";
 }
+/**
+ * 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 {
     entries = new Map();
     cache = new Map();
@@ -23,7 +47,7 @@ export class ContextRegistry {
     }
     add(path, context) {
         this.entries.set(path, context);
-        this.cache.set(path, cloneDeep(context));
+        this.cache.set(path, cloneForCache(context));
     }
     find(path) {
         return (this.getContextIgnoreCase(this.entries, path) ??
@@ -45,7 +69,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/index.ts

@@ -255,8 +255,10 @@ type HttpStatusCode =
 interface OpenApiParameters {
   in: "body" | "cookie" | "formData" | "header" | "path" | "query";
   name: string;
+  required?: boolean;
   schema?: {
-    type: string;
+    [key: string]: unknown;
+    type?: string;
   };
   type?: "string" | "number" | "integer" | "boolean";
 }
@@ -264,6 +266,14 @@ interface OpenApiParameters {
 interface OpenApiOperation {
   parameters?: OpenApiParameters[];
   produces?: string[];
+  requestBody?: {
+    content?: {
+      [mediaType: string]: {
+        schema: { [key: string]: unknown };
+      };
+    };
+    required?: boolean;
+  };
   responses: {
     [status: string]: {
       content?: {

package/dist/server/determine-module-kind.js

@@ -6,7 +6,7 @@ export async function determineModuleKind(modulePath) {
     if (modulePath.endsWith(".cjs")) {
         return "commonjs";
     }
-    if (modulePath.endsWith(".mjs")) {
+    if (modulePath.endsWith(".mjs") || modulePath.endsWith(".ts")) {
         return "module";
     }
     if (modulePath === path.parse(modulePath).root) {

package/dist/server/dispatcher.js

@@ -2,6 +2,7 @@ import { mediaTypes } from "@hapi/accept";
 import createDebugger from "debug";
 import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
+import { validateRequest } from "./request-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
 function parseCookies(cookieHeader) {
@@ -17,7 +18,8 @@ function parseCookies(cookieHeader) {
             try {
                 cookies[key] = decodeURIComponent(value);
             }
-            catch {
+            catch (error) {
+                debug("could not decode cookie value for key %s: %o", key, error);
                 cookies[key] = value;
             }
         }
@@ -39,12 +41,12 @@ export class Dispatcher {
     }
     parameterTypes(parameters) {
         const types = {
-            body: {},
-            cookie: {},
-            formData: {},
-            header: {},
-            path: {},
-            query: {},
+            body: new Map(),
+            cookie: new Map(),
+            formData: new Map(),
+            header: new Map(),
+            path: new Map(),
+            query: new Map(),
         };
         if (!parameters) {
             return types;
@@ -52,8 +54,7 @@ export class Dispatcher {
         for (const parameter of parameters) {
             const type = parameter?.type;
             if (type !== undefined) {
-                types[parameter.in][parameter.name] =
-                    type === "integer" ? "number" : type;
+                types[parameter.in].set(parameter.name, type === "integer" ? "number" : type);
             }
         }
         return types;
@@ -137,7 +138,7 @@ export class Dispatcher {
         // If the incoming path includes the base path, remove it
         if (this.openApiDocument?.basePath !== undefined &&
             path.toLowerCase().startsWith(this.openApiDocument.basePath.toLowerCase())) {
-            path = path.replace(new RegExp(this.openApiDocument.basePath, "iu"), "");
+            path = path.slice(this.openApiDocument.basePath.length);
         }
         const { matchedPath } = this.registry.handler(path, method);
         if (!this.registry.exists(method, path) &&
@@ -150,6 +151,16 @@ export class Dispatcher {
             };
         }
         const operation = this.operationForPathAndMethod(matchedPath, method);
+        if (this.config?.validateRequests !== false) {
+            const validation = validateRequest(operation, { body, headers, query });
+            if (!validation.valid) {
+                return {
+                    body: `Request validation failed:\n${validation.errors.join("\n")}`,
+                    contentType: "text/plain",
+                    status: 400,
+                };
+            }
+        }
         const continuousDistribution = (min, max) => {
             return min + Math.random() * (max - min);
         };

package/dist/server/file-discovery.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import { escapePathForWindows } from "../util/windows-escape.js";
+const JS_EXTENSIONS = new Set(["cjs", "cts", "js", "mjs", "mts", "ts"]);
+export class FileDiscovery {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath.replaceAll("\\", "/");
+    }
+    async findFiles(directory = "") {
+        const fullDir = nodePath
+            .join(this.basePath, directory)
+            .replaceAll("\\", "/");
+        if (!existsSync(fullDir)) {
+            throw new Error(`Directory does not exist ${fullDir}`);
+        }
+        const entries = await fs.readdir(fullDir, { withFileTypes: true });
+        const results = await Promise.all(entries.map(async (entry) => {
+            if (entry.isDirectory()) {
+                return this.findFiles(nodePath.join(directory, entry.name).replaceAll("\\", "/"));
+            }
+            const extension = entry.name.split(".").at(-1);
+            if (!JS_EXTENSIONS.has(extension ?? "")) {
+                return [];
+            }
+            const fullPath = nodePath
+                .join(this.basePath, directory, entry.name)
+                .replaceAll("\\", "/");
+            return [escapePathForWindows(fullPath)];
+        }));
+        return results.flat();
+    }
+}

package/dist/server/middleware-detector.js

@@ -0,0 +1,8 @@
+export function isContextModule(module) {
+    return "Context" in module && typeof module.Context === "function";
+}
+export function isMiddlewareModule(module) {
+    return ("middleware" in module &&
+        typeof Object.getOwnPropertyDescriptor(module, "middleware")?.value ===
+            "function");
+}

package/dist/server/module-dependency-graph.js

@@ -1,12 +1,15 @@
 import { dirname, resolve } from "node:path";
+import createDebug from "debug";
 import precinct from "precinct";
+const debug = createDebug("counterfact:server:module-dependency-graph");
 export class ModuleDependencyGraph {
     dependents = new Map();
     loadDependencies(path) {
         try {
             return precinct.paperwork(path);
         }
-        catch {
+        catch (error) {
+            debug("could not load dependencies for %s: %o", path, error);
             return [];
         }
     }

package/dist/server/module-loader.js

@@ -1,5 +1,4 @@
 import { once } from "node:events";
-import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath, { basename, dirname } from "node:path";
 import { watch } from "chokidar";
@@ -7,25 +6,20 @@ import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 import { ContextRegistry } from "./context-registry.js";
 import { determineModuleKind } from "./determine-module-kind.js";
+import { FileDiscovery } from "./file-discovery.js";
+import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
 const debug = createDebug("counterfact:server:module-loader");
-import { escapePathForWindows, unescapePathForWindows, } from "../util/windows-escape.js";
-function isContextModule(module) {
-    return "Context" in module && typeof module.Context === "function";
-}
-function isMiddlewareModule(module) {
-    return ("middleware" in module &&
-        typeof Object.getOwnPropertyDescriptor(module, "middleware")?.value ===
-            "function");
-}
 export class ModuleLoader extends EventTarget {
     basePath;
     registry;
     watcher;
     contextRegistry;
     dependencyGraph = new ModuleDependencyGraph();
+    fileDiscovery;
     uncachedImport = async function (moduleName) {
         throw new Error(`uncachedImport not set up; importing ${moduleName}`);
     };
@@ -34,6 +28,7 @@ export class ModuleLoader extends EventTarget {
         this.basePath = basePath.replaceAll("\\", "/");
         this.registry = registry;
         this.contextRegistry = contextRegistry;
+        this.fileDiscovery = new FileDiscovery(this.basePath);
     }
     async watch() {
         this.watcher = watch(this.basePath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
@@ -69,27 +64,8 @@ export class ModuleLoader extends EventTarget {
         await this.watcher?.close();
     }
     async load(directory = "") {
-        if (!existsSync(nodePath.join(this.basePath, directory).replaceAll("\\", "/"))) {
-            throw new Error(`Directory does not exist ${this.basePath}`);
-        }
-        const files = await fs.readdir(nodePath.join(this.basePath, directory).replaceAll("\\", "/"), {
-            withFileTypes: true,
-        });
-        const imports = files.flatMap(async (file) => {
-            const extension = file.name.split(".").at(-1);
-            if (file.isDirectory()) {
-                await this.load(nodePath.join(directory, file.name).replaceAll("\\", "/"));
-                return;
-            }
-            if (!["cjs", "cts", "js", "mjs", "mts", "ts"].includes(extension ?? "")) {
-                return;
-            }
-            const fullPath = nodePath
-                .join(this.basePath, directory, file.name)
-                .replaceAll("\\", "/");
-            await this.loadEndpoint(escapePathForWindows(fullPath));
-        });
-        await Promise.all(imports);
+        const files = await this.fileDiscovery.findFiles(directory);
+        await Promise.all(files.map((file) => this.loadEndpoint(file)));
     }
     async loadEndpoint(pathName) {
         debug("importing module: %s", pathName);