api-json-server 1.0.1 → 1.2.0

package/src/requestMatch.ts

@@ -0,0 +1,104 @@
+import type { FastifyRequest } from "fastify";
+import type { Primitive } from "./spec.js";
+
+export type MatchRule = {
+     query?: Record<string, Primitive>;
+     body?: Record<string, Primitive>;
+     headers?: Record<string, string>;
+     cookies?: Record<string, string>;
+};
+
+/**
+ * Safely coerce a value to a plain object record.
+ */
+/**
+ * Safely coerce a value to a plain object record.
+ */
+export function toRecord(value: unknown): Record<string, unknown> {
+     if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+     return {};
+}
+
+/**
+ * Check if the request query matches the expected values.
+ */
+function queryMatches(req: FastifyRequest, expected?: Record<string, Primitive>): boolean {
+     if (!expected) return true;
+     const query = toRecord(req.query);
+
+     for (const [key, exp] of Object.entries(expected)) {
+          const actual = query[key];
+          if (Array.isArray(actual)) return false;
+          if (String(actual ?? "") !== String(exp)) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if the request body matches the expected top-level values.
+ */
+function bodyMatches(req: FastifyRequest, expected?: Record<string, Primitive>): boolean {
+     if (!expected) return true;
+
+     const body = req.body;
+     if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+
+     const record = body as Record<string, unknown>;
+     for (const [key, exp] of Object.entries(expected)) {
+          const actual = record[key];
+          if (String(actual ?? "") !== String(exp)) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if the request headers match the expected values (case-insensitive).
+ */
+function headersMatch(req: FastifyRequest, expected?: Record<string, string>): boolean {
+     if (!expected) return true;
+
+     // Normalize header keys to lowercase for case-insensitive matching
+     const headers = new Map<string, string>();
+     for (const [key, value] of Object.entries(req.headers)) {
+          if (typeof value === "string") {
+               headers.set(key.toLowerCase(), value);
+          }
+     }
+
+     for (const [key, exp] of Object.entries(expected)) {
+          const actual = headers.get(key.toLowerCase());
+          if (actual !== exp) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if the request cookies match the expected values.
+ */
+function cookiesMatch(req: FastifyRequest, expected?: Record<string, string>): boolean {
+     if (!expected) return true;
+
+     const cookies = (req as FastifyRequest & { cookies?: Record<string, string> }).cookies;
+     if (!cookies) return false;
+
+     for (const [key, exp] of Object.entries(expected)) {
+          if (cookies[key] !== exp) return false;
+     }
+
+     return true;
+}
+
+/**
+ * Check if a request matches query/body/headers/cookies rules.
+ */
+export function matchRequest(req: FastifyRequest, match?: MatchRule): boolean {
+     if (!match) return true;
+     if (!queryMatches(req, match.query)) return false;
+     if (!bodyMatches(req, match.body)) return false;
+     if (!headersMatch(req, match.headers)) return false;
+     if (!cookiesMatch(req, match.cookies)) return false;
+     return true;
+}

package/src/responseRenderer.ts

@@ -0,0 +1,112 @@
+import { faker as baseFaker, type Faker } from "@faker-js/faker";
+import type { FakerTemplate, RepeatTemplate, TemplateValue } from "./spec.js";
+import { renderStringTemplate, type TemplateContext } from "./stringTemplate.js";
+
+export type RenderContext = TemplateContext & {
+     faker: Faker;
+};
+
+/**
+ * Create a render context with an optional faker seed applied.
+ */
+export function createRenderContext(ctx: TemplateContext, fakerSeed?: number): RenderContext {
+     if (typeof fakerSeed === "number") {
+          baseFaker.seed(fakerSeed);
+     }
+     return { ...ctx, faker: baseFaker };
+}
+
+/**
+ * Check if a template value is a faker directive.
+ */
+function isFakerTemplate(value: TemplateValue): value is FakerTemplate {
+     return typeof value === "object" && value !== null && !Array.isArray(value) && "__faker" in value;
+}
+
+/**
+ * Check if a template value is a repeat directive.
+ */
+function isRepeatTemplate(value: TemplateValue): value is RepeatTemplate {
+     return typeof value === "object" && value !== null && !Array.isArray(value) && "__repeat" in value;
+}
+
+/**
+ * Resolve a faker method path (e.g. "person.firstName") to a callable function.
+ */
+function resolveFakerMethod(faker: Faker, methodPath: string): (...args: unknown[]) => unknown {
+     const parts = methodPath.split(".");
+     let current: unknown = faker;
+
+     for (const part of parts) {
+          if (current === null || current === undefined) {
+               throw new Error(`Faker method not found: ${methodPath}`);
+          }
+          if (typeof current !== "object" && typeof current !== "function") {
+               throw new Error(`Faker method not found: ${methodPath}`);
+          }
+
+          const record = current as Record<string, unknown>;
+          current = record[part];
+     }
+
+     if (typeof current !== "function") {
+          throw new Error(`Faker method is not callable: ${methodPath}`);
+     }
+
+     return current as (...args: unknown[]) => unknown;
+}
+
+/**
+ * Render a faker directive to a concrete value.
+ */
+function renderFakerTemplate(template: FakerTemplate, ctx: RenderContext): unknown {
+     const faker = ctx.faker;
+     const raw = template.__faker;
+     const methodPath = typeof raw === "string" ? raw : raw.method;
+     const args = typeof raw === "string" ? [] : raw.args ?? [];
+     const renderedArgs = args.map((arg) => renderTemplateValue(arg, ctx));
+     const method = resolveFakerMethod(faker, methodPath);
+     return method(...renderedArgs);
+}
+
+/**
+ * Render a repeat directive to an array of rendered items.
+ */
+function renderRepeatTemplate(template: RepeatTemplate, ctx: RenderContext): unknown[] {
+     const faker = ctx.faker;
+     const { count, min, max, template: itemTemplate } = template.__repeat;
+     const minValue = typeof min === "number" ? min : 0;
+
+     if (typeof count === "number") {
+          return Array.from({ length: count }, () => renderTemplateValue(itemTemplate, ctx));
+     }
+
+     const upper = typeof max === "number" ? max : minValue;
+     if (upper < minValue) {
+          throw new Error(`Repeat max must be >= min (min=${minValue}, max=${upper})`);
+     }
+
+     const total = faker.number.int({ min: minValue, max: upper });
+     return Array.from({ length: total }, () => renderTemplateValue(itemTemplate, ctx));
+}
+
+/**
+ * Render a template value into a concrete JSON-compatible value.
+ */
+export function renderTemplateValue(value: TemplateValue, ctx: RenderContext): unknown {
+     if (typeof value === "string") return renderStringTemplate(value, ctx);
+     if (typeof value === "number" || typeof value === "boolean" || value === null) return value;
+
+     if (Array.isArray(value)) {
+          return value.map((item) => renderTemplateValue(item, ctx));
+     }
+
+     if (isFakerTemplate(value)) return renderFakerTemplate(value, ctx);
+     if (isRepeatTemplate(value)) return renderRepeatTemplate(value, ctx);
+
+     const output: Record<string, unknown> = {};
+     for (const [key, item] of Object.entries(value)) {
+          output[key] = renderTemplateValue(item, ctx);
+     }
+     return output;
+}

package/src/server.ts

@@ -1,29 +1,251 @@
-import Fastify, { FastifyInstance } from "fastify";
-import { MockSpecInferSchema } from "./spec.js";
+import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest, type FastifyBaseLogger } from "fastify";
+import type { MockSpecInferSchema } from "./spec.js";
 import { registerEndpoints } from "./registerEndpoints.js";
+import swaggerUiDist from "swagger-ui-dist";
+import { generateOpenApi } from "./openapi.js";
+import fastifyStatic from "@fastify/static";
+import fastifyCookie from "@fastify/cookie";
+import fastifyCors from "@fastify/cors";
+import YAML from "yaml";
+import { createLogger } from "./logger/customLogger.js";
+import type { LoggerOptions } from "./logger/types.js";
+import { HistoryRecorder } from "./history/historyRecorder.js";
+import type { HistoryFilter } from "./history/types.js";
 
-export function buildServer(spec: MockSpecInferSchema, meta?: { specPath?: string; loadedAt?: string }): FastifyInstance {
+type SwaggerUiDistModule = {
+     getAbsoluteFSPath?: () => string;
+};
+
+/**
+ * Resolve the path to swagger-ui-dist assets.
+ */
+function getSwaggerUiRoot(): string {
+     // swagger-ui-dist can be CJS or ESM depending on environment.
+     // CJS: require("swagger-ui-dist").getAbsoluteFSPath()
+     // ESM: default export may itself be the function.
+     const mod: unknown = swaggerUiDist;
+
+     if (typeof mod === "function") return mod();
+     if (mod && typeof (mod as SwaggerUiDistModule).getAbsoluteFSPath === "function") {
+          return (mod as SwaggerUiDistModule).getAbsoluteFSPath!();
+     }
+
+     throw new Error("swagger-ui-dist: cannot determine absolute FS path to dist assets");
+}
+
+/**
+ * Resolve the server URL for OpenAPI output.
+ */
+function resolveServerUrl(req: FastifyRequest, baseUrl?: string): string {
+     if (baseUrl && baseUrl.trim().length > 0) return baseUrl.trim();
+
+     const host = req.headers.host ?? "localhost";
+     const protocol = req.protocol ?? "http";
+     return `${protocol}://${host}`;
+}
+
+/**
+ * Create a Fastify server with mock endpoints and docs.
+ */
+export function buildServer(
+     spec: MockSpecInferSchema,
+     meta?: { specPath?: string; loadedAt?: string; baseUrl?: string; logger?: FastifyBaseLogger | boolean }
+): FastifyInstance {
      const app = Fastify({
-          logger: true
+          logger: meta?.logger ?? true,
+          trustProxy: true,
+          disableRequestLogging: false
      });
 
-     // Basic sanity route
-     app.get("/health", async () => {
-          return { ok: true };
+     // Register CORS if configured
+     if (spec.settings.cors) {
+          app.register(fastifyCors, {
+               origin: spec.settings.cors.origin ?? true,
+               credentials: spec.settings.cors.credentials ?? false,
+               methods: spec.settings.cors.methods,
+               allowedHeaders: spec.settings.cors.allowedHeaders,
+               exposedHeaders: spec.settings.cors.exposedHeaders,
+               maxAge: spec.settings.cors.maxAge
+          });
+     }
+
+     // Register cookie parser plugin
+     app.register(fastifyCookie);
+
+     // Create history recorder
+     const history = new HistoryRecorder(1000);
+
+     // Record all requests in onRequest hook (after body parsing)
+     app.addHook("preHandler", async (req, reply) => {
+          const startTime = Date.now();
+
+          // Store start time for response hook
+          (req as FastifyRequest & { startTime?: number }).startTime = startTime;
+
+          history.record({
+               method: req.method,
+               url: req.url,
+               path: req.routeOptions?.url ?? req.url.split("?")[0],
+               query: req.query as Record<string, unknown>,
+               headers: req.headers,
+               body: req.body
+          });
+     });
+
+     // Update history with response details in onResponse hook
+     app.addHook("onResponse", async (req, reply) => {
+          const startTime = (req as FastifyRequest & { startTime?: number }).startTime ?? Date.now();
+          const responseTime = Date.now() - startTime;
+
+          // Find and update the last entry (just added in onRequest)
+          const entries = history.query({ limit: 1 });
+          if (entries.length > 0) {
+               const lastEntry = entries[entries.length - 1];
+               lastEntry.statusCode = reply.statusCode;
+               lastEntry.responseTime = responseTime;
+          }
      });
 
+     /**
+      * Handler for the /__spec route with bound metadata.
+      */
+     function specRouteHandler() {
+          return specHandler(spec, meta);
+     }
+
+     /**
+      * Handler for the /__openapi.json route.
+      */
+     function openApiJsonRouteHandler(req: FastifyRequest) {
+          return openApiJsonHandler(req, spec, meta?.baseUrl);
+     }
+
+     /**
+      * Handler for the /__openapi.yaml route.
+      */
+     function openApiYamlRouteHandler(req: FastifyRequest, reply: FastifyReply): void {
+          return openApiYamlHandler(req, reply, spec, meta?.baseUrl);
+     }
+
+     /**
+      * Handler for the /docs route.
+      */
+     function docsRouteHandler(req: FastifyRequest, reply: FastifyReply): void {
+          return docsHandler(req, reply);
+     }
+
+     // Basic sanity route
+     app.get("/health", healthHandler);
+
      // Internal inspection endpoint
-     app.get("/__spec", async () => {
-          return {
-               meta: {
-                    specPath: meta?.specPath ?? null,
-                    loadedAt: meta?.loadedAt ?? null
-               },
-               spec
+     app.get("/__spec", specRouteHandler);
+
+     app.get("/__openapi.json", openApiJsonRouteHandler);
+
+     app.get("/__openapi.yaml", openApiYamlRouteHandler);
+
+     app.register(fastifyStatic, {
+          root: getSwaggerUiRoot(),
+          prefix: "/docs/assets/",
+          decorateReply: false
+     });
+
+     app.get("/docs", docsRouteHandler);
+
+     // History endpoints
+     app.get("/__history", async (req) => {
+          const query = req.query as Record<string, string>;
+          const filter: HistoryFilter = {
+               endpoint: query.endpoint,
+               method: query.method,
+               statusCode: query.statusCode ? Number(query.statusCode) : undefined,
+               limit: query.limit ? Number(query.limit) : undefined
           };
+          return { entries: history.query(filter), total: history.count() };
+     });
+
+     app.delete("/__history", async () => {
+          history.clear();
+          return { ok: true, message: "History cleared" };
      });
 
      registerEndpoints(app, spec);
 
      return app;
 }
+
+/**
+ * Health check handler.
+ */
+function healthHandler(): { ok: true } {
+     return { ok: true };
+}
+
+/**
+ * Debug handler that exposes the current spec and metadata.
+ */
+function specHandler(spec: MockSpecInferSchema, meta?: { specPath?: string; loadedAt?: string }) {
+     return {
+          meta: {
+               specPath: meta?.specPath ?? null,
+               loadedAt: meta?.loadedAt ?? null
+          },
+          spec
+     };
+}
+
+/**
+ * Serve the OpenAPI document as JSON.
+ */
+function openApiJsonHandler(req: FastifyRequest, spec: MockSpecInferSchema, baseUrl?: string) {
+     const serverUrl = resolveServerUrl(req, baseUrl);
+     return generateOpenApi(spec, serverUrl);
+}
+
+/**
+ * Serve the OpenAPI document as YAML.
+ */
+function openApiYamlHandler(
+     req: FastifyRequest,
+     reply: FastifyReply,
+     spec: MockSpecInferSchema,
+     baseUrl?: string
+): void {
+     const serverUrl = resolveServerUrl(req, baseUrl);
+     const doc = generateOpenApi(spec, serverUrl);
+     const yaml = YAML.stringify(doc);
+     reply.type("application/yaml; charset=utf-8").send(yaml);
+}
+
+/**
+ * Serve the Swagger UI HTML page.
+ */
+function docsHandler(_req: FastifyRequest, reply: FastifyReply): void {
+     const html = `<!DOCTYPE html>
+     <html lang="en">
+     <head>
+       <meta charset="UTF-8" />
+       <meta name="viewport" content="width=device-width, initial-scale=1" />
+       <title>mockserve docs</title>
+       <link rel="stylesheet" href="/docs/assets/swagger-ui.css" />
+       <style>
+         html, body { margin: 0; padding: 0; }
+       </style>
+     </head>
+     <body>
+       <div id="swagger-ui"></div>
+     
+       <script src="/docs/assets/swagger-ui-bundle.js"></script>
+       <script src="/docs/assets/swagger-ui-standalone-preset.js"></script>
+       <script>
+         window.ui = SwaggerUIBundle({
+           url: "/__openapi.json",
+           dom_id: "#swagger-ui",
+           presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+           layout: "BaseLayout"
+         });
+       </script>
+     </body>
+     </html>`;
+     reply.type("text/html; charset=utf-8").send(html);
+}

package/src/spec.ts

@@ -1,25 +1,100 @@
 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(),
+     // Header matching (case-insensitive keys)
+     headers: z.record(z.string(), z.string()).optional(),
+     // Cookie matching
+     cookies: z.record(z.string(), z.string()).optional()
 });
 
+const DelaySchema = z.union([
+     z.number().int().min(0),
+     z.object({
+          min: z.number().int().min(0),
+          max: z.number().int().min(0)
+     })
+]);
+
 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(),
+     response: TemplateValueSchema,
+     headers: z.record(z.string(), z.string()).optional(),
 
      // Simulation overrides per variant (optional)
      delayMs: z.number().int().min(0).optional(),
+     delay: DelaySchema.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 +106,27 @@ export const EndpointSchema = z.object({
 
      // Response behavior:
      status: z.number().int().min(200).max(599).default(200),
-     response: z.unknown(),
+     response: TemplateValueSchema,
+     headers: z.record(z.string(), z.string()).optional(),
+
+     // Per-endpoint CORS override
+     cors: z
+          .object({
+               origin: z.union([z.string(), z.array(z.string()), z.boolean()]).optional(),
+               credentials: z.boolean().optional(),
+               methods: z.array(z.string()).optional(),
+               allowedHeaders: z.array(z.string()).optional(),
+               exposedHeaders: z.array(z.string()).optional(),
+               maxAge: z.number().int().optional()
+          })
+          .optional(),
 
      // Simulation (optional overrides)
      delayMs: z.number().int().min(0).optional(),
+     delay: DelaySchema.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 +136,18 @@ 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(),
+               cors: z
+                    .object({
+                         origin: z.union([z.string(), z.array(z.string()), z.boolean()]).optional(),
+                         credentials: z.boolean().optional(),
+                         methods: z.array(z.string()).optional(),
+                         allowedHeaders: z.array(z.string()).optional(),
+                         exposedHeaders: z.array(z.string()).optional(),
+                         maxAge: z.number().int().optional()
+                    })
+                    .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);
+}