llm-mock-server 1.0.6 → 1.0.7

package/src/route-handler.ts

@@ -1,144 +0,0 @@
-import type { FastifyReply, FastifyRequest } from "fastify";
-import { ZodError } from "zod";
-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";
-import type { Logger } from "./logger.js";
-import { writeSSE } from "./sse-writer.js";
-
-const HTTP_BAD_REQUEST = 400;
-
-function normaliseReply(reply: Reply): ReplyObject {
-  if (typeof reply === "string") return { text: reply };
-  return reply;
-}
-
-async function resolveReply(
-  matched: Rule | undefined,
-  mockReq: MockRequest,
-  fallback: Reply,
-  logger: Logger,
-): Promise<{ reply: ReplyObject; ruleDesc: string | undefined }> {
-  if (!matched) {
-    logger.warn(
-      `No matching rule for "${mockReq.lastMessage}", using fallback`,
-    );
-    return { reply: normaliseReply(fallback), ruleDesc: undefined };
-  }
-
-  try {
-    const raw =
-      typeof matched.resolve === "function"
-        ? await matched.resolve(mockReq)
-        : matched.resolve;
-    logger.debug(`Matched rule ${matched.description}`);
-    return { reply: normaliseReply(raw), ruleDesc: matched.description };
-  } catch (err) {
-    logger.error(`Resolver threw for rule ${matched.description}`, err);
-    return { reply: normaliseReply(fallback), ruleDesc: matched.description };
-  }
-}
-
-interface RouteHandlerDeps {
-  engine: RuleEngine;
-  history: RequestHistory;
-  logger: Logger;
-  defaultOptions: ReplyOptions;
-  getFallback: () => Reply;
-}
-
-export function createRouteHandler(
-  format: Format,
-  deps: RouteHandlerDeps,
-): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
-  const { engine, history, logger, defaultOptions, getFallback } = deps;
-
-  return async (request: FastifyRequest, reply: FastifyReply) => {
-    const body = request.body;
-    const headers: Record<string, string | undefined> = {};
-    for (const [key, val] of Object.entries(request.headers)) {
-      headers[key] = Array.isArray(val) ? val.join(", ") : val;
-    }
-    const meta = { headers, path: request.url };
-
-    let mockReq: MockRequest;
-    try {
-      mockReq = format.parseRequest(body, meta);
-    } catch (err) {
-      if (err instanceof ZodError) {
-        logger.warn(
-          `Invalid ${format.name} request: ${err.issues.map((i) => i.message).join(", ")}`,
-        );
-        return reply
-          .status(HTTP_BAD_REQUEST)
-          .type("application/json")
-          .send(
-            format.serializeError({
-              status: HTTP_BAD_REQUEST,
-              message: "Invalid request body",
-              type: "invalid_request_error",
-            }),
-          );
-      }
-      throw err;
-    }
-    const startTime = Date.now();
-
-    logger.debug(
-      `${format.name} request: model=${mockReq.model} streaming=${mockReq.streaming} messages=${mockReq.messages.length}`,
-    );
-
-    const matched = engine.match(mockReq);
-    const { reply: resolvedReply, ruleDesc } = await resolveReply(
-      matched,
-      mockReq,
-      getFallback(),
-      logger,
-    );
-
-    if (resolvedReply.error) {
-      const { error } = resolvedReply;
-      logger.info(`Error reply: ${String(error.status)} ${error.message}`);
-      history.record(mockReq, ruleDesc);
-      return reply
-        .status(error.status)
-        .type("application/json")
-        .send(format.serializeError(error));
-    }
-
-    history.record(mockReq, ruleDesc);
-
-    const isStreaming = format.isStreaming(body);
-    const effectiveOptions = { ...defaultOptions, ...matched?.options };
-    const elapsed = Date.now() - startTime;
-    const mode = isStreaming ? "stream" : "json";
-
-    logger.info(
-      `POST ${format.route} [${mode}] "${mockReq.lastMessage}" -> ${ruleDesc ?? "fallback"} (${elapsed}ms)`,
-    );
-    if (resolvedReply.text) {
-      logger.debug(`Reply text: "${resolvedReply.text}"`);
-    }
-    if (resolvedReply.tools?.length) {
-      logger.debug(
-        `Reply tool calls: ${resolvedReply.tools.map((t) => t.name).join(", ")}`,
-      );
-    }
-
-    if (!isStreaming) {
-      return reply
-        .type("application/json")
-        .send(format.serializeComplete(resolvedReply, mockReq.model));
-    }
-
-    const chunks = format.serialize(
-      resolvedReply,
-      mockReq.model,
-      effectiveOptions,
-    );
-    await writeSSE(reply, chunks, effectiveOptions);
-  };
-}

