api-json-server 1.0.1 → 1.1.0

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.1.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,21 @@
   "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/static": "^9.0.0",
     "commander": "^14.0.2",
     "fastify": "^5.7.1",
+    "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,42 @@
+import type { TemplateValue } from "./spec.js";
+
+export type BehaviorSettings = {
+     delayMs: number;
+     errorRate: number;
+     errorStatus: number;
+     errorResponse: TemplateValue;
+};
+
+export type BehaviorOverrides = Partial<BehaviorSettings>;
+
+/**
+ * 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/index.ts

@@ -17,106 +17,132 @@ 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);
-          }
+     .option("--base-url <url>", "Public base URL used in OpenAPI servers[] (e.g. https://example.com)")
+     .action(async (opts: { port: string; spec: string; watch: boolean; baseUrl?: string }) => {
+          await startCommand(opts);
+     });
 
-          const specPath = opts.spec;
+/**
+ * Run the mock server CLI command.
+ */
+async function startCommand(opts: { port: string; spec: string; watch: boolean; baseUrl?: string }): Promise<void> {
+     const port = Number(opts.port);
 
-          const { loadSpecFromFile } = await import("./loadSpec.js");
-          const { buildServer } = await import("./server.js");
+     if (!Number.isFinite(port) || port <= 0) {
+          console.error(`Invalid port: ${opts.port}`);
+          process.exit(1);
+     }
 
-          let app = null as null | import("fastify").FastifyInstance;
-          let isReloading = false;
-          let debounceTimer: NodeJS.Timeout | null = null;
+     const specPath = opts.spec;
 
-          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);
+          console.log(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
 
-               return nextApp;
+          const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl });
+          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;
+          nextApp.log.info(`Mock server running on http://localhost:${port}`);
+          nextApp.log.info(`Spec: ${specPath} (loadedAt=${loadedAt})`);
 
-               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 {
+               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;
+               }
+
+               // 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));
-               process.exit(1);
-          }
 
-          // 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) {
+                         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;
           }
