api-json-server 1.0.1 → 1.1.0

package/src/registerEndpoints.ts

@@ -1,183 +1,97 @@
-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;
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import type { MockSpecInferSchema, EndpointSpecInferSchema, TemplateValue } from "./spec.js";
+import { matchRequest, toRecord } from "./requestMatch.js";
+import { createRenderContext, renderTemplateValue } from "./responseRenderer.js";
+import { resolveBehavior, shouldFail, sleep, type BehaviorOverrides } from "./behavior.js";
+
+type ResponseSource = {
+     status?: number;
+     response: TemplateValue;
+} & BehaviorOverrides;
+
+/**
+ * Select a response source from the first matching variant.
+ */
+function selectVariant(req: FastifyRequest, endpoint: EndpointSpecInferSchema): ResponseSource | null {
+     if (!endpoint.variants || endpoint.variants.length === 0) return null;
+     for (const variant of endpoint.variants) {
+          if (matchRequest(req, variant.match)) {
+               return {
+                    status: variant.status,
+                    response: variant.response,
+                    delayMs: variant.delayMs,
+                    errorRate: variant.errorRate,
+                    errorStatus: variant.errorStatus,
+                    errorResponse: variant.errorResponse
+               };
           }
      }
-
-     // body exact match (top-level)
-     if (!bodyMatches(req, match.body)) return false;
-
-     return true;
+     return null;
 }
 
+/**
+ * Build a response source from the endpoint itself.
+ */
+function selectEndpointSource(endpoint: EndpointSpecInferSchema): ResponseSource {
+     return {
+          status: endpoint.status,
+          response: endpoint.response,
+          delayMs: endpoint.delayMs,
+          errorRate: endpoint.errorRate,
+          errorStatus: endpoint.errorStatus,
+          errorResponse: endpoint.errorResponse
+     };
+}
 
+/**
+ * Register all endpoints defined in a mock spec.
+ */
 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" };
-                         }
+               handler: buildEndpointHandler(spec, endpoint)
+          });
 
-                         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
-                         };
-                    }
+          app.log.info(
+               `Registered ${endpoint.method} ${endpoint.path} -> ${endpoint.status} (delay=${endpoint.delayMs ?? spec.settings.delayMs}ms, errorRate=${endpoint.errorRate ?? spec.settings.errorRate})`
+          );
+     }
+}
 
-                    // 3) Resolve behavior: chosen overrides -> endpoint -> global settings
-                    const settings = spec.settings;
+/**
+ * Build a Fastify handler for a single endpoint definition.
+ */
+function buildEndpointHandler(spec: MockSpecInferSchema, endpoint: EndpointSpecInferSchema) {
+     return async (req: FastifyRequest, reply: FastifyReply) => {
+          const variant = selectVariant(req, endpoint);
 
-                    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 (!variant && !matchRequest(req, endpoint.match)) {
+               reply.code(404);
+               return { error: "No matching mock for request" };
+          }
 
-                    if (delayMs > 0) {
-                         await sleep(delayMs);
-                    }
+          const source = variant ?? selectEndpointSource(endpoint);
+          const behavior = resolveBehavior(spec.settings, endpoint, source);
 
-                    if (shouldFail(errorRate)) {
-                         reply.code(errorStatus);
-                         return errorResponse;
-                    }
+          if (behavior.delayMs > 0) {
+               await sleep(behavior.delayMs);
+          }
 
-                    // 4) Template rendering using request context
-                    const params = asRecord(req.params);
-                    const query = asRecord(req.query);
-                    const body = req.body;
+          const params = toRecord(req.params);
+          const query = toRecord(req.query);
+          const body = req.body;
+          const renderContext = createRenderContext({ params, query, body }, spec.settings.fakerSeed);
 
-                    const rendered = renderTemplate(chosen.response, { params, query, body });
+          if (shouldFail(behavior.errorRate)) {
+               reply.code(behavior.errorStatus);
+               return renderTemplateValue(behavior.errorResponse, renderContext);
+          }
 
-                    // 5) Status code precedence: chosen -> endpoint -> 200
-                    reply.code(chosen.status ?? endpoint.status ?? 200);
-                    return rendered;
-               }
-          });
+          const rendered = renderTemplateValue(source.response, renderContext);
 
-          app.log.info(
-               `Registered ${endpoint.method} ${endpoint.path} -> ${endpoint.status} (delay=${endpoint.delayMs ?? spec.settings.delayMs}ms, errorRate=${endpoint.errorRate ?? spec.settings.errorRate})`
-          );
-     }
+          reply.code(source.status ?? endpoint.status ?? 200);
+          return rendered;
+     };
 }

package/src/requestMatch.ts

@@ -0,0 +1,62 @@
+import type { FastifyRequest } from "fastify";
+import type { Primitive } from "./spec.js";
+
+export type MatchRule = {
+     query?: Record<string, Primitive>;
+     body?: Record<string, Primitive>;
+};
+
+/**
+ * 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 a request matches query/body 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;
+     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,178 @@
-import Fastify, { FastifyInstance } from "fastify";
-import { MockSpecInferSchema } from "./spec.js";
+import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } 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 YAML from "yaml";
 
-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 }
+): FastifyInstance {
      const app = Fastify({
-          logger: true
+          logger: true,
+          trustProxy: true
      });
 
+     /**
+      * 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", async () => {
-          return { ok: true };
-     });
+     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);
+
      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);
+}