package/src/rule-builder.ts

@@ -1,73 +0,0 @@
-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,165 +0,0 @@
-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
-    ? new RegExp(re.source, re.flags.replace(/[gy]/g, ""))
-    : re;
-}
-
-function compilePattern(pattern: string | RegExp): (value: string) => boolean {
-  if (typeof pattern === "string") {
-    const lower = pattern.toLowerCase();
-    return (value) => value.toLowerCase().includes(lower);
-  }
-  const re = safeRegex(pattern);
-  return (value) => re.test(value);
-}
-
-function compileMatcher(match: Match): (req: MockRequest) => boolean {
-  if (typeof match === "string") {
-    const test = compilePattern(match);
-    return (req) => test(req.lastMessage);
-  }
-  if (match instanceof RegExp) {
-    const test = compilePattern(match);
-    return (req) => test(req.lastMessage);
-  }
-  if (typeof match === "function") {
-    return match;
-  }
-  const obj = match;
-  const messageTest =
-    obj.message !== undefined ? compilePattern(obj.message) : undefined;
-  const modelTest =
-    obj.model !== undefined ? compilePattern(obj.model) : undefined;
-  const systemTest =
-    obj.system !== undefined ? compilePattern(obj.system) : undefined;
-  return (req) => {
-    if (messageTest && !messageTest(req.lastMessage)) return false;
-    if (modelTest && !modelTest(req.model)) return false;
-    if (systemTest && !systemTest(req.systemMessage)) return false;
-    if (obj.format !== undefined && req.format !== obj.format) return false;
-    if (obj.toolName !== undefined && !req.toolNames.includes(obj.toolName))
-      return false;
-    if (obj.toolCallId !== undefined && req.lastToolCallId !== obj.toolCallId)
-      return false;
-    if (obj.predicate && !obj.predicate(req)) return false;
-    return true;
-  };
-}
-
-function describeMatch(match: Match): string {
-  if (typeof match === "string") return `"${match}"`;
-  if (match instanceof RegExp) return match.toString();
-  if (typeof match === "function") return "(predicate)";
-  const obj: MatchObject = match;
-  const parts = Object.entries(obj)
-    .filter(([, v]) => v !== undefined && typeof v !== "function")
-    .map(([k, v]) => `${k}=${String(v)}`);
-  return `{${parts.join(", ")}}`;
-}
-
-function createRule(
-  match: Match,
-  resolve: Resolver,
-  options: ReplyOptions,
-  description?: string,
-): Rule {
-  return {
-    description: description ?? describeMatch(match),
-    match: compileMatcher(match),
-    resolve,
-    options,
-    remaining: Infinity,
-  };
-}
-
-interface SequenceStep {
-  readonly reply: Reply;
-  readonly options?: ReplyOptions | undefined;
-}
-
-export function createSequenceResolver(
-  steps: readonly SequenceStep[],
-  rule: { options: ReplyOptions },
-): { resolver: () => Reply; entryCount: number } {
-  if (steps.length === 0)
-    throw new Error("Sequence requires at least one entry.");
-  let index = 0;
-  const last = steps[steps.length - 1]!;
-  return {
-    resolver: () => {
-      const step = steps[index++] ?? last;
-      rule.options = step.options ?? {};
-      return step.reply;
-    },
-    entryCount: steps.length,
-  };
-}
-
-export class RuleEngine {
-  private readonly rules: Rule[] = [];
-
-  add(match: Match, resolve: Resolver, options: ReplyOptions = {}): Rule {
-    const rule = createRule(match, resolve, options);
-    this.rules.push(rule);
-    return rule;
-  }
-
-  moveToFront(rule: Rule): void {
-    const idx = this.rules.indexOf(rule);
-    if (idx > 0) {
-      this.rules.splice(idx, 1);
-      this.rules.unshift(rule);
-    }
-  }
-
-  addHandler(
-    matchFn: (req: MockRequest) => boolean,
-    respond: Resolver,
-    description = "(handler)",
-  ): Rule {
-    const rule = createRule(matchFn, respond, {}, description);
-    this.rules.push(rule);
-    return rule;
-  }
-
-  match(req: MockRequest): Rule | undefined {
-    for (let i = 0; i < this.rules.length; i++) {
-      const rule = this.rules[i]!;
-
-      if (rule.remaining <= 0) continue;
-      if (!rule.match(req)) continue;
-
-      rule.remaining--;
-      if (rule.remaining <= 0) {
-        this.rules.splice(i, 1);
-      }
-      return rule;
-    }
-    return undefined;
-  }
-
-  isDone(): boolean {
-    return this.rules.every(
-      (r) => !Number.isFinite(r.remaining) || r.remaining <= 0,
-    );
-  }
-
-  get ruleCount(): number {
-    return this.rules.length;
-  }
-
-  describe(): readonly RuleSummary[] {
-    return this.rules.map((r) => ({
-      description: r.description,
-      remaining: r.remaining,
-    }));
-  }
-
-  clear(): void {
-    this.rules.length = 0;
-  }
-}

