api-json-server 1.0.1 → 1.1.0

package/src/spec.ts

@@ -1,11 +1,72 @@
 import * as z from 'zod'
 
-const Primitive = z.union([z.string(), z.number(), z.boolean()]);
+export type Primitive = string | number | boolean;
+
+const PrimitiveSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+export interface TemplateArray extends Array<TemplateValue> {}
+
+export interface TemplateObject {
+     [key: string]: TemplateValue;
+}
+
+export type FakerTemplate = {
+     __faker: string | { method: string; args?: TemplateValue[] };
+};
+
+export type RepeatTemplate = {
+     __repeat: {
+          min?: number;
+          max?: number;
+          count?: number;
+          template: TemplateValue;
+     };
+};
+
+export type TemplateValue =
+     | Primitive
+     | null
+     | TemplateArray
+     | TemplateObject
+     | FakerTemplate
+     | RepeatTemplate;
+
+const TemplateValueSchema: z.ZodType<TemplateValue> = z.lazy(() =>
+     z.union([
+          PrimitiveSchema,
+          z.null(),
+          z.array(TemplateValueSchema),
+          z.object({ __faker: z.string().min(1) }).strict(),
+          z
+               .object({
+                    __faker: z
+                         .object({
+                              method: z.string().min(1),
+                              args: z.array(TemplateValueSchema).optional()
+                         })
+                         .strict()
+               })
+               .strict(),
+          z
+               .object({
+                    __repeat: z
+                         .object({
+                                       min: z.number().int().min(0).optional(),
+                              max: z.number().int().min(0).optional(),
+                              count: z.number().int().min(0).optional(),
+                              template: TemplateValueSchema
+                         })
+                         .strict()
+               })
+               .strict(),
+          z.record(z.string(), TemplateValueSchema)
+     ])
+);
 
 export const MatchSchema = z.object({
-     query: z.record(z.string(), Primitive).optional(),
+     query: z.record(z.string(), PrimitiveSchema).optional(),
      // Exact match for top-level body fields only (keeps v1 simple)
-     body: z.record(z.string(), Primitive).optional()
+     body: z.record(z.string(), PrimitiveSchema).optional()
 });
 
 export const VariantSchema = z.object({
@@ -13,13 +74,13 @@ export const VariantSchema = z.object({
      match: MatchSchema.optional(),
 
      status: z.number().int().min(100).max(599).optional(),
-     response: z.unknown(),
+     response: TemplateValueSchema,
 
      // 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()
+     errorResponse: TemplateValueSchema.optional()
 });
 
 export const EndpointSchema = z.object({
@@ -31,13 +92,13 @@ export const EndpointSchema = z.object({
 
      // Response behavior:
      status: z.number().int().min(200).max(599).default(200),
-     response: z.unknown(),
+     response: TemplateValueSchema,
 
      // 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()
+     errorResponse: TemplateValueSchema.optional()
 })
 
 export const MockSpecSchema = z.object({
@@ -47,7 +108,8 @@ export const MockSpecSchema = 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" })
+               errorResponse: TemplateValueSchema.default({ error: "Mock error" }),
+               fakerSeed: z.number().int().min(0).optional()
           })
           .default({ delayMs: 0, errorRate: 0, errorStatus: 500, errorResponse: { error: "Mock error" } }),
      endpoints: z.array(EndpointSchema).min(1)

package/src/stringTemplate.ts

@@ -0,0 +1,55 @@
+export type TemplateContext = {
+     params: Record<string, unknown>;
+     query: Record<string, unknown>;
+     body: unknown;
+};
+
+/**
+ * Safely read a nested property from an object using a dot path.
+ */
+export function getPathValue(obj: unknown, path: string): unknown {
+     if (!path) return undefined;
+
+     const parts = path.split(".");
+     let current: unknown = obj;
+
+     for (const part of parts) {
+          if (current === null || current === undefined) return undefined;
+          if (typeof current !== "object") return undefined;
+
+          const record = current as Record<string, unknown>;
+          current = record[part];
+     }
+
+     return current;
+}
+
+/**
+ * Render string templates like {{params.id}}, {{query.type}}, {{body.email}}.
+ */
+export function renderStringTemplate(input: string, ctx: TemplateContext): string {
+     /**
+      * Replace a single template token with its resolved value.
+      */
+     function replaceToken(_match: string, root: string, path: string): string {
+          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 = getPathValue(source, path);
+
+          if (value === undefined || value === null) return "";
+          if (typeof value === "string") return value;
+          if (typeof value === "number" || typeof value === "boolean") return String(value);
+
+          try {
+               return JSON.stringify(value);
+          } catch {
+               return "";
+          }
+     }
+
+     return input.replace(/\{\{\s*([a-zA-Z]+)\.([a-zA-Z0-9_.]+)\s*\}\}/g, replaceToken);
+}

package/tests/behavior.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("behavior settings", () => {
+     it("uses error response when errorRate is 1", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, errorRate: 1 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/always-fail",
+                         response: { ok: true },
+                         errorStatus: 503,
+                         errorResponse: { message: "Service down" }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/always-fail" });
+          expect(res.statusCode).toBe(503);
+          expect(res.json()).toEqual({ message: "Service down" });
+
+          await app.close();
+     });
+
+     it("renders templates in error responses", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, errorRate: 1 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/users/:id",
+                         response: { ok: true },
+                         errorStatus: 400,
+                         errorResponse: { message: "User {{params.id}} missing" }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/users/55" });
+          expect(res.statusCode).toBe(400);
+          expect(res.json()).toEqual({ message: "User 55 missing" });
+
+          await app.close();
+     });
+
+     it("uses variant-level status codes", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/login",
+                         response: { ok: true },
+                         variants: [
+                              {
+                                   name: "unauthorized",
+                                   match: { body: { password: "wrong" } },
+                                   status: 401,
+                                   response: { ok: false }
+                              }
+                         ]
+                    }
+               ]
+          });
+
+          const res = await app.inject({
+               method: "POST",
+               url: "/login",
+               payload: { password: "wrong" }
+          });
+
+          expect(res.statusCode).toBe(401);
+          expect(res.json()).toEqual({ ok: false });
+
+          await app.close();
+     });
+});

