llm-mock-server 1.0.4 → 1.0.6

package/src/formats/anthropic/serialize.ts

@@ -1,5 +1,5 @@
-import type { ReplyObject, ReplyOptions } from "../../types.js";
-import type { SSEChunk } from "../types.js";
+import type { ReplyObject, ReplyOptions } from "#/types/reply.js";
+import type { SSEChunk } from "#/formats/types.js";
 import {
   splitText,
   genId,
@@ -7,7 +7,7 @@ import {
   shouldEmitText,
   finishReason,
   DEFAULT_USAGE,
-} from "../serialize-helpers.js";
+} from "#/formats/serialize-helpers.js";
 
 function buildUsage(usage: { input: number; output: number }) {
   return { input_tokens: usage.input, output_tokens: usage.output };

package/src/formats/openai/{index.ts → chat-completions/index.ts}

@@ -1,9 +1,9 @@
-import type { Format } from "../types.js";
-import { isStreaming } from "../request-helpers.js";
+import type { Format } from "#/formats/types.js";
+import { isStreaming } from "#/formats/request-helpers.js";
 import { parseRequest } from "./parse.js";
 import { serialize, serializeComplete, serializeError } from "./serialize.js";
 
-export const openaiFormat: Format = {
+export const chatCompletionsFormat: Format = {
   name: "openai",
   route: "/v1/chat/completions",
   parseRequest,

package/src/formats/openai/{parse.ts → chat-completions/parse.ts}

@@ -1,5 +1,8 @@
-import type { MockRequest, Message, ToolDef } from "../../types.js";
-import { buildMockRequest, type RequestMeta } from "../request-helpers.js";
+import type { MockRequest, Message, ToolDef } from "#/types/request.js";
+import {
+  buildMockRequest,
+  type RequestMeta,
+} from "#/formats/request-helpers.js";
 import { OpenAIRequestSchema, type OpenAIRequest } from "./schema.js";
 
 function extractContent(

package/src/formats/openai/{serialize.ts → chat-completions/serialize.ts}

@@ -1,5 +1,5 @@
-import type { ReplyObject, ReplyOptions } from "../../types.js";
-import type { SSEChunk } from "../types.js";
+import type { ReplyObject, ReplyOptions } from "#/types/reply.js";
+import type { SSEChunk } from "#/formats/types.js";
 import {
   splitText,
   genId,
@@ -7,7 +7,7 @@ import {
   finishReason,
   MS_PER_SECOND,
   DEFAULT_USAGE,
-} from "../serialize-helpers.js";
+} from "#/formats/serialize-helpers.js";
 
 function buildUsage(usage: { input: number; output: number }) {
   return {

package/src/formats/{responses → openai/responses}/index.ts

@@ -1,5 +1,5 @@
-import type { Format } from "../types.js";
-import { isStreaming } from "../request-helpers.js";
+import type { Format } from "#/formats/types.js";
+import { isStreaming } from "#/formats/request-helpers.js";
 import { parseRequest } from "./parse.js";
 import { serialize, serializeComplete, serializeError } from "./serialize.js";
 

package/src/formats/{responses → openai/responses}/parse.ts

@@ -1,5 +1,8 @@
-import type { MockRequest, Message, ToolDef } from "../../types.js";
-import { buildMockRequest, type RequestMeta } from "../request-helpers.js";
+import type { MockRequest, Message, ToolDef } from "#/types/request.js";
+import {
+  buildMockRequest,
+  type RequestMeta,
+} from "#/formats/request-helpers.js";
 import {
   ResponsesRequestSchema,
   FunctionToolSchema,

package/src/formats/{responses → openai/responses}/serialize.ts

@@ -1,5 +1,5 @@
-import type { ReplyObject, ReplyOptions, ToolCall } from "../../types.js";
-import type { SSEChunk } from "../types.js";
+import type { ReplyObject, ReplyOptions, ToolCall } from "#/types/reply.js";
+import type { SSEChunk } from "#/formats/types.js";
 import {
   splitText,
   genId,
@@ -7,7 +7,7 @@ import {
   shouldEmitText,
   MS_PER_SECOND,
   DEFAULT_USAGE,
-} from "../serialize-helpers.js";
+} from "#/formats/serialize-helpers.js";
 
 function buildUsage(usage: { input: number; output: number }) {
   return {

package/src/formats/request-helpers.ts

@@ -1,4 +1,9 @@
-import type { FormatName, Message, MockRequest, ToolDef } from "../types.js";
+import type {
+  FormatName,
+  Message,
+  MockRequest,
+  ToolDef,
+} from "#/types/request.js";
 
 function asRecord(body: unknown): Record<string, unknown> {
   if (typeof body === "object" && body !== null)

package/src/formats/serialize-helpers.ts

@@ -1,7 +1,6 @@
-import type { ReplyObject } from "../types.js";
+import type { ReplyObject } from "#/types/reply.js";
 
 export const MS_PER_SECOND = 1000;
-const BASE_36 = 36;
 export const DEFAULT_USAGE = { input: 10, output: 5 } as const;
 
 export function splitText(text: string, chunkSize: number): string[] {
@@ -13,8 +12,14 @@ export function splitText(text: string, chunkSize: number): string[] {
   return chunks;
 }
 
+const ID_SUFFIX_LENGTH = 12;
+
+function randomSuffix(): string {
+  return crypto.randomUUID().replaceAll("-", "").slice(0, ID_SUFFIX_LENGTH);
+}
+
 export function genId(prefix: string): string {
-  return `${prefix}_${Date.now().toString(BASE_36)}`;
+  return `${prefix}_${randomSuffix()}`;
 }
 
 export function toolId(
@@ -22,7 +27,7 @@ export function toolId(
   prefix: string,
   index: number,
 ): string {
-  return tool.id ?? `${prefix}_${Date.now().toString(BASE_36)}_${index}`;
+  return tool.id ?? `${prefix}_${randomSuffix()}_${index}`;
 }
 
 export function shouldEmitText(reply: ReplyObject): boolean {

package/src/formats/types.ts

@@ -1,9 +1,5 @@
-import type {
-  FormatName,
-  MockRequest,
-  ReplyObject,
-  ReplyOptions,
-} from "../types.js";
+import type { FormatName, MockRequest } from "#/types/request.js";
+import type { ReplyObject, ReplyOptions } from "#/types/reply.js";
 import type { RequestMeta } from "./request-helpers.js";
 
 export interface SSEChunk {

package/src/history.ts

@@ -1,10 +1,12 @@
-import type { MockRequest } from "./types.js";
+import type { MockRequest } from "./types/request.js";
 
 /** A recorded request with the rule that matched and when it happened. */
 export interface RecordedRequest {
+  /** The normalised request that was received. */
   readonly request: MockRequest;
-  /** The rule that matched, or `undefined` if the fallback was used. */
+  /** Description of the rule that matched, or `undefined` if the fallback was used. */
   readonly rule: string | undefined;
+  /** When the request was recorded (`Date.now()` value). */
   readonly timestamp: number;
 }
 
@@ -56,10 +58,12 @@ export class RequestHistory {
     return this.entries;
   }
 
+  /** Remove all recorded entries. */
   clear(): void {
     this.entries.length = 0;
   }
 
+  /** Enables `for...of` iteration over recorded entries. */
   [Symbol.iterator](): Iterator<RecordedRequest> {
     return this.entries[Symbol.iterator]();
   }

package/src/loader.ts

@@ -2,7 +2,8 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { join, extname } from "node:path";
 import JSON5 from "json5";
 import { z } from "zod";
-import type { Handler, Match, MatchObject, Reply } from "./types.js";
+import type { Reply } from "./types/reply.js";
+import type { Handler, Match, MatchObject } from "./types/rule.js";
 import { type RuleEngine, createSequenceResolver } from "./rule-engine.js";
 
 interface LoadContext {

package/src/mock-server.ts

@@ -1,46 +1,60 @@
 import Fastify from "fastify";
 import type { FastifyInstance } from "fastify";
-import type {
-  Match,
-  PendingRule,
-  Reply,
-  ReplyOptions,
-  Resolver,
-  Rule,
-  RuleHandle,
-  RuleSummary,
-  SequenceEntry,
-} from "./types.js";
-import { RuleEngine, createSequenceResolver } from "./rule-engine.js";
+import type { Reply, ReplyOptions } from "./types/reply.js";
+import type { RuleSummary } from "./types/rule.js";
+import { RuleEngine } from "./rule-engine.js";
+import { RuleBuilder } from "./rule-builder.js";
 import { RequestHistory } from "./history.js";
-import { openaiFormat } from "./formats/openai/index.js";
+import { chatCompletionsFormat } from "./formats/openai/chat-completions/index.js";
 import { anthropicFormat } from "./formats/anthropic/index.js";
-import { responsesFormat } from "./formats/responses/index.js";
+import { responsesFormat } from "./formats/openai/responses/index.js";
 import type { Format } from "./formats/types.js";
 import { Logger } from "./logger.js";
 import type { LogLevel } from "./logger.js";
 import { createRouteHandler } from "./route-handler.js";
 
 const formats: readonly Format[] = [
-  openaiFormat,
+  chatCompletionsFormat,
   anthropicFormat,
   responsesFormat,
 ];
 
+/** Options for constructing a `MockServer` or calling `createMock()`. */
 export interface MockServerOptions {
+  /**
+   * Port to listen on. Pass `0` for a random port (useful in tests).
+   * @defaultValue `0`
+   */
   readonly port?: number;
-  /** Defaults to `"127.0.0.1"`. Set to `"0.0.0.0"` to listen on all interfaces. */
+  /**
+   * Host to bind to. Set to `"0.0.0.0"` to listen on all interfaces.
+   * @defaultValue `"127.0.0.1"`
+   */
   readonly host?: string;
-  /** Defaults to `"none"` (silent). */
+  /**
+   * Log verbosity.
+   * @defaultValue `"none"`
+   */
   readonly logLevel?: LogLevel;
-  /** Default ms delay between SSE chunks. Individual rules can override this. */
+  /**
+   * Default ms delay between SSE chunks. Individual rules can override this.
+   * @defaultValue `0`
+   */
   readonly defaultLatency?: number;
-  /** Default characters per SSE text chunk. Individual rules can override this. */
+  /**
+   * Default characters per SSE text chunk. Individual rules can override this.
+   * @defaultValue `0`
+   */
   readonly defaultChunkSize?: number;
 }
 
+type RuleAPI = Pick<
+  RuleBuilder,
+  "when" | "whenTool" | "whenToolResult" | "nextError"
+>;
+
 /**
- * Mock LLM server that handles OpenAI, Anthropic, and Responses API formats.
+ * Mock LLM server that handles OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses API formats.
  * Register rules with `when()`, point your SDK at `url`, and go.
  *
  * Supports `await using` for automatic cleanup.
@@ -54,9 +68,10 @@ export interface MockServerOptions {
  * await server.stop();
  * ```
  */
-export class MockServer {
+export class MockServer implements RuleAPI {
   private readonly app: FastifyInstance;
   private readonly engine = new RuleEngine();
+  private readonly rules_ = new RuleBuilder(this.engine);
   private readonly history_ = new RequestHistory();
   private readonly logger: Logger;
   private readonly host: string;
@@ -64,6 +79,15 @@ export class MockServer {
   private fallbackReply: Reply = "Mock server: no matching rule.";
   private listening = false;
 
+  /** Register a matching rule. Call `.reply()` on the result to set the response. */
+  when = this.rules_.when.bind(this.rules_);
+  /** Shorthand for `when({ toolName })`. */
+  whenTool = this.rules_.whenTool.bind(this.rules_);
+  /** Shorthand for `when({ toolCallId })`. */
+  whenToolResult = this.rules_.whenToolResult.bind(this.rules_);
+  /** Queue a one-shot error for the very next request. Fires once then removes itself. */
+  nextError = this.rules_.nextError.bind(this.rules_);
+
   constructor(options: MockServerOptions = {}) {
     this.host = options.host ?? "127.0.0.1";
     this.logger = new Logger(options.logLevel ?? "none");
@@ -91,92 +115,9 @@ export class MockServer {
   }
 
   /**
-   * Register a matching rule. Call `.reply()` on the result to set the response.
-   *
-   * @example
-   * ```ts
-   * server.when("hello").reply("Hi!");
-   * server.when(/explain (\w+)/i).reply((req) => `Let me explain ${req.lastMessage}`);
-   * server.when({ model: /claude/ }).reply("I'm Claude.");
-   * ```
-   */
-  when(match: Match): PendingRule {
-    const engine = this.engine;
-
-    const makeHandle = (rule: Rule): RuleHandle => ({
-      times(n: number): RuleHandle {
-        rule.remaining = n;
-        return this;
-      },
-      first(): RuleHandle {
-        engine.moveToFront(rule);
-        return this;
-      },
-    });
-
-    return {
-      reply(response: Resolver, options?: ReplyOptions): RuleHandle {
-        return makeHandle(engine.add(match, response, options));
-      },
-      replySequence(entries: readonly SequenceEntry[]): RuleHandle {
-        const steps = entries.map((entry) =>
-          typeof entry === "string" || !("reply" in entry)
-            ? { reply: entry as Reply }
-            : { reply: entry.reply, options: entry.options },
-        );
-        const rule = engine.add(match, "");
-        const { resolver, entryCount } = createSequenceResolver(steps, rule);
-        rule.resolve = resolver;
-        rule.remaining = entryCount;
-        return makeHandle(rule);
-      },
-    };
-  }
-
-  /**
-   * Register a rule that matches when the request includes a tool with this name.
-   *
-   * @example
-   * ```ts
-   * server.whenTool("get_weather").reply({
-   *   tools: [{ name: "get_weather", args: { location: "London" } }],
-   * });
-   * ```
-   */
-  whenTool(toolName: string): PendingRule {
-    return this.when({ toolName });
-  }
-
-  /**
-   * Register a rule that matches when the last message is a tool result with this call ID.
-   *
-   * @example
-   * ```ts
-   * server.whenToolResult("call_abc").reply("Got your result, cheers!");
-   * ```
-   */
-  whenToolResult(toolCallId: string): PendingRule {
-    return this.when({ toolCallId });
-  }
-
-  /**
-   * Queue a one-shot error for the very next request, regardless of content.
-   * Fires once then removes itself.
-   *
-   * @example
-   * ```ts
-   * server.nextError(429, "Rate limited");
-   * // next request gets a 429, after that normal matching resumes
-   * ```
+   * Set the reply used when no rule matches.
+   * @defaultValue `"Mock server: no matching rule."`
    */
-  nextError(status: number, message: string, type?: string): RuleHandle {
-    return this.when(() => true)
-      .reply({ error: { status, message, type } })
-      .times(1)
-      .first();
-  }
-
-  /** Set the reply used when no rule matches. Defaults to a generic message. */
   fallback(reply: Reply): void {
     this.fallbackReply = reply;
   }
@@ -224,6 +165,12 @@ export class MockServer {
     return `http://${this.host}:${port}`;
   }
 
+  /** The API routes registered on this server, e.g. `["/v1/chat/completions", ...]`. */
+  get routes(): readonly string[] {
+    return formats.map((f) => f.route);
+  }
+
+  /** Number of currently registered rules. */
   get ruleCount(): number {
     return this.engine.ruleCount;
   }
@@ -241,6 +188,7 @@ export class MockServer {
     this.logger.info(`Listening on ${this.url}`);
   }
 
+  /** Stop the server. Safe to call multiple times. */
   async stop(): Promise<void> {
     if (!this.listening) return;
     await this.app.close();
@@ -248,6 +196,7 @@ export class MockServer {
     this.logger.info("Server stopped");
   }
 
+  /** Calls `stop()`. Enables `await using server = ...` for automatic cleanup. */
   async [Symbol.asyncDispose](): Promise<void> {
     await this.stop();
   }

package/src/route-handler.ts

@@ -1,12 +1,8 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { ZodError } from "zod";
-import type {
-  Reply,
-  ReplyObject,
-  ReplyOptions,
-  MockRequest,
-  Rule,
-} from "./types.js";
+import type { MockRequest } from "./types/request.js";
+import type { Reply, ReplyObject, ReplyOptions } from "./types/reply.js";
+import type { Rule } from "./types/rule.js";
 import type { Format } from "./formats/types.js";
 import type { RuleEngine } from "./rule-engine.js";
 import type { RequestHistory } from "./history.js";
@@ -15,7 +11,7 @@ import { writeSSE } from "./sse-writer.js";
 
 const HTTP_BAD_REQUEST = 400;
 
-function normalizeReply(reply: Reply): ReplyObject {
+function normaliseReply(reply: Reply): ReplyObject {
   if (typeof reply === "string") return { text: reply };
   return reply;
 }
@@ -30,7 +26,7 @@ async function resolveReply(
     logger.warn(
       `No matching rule for "${mockReq.lastMessage}", using fallback`,
     );
-    return { reply: normalizeReply(fallback), ruleDesc: undefined };
+    return { reply: normaliseReply(fallback), ruleDesc: undefined };
   }
 
   try {
@@ -39,10 +35,10 @@ async function resolveReply(
         ? await matched.resolve(mockReq)
         : matched.resolve;
     logger.debug(`Matched rule ${matched.description}`);
-    return { reply: normalizeReply(raw), ruleDesc: matched.description };
+    return { reply: normaliseReply(raw), ruleDesc: matched.description };
   } catch (err) {
     logger.error(`Resolver threw for rule ${matched.description}`, err);
-    return { reply: normalizeReply(fallback), ruleDesc: matched.description };
+    return { reply: normaliseReply(fallback), ruleDesc: matched.description };
   }
 }
 

package/src/rule-builder.ts

@@ -0,0 +1,73 @@
+import type {
+  Reply,
+  ReplyOptions,
+  Resolver,
+  SequenceEntry,
+} from "./types/reply.js";
+import type { Match, PendingRule, Rule, RuleHandle } from "./types/rule.js";
+import type { RuleEngine } from "./rule-engine.js";
+import { createSequenceResolver } from "./rule-engine.js";
+
+function makeHandle(engine: RuleEngine, rule: Rule): RuleHandle {
+  return {
+    times(n: number): RuleHandle {
+      rule.remaining = n;
+      return this;
+    },
+    first(): RuleHandle {
+      engine.moveToFront(rule);
+      return this;
+    },
+  };
+}
+
+/** Builds matching rules against the rule engine. Proxied onto `MockServer`. */
+export class RuleBuilder {
+  constructor(private readonly engine: RuleEngine) {}
+
+  /** Register a matching rule. Call `.reply()` on the result to set the response. */
+  when(match: Match): PendingRule {
+    const engine = this.engine;
+    return {
+      reply(response: Resolver, options?: ReplyOptions): RuleHandle {
+        return makeHandle(engine, engine.add(match, response, options));
+      },
+      replySequence(entries: readonly SequenceEntry[]): RuleHandle {
+        const steps = normaliseSequenceEntries(entries);
+        const rule = engine.add(match, "");
+        const { resolver, entryCount } = createSequenceResolver(steps, rule);
+        rule.resolve = resolver;
+        rule.remaining = entryCount;
+        return makeHandle(engine, rule);
+      },
+    };
+  }
+
+  /** Shorthand for `when({ toolName })`. */
+  whenTool(toolName: string): PendingRule {
+    return this.when({ toolName });
+  }
+
+  /** Shorthand for `when({ toolCallId })`. */
+  whenToolResult(toolCallId: string): PendingRule {
+    return this.when({ toolCallId });
+  }
+
+  /** Queue a one-shot error for the very next request. Fires once then removes itself. */
+  nextError(status: number, message: string, type?: string): RuleHandle {
+    return this.when(() => true)
+      .reply({ error: { status, message, type } })
+      .times(1)
+      .first();
+  }
+}
+
+export function normaliseSequenceEntries(
+  entries: readonly SequenceEntry[],
+): { reply: Reply; options?: ReplyOptions | undefined }[] {
+  return entries.map((entry) =>
+    typeof entry === "string" || !("reply" in entry)
+      ? { reply: entry as Reply }
+      : { reply: entry.reply, options: entry.options },
+  );
+}

package/src/rule-engine.ts

@@ -1,13 +1,6 @@
-import type {
-  Match,
-  MatchObject,
-  MockRequest,
-  Resolver,
-  Reply,
-  ReplyOptions,
-  Rule,
-  RuleSummary,
-} from "./types.js";
+import type { MockRequest } from "./types/request.js";
+import type { Reply, ReplyOptions, Resolver } from "./types/reply.js";
+import type { Match, MatchObject, Rule, RuleSummary } from "./types/rule.js";
 
 function safeRegex(re: RegExp): RegExp {
   return re.global || re.sticky

package/src/sse-writer.ts

@@ -1,6 +1,6 @@
 import type { FastifyReply } from "fastify";
 import type { SSEChunk } from "./formats/types.js";
-import type { ReplyOptions } from "./types.js";
+import type { ReplyOptions } from "./types/reply.js";
 
 const HTTP_OK = 200;
 

package/src/types/reply.ts

@@ -3,13 +3,28 @@ import type { MockRequest } from "./request.js";
 /** A reply is either a plain string (turns into `{ text: "..." }`) or a full reply object. */
 export type Reply = string | ReplyObject;
 
-/** A structured reply. Text, reasoning, tool calls, usage, and errors are all optional. */
+/**
+ * A structured reply. Text, reasoning, tool calls, usage, and errors are all optional.
+ *
+ * @example
+ * ```ts
+ * server.when("hello").reply({ text: "Hi!", reasoning: "Simple greeting." });
+ * server.when("weather").reply({
+ *   tools: [{ name: "get_weather", args: { city: "London" } }],
+ * });
+ * ```
+ */
 export interface ReplyObject {
+  /** Text content to send back. */
   readonly text?: string | undefined;
   /** Extended thinking or chain-of-thought. Works with Anthropic and Responses formats. */
   readonly reasoning?: string | undefined;
+  /** Tool calls the model wants to make. */
   readonly tools?: readonly ToolCall[] | undefined;
-  /** Falls back to `{ input: 10, output: 5 }` if omitted. */
+  /**
+   * Token counts to report.
+   * @defaultValue `{ input: 10, output: 5 }`
+   */
   readonly usage?:
     | { readonly input: number; readonly output: number }
     | undefined;
@@ -19,31 +34,59 @@ export interface ReplyObject {
 
 /** An HTTP error response. The server returns this status code with a format-appropriate body. */
 export interface ErrorReply {
+  /** HTTP status code, e.g. `429` or `500`. */
   readonly status: number;
+  /** Error message in the response body. */
   readonly message: string;
-  /** Each format has its own default if omitted. */
+  /**
+   * Error type string in the response body.
+   * @defaultValue Format-specific (e.g. `"server_error"` for OpenAI, `"api_error"` for Anthropic).
+   */
   readonly type?: string | undefined;
 }
 
+/** A tool call in the mock response. */
 export interface ToolCall {
-  /** Auto-generated if omitted. */
+  /** Explicit ID for the call. Auto-generated if omitted. */
   readonly id?: string | undefined;
+  /** Tool function name. */
   readonly name: string;
+  /** Arguments to pass to the tool. */
   readonly args: Readonly<Record<string, unknown>>;
 }
 
-/** A reply value or a function that produces one. Async functions are supported. */
+/**
+ * A reply value or a function that produces one. Async functions are supported.
+ *
+ * @example
+ * ```ts
+ * server.when("echo").reply((req) => `You said: ${req.lastMessage}`);
+ * server.when("slow").reply(async (req) => {
+ *   return { text: "Done thinking." };
+ * });
+ * ```
+ */
 export type Resolver = Reply | ((req: MockRequest) => Reply | Promise<Reply>);
 
 /** Per-rule streaming options. Merged with server-level defaults, with per-rule values winning. */
 export interface ReplyOptions {
-  /** Milliseconds between SSE chunks. */
+  /** Milliseconds to wait between SSE chunks. */
   readonly latency?: number | undefined;
-  /** Characters per SSE chunk for more realistic streaming. */
+  /** Split text into chunks of this many characters for more realistic streaming. */
   readonly chunkSize?: number | undefined;
 }
 
-/** A single entry in a reply sequence. Can be a plain reply or a reply with per-step options. */
+/**
+ * A single entry in a reply sequence. Can be a plain reply or a reply with per-step options.
+ *
+ * @example
+ * ```ts
+ * server.when("step").replySequence([
+ *   "Starting.",
+ *   { reply: "Done.", options: { latency: 100 } },
+ * ]);
+ * ```
+ */
 export type SequenceEntry =
   | Reply
   | { readonly reply: Reply; readonly options?: ReplyOptions };