llm-mock-server 1.0.2 → 1.0.3

package/src/index.ts

@@ -37,7 +37,9 @@ import type { MockServerOptions } from "./mock-server.js";
  * await server.stop();
  * ```
  */
-export async function createMock(options: MockServerOptions = {}): Promise<MockServer> {
+export async function createMock(
+  options: MockServerOptions = {},
+): Promise<MockServer> {
   const server = new MockServer(options);
   await server.start(options.port ?? 0);
   return server;

package/src/loader.ts

@@ -25,7 +25,11 @@ const json5ReplySchema = z.union([
   z.object({
     text: z.string().optional(),
     reasoning: z.string().optional(),
-    tools: z.array(z.object({ name: z.string(), args: z.record(z.string(), z.unknown()) })).optional(),
+    tools: z
+      .array(
+        z.object({ name: z.string(), args: z.record(z.string(), z.unknown()) }),
+      )
+      .optional(),
   }),
 ]);
 
@@ -77,7 +81,9 @@ function compileMatch(when: z.infer<typeof json5MatchSchema>): Match {
     return parseRegexString(when);
   }
   const obj: MatchObject = {
-    ...(when.message !== undefined && { message: parseRegexString(when.message) }),
+    ...(when.message !== undefined && {
+      message: parseRegexString(when.message),
+    }),
     ...(when.model !== undefined && { model: parseRegexString(when.model) }),
     ...(when.system !== undefined && { system: parseRegexString(when.system) }),
     ...(when.format !== undefined && { format: when.format }),
@@ -124,14 +130,21 @@ function addSequenceRule(
   rule.remaining = entryCount;
 }
 
-async function loadJson5File(filePath: string, ctx: LoadContext): Promise<void> {
+async function loadJson5File(
+  filePath: string,
+  ctx: LoadContext,
+): Promise<void> {
   const content = await readFile(filePath, "utf-8");
   const parsed = json5FileSchema.parse(JSON5.parse(content));
 
   const rules = Array.isArray(parsed) ? parsed : parsed.rules;
   const templates = Array.isArray(parsed) ? undefined : parsed.templates;
 
-  if (!Array.isArray(parsed) && parsed.fallback !== undefined && ctx.setFallback) {
+  if (
+    !Array.isArray(parsed) &&
+    parsed.fallback !== undefined &&
+    ctx.setFallback
+  ) {
     ctx.setFallback(parsed.fallback);
   }
 
@@ -152,7 +165,9 @@ async function loadJson5File(filePath: string, ctx: LoadContext): Promise<void>
 const handlerSchema = z.custom<Handler>((val): val is Handler => {
   if (typeof val !== "object" || val === null) return false;
   const obj = val as Record<string, unknown>;
-  return typeof obj["match"] === "function" && typeof obj["respond"] === "function";
+  return (
+    typeof obj["match"] === "function" && typeof obj["respond"] === "function"
+  );
 });
 
 const handlerExportSchema = z.object({
@@ -160,7 +175,10 @@ const handlerExportSchema = z.object({
   fallback: json5ReplySchema.optional(),
 });
 
-async function loadHandlerFile(filePath: string, ctx: LoadContext): Promise<void> {
+async function loadHandlerFile(
+  filePath: string,
+  ctx: LoadContext,
+): Promise<void> {
   const mod = await import(filePath);
   const parsed = handlerExportSchema.safeParse(mod);
   if (!parsed.success) {
@@ -168,14 +186,20 @@ async function loadHandlerFile(filePath: string, ctx: LoadContext): Promise<void
       `Invalid handler file ${filePath}. Expected default export with { match: Function, respond: Function }.`,
     );
   }
-  const handlers = Array.isArray(parsed.data.default) ? parsed.data.default : [parsed.data.default];
+  const handlers = Array.isArray(parsed.data.default)
+    ? parsed.data.default
+    : [parsed.data.default];
 
   if (parsed.data.fallback !== undefined && ctx.setFallback) {
     ctx.setFallback(parsed.data.fallback);
   }
 
   for (const handler of handlers) {
-    ctx.engine.addHandler(handler.match, handler.respond, `(handler: ${filePath})`);
+    ctx.engine.addHandler(
+      handler.match,
+      handler.respond,
+      `(handler: ${filePath})`,
+    );
   }
 }
 
@@ -189,7 +213,10 @@ const loaderByExtension: ReadonlyMap<string, FileLoader> = new Map([
   [".mjs", loadHandlerFile],
 ]);
 
-export async function loadRulesFromPath(pathOrDir: string, ctx: LoadContext): Promise<void> {
+export async function loadRulesFromPath(
+  pathOrDir: string,
+  ctx: LoadContext,
+): Promise<void> {
   const info = await stat(pathOrDir);
 
   if (info.isFile()) {

package/src/logger.ts

@@ -21,7 +21,10 @@ const LEVEL_STYLE = {
 
 type ConsoleMethod = "error" | "warn" | "log";
 
-const LEVEL_CONFIG: Record<keyof typeof LEVEL_STYLE, { priority: number; method: ConsoleMethod; dim?: boolean }> = {
+const LEVEL_CONFIG: Record<
+  keyof typeof LEVEL_STYLE,
+  { priority: number; method: ConsoleMethod; dim?: boolean }
+> = {
   error: { priority: LEVEL_PRIORITY.error, method: "error" },
   warn: { priority: LEVEL_PRIORITY.warning, method: "warn" },
   info: { priority: LEVEL_PRIORITY.info, method: "log" },
@@ -37,16 +40,31 @@ export class Logger {
     this.threshold = LEVEL_PRIORITY[level];
   }
 
-  private log(key: keyof typeof LEVEL_STYLE, msg: string, args: unknown[]): void {
+  private log(
+    key: keyof typeof LEVEL_STYLE,
+    msg: string,
+    args: unknown[],
+  ): void {
     const config = LEVEL_CONFIG[key];
     if (this.threshold < config.priority) return;
     const { label, symbol } = LEVEL_STYLE[key];
     const text = config.dim ? pc.dim(msg) : msg;
-    console[config.method](`${pc.dim(new Date().toISOString())} ${symbol} ${label} ${text}`, ...args);
+    console[config.method](
+      `${pc.dim(new Date().toISOString())} ${symbol} ${label} ${text}`,
+      ...args,
+    );
   }
 
-  error(msg: string, ...args: unknown[]): void { this.log("error", msg, args); }
-  warn(msg: string, ...args: unknown[]): void { this.log("warn", msg, args); }
-  info(msg: string, ...args: unknown[]): void { this.log("info", msg, args); }
-  debug(msg: string, ...args: unknown[]): void { this.log("debug", msg, args); }
+  error(msg: string, ...args: unknown[]): void {
+    this.log("error", msg, args);
+  }
+  warn(msg: string, ...args: unknown[]): void {
+    this.log("warn", msg, args);
+  }
+  info(msg: string, ...args: unknown[]): void {
+    this.log("info", msg, args);
+  }
+  debug(msg: string, ...args: unknown[]): void {
+    this.log("debug", msg, args);
+  }
 }

package/src/mock-server.ts

@@ -1,7 +1,15 @@
 import Fastify from "fastify";
 import type { FastifyInstance } from "fastify";
 import type {
-  Match, PendingRule, Reply, ReplyOptions, Resolver, Rule, RuleHandle, RuleSummary, SequenceEntry,
+  Match,
+  PendingRule,
+  Reply,
+  ReplyOptions,
+  Resolver,
+  Rule,
+  RuleHandle,
+  RuleSummary,
+  SequenceEntry,
 } from "./types.js";
 import { RuleEngine, createSequenceResolver } from "./rule-engine.js";
 import { RequestHistory } from "./history.js";
@@ -13,7 +21,11 @@ import { Logger } from "./logger.js";
 import type { LogLevel } from "./logger.js";
 import { createRouteHandler } from "./route-handler.js";
 
-const formats: readonly Format[] = [openaiFormat, anthropicFormat, responsesFormat];
+const formats: readonly Format[] = [
+  openaiFormat,
+  anthropicFormat,
+  responsesFormat,
+];
 
 export interface MockServerOptions {
   readonly port?: number;
@@ -56,8 +68,12 @@ export class MockServer {
     this.host = options.host ?? "127.0.0.1";
     this.logger = new Logger(options.logLevel ?? "none");
     this.defaultOptions = {
-      ...(options.defaultLatency !== undefined && { latency: options.defaultLatency }),
-      ...(options.defaultChunkSize !== undefined && { chunkSize: options.defaultChunkSize }),
+      ...(options.defaultLatency !== undefined && {
+        latency: options.defaultLatency,
+      }),
+      ...(options.defaultChunkSize !== undefined && {
+        chunkSize: options.defaultChunkSize,
+      }),
     };
     this.app = Fastify({ logger: false });
 
@@ -171,10 +187,14 @@ export class MockServer {
     const { loadRulesFromPath } = await import("./loader.js");
     await loadRulesFromPath(pathOrDir, {
       engine: this.engine,
-      setFallback: (reply) => { this.fallbackReply = reply; },
+      setFallback: (reply) => {
+        this.fallbackReply = reply;
+      },
     });
     const loaded = this.engine.ruleCount - before;
-    this.logger.info(`Loaded ${loaded} rule${loaded !== 1 ? "s" : ""} from ${pathOrDir}`);
+    this.logger.info(
+      `Loaded ${loaded} rule${loaded !== 1 ? "s" : ""} from ${pathOrDir}`,
+    );
   }
 
   /** Every request the server has handled. */
@@ -197,7 +217,8 @@ export class MockServer {
 
   /** The base URL the server is listening on, e.g. `http://127.0.0.1:12345`. Throws if the server hasn't started. */
   get url(): string {
-    if (!this.listening) throw new Error("Server is not running. Call start() first.");
+    if (!this.listening)
+      throw new Error("Server is not running. Call start() first.");
     const addr = this.app.server.address();
     const port = addr !== null && typeof addr === "object" ? addr.port : 0;
     return `http://${this.host}:${port}`;

package/src/route-handler.ts

@@ -1,6 +1,12 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { ZodError } from "zod";
-import type { Reply, ReplyObject, ReplyOptions, MockRequest, Rule } from "./types.js";
+import type {
+  Reply,
+  ReplyObject,
+  ReplyOptions,
+  MockRequest,
+  Rule,
+} from "./types.js";
 import type { Format } from "./formats/types.js";
 import type { RuleEngine } from "./rule-engine.js";
 import type { RequestHistory } from "./history.js";
@@ -21,14 +27,17 @@ async function resolveReply(
   logger: Logger,
 ): Promise<{ reply: ReplyObject; ruleDesc: string | undefined }> {
   if (!matched) {
-    logger.warn(`No matching rule for "${mockReq.lastMessage}", using fallback`);
+    logger.warn(
+      `No matching rule for "${mockReq.lastMessage}", using fallback`,
+    );
     return { reply: normalizeReply(fallback), ruleDesc: undefined };
   }
 
   try {
-    const raw = typeof matched.resolve === "function"
-      ? await matched.resolve(mockReq)
-      : matched.resolve;
+    const raw =
+      typeof matched.resolve === "function"
+        ? await matched.resolve(mockReq)
+        : matched.resolve;
     logger.debug(`Matched rule ${matched.description}`);
     return { reply: normalizeReply(raw), ruleDesc: matched.description };
   } catch (err) {
@@ -45,7 +54,10 @@ interface RouteHandlerDeps {
   getFallback: () => Reply;
 }
 
-export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
+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) => {
@@ -61,10 +73,19 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
       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" }),
+        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;
     }
@@ -76,14 +97,20 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
 
     const matched = engine.match(mockReq);
     const { reply: resolvedReply, ruleDesc } = await resolveReply(
-      matched, mockReq, getFallback(), logger,
+      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));
+      return reply
+        .status(error.status)
+        .type("application/json")
+        .send(format.serializeError(error));
     }
 
     history.record(mockReq, ruleDesc);
@@ -100,14 +127,22 @@ export function createRouteHandler(format: Format, deps: RouteHandlerDeps): (req
       logger.debug(`Reply text: "${resolvedReply.text}"`);
     }
     if (resolvedReply.tools?.length) {
-      logger.debug(`Reply tool calls: ${resolvedReply.tools.map((t) => t.name).join(", ")}`);
+      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));
+      return reply
+        .type("application/json")
+        .send(format.serializeComplete(resolvedReply, mockReq.model));
     }
 
-    const chunks = format.serialize(resolvedReply, mockReq.model, effectiveOptions);
+    const chunks = format.serialize(
+      resolvedReply,
+      mockReq.model,
+      effectiveOptions,
+    );
     await writeSSE(reply, chunks, effectiveOptions);
   };
 }

package/src/rule-engine.ts

@@ -1,7 +1,18 @@
-import type { Match, MatchObject, MockRequest, Resolver, Reply, ReplyOptions, Rule, RuleSummary } from "./types.js";
+import type {
+  Match,
+  MatchObject,
+  MockRequest,
+  Resolver,
+  Reply,
+  ReplyOptions,
+  Rule,
+  RuleSummary,
+} from "./types.js";
 
 function safeRegex(re: RegExp): RegExp {
-  return (re.global || re.sticky) ? new RegExp(re.source, re.flags.replace(/[gy]/g, "")) : re;
+  return re.global || re.sticky
+    ? new RegExp(re.source, re.flags.replace(/[gy]/g, ""))
+    : re;
 }
 
 function compilePattern(pattern: string | RegExp): (value: string) => boolean {
@@ -26,16 +37,21 @@ function compileMatcher(match: Match): (req: MockRequest) => boolean {
     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;
+  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.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;
   };
@@ -52,7 +68,12 @@ function describeMatch(match: Match): string {
   return `{${parts.join(", ")}}`;
 }
 
-function createRule(match: Match, resolve: Resolver, options: ReplyOptions, description?: string): Rule {
+function createRule(
+  match: Match,
+  resolve: Resolver,
+  options: ReplyOptions,
+  description?: string,
+): Rule {
   return {
     description: description ?? describeMatch(match),
     match: compileMatcher(match),
@@ -71,7 +92,8 @@ 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.");
+  if (steps.length === 0)
+    throw new Error("Sequence requires at least one entry.");
   let index = 0;
   const last = steps[steps.length - 1]!;
   return {
@@ -101,7 +123,11 @@ export class RuleEngine {
     }
   }
 
-  addHandler(matchFn: (req: MockRequest) => boolean, respond: Resolver, description = "(handler)"): Rule {
+  addHandler(
+    matchFn: (req: MockRequest) => boolean,
+    respond: Resolver,
+    description = "(handler)",
+  ): Rule {
     const rule = createRule(matchFn, respond, {}, description);
     this.rules.push(rule);
     return rule;
@@ -124,7 +150,9 @@ export class RuleEngine {
   }
 
   isDone(): boolean {
-    return this.rules.every((r) => !Number.isFinite(r.remaining) || r.remaining <= 0);
+    return this.rules.every(
+      (r) => !Number.isFinite(r.remaining) || r.remaining <= 0,
+    );
   }
 
   get ruleCount(): number {
@@ -132,7 +160,10 @@ export class RuleEngine {
   }
 
   describe(): readonly RuleSummary[] {
-    return this.rules.map((r) => ({ description: r.description, remaining: r.remaining }));
+    return this.rules.map((r) => ({
+      description: r.description,
+      remaining: r.remaining,
+    }));
   }
 
   clear(): void {

package/src/types/reply.ts

@@ -10,7 +10,9 @@ export interface ReplyObject {
   readonly reasoning?: string | undefined;
   readonly tools?: readonly ToolCall[] | undefined;
   /** Falls back to `{ input: 10, output: 5 }` if omitted. */
-  readonly usage?: { readonly input: number; readonly output: number } | undefined;
+  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;
 }
@@ -42,4 +44,6 @@ export interface ReplyOptions {
 }
 
 /** A single entry in a reply sequence. Can be a plain reply or a reply with per-step options. */
-export type SequenceEntry = Reply | { readonly reply: Reply; readonly options?: ReplyOptions };
+export type SequenceEntry =
+  | Reply
+  | { readonly reply: Reply; readonly options?: ReplyOptions };

package/src/types.ts

@@ -1,3 +1,24 @@
-export type { FormatName, MockRequest, Message, ToolDef } from "./types/request.js";
-export type { Reply, ReplyObject, ErrorReply, ToolCall, Resolver, ReplyOptions, SequenceEntry } from "./types/reply.js";
-export type { Match, MatchObject, PendingRule, RuleHandle, RuleSummary, Handler, Rule } from "./types/rule.js";
+export type {
+  FormatName,
+  MockRequest,
+  Message,
+  ToolDef,
+} from "./types/request.js";
+export type {
+  Reply,
+  ReplyObject,
+  ErrorReply,
+  ToolCall,
+  Resolver,
+  ReplyOptions,
+  SequenceEntry,
+} from "./types/reply.js";
+export type {
+  Match,
+  MatchObject,
+  PendingRule,
+  RuleHandle,
+  RuleSummary,
+  Handler,
+  Rule,
+} from "./types/rule.js";

package/test/cli-validators.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { parsePort, parseHost, parseChunkSize, parseLogLevel, parseLatency } from "../src/cli-validators.js";
+import {
+  parsePort,
+  parseHost,
+  parseChunkSize,
+  parseLogLevel,
+  parseLatency,
+} from "../src/cli-validators.js";
 
 describe("parsePort", () => {
   it("parses a valid port", () => {
@@ -48,7 +54,9 @@ describe("parseLogLevel", () => {
   );
 
   it("throws on invalid level", () => {
-    expect(() => parseLogLevel("verbose")).toThrow('Invalid log level "verbose"');
+    expect(() => parseLogLevel("verbose")).toThrow(
+      'Invalid log level "verbose"',
+    );
   });
 
   it("throws on empty string", () => {
@@ -78,11 +86,15 @@ describe("parseHost", () => {
   });
 
   it("rejects an unresolvable hostname", async () => {
-    await expect(parseHost("not.a.real.host.invalid")).rejects.toThrow("Invalid host");
+    await expect(parseHost("not.a.real.host.invalid")).rejects.toThrow(
+      "Invalid host",
+    );
   });
 
   it("rejects a string with spaces", async () => {
-    await expect(parseHost("local host")).rejects.toThrow('Invalid host "local host"');
+    await expect(parseHost("local host")).rejects.toThrow(
+      'Invalid host "local host"',
+    );
   });
 });