counterfact 2.6.0 → 2.7.0

package/dist/repl/repl.js

@@ -15,8 +15,51 @@ const ROUTE_BUILDER_METHODS = [
     "ready(",
     "send(",
 ];
-export function createCompleter(registry, fallback) {
+/**
+ * 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) => {
+        // 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) {
@@ -41,7 +84,7 @@ export function createCompleter(registry, fallback) {
         callback(null, [matches, partial]);
     };
 }
-export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument) {
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -85,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.");
@@ -129,5 +172,55 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     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/server/context-registry.js

@@ -29,11 +29,12 @@ function cloneForCache(value) {
     }
     return clone;
 }
-export class ContextRegistry {
+export class ContextRegistry extends EventTarget {
     entries = new Map();
     cache = new Map();
     seen = new Set();
     constructor() {
+        super();
         this.add("/", {});
     }
     getContextIgnoreCase(map, key) {
@@ -48,6 +49,21 @@ export class ContextRegistry {
     add(path, context) {
         this.entries.set(path, 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) ??

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;
+}

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

@@ -0,0 +1,164 @@
+import type { COUNTERFACT_RESPONSE } from "./counterfact-response.js";
+import type { CookieOptions } from "./cookie-options.js";
+import type { ExampleNames } from "./example-names.js";
+import type { IfHasKey } from "./if-has-key.js";
+import type { MediaType } from "./media-type.js";
+import type { OmitAll } from "./omit-all.js";
+import type { OmitValueWhenNever } from "./omit-value-when-never.js";
+import type { OpenApiResponse } from "./open-api-response.js";
+import type { RandomFunction } from "./random-function.js";
+
+/**
+ * Returns `never` when `Record` is an empty object type (`{}`), signalling
+ * that there are no remaining choices available on the response builder.
+ */
+type NeverIfEmpty<Record> = object extends Record ? never : Record;
+
+/**
+ * Extracts the union of schema types from a map of media-type content entries.
+ * Used to type the body argument of shortcut methods like `.json()` or `.html()`.
+ */
+type SchemasOf<T extends { [key: string]: { schema: unknown } }> = {
+  [K in keyof T]: T[K]["schema"];
+}[keyof T];
+
+/**
+ * Produces a builder method for a shortcut (e.g. `.json()`, `.html()`) when
+ * the response contains at least one of the given `ContentTypes`, and `never`
+ * otherwise. Calling the method narrows the builder by removing those content
+ * types from the remaining options.
+ */
+type MaybeShortcut<
+  ContentTypes extends MediaType[],
+  Response extends OpenApiResponse,
+> = IfHasKey<
+  Response["content"],
+  ContentTypes,
+  (body: SchemasOf<Response["content"]>) => GenericResponseBuilder<{
+    content: NeverIfEmpty<OmitAll<Response["content"], ContentTypes>>;
+    headers: Response["headers"];
+    requiredHeaders: Response["requiredHeaders"];
+  }>,
+  never
+>;
+
+/**
+ * The type of the `.match(contentType, body)` method on the generic response
+ * builder. Calling it narrows the builder by removing the chosen content type
+ * from the remaining options.
+ */
+type MatchFunction<Response extends OpenApiResponse> = <
+  ContentType extends MediaType & keyof Response["content"],
+>(
+  contentType: ContentType,
+  body: Response["content"][ContentType]["schema"],
+) => GenericResponseBuilder<{
+  content: NeverIfEmpty<Omit<Response["content"], ContentType>>;
+  headers: Response["headers"];
+  requiredHeaders: Response["requiredHeaders"];
+}>;
+
+/**
+ * The type of the `.header(name, value)` method on the generic response
+ * builder. Calling it narrows the builder by removing the satisfied header
+ * from the set of required headers.
+ */
+type HeaderFunction<Response extends OpenApiResponse> = <
+  Header extends string & keyof Response["headers"],
+>(
+  header: Header,
+  value: Response["headers"][Header]["schema"],
+) => GenericResponseBuilder<{
+  content: NeverIfEmpty<Response["content"]>;
+  headers: NeverIfEmpty<Omit<Response["headers"], Header>>;
+  requiredHeaders: Exclude<Response["requiredHeaders"], Header>;
+}>;
+
+/**
+ * The inner shape of the generic response builder, listing all methods that
+ * are currently available given the remaining response constraints.
+ * Methods whose type resolves to `never` are stripped by `OmitValueWhenNever`.
+ *
+ * Note: `[T] extends [never]` (non-distributive tuple wrapping) is used
+ * alongside `[keyof T] extends [never]` to correctly handle both `T = never`
+ * (spec-generated no-body) and `T = {}` (all content types consumed) cases.
+ * TypeScript evaluates `keyof never` as `string | number | symbol`, so a
+ * direct `[keyof never] extends [never]` check would incorrectly return false.
+ */
+export type GenericResponseBuilderInner<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = OmitValueWhenNever<{
+  binary: MaybeShortcut<["application/octet-stream"], Response>;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => GenericResponseBuilder<Response>;
+  empty: [Response["content"]] extends [never]
+    ? () => COUNTERFACT_RESPONSE
+    : [keyof Response["content"]] extends [never]
+      ? () => COUNTERFACT_RESPONSE
+      : never;
+  header: [Response["headers"]] extends [never]
+    ? never
+    : [keyof Response["headers"]] extends [never]
+      ? never
+      : HeaderFunction<Response>;
+  html: MaybeShortcut<["text/html"], Response>;
+  json: MaybeShortcut<
+    [
+      "application/json",
+      "text/json",
+      "text/x-json",
+      "application/xml",
+      "text/xml",
+    ],
+    Response
+  >;
+  match: [Response["content"]] extends [never]
+    ? never
+    : [keyof Response["content"]] extends [never]
+      ? never
+      : MatchFunction<Response>;
+  random: [Response["content"]] extends [never]
+    ? never
+    : [keyof Response["content"]] extends [never]
+      ? never
+      : RandomFunction;
+  example: [ExampleNames<Response>] extends [never]
+    ? never
+    : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
+  text: MaybeShortcut<["text/plain"], Response>;
+  xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
+}>;
+
+/**
+ * The strongly-typed, fluent response builder generated for each operation in
+ * a route handler. Its available methods are derived from the OpenAPI response
+ * schema: as methods are called, the builder type narrows until all required
+ * content and headers have been provided, at which point it resolves to
+ * `COUNTERFACT_RESPONSE`.
+ *
+ * When a Response type carries an `examples` key it is a spec-generated
+ * response (either the initial no-body builder or a builder that still has
+ * content/headers to satisfy). Those always go through
+ * `GenericResponseBuilderInner`, which exposes `empty()` when `content` is
+ * `never`.
+ *
+ * When a Response type has no `examples` key it is a narrowed type produced
+ * by a method call (e.g. `.json()` sets the body and returns a type without
+ * `examples`). Those go through the existing collapse logic so that
+ * fully-satisfied responses resolve directly to `COUNTERFACT_RESPONSE`.
+ */
+export type GenericResponseBuilder<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = "examples" extends keyof Response
+  ? GenericResponseBuilderInner<Response>
+  : object extends OmitValueWhenNever<Omit<Response, "examples">>
+    ? COUNTERFACT_RESPONSE
+    : keyof OmitValueWhenNever<Omit<Response, "examples">> extends "headers"
+      ? {
+          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
+          header: HeaderFunction<Response>;
+        }
+      : GenericResponseBuilderInner<Response>;

package/dist/server/counterfact-types/http-status-code.ts

@@ -0,0 +1,62 @@
+/**
+ * A union of all standard HTTP status codes.
+ * Used to constrain the status code argument in response builder calls and
+ * generated route handler types.
+ */
+export type HttpStatusCode =
+  | 100
+  | 101
+  | 102
+  | 200
+  | 201
+  | 202
+  | 203
+  | 204
+  | 205
+  | 206
+  | 207
+  | 226
+  | 300
+  | 301
+  | 302
+  | 303
+  | 304
+  | 305
+  | 307
+  | 308
+  | 400
+  | 401
+  | 402
+  | 403
+  | 404
+  | 405
+  | 406
+  | 407
+  | 408
+  | 409
+  | 410
+  | 411
+  | 412
+  | 413
+  | 414
+  | 415
+  | 416
+  | 417
+  | 418
+  | 422
+  | 423
+  | 424
+  | 426
+  | 428
+  | 429
+  | 431
+  | 451
+  | 500
+  | 501
+  | 502
+  | 503
+  | 504
+  | 505
+  | 506
+  | 507
+  | 511;

package/dist/server/counterfact-types/if-has-key.ts

@@ -0,0 +1,19 @@
+/**
+ * Conditional type that resolves to `Yes` when `SomeObject` has at least one
+ * key that contains any string from `Keys` as a substring, and `No` otherwise.
+ * Used to determine whether a shortcut method (e.g. `.json()`, `.html()`)
+ * should be present on the response builder for a given response type.
+ */
+export type IfHasKey<
+  SomeObject,
+  Keys extends readonly string[],
+  Yes,
+  No,
+> = Keys extends [
+  infer FirstKey extends string,
+  ...infer RestKeys extends string[],
+]
+  ? Extract<keyof SomeObject, `${string}${FirstKey}${string}`> extends never
+    ? IfHasKey<SomeObject, RestKeys, Yes, No>
+    : Yes
+  : No;