package/tests/faker.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("faker templates", () => {
+     it("generates deterministic faker data when fakerSeed is set", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, fakerSeed: 123 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/profile",
+                         response: {
+                              firstName: { __faker: "person.firstName" },
+                              lastName: { __faker: "person.lastName" },
+                              email: { __faker: "internet.email" }
+                         }
+                    }
+               ]
+          });
+
+          const res1 = await app.inject({ method: "GET", url: "/profile" });
+          const res2 = await app.inject({ method: "GET", url: "/profile" });
+
+          expect(res1.statusCode).toBe(200);
+          expect(res2.statusCode).toBe(200);
+          expect(res1.json()).toEqual(res2.json());
+
+          await app.close();
+     });
+
+     it("supports faker methods with arguments", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, fakerSeed: 7 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/token",
+                         response: {
+                              token: { __faker: { method: "string.alpha", args: [16] } }
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/token" });
+          const body = res.json();
+
+          expect(res.statusCode).toBe(200);
+          expect(typeof body.token).toBe("string");
+          expect(body.token).toHaveLength(16);
+
+          await app.close();
+     });
+
+     it("renders repeat directives with a min/max range", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, fakerSeed: 55 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/users",
+                         response: {
+                              users: {
+                                   __repeat: {
+                                        min: 10,
+                                        max: 15,
+                                        template: {
+                                             id: { __faker: "string.uuid" },
+                                             firstName: { __faker: "person.firstName" },
+                                             email: { __faker: "internet.email" }
+                                        }
+                                   }
+                              }
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/users" });
+          const body = res.json();
+
+          expect(res.statusCode).toBe(200);
+          expect(Array.isArray(body.users)).toBe(true);
+          expect(body.users.length).toBeGreaterThanOrEqual(10);
+          expect(body.users.length).toBeLessThanOrEqual(15);
+          expect(typeof body.users[0].firstName).toBe("string");
+
+          await app.close();
+     });
+
+     it("renders repeat directives with a fixed count", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: { ...baseSettings, fakerSeed: 1 },
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/companies",
+                         response: {
+                              companies: {
+                                   __repeat: {
+                                        count: 3,
+                                        min: 0,
+                                        template: {
+                                             name: { __faker: "company.name" },
+                                             phone: { __faker: "phone.number" }
+                                        }
+                                   }
+                              }
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/companies" });
+          const body = res.json();
+
+          expect(res.statusCode).toBe(200);
+          expect(body.companies).toHaveLength(3);
+
+          await app.close();
+     });
+
+     it("returns 500 when faker method is invalid", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/bad",
+                         response: { value: { __faker: "nope.method" } }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/bad" });
+          expect(res.statusCode).toBe(500);
+
+          await app.close();
+     });
+
+     it("returns 500 when repeat max is below min", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/bad-repeat",
+                         response: {
+                              items: {
+                                   __repeat: { min: 5, max: 2, template: { id: 1 } }
+                              }
+                         }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/bad-repeat" });
+          expect(res.statusCode).toBe(500);
+
+          await app.close();
+     });
+});

package/tests/fixtures/spec.basic.json

