api-json-server 1.0.1

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const program = new commander_1.Command();
+program
+    .name("mockserve")
+    .description("A simple API Mock Server driven by a JSON spec file.")
+    .version("0.1.0");
+program
+    .command("serve")
+    .description("Start the mock server.")
+    .option("-p, --port <number>", "Port to run the server on", "3000")
+    .option("-s, --spec <path>", "Path to the spec JSON file", "mock.spec.json")
+    .action((opts) => {
+    console.log("mockserve serve called with:");
+    console.log(`- port: ${opts.port}`);
+    console.log(`- spec: ${opts.spec}`);
+    console.log("Server not implemented yet.");
+});
+program.parse(process.argv);

package/mock.spec.json

@@ -0,0 +1,65 @@
+{
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 503,
+    "errorResponse": { "error": "Service temporarily unavailable" }
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/users/:id",
+      "status": 200,
+      "response": {
+        "id": "{{params.id}}",
+        "type": "{{query.type}}",
+        "message": "User lookup ok"
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/search",
+      "status": 200,
+      "match": { "query": { "type": "premium" } },
+      "response": {
+        "ok": true,
+        "filter": "{{query.type}}",
+        "results": [
+          { "id": "u1", "tier": "premium" },
+          { "id": "u2", "tier": "premium" }
+        ]
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/echo",
+      "status": 201,
+      "response": {
+        "receivedEmail": "{{body.email}}",
+        "receivedName": "{{body.name}}",
+        "rawBody": "{{body}}"
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/login",
+      "status": 200,
+      "response": { "ok": true, "message": "Default login response" },
+      "variants": [
+        {
+          "name": "invalid password",
+          "match": { "body": { "password": "wrong" } },
+          "status": 401,
+          "response": { "ok": false, "error": "Invalid credentials" }
+        },
+        {
+          "name": "admin login",
+          "match": { "body": { "email": "admin@example.com" } },
+          "status": 200,
+          "response": { "ok": true, "role": "admin", "token": "tok_{{body.email}}" }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "api-json-server",
+  "version": "1.0.1",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "bin": {
+    "mockserve": "dist/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "fastify": "^5.7.1",
+    "zod": "^4.3.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { watch } from "node:fs";
+
+const program = new Command();
+
+program
+     .name("mockserve")
+     .description("A simple API Mock Server driven by a JSON spec file.")
+     .version("0.1.0");
+
+program
+     .command("serve")
+     .description("Start the mock server.")
+     .option("-p, --port <number>", "Port to run the server on", "3000")
+     .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");
+
+          let app = null as null | import("fastify").FastifyInstance;
+          let isReloading = false;
+          let debounceTimer: NodeJS.Timeout | null = null;
+
+          async function startWithSpec() {
+               const loadedAt = new Date().toISOString();
+
+               const spec = await loadSpecFromFile(specPath);
+               console.log(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
+
+               const nextApp = buildServer(spec, { specPath, loadedAt });
+               try {
+                    await nextApp.listen({ port, host: "0.0.0.0" });
+               } catch (err) {
+                    nextApp.log.error(err);
+                    throw err;
+               }
+
+               nextApp.log.info(`Mock server running on http://localhost:${port}`);
+               nextApp.log.info(`Spec: ${specPath} (loadedAt=${loadedAt})`);
+
+               return nextApp;
+          }
+
+          async function reload() {
+               if (isReloading) return;
+               isReloading = true;
+
+               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));
+
+                    // 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
+          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).");
+          }
+     });
+
+program.parse(process.argv);

package/src/loadSpec.ts

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises'
+import { MockSpecSchema, type MockSpecInferSchema } from './spec.js'
+
+export async function loadSpecFromFile(specPath: string): Promise<MockSpecInferSchema> {
+     let raw: string
+     try {
+          raw = await readFile(specPath, 'utf-8')
+     } catch (err) {
+          throw new Error(`Failed to read spec file ${specPath}: ${err instanceof Error ? err.message : String(err)}`)
+     }
+
+     let json: unknown
+     try {
+          json = JSON.parse(raw)
+     } catch (err) {
+          throw new Error(`Failed to parse spec file ${specPath}: ${err instanceof Error ? err.message : String(err)}`)
+     }
+
+     const parsed = MockSpecSchema.safeParse(json)
+     if (!parsed.success) {
+          const issues = parsed.error.issues
+               .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`)
+               .join("\n")
+          throw new Error(`Invalid spec file ${specPath}: ${issues}`)
+     }
+
+     return parsed.data
+}

package/src/registerEndpoints.ts

@@ -0,0 +1,183 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify'
+import type { MockSpecInferSchema, EndpointSpecInferSchema } from './spec.js'
+import { renderTemplate } from './template.js';
+
+
+function normalizeMethod(method: EndpointSpecInferSchema["method"]): Lowercase<EndpointSpecInferSchema["method"]> {
+     return method.toLowerCase() as Lowercase<EndpointSpecInferSchema["method"]>;
+}
+
+function sleep(ms: number): Promise<void> {
+     return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function shouldFail(errorRate: number): boolean {
+     if (errorRate <= 0) return false;
+     if (errorRate >= 1) return true;
+     return Math.random() < errorRate;
+}
+
+
+function resolveBehavior(spec: MockSpecInferSchema, endpoint: EndpointSpecInferSchema) {
+     const settings = spec.settings;
+
+     const delayMs = endpoint.delayMs ?? settings.delayMs;
+     const errorRate = endpoint.errorRate ?? settings.errorRate;
+
+     const errorStatus = endpoint.errorStatus ?? settings.errorStatus;
+     const errorResponse = endpoint.errorResponse ?? settings.errorResponse;
+
+     return { delayMs, errorRate, errorStatus, errorResponse };
+}
+
+
+function asRecord(value: unknown): Record<string, unknown> {
+     if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+     return {};
+}
+
+function queryMatches(req: FastifyRequest, endpoint: EndpointSpecInferSchema): boolean {
+     const required = endpoint.match?.query;
+     if (!required) return true;
+
+     const q = asRecord(req.query);
+
+     for (const [key, expected] of Object.entries(required)) {
+          const actual = q[key];
+
+          if (Array.isArray(actual)) return false;
+
+          if (String(actual ?? "") !== String(expected)) return false;
+     }
+
+     return true;
+}
+
+function bodyMatches(req: FastifyRequest, expected?: Record<string, string | number | boolean>): boolean {
+     if (!expected) return true;
+
+     const b = req.body;
+     if (!b || typeof b !== "object" || Array.isArray(b)) return false;
+
+     const body = b as Record<string, unknown>;
+
+     for (const [key, exp] of Object.entries(expected)) {
+          const actual = body[key];
+          if (String(actual ?? "") !== String(exp)) return false;
+     }
+     return true;
+}
+
+function matchRequest(req: FastifyRequest, match?: { query?: Record<string, any>; body?: Record<string, any> }): boolean {
+     if (!match) return true;
+
+     // query exact match
+     const requiredQuery = match.query;
+     if (requiredQuery) {
+          const q = asRecord(req.query);
+          for (const [key, expected] of Object.entries(requiredQuery)) {
+               const actual = q[key];
+               if (Array.isArray(actual)) return false;
+               if (String(actual ?? "") !== String(expected)) return false;
+          }
+     }
+
+     // body exact match (top-level)
+     if (!bodyMatches(req, match.body)) return false;
+
+     return true;
+}
+
+
+export function registerEndpoints(app: FastifyInstance, spec: MockSpecInferSchema): void {
+     for (const endpoint of spec.endpoints) {
+          app.route({
+               method: endpoint.method,
+               url: endpoint.path,
+               handler: async (req, reply) => {
+                    // Decide which "response source" to use: variant or base endpoint
+                    let chosen:
+                         | {
+                              status?: number;
+                              response: unknown;
+                              delayMs?: number;
+                              errorRate?: number;
+                              errorStatus?: number;
+                              errorResponse?: unknown;
+                         }
+                         | null = null;
+
+                    // 1) Try variants first (first match wins)
+                    if (endpoint.variants && endpoint.variants.length > 0) {
+                         for (const v of endpoint.variants) {
+                              if (matchRequest(req, v.match)) {
+                                   chosen = {
+                                        status: v.status,
+                                        response: v.response,
+                                        delayMs: v.delayMs,
+                                        errorRate: v.errorRate,
+                                        errorStatus: v.errorStatus,
+                                        errorResponse: v.errorResponse
+                                   };
+                                   break;
+                              }
+                         }
+                    }
+
+                    // 2) If no variant matched, fall back to endpoint-level match/response
+                    if (!chosen) {
+                         // Backward compatible: if your endpoint only has query match, this still works
+                         // If you've upgraded schema to endpoint.match (query/body), this uses it
+                         // If you haven't, you can replace endpoint.match with: { query: endpoint.match?.query }
+                         const endpointMatch = (endpoint as any).match ?? { query: (endpoint as any).match?.query };
+
+                         if (!matchRequest(req, endpointMatch)) {
+                              reply.code(404);
+                              return { error: "No matching mock for request" };
+                         }
+
+                         chosen = {
+                              status: endpoint.status,
+                              response: endpoint.response,
+                              delayMs: (endpoint as any).delayMs,
+                              errorRate: (endpoint as any).errorRate,
+                              errorStatus: (endpoint as any).errorStatus,
+                              errorResponse: (endpoint as any).errorResponse
+                         };
+                    }
+
+                    // 3) Resolve behavior: chosen overrides -> endpoint -> global settings
+                    const settings = spec.settings;
+
+                    const delayMs = chosen.delayMs ?? (endpoint as any).delayMs ?? settings.delayMs;
+                    const errorRate = chosen.errorRate ?? (endpoint as any).errorRate ?? settings.errorRate;
+                    const errorStatus = chosen.errorStatus ?? (endpoint as any).errorStatus ?? settings.errorStatus;
+                    const errorResponse = chosen.errorResponse ?? (endpoint as any).errorResponse ?? settings.errorResponse;
+
+                    if (delayMs > 0) {
+                         await sleep(delayMs);
+                    }
+
+                    if (shouldFail(errorRate)) {
+                         reply.code(errorStatus);
+                         return errorResponse;
+                    }
+
+                    // 4) Template rendering using request context
+                    const params = asRecord(req.params);
+                    const query = asRecord(req.query);
+                    const body = req.body;
+
+                    const rendered = renderTemplate(chosen.response, { params, query, body });
+
+                    // 5) Status code precedence: chosen -> endpoint -> 200
+                    reply.code(chosen.status ?? endpoint.status ?? 200);
+                    return rendered;
+               }
+          });
+
+          app.log.info(
+               `Registered ${endpoint.method} ${endpoint.path} -> ${endpoint.status} (delay=${endpoint.delayMs ?? spec.settings.delayMs}ms, errorRate=${endpoint.errorRate ?? spec.settings.errorRate})`
+          );
+     }
+}

package/src/server.ts

@@ -0,0 +1,29 @@
+import Fastify, { FastifyInstance } from "fastify";
+import { MockSpecInferSchema } from "./spec.js";
+import { registerEndpoints } from "./registerEndpoints.js";
+
+export function buildServer(spec: MockSpecInferSchema, meta?: { specPath?: string; loadedAt?: string }): FastifyInstance {
+     const app = Fastify({
+          logger: true
+     });
+
+     // Basic sanity route
+     app.get("/health", async () => {
+          return { ok: true };
+     });
+
+     // Internal inspection endpoint
+     app.get("/__spec", async () => {
+          return {
+               meta: {
+                    specPath: meta?.specPath ?? null,
+                    loadedAt: meta?.loadedAt ?? null
+               },
+               spec
+          };
+     });
+
+     registerEndpoints(app, spec);
+
+     return app;
+}

package/src/spec.ts

@@ -0,0 +1,58 @@
+import * as z from 'zod'
+
+const Primitive = z.union([z.string(), z.number(), z.boolean()]);
+
+export const MatchSchema = z.object({
+     query: z.record(z.string(), Primitive).optional(),
+     // Exact match for top-level body fields only (keeps v1 simple)
+     body: z.record(z.string(), Primitive).optional()
+});
+
+export const VariantSchema = z.object({
+     name: z.string().min(1).optional(),
+     match: MatchSchema.optional(),
+
+     status: z.number().int().min(100).max(599).optional(),
+     response: z.unknown(),
+
+     // Simulation overrides per variant (optional)
+     delayMs: z.number().int().min(0).optional(),
+     errorRate: z.number().min(0).max(1).optional(),
+     errorStatus: z.number().int().min(100).max(599).optional(),
+     errorResponse: z.unknown().optional()
+});
+
+export const EndpointSchema = z.object({
+     method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
+     path: z.string().min(1),
+
+     match: MatchSchema.optional(),
+     variants: z.array(VariantSchema).min(1).optional(),
+
+     // Response behavior:
+     status: z.number().int().min(200).max(599).default(200),
+     response: z.unknown(),
+
+     // Simulation (optional overrides)
+     delayMs: z.number().int().min(0).optional(),
+     errorRate: z.number().min(0).max(1).optional(),
+     errorStatus: z.number().int().min(100).max(599).optional(),
+     errorResponse: z.unknown().optional()
+})
+
+export const MockSpecSchema = z.object({
+     version: z.literal(1),
+     settings: z
+          .object({
+               delayMs: z.number().int().min(0).default(0),
+               errorRate: z.number().min(0).max(1).default(0),
+               errorStatus: z.number().int().min(100).max(599).default(500),
+               errorResponse: z.unknown().default({ error: "Mock error" })
+          })
+          .default({ delayMs: 0, errorRate: 0, errorStatus: 500, errorResponse: { error: "Mock error" } }),
+     endpoints: z.array(EndpointSchema).min(1)
+})
+
+export type MockSpecInferSchema = z.infer<typeof MockSpecSchema>;
+export type EndpointSpecInferSchema = z.infer<typeof EndpointSchema>;
+export type VariantSpecInferSchema = z.infer<typeof VariantSchema>;

package/src/template.ts

@@ -0,0 +1,61 @@
+type TemplateContext = {
+     params: Record<string, unknown>;
+     query: Record<string, unknown>;
+     body: unknown;
+};
+
+function getPath(obj: unknown, path: string): unknown {
+     if (!path) return undefined;
+
+     const parts = path.split(".");
+     let cur: any = obj;
+
+     for (const p of parts) {
+          if (cur == null) return undefined;
+          cur = cur[p];
+     }
+     return cur;
+}
+
+function renderStringTemplate(input: string, ctx: TemplateContext): string {
+     // Replaces occurrences like {{params.id}} or {{query.type}} or {{body.email}}
+     return input.replace(/\{\{\s*([a-zA-Z]+)\.([a-zA-Z0-9_.]+)\s*\}\}/g, (_m, root, path) => {
+          let source: unknown;
+          if (root === "params") source = ctx.params;
+          else if (root === "query") source = ctx.query;
+          else if (root === "body") source = ctx.body;
+          else return "";
+
+          const value = root === "body" ? getPath(source, path) : getPath(source, path);
+
+          if (value === undefined || value === null) return "";
+          if (typeof value === "string") return value;
+          if (typeof value === "number" || typeof value === "boolean") return String(value);
+
+          // For objects/arrays, stringify to keep output valid (still a string substitution)
+          try {
+               return JSON.stringify(value);
+          } catch {
+               return "";
+          }
+     });
+}
+
+export function renderTemplate(value: unknown, ctx: TemplateContext): unknown {
+     if (typeof value === "string") return renderStringTemplate(value, ctx);
+
+     if (Array.isArray(value)) {
+          return value.map((v) => renderTemplate(v, ctx));
+     }
+
+     if (value && typeof value === "object") {
+          const out: Record<string, unknown> = {};
+          for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+               out[k] = renderTemplate(v, ctx);
+          }
+          return out;
+     }
+
+     // numbers, booleans, null, undefined stay as-is
+     return value;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}