package/src/sse-writer.ts

@@ -1,35 +0,0 @@
-import type { FastifyReply } from "fastify";
-import type { SSEChunk } from "./formats/types.js";
-import type { ReplyOptions } from "./types/reply.js";
-
-const HTTP_OK = 200;
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function formatSSEChunk(chunk: SSEChunk): string {
-  const eventLine = chunk.event ? `event: ${chunk.event}\n` : "";
-  return `${eventLine}data: ${chunk.data}\n\n`;
-}
-
-export async function writeSSE(
-  reply: FastifyReply,
-  chunks: readonly SSEChunk[],
-  options: ReplyOptions = {},
-): Promise<void> {
-  const latency = options.latency ?? 0;
-
-  reply.raw.writeHead(HTTP_OK, {
-    "Content-Type": "text/event-stream",
-    "Cache-Control": "no-cache",
-    Connection: "keep-alive",
-  });
-
-  for (const chunk of chunks) {
-    reply.raw.write(formatSSEChunk(chunk));
-    if (latency > 0) await sleep(latency);
-  }
-
-  reply.raw.end();
-}

package/src/types/reply.ts

@@ -1,92 +0,0 @@
-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.
- *
- * @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;
-  /**
-   * Token counts to report.
-   * @defaultValue `{ input: 10, output: 5 }`
-   */
-  readonly usage?:
-    | { readonly input: number; readonly output: number }
-    | undefined;
-  /** When set, the server responds with this HTTP error instead of a normal reply. */
-  readonly error?: ErrorReply | undefined;
-}
-
-/** 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;
-  /**
-   * 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 {
-  /** 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.
- *
- * @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 to wait between SSE chunks. */
-  readonly latency?: number | undefined;
-  /** 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.
- *
- * @example
- * ```ts
- * server.when("step").replySequence([
- *   "Starting.",
- *   { reply: "Done.", options: { latency: 100 } },
- * ]);
- * ```
- */
-export type SequenceEntry =
-  | Reply
-  | { readonly reply: Reply; readonly options?: ReplyOptions };

package/src/types/request.ts

@@ -1,56 +0,0 @@
-/** The LLM API wire format that was detected for a request. */
-export type FormatName = "openai" | "anthropic" | "responses";
-
-/**
- * A normalised view of an incoming request, regardless of the original wire format.
- * This is what rule matchers and resolvers receive.
- */
-export interface MockRequest {
-  /** Which API format route the request came in on. */
-  readonly format: FormatName;
-  /** The model string from the request, e.g. `"gpt-5.4"` or `"claude-sonnet-4-6"`. */
-  readonly model: string;
-  /**
-   * Whether the client asked for SSE streaming (from the `stream` field).
-   * @defaultValue `true`
-   */
-  readonly streaming: boolean;
-  /** Full conversation, normalised from whatever format came in. */
-  readonly messages: readonly Message[];
-  /** The last user message's text. This is what most matchers check. */
-  readonly lastMessage: string;
-  /** System prompt text, or empty string if there wasn't one. */
-  readonly systemMessage: string;
-  /** Tool definitions from the request, if any were sent. */
-  readonly tools?: readonly ToolDef[] | undefined;
-  /** Tool names pulled out from `tools` for quick lookups via `whenTool()`. */
-  readonly toolNames: readonly string[];
-  /** Set when the last message was a tool result. Used by `whenToolResult()`. */
-  readonly lastToolCallId: string | undefined;
-  /** The raw request body, for anything we don't extract. */
-  readonly raw: unknown;
-  /** HTTP headers from the incoming request. */
-  readonly headers: Readonly<Record<string, string | undefined>>;
-  /** The URL path that was hit, e.g. `/v1/chat/completions`. */
-  readonly path: string;
-}
-
-/** A single conversation message, normalised across all supported formats. */
-export interface Message {
-  /** The role of the message sender. */
-  readonly role: "system" | "user" | "assistant" | "tool";
-  /** The text content of the message. */
-  readonly content: string;
-  /** Links the result back to its tool call. Only set on `"tool"` messages. */
-  readonly toolCallId?: string | undefined;
-}
-
-/** A tool definition from the request's `tools` array, normalised across formats. */
-export interface ToolDef {
-  /** The tool function name. */
-  readonly name: string;
-  /** A description of what the tool does. */
-  readonly description?: string | undefined;
-  /** JSON Schema for the tool's parameters, passed through as-is. */
-  readonly parameters?: unknown;
-}