@@ -0,0 +1,39 @@
+{
+     "version": 1,
+     "settings": {
+       "delayMs": 0,
+       "errorRate": 0,
+       "errorStatus": 500,
+       "errorResponse": { "error": "Mock error" }
+     },
+     "endpoints": [
+       {
+         "method": "GET",
+         "path": "/users/:id",
+         "status": 200,
+         "response": { "id": "{{params.id}}", "type": "{{query.type}}"}
+       },
+       {
+         "method": "GET",
+         "path": "/search",
+         "status": 200,
+         "match": { "query": { "type": "premium" } },
+         "response": { "ok": true, "tier": "premium" }
+       },
+       {
+         "method": "POST",
+         "path": "/login",
+         "status": 200,
+         "response": { "ok": true, "message": "default" },
+         "variants": [
+           {
+             "name": "wrong password",
+             "match": { "body": { "password": "wrong" } },
+             "status": 401,
+             "response": { "ok": false, "error": "Invalid credentials" }
+           }
+         ]
+       }
+     ]
+   }
+   

package/tests/helpers.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import type { FastifyInstance } from "fastify";
+import { buildServer } from "../src/server.js";
+import { MockSpecSchema, type MockSpecInferSchema } from "../src/spec.js";
+
+/**
+ * Load and validate a fixture spec file.
+ */
+export async function loadFixture(path: string): Promise<MockSpecInferSchema> {
+     const raw = await readFile(path, "utf-8");
+     const json = JSON.parse(raw) as unknown;
+     return MockSpecSchema.parse(json);
+}
+
+/**
+ * Build a Fastify instance from a fixture spec file.
+ */
+export async function buildTestServerFromFixture(path: string): Promise<FastifyInstance> {
+     const spec = await loadFixture(path);
+     return buildServer(spec, { specPath: path, loadedAt: "now" });
+}
+
+/**
+ * Build a Fastify instance from an in-memory spec object.
+ */
+export function buildTestServer(spec: MockSpecInferSchema): FastifyInstance {
+     return buildServer(spec, { specPath: "inline", loadedAt: "now" });
+}

package/tests/matching.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest";
+import { buildTestServer } from "./helpers.js";
+
+const baseSettings = {
+     delayMs: 0,
+     errorRate: 0,
+     errorStatus: 500,
+     errorResponse: { error: "Mock error" }
+};
+
+describe("matching rules", () => {
+     it("returns 404 when endpoint-level query match fails", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/search",
+                         match: { query: { type: "premium" } },
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/search?type=basic" });
+          expect(res.statusCode).toBe(404);
+
+          await app.close();
+     });
+
+     it("matches endpoint-level body rules for POST", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/login",
+                         match: { body: { password: "secret" } },
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          const ok = await app.inject({ method: "POST", url: "/login", payload: { password: "secret" } });
+          expect(ok.statusCode).toBe(200);
+
+          const bad = await app.inject({ method: "POST", url: "/login", payload: { password: "wrong" } });
+          expect(bad.statusCode).toBe(404);
+
+          await app.close();
+     });
+
+     it("uses first matching variant when multiple variants match", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/variants",
+                         response: { ok: true, source: "base" },
+                         variants: [
+                              {
+                                   name: "first",
+                                   match: { body: { role: "admin" } },
+                                   status: 403,
+                                   response: { ok: false, source: "first" }
+                              },
+                              {
+                                   name: "second",
+                                   match: { body: { role: "admin" } },
+                                   status: 200,
+                                   response: { ok: true, source: "second" }
+                              }
+                         ]
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "POST", url: "/variants", payload: { role: "admin" } });
+          expect(res.statusCode).toBe(403);
+          expect(res.json()).toEqual({ ok: false, source: "first" });
+
+          await app.close();
+     });
+
+     it("falls back to endpoint response when no variant matches", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "POST",
+                         path: "/variants",
+                         response: { ok: true, source: "base" },
+                         variants: [
+                              {
+                                   name: "only",
+                                   match: { body: { role: "admin" } },
+                                   status: 201,
+                                   response: { ok: true, source: "variant" }
+                              }
+                         ]
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "POST", url: "/variants", payload: { role: "user" } });
+          expect(res.statusCode).toBe(200);
+          expect(res.json()).toEqual({ ok: true, source: "base" });
+
+          await app.close();
+     });
+
+     it("rejects array query values for match rules", async () => {
+          const app = buildTestServer({
+               version: 1,
+               settings: baseSettings,
+               endpoints: [
+                    {
+                         method: "GET",
+                         path: "/search",
+                         match: { query: { type: "premium" } },
+                         response: { ok: true }
+                    }
+               ]
+          });
+
+          const res = await app.inject({ method: "GET", url: "/search?type=premium&type=basic" });
+          expect(res.statusCode).toBe(404);
+
+          await app.close();
+     });
+});