-     });
+     }
+
+     // Initial start
+     try {
+          app = await startWithSpec();
+     } catch (err) {
+          console.error(String(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) {
+          console.log(`Watching spec file for changes: ${specPath}`);
+
+          // fs.watch emits multiple events; debounce to avoid rapid reload loops
+          watch(specPath, onSpecChange);
+     } else {
+          console.log("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 {

package/src/openapi.ts

@@ -0,0 +1,203 @@
+import type { MockSpecInferSchema } from "./spec.js";
+
+type OpenApiParameter = {
+     name: string;
+     in: "path" | "query";
+     required: boolean;
+     schema: Record<string, unknown>;
+     description?: string;
+};
+
+type OpenApiRequestBody = {
+     required: boolean;
+     content: Record<string, { schema: Record<string, unknown> }>;
+};
+
+type OpenApiResponse = {
+     description: string;
+     content: Record<string, { examples: Record<string, { value: unknown }> }>;
+};
+
+type OpenApiOperation = {
+     summary: string;
+     parameters?: OpenApiParameter[];
+     requestBody?: OpenApiRequestBody;
+     responses: Record<string, OpenApiResponse>;
+};
+
+type OpenApi = {
+     openapi: string;
+     info: { title: string; version: string; description: string };
+     servers: Array<{ url: string }>;
+     paths: Record<string, Record<string, OpenApiOperation>>;
+};
+
+/**
+ * Convert Fastify-style route params to OpenAPI style.
+ */
+function toOpenApiPath(fastifyPath: string): string {
+     // Fastify style: /users/:id -> OpenAPI style: /users/{id}
+     return fastifyPath.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+
+/**
+ * Extract path parameter names from a Fastify-style route.
+ */
+function extractPathParams(fastifyPath: string): string[] {
+     const matches = [...fastifyPath.matchAll(/:([A-Za-z0-9_]+)/g)];
+     return matches.map((m) => m[1]);
+}
+
+/**
+ * Deduplicate values while preserving order.
+ */
+function uniq<T>(items: T[]): T[] {
+     return [...new Set(items)];
+}
+
+/**
+ * Convert a list of values into a list of string enums.
+ */
+function asStringEnum(values: unknown[]): string[] {
+     return uniq(
+          values
+               .filter((v) => v !== undefined && v !== null)
+               .map((v) => String(v))
+     );
+}
+
+/**
+ * Generate a minimal OpenAPI document for the mock spec.
+ */
+export function generateOpenApi(spec: MockSpecInferSchema, serverUrl: string): OpenApi {
+     const paths: Record<string, Record<string, OpenApiOperation>> = {};
+
+     for (const ep of spec.endpoints) {
+          const oasPath = toOpenApiPath(ep.path);
+          const method = ep.method.toLowerCase();
+
+          const pathParams = extractPathParams(ep.path);
+
+          // Collect query match keys/values across endpoint + variants
+          const queryMatchValues: Record<string, string[]> = {};
+          const bodyMatchKeys: Set<string> = new Set();
+
+          /**
+           * Collect query match values into a set for documentation.
+           */
+          const collectQuery = (obj?: Record<string, string | number | boolean>) => {
+               if (!obj) return;
+               for (const [k, v] of Object.entries(obj)) {
+                    if (!queryMatchValues[k]) queryMatchValues[k] = [];
+                    queryMatchValues[k].push(String(v));
+               }
+          };
+
+          /**
+           * Collect body match keys for request body documentation.
+           */
+          const collectBody = (obj?: Record<string, string | number | boolean>) => {
+               if (!obj) return;
+               for (const k of Object.keys(obj)) bodyMatchKeys.add(k);
+          };
+
+          collectQuery(ep.match?.query);
+          collectBody(ep.match?.body);
+
+          if (ep.variants?.length) {
+               for (const v of ep.variants) {
+                    collectQuery(v.match?.query);
+                    collectBody(v.match?.body);
+               }
+          }
+
+          // Parameters: path params + known query keys
+          const parameters: OpenApiParameter[] = [];
+
+          for (const p of pathParams) {
+               parameters.push({
+                    name: p,
+                    in: "path",
+                    required: true,
+                    schema: { type: "string" }
+               });
+          }
+
+          for (const [k, vals] of Object.entries(queryMatchValues)) {
+               const enumVals = asStringEnum(vals);
+               parameters.push({
+                    name: k,
+                    in: "query",
+                    required: false,
+                    schema: enumVals.length > 0 ? { type: "string", enum: enumVals } : { type: "string" },
+                    description: "Query param used by mock matching (if configured)."
+               });
+          }
+
+          // Request body: for non-GET/DELETE, document as generic object with known keys (from match rules)
+          const hasRequestBody = ep.method !== "GET" && ep.method !== "DELETE";
+          const requestBody: OpenApiRequestBody | undefined =
+               hasRequestBody && bodyMatchKeys.size > 0
+                    ? {
+                         required: false,
+                         content: {
+                              "application/json": {
+                                   schema: {
+                                        type: "object",
+                                        properties: Object.fromEntries([...bodyMatchKeys].map((k) => [k, { type: "string" }]))
+                                   }
+                              }
+                         }
+                    }
+                    : undefined;
+
+          // Responses: base + variants (grouped per status)
+          const responses: Record<string, OpenApiResponse> = {};
+
+          /**
+           * Add a response example to the OpenAPI response map.
+           */
+          const addResponseExample = (status: number, name: string, example: unknown) => {
+               const key = String(status);
+               if (!responses[key]) {
+                    responses[key] = {
+                         description: "Mock response",
+                         content: { "application/json": { examples: {} as Record<string, { value: unknown }> } }
+                    };
+               }
+               const examples = responses[key].content["application/json"].examples as Record<string, { value: unknown }>;
+               examples[name] = { value: example };
+          };
+
+          // Base response
+          addResponseExample(ep.status ?? 200, "default", ep.response);
+
+          // Variant responses
+          if (ep.variants?.length) {
+               for (const v of ep.variants) {
+                    addResponseExample(v.status ?? ep.status ?? 200, v.name ?? "variant", v.response);
+               }
+          }
+
+          const operation: OpenApiOperation = {
+               summary: `Mock ${ep.method} ${ep.path}`,
+               parameters: parameters.length ? parameters : undefined,
+               requestBody,
+               responses
+          };
+
+          if (!paths[oasPath]) paths[oasPath] = {};
+          paths[oasPath][method] = operation;
+     }
+
+     return {
+          openapi: "3.0.3",
+          info: {
+               title: "mockserve",
+               version: "0.1.0",
+               description: "OpenAPI document generated from mockserve JSON spec."
+          },
+          servers: [{ url: serverUrl }],
+          paths
+     };
+}