package/src/types/rule.ts

@@ -1,125 +0,0 @@
-import type { MockRequest, FormatName } from "./request.js";
-import type { Resolver, ReplyOptions, Reply, SequenceEntry } from "./reply.js";
-
-/**
- * Determines whether a rule matches an incoming request.
- *
- * A `string` does a case-insensitive substring match on the last user message.
- * A `RegExp` gets tested against the last user message.
- * A `MatchObject` checks multiple fields at once with AND logic.
- * A function receives the normalised request and returns a boolean.
- *
- * @example
- * ```ts
- * server.when("hello").reply("Hi!");
- * server.when(/explain (\w+)/i).reply("Here's an explanation.");
- * server.when({ model: /claude/, format: "anthropic" }).reply("Bonjour!");
- * server.when((req) => req.messages.length > 5).reply("Long conversation!");
- * ```
- */
-export type Match =
-  | string
-  | RegExp
-  | MatchObject
-  | ((req: MockRequest) => boolean);
-
-/**
- * A structured matcher. Every field you set must match for the rule to fire.
- *
- * @example
- * ```ts
- * server.when({
- *   model: /gpt/,
- *   format: "openai",
- *   system: /translator/i,
- *   predicate: (req) => req.messages.length > 2,
- * }).reply("Translated output.");
- * ```
- */
-export interface MatchObject {
-  /** Substring or regex against the last user message. */
-  readonly message?: string | RegExp;
-  /** Substring or regex against the model name. */
-  readonly model?: string | RegExp;
-  /** Substring or regex against the system prompt. */
-  readonly system?: string | RegExp;
-  /** Only match requests from this API format. */
-  readonly format?: FormatName;
-  /** Match when the request includes a tool definition with this name. */
-  readonly toolName?: string;
-  /** Match when the last tool-result message has this `tool_call_id`. */
-  readonly toolCallId?: string;
-  /** Extra predicate that runs after all other fields pass. */
-  readonly predicate?: (req: MockRequest) => boolean;
-}
-
-/**
- * Returned by `when()`. Call `.reply()` or `.replySequence()` on it to complete the rule.
- *
- * @example
- * ```ts
- * server.when("hello").reply("Hi!");
- * server.when("step").replySequence(["First.", "Second.", "Done."]);
- * ```
- */
-export interface PendingRule {
-  /** Set the response for this rule. Accepts a static value, object, or resolver function. */
-  reply(response: Resolver, options?: ReplyOptions): RuleHandle;
-  /** Set a sequence of replies. Each match advances through the array. */
-  replySequence(entries: readonly SequenceEntry[]): RuleHandle;
-}
-
-/**
- * A handle to a registered rule. All methods return `this` for chaining.
- *
- * @example
- * ```ts
- * server.when("hello").reply("Hi!").times(3);
- * server.when("urgent").reply("On it!").first();
- * ```
- */
-export interface RuleHandle {
-  /** Auto-expire the rule after `n` matches. */
-  times(n: number): RuleHandle;
-  /** Move this rule to the front of the list so it matches first. */
-  first(): RuleHandle;
-}
-
-/**
- * The shape of a handler file's default export.
- * You can export a single handler or an array of them.
- *
- * @example
- * ```ts
- * import type { Handler } from "llm-mock-server";
- * export default {
- *   match: (req) => req.lastMessage.includes("echo"),
- *   respond: (req) => `Echo: ${req.lastMessage}`,
- * } satisfies Handler;
- * ```
- */
-export interface Handler {
-  /** Return `true` if this handler should respond to the request. */
-  match: (req: MockRequest) => boolean;
-  /** Produce the reply for a matched request. Can be async. */
-  respond: (req: MockRequest) => Reply | Promise<Reply>;
-}
-
-/** A summary of a registered rule, for inspection via `server.rules`. */
-export interface RuleSummary {
-  /** Human-readable description of what the rule matches. */
-  readonly description: string;
-  /**
-   * How many matches are left.
-   * @defaultValue `Infinity` (unlimited)
-   */
-  readonly remaining: number;
-}
-
-export interface Rule {
-  readonly description: string;
-  readonly match: (req: MockRequest) => boolean;
-  resolve: Resolver;
-  options: ReplyOptions;
-  remaining: number;
-}