api-json-server 1.0.1 → 1.2.0

package/examples/companies-nested.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../mockserve.spec.schema.json",
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" },
+    "fakerSeed": 42
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/companies",
+      "response": {
+        "companies": {
+          "__repeat": {
+            "min": 3,
+            "max": 5,
+            "template": {
+              "id": { "__faker": "string.uuid" },
+              "name": { "__faker": "company.name" },
+              "domain": { "__faker": "internet.domainName" },
+              "address": {
+                "street": { "__faker": "location.streetAddress" },
+                "city": { "__faker": "location.city" },
+                "zip": { "__faker": "location.zipCode" },
+                "country": { "__faker": "location.country" }
+              },
+              "contacts": {
+                "__repeat": {
+                  "count": 2,
+                  "min": 0,
+                  "template": {
+                    "name": { "__faker": "person.fullName" },
+                    "email": { "__faker": "internet.email" },
+                    "phone": { "__faker": "phone.number" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/examples/orders-and-matches.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../mockserve.spec.schema.json",
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" }
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/orders",
+      "match": { "query": { "status": "pending" } },
+      "response": {
+        "status": "{{query.status}}",
+        "orders": {
+          "__repeat": {
+            "min": 5,
+            "max": 8,
+            "template": {
+              "id": { "__faker": "string.uuid" },
+              "total": { "__faker": { "method": "number.int", "args": [ { "min": 20, "max": 200 } ] } },
+              "placedAt": { "__faker": { "method": "date.recent", "args": [7] } }
+            }
+          }
+        }
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/orders",
+      "status": 201,
+      "response": {
+        "id": { "__faker": "string.uuid" },
+        "priority": "{{body.priority}}",
+        "message": "Order created"
+      },
+      "variants": [
+        {
+          "name": "high priority",
+          "match": { "body": { "priority": "high" } },
+          "status": 202,
+          "response": { "queued": true, "message": "Order queued for review" }
+        }
+      ]
+    }
+  ]
+}

package/examples/users-faker.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../mockserve.spec.schema.json",
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" },
+    "fakerSeed": 123
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/users",
+      "response": {
+        "users": {
+          "__repeat": {
+            "min": 10,
+            "max": 15,
+            "template": {
+              "id": { "__faker": "string.uuid" },
+              "firstName": { "__faker": "person.firstName" },
+              "lastName": { "__faker": "person.lastName" },
+              "avatarUrl": { "__faker": "image.avatar" },
+              "phone": { "__faker": "phone.number" },
+              "email": { "__faker": "internet.email" },
+              "company": { "__faker": "company.name" },
+              "joinedAt": { "__faker": { "method": "date.recent", "args": [30] } }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/mock.spec.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "./mockserve.spec.schema.json",
   "version": 1,
   "settings": {
     "delayMs": 0,

package/mockserve.spec.schema.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/MockServeSpec",
+  "definitions": {
+    "MockServeSpec": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "api-json-server",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "",
   "main": "index.js",
   "scripts": {
     "dev": "tsx src/index.ts",
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "schema:build": "tsx scripts/build-schema.ts"
   },
   "bin": {
     "mockserve": "dist/index.js"
@@ -17,12 +20,26 @@
   "type": "commonjs",
   "devDependencies": {
     "@types/node": "^25.0.9",
+    "@types/supertest": "^6.0.3",
+    "@types/swagger-ui-dist": "^3.30.6",
+    "supertest": "^7.2.2",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17",
+    "zod-to-json-schema": "^3.25.1"
   },
   "dependencies": {
+    "@faker-js/faker": "^10.2.0",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/http-proxy": "^11.4.1",
+    "@fastify/static": "^9.0.0",
+    "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "fastify": "^5.7.1",
+    "pino-pretty": "^13.1.3",
+    "swagger-ui-dist": "^5.31.0",
+    "yaml": "^2.8.2",
     "zod": "^4.3.5"
   }
 }

package/scripts/build-schema.ts

@@ -0,0 +1,21 @@
+import { writeFile } from "node:fs/promises";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { MockSpecSchema } from "../src/spec.js";
+
+/**
+ * Build the JSON schema file from the Zod spec.
+ */
+async function main() {
+     const schema = MockSpecSchema as unknown as Parameters<typeof zodToJsonSchema>[0];
+     const jsonSchema = zodToJsonSchema(schema, {
+          name: "MockServeSpec"
+     });
+
+     await writeFile("mockserve.spec.schema.json", JSON.stringify(jsonSchema, null, 2), "utf-8");
+     console.log("Wrote mockserve.spec.schema.json");
+}
+
+main().catch((err) => {
+     console.error(err);
+     process.exit(1);
+});

package/src/behavior.ts

@@ -0,0 +1,56 @@
+import type { TemplateValue } from "./spec.js";
+import { faker } from "@faker-js/faker";
+
+export type DelayConfig = number | { min: number; max: number };
+
+export type BehaviorSettings = {
+     delayMs: number;
+     errorRate: number;
+     errorStatus: number;
+     errorResponse: TemplateValue;
+};
+
+export type BehaviorOverrides = Partial<BehaviorSettings> & {
+     delay?: DelayConfig;
+};
+
+/**
+ * Resolve a delay value from either a number or a range configuration.
+ */
+export function resolveDelay(delay?: DelayConfig): number {
+     if (!delay) return 0;
+     if (typeof delay === "number") return delay;
+     return faker.number.int({ min: delay.min, max: delay.max });
+}
+
+/**
+ * Pause for the given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+     return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Decide whether a request should fail based on an error rate.
+ */
+export function shouldFail(errorRate: number): boolean {
+     if (errorRate <= 0) return false;
+     if (errorRate >= 1) return true;
+     return Math.random() < errorRate;
+}
+
+/**
+ * Resolve behavior settings with precedence: chosen overrides -> endpoint overrides -> global settings.
+ */
+export function resolveBehavior(
+     settings: BehaviorSettings,
+     endpointOverrides?: BehaviorOverrides,
+     chosenOverrides?: BehaviorOverrides
+): BehaviorSettings {
+     return {
+          delayMs: chosenOverrides?.delayMs ?? endpointOverrides?.delayMs ?? settings.delayMs,
+          errorRate: chosenOverrides?.errorRate ?? endpointOverrides?.errorRate ?? settings.errorRate,
+          errorStatus: chosenOverrides?.errorStatus ?? endpointOverrides?.errorStatus ?? settings.errorStatus,
+          errorResponse: chosenOverrides?.errorResponse ?? endpointOverrides?.errorResponse ?? settings.errorResponse
+     };
+}

package/src/history/historyRecorder.ts

@@ -0,0 +1,77 @@
+import type { HistoryEntry, HistoryFilter } from "./types.js";
+import { randomUUID } from "node:crypto";
+
+/**
+ * In-memory request history recorder.
+ */
+export class HistoryRecorder {
+     private entries: HistoryEntry[] = [];
+     private readonly maxEntries: number;
+
+     /**
+      * Create a new history recorder.
+      * @param maxEntries Maximum number of entries to keep (default 1000).
+      */
+     constructor(maxEntries = 1000) {
+          this.maxEntries = maxEntries;
+     }
+
+     /**
+      * Record a new request.
+      */
+     record(entry: Omit<HistoryEntry, "id" | "timestamp">): HistoryEntry {
+          const fullEntry: HistoryEntry = {
+               id: randomUUID(),
+               timestamp: new Date().toISOString(),
+               ...entry
+          };
+
+          this.entries.push(fullEntry);
+
+          // Keep only the most recent entries
+          if (this.entries.length > this.maxEntries) {
+               this.entries.shift();
+          }
+
+          return fullEntry;
+     }
+
+     /**
+      * Get all history entries, optionally filtered.
+      */
+     query(filter?: HistoryFilter): HistoryEntry[] {
+          let results = this.entries;
+
+          if (filter?.endpoint) {
+               results = results.filter((e) => e.path === filter.endpoint);
+          }
+
+          if (filter?.method) {
+               results = results.filter((e) => e.method.toUpperCase() === filter.method?.toUpperCase());
+          }
+
+          if (filter?.statusCode !== undefined) {
+               results = results.filter((e) => e.statusCode === filter.statusCode);
+          }
+
+          if (filter?.limit && filter.limit > 0) {
+               results = results.slice(-filter.limit);
+          }
+
+          return results;
+     }
+
+     /**
+      * Clear all history entries.
+      */
+     clear(): void {
+          this.entries = [];
+     }
+
+     /**
+      * Get the total number of recorded entries.
+      */
+     count(): number {
+          return this.entries.length;
+     }
+}

package/src/history/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Request history entry structure.
+ */
+export interface HistoryEntry {
+     id: string;
+     timestamp: string;
+     method: string;
+     url: string;
+     path: string;
+     query: Record<string, unknown>;
+     headers: Record<string, string | string[] | undefined>;
+     body: unknown;
+     statusCode?: number;
+     responseTime?: number;
+}
+
+/**
+ * Filter options for querying history.
+ */
+export interface HistoryFilter {
+     endpoint?: string;
+     method?: string;
+     statusCode?: number;
+     limit?: number;
+}

package/src/index.ts

@@ -2,6 +2,8 @@
 
 import { Command } from "commander";
 import { watch } from "node:fs";
+import { createLogger, logServerStart, logServerReload } from "./logger/customLogger.js";
+import type { LoggerOptions } from "./logger/types.js";
 
 const program = new Command();
 
@@ -17,106 +19,143 @@ program
      .option("-s, --spec <path>", "Path to the spec JSON file", "mock.spec.json")
      .option("--watch", "Reload when spec file changes", true)
      .option("--no-watch", "Disable reload when spec file changes")
-     .action(async (opts: { port: string; spec: string, watch: boolean }) => {
-          const port = Number(opts.port);
-
-          if (!Number.isFinite(port) || port <= 0) {
-               console.error(`Invalid port: ${opts.port}`);
-               process.exit(1);
-          }
-
-          const specPath = opts.spec;
-
-          const { loadSpecFromFile } = await import("./loadSpec.js");
-          const { buildServer } = await import("./server.js");
+     .option("--base-url <url>", "Public base URL used in OpenAPI servers[] (e.g. https://example.com)")
+     .option("--log-format <format>", "Log format: pretty or json", "pretty")
+     .option("--log-level <level>", "Log level: trace, debug, info, warn, error, fatal", "info")
+     .action(async (opts: { port: string; spec: string; watch: boolean; baseUrl?: string; logFormat: string; logLevel: string }) => {
+          await startCommand(opts);
+     });
 
-          let app = null as null | import("fastify").FastifyInstance;
-          let isReloading = false;
-          let debounceTimer: NodeJS.Timeout | null = null;
+/**
+ * Run the mock server CLI command.
+ */
+async function startCommand(opts: { port: string; spec: string; watch: boolean; baseUrl?: string; logFormat: string; logLevel: string }): Promise<void> {
+     const port = Number(opts.port);
+
+     if (!Number.isFinite(port) || port <= 0) {
+          console.error(`Invalid port: ${opts.port}`);
+          process.exit(1);
+     }
+
+     const specPath = opts.spec;
+
+     // Create logger based on CLI options
+     const logFormat = opts.logFormat === "json" ? "json" : "pretty";
+     const logLevel = ["trace", "debug", "info", "warn", "error", "fatal"].includes(opts.logLevel)
+          ? opts.logLevel as LoggerOptions["level"]
+          : "info";
+
+     const logger = createLogger({
+          enabled: true,
+          format: logFormat,
+          level: logLevel
+     });
 
-          async function startWithSpec() {
-               const loadedAt = new Date().toISOString();
+     const { loadSpecFromFile } = await import("./loadSpec.js");
+     const { buildServer } = await import("./server.js");
 
-               const spec = await loadSpecFromFile(specPath);
-               console.log(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
+     let app = null as null | import("fastify").FastifyInstance;
+     let isReloading = false;
+     let debounceTimer: NodeJS.Timeout | null = null;
 
-               const nextApp = buildServer(spec, { specPath, loadedAt });
-               try {
-                    await nextApp.listen({ port, host: "0.0.0.0" });
-               } catch (err) {
-                    nextApp.log.error(err);
-                    throw err;
-               }
+     /**
+      * Build and start a server using the current spec file.
+      */
+     async function startWithSpec() {
+          const loadedAt = new Date().toISOString();
 
-               nextApp.log.info(`Mock server running on http://localhost:${port}`);
-               nextApp.log.info(`Spec: ${specPath} (loadedAt=${loadedAt})`);
+          const spec = await loadSpecFromFile(specPath);
+          logger.info(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
 
-               return nextApp;
+          const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl, logger: true });
+          try {
+               await nextApp.listen({ port, host: "0.0.0.0" });
+          } catch (err) {
+               nextApp.log.error(err);
+               throw err;
           }
 
-          async function reload() {
-               if (isReloading) return;
-               isReloading = true;
+          logServerStart(nextApp.log, port, specPath);
 
-               try {
-                    console.log("Reloading spec...");
-
-                    // 1) Stop accepting requests on the old server FIRST
-                    if (app) {
-                         console.log("Closing current server...");
-                         await app.close();
-                         console.log("Current server closed.");
-                         app = null;
-                    }
+          return nextApp;
+     }
 
-                    // 2) Start a new server on the same port with the updated spec
-                    app = await startWithSpec();
-
-                    console.log("Reload complete.");
-               } catch (err) {
-                    console.error("Reload failed.");
-
-                    // At this point the old server may already be closed. We want visibility.
-                    console.error(String(err));
-
-                    // Optional: try to start again to avoid being down
-                    try {
-                         if (!app) {
-                              console.log("Attempting to start server again after reload failure...");
-                              app = await startWithSpec();
-                              console.log("Recovery start succeeded.");
-                         }
-                    } catch (err2) {
-                         console.error("Recovery start failed. Server is down until next successful reload.");
-                         console.error(String(err2));
-                    }
-               } finally {
-                    isReloading = false;
-               }
-          }
+     /**
+      * Reload the server when the spec changes.
+      */
+     async function reload() {
+          if (isReloading) return;
+          isReloading = true;
 
-          // Initial start
           try {
+               logger.info("Reloading spec...");
+
+               // 1) Stop accepting requests on the old server FIRST
+               if (app) {
+                    logger.debug("Closing current server...");
+                    await app.close();
+                    logger.debug("Current server closed.");
+                    app = null;
+               }
+
+               // 2) Start a new server on the same port with the updated spec
                app = await startWithSpec();
+
+               logServerReload(logger, true);
           } catch (err) {
-               console.error(String(err));
-               process.exit(1);
-          }
+               const errorMsg = err instanceof Error ? err.message : String(err);
+               logServerReload(logger, false, errorMsg);
 
-          // Watch spec for changes
-          if (opts.watch) {
-               console.log(`Watching spec file for changes: ${specPath}`);
-
-               // fs.watch emits multiple events; debounce to avoid rapid reload loops
-               watch(specPath, () => {
-                    if (debounceTimer) clearTimeout(debounceTimer);
-                    debounceTimer = setTimeout(() => {
-                         void reload();
-                    }, 200);
-               });
-          } else {
-               console.log("Watch disabled (--no-watch).");
+               // Optional: try to start again to avoid being down
+               try {
+                    if (!app) {
+                         logger.info("Attempting to start server again after reload failure...");
+                         app = await startWithSpec();
+                         logger.info("Recovery start succeeded.");
+                    }
+               } catch (err2) {
+                    logger.error("Recovery start failed. Server is down until next successful reload.");
+                    logger.error(err2);
+               }
+          } finally {
+               isReloading = false;
           }
-     });
+     }
+
+     // Initial start
+     try {
+          app = await startWithSpec();
+     } catch (err) {
+          logger.error(err);
+          process.exit(1);
+     }
+
+     // Watch spec for changes
+     /**
+      * Handle file changes with a debounced reload.
+      */
+     function onSpecChange(): void {
+          debounceTimer = scheduleReload(reload, debounceTimer);
+     }
+
+     if (opts.watch) {
+          logger.info(`Watching spec file for changes: ${specPath}`);
+
+          // fs.watch emits multiple events; debounce to avoid rapid reload loops
+          watch(specPath, onSpecChange);
+     } else {
+          logger.info("Watch disabled (--no-watch).");
+     }
+}
+
+/**
+ * Schedule a debounced reload when the spec changes.
+ */
+function scheduleReload(reload: () => Promise<void>, debounceTimer: NodeJS.Timeout | null): NodeJS.Timeout {
+     if (debounceTimer) clearTimeout(debounceTimer);
+     return setTimeout(() => {
+          void reload();
+     }, 200);
+}
 
 program.parse(process.argv);

package/src/loadSpec.ts

@@ -1,6 +1,9 @@
-import { readFile } from 'node:fs/promises'
-import { MockSpecSchema, type MockSpecInferSchema } from './spec.js'
+import { readFile } from "node:fs/promises";
+import { MockSpecSchema, type MockSpecInferSchema } from "./spec.js";
 
+/**
+ * Load and validate a mock spec from disk.
+ */
 export async function loadSpecFromFile(specPath: string): Promise<MockSpecInferSchema> {
      let raw: string
      try {