api-json-server 1.0.1 → 1.2.0

package/src/logger/customLogger.ts

@@ -0,0 +1,85 @@
+import type { FastifyBaseLogger } from "fastify";
+import pino from "pino";
+import type { LoggerOptions } from "./types.js";
+import { formatStatusCode, formatMethod, formatResponseTime, formatTimestamp, formatLogLevel } from "./formatters.js";
+
+/**
+ * Create a custom logger for the mock server.
+ */
+export function createLogger(options: LoggerOptions): FastifyBaseLogger {
+     if (!options.enabled) {
+          return pino({ level: "silent" });
+     }
+
+     if (options.format === "json") {
+          return pino({
+               level: options.level,
+               timestamp: pino.stdTimeFunctions.isoTime
+          });
+     }
+
+     // Pretty format with custom output (simplified to avoid serialization issues in tests)
+     return pino({
+          level: options.level,
+          transport: {
+               target: "pino-pretty",
+               options: {
+                    colorize: true,
+                    translateTime: "HH:MM:ss",
+                    ignore: "pid,hostname",
+                    messageFormat: "{msg}"
+               }
+          }
+     });
+}
+
+/**
+ * Format and log a request/response pair.
+ */
+export function logRequest(
+     logger: FastifyBaseLogger,
+     method: string,
+     url: string,
+     statusCode: number,
+     responseTime: number
+): void {
+     const formattedMethod = formatMethod(method);
+     const formattedStatus = formatStatusCode(statusCode);
+     const formattedTime = formatResponseTime(responseTime);
+
+     logger.info(`${formattedMethod} ${url} ${formattedStatus} ${formattedTime}`);
+}
+
+/**
+ * Log server startup.
+ */
+export function logServerStart(logger: FastifyBaseLogger, port: number, specPath: string): void {
+     logger.info(`🚀 Mock server running on http://localhost:${port}`);
+     logger.info(`📄 Spec: ${specPath}`);
+     logger.info(`📖 Docs: http://localhost:${port}/docs`);
+}
+
+/**
+ * Log server reload.
+ */
+export function logServerReload(logger: FastifyBaseLogger, success: boolean, error?: string): void {
+     if (success) {
+          logger.info("✅ Spec reloaded successfully");
+     } else {
+          logger.error(`❌ Reload failed: ${error}`);
+     }
+}
+
+/**
+ * Log endpoint registration.
+ */
+export function logEndpointRegistered(
+     logger: FastifyBaseLogger,
+     method: string,
+     path: string,
+     status?: number
+): void {
+     const formattedMethod = formatMethod(method);
+     const statusInfo = status ? ` → ${status}` : "";
+     logger.debug(`Registered ${formattedMethod} ${path}${statusInfo}`);
+}

package/src/logger/formatters.ts

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+
+/**
+ * Format HTTP status code with color based on status range.
+ */
+export function formatStatusCode(statusCode: number): string {
+     if (statusCode >= 500) {
+          return chalk.red(statusCode.toString());
+     }
+     if (statusCode >= 400) {
+          return chalk.yellow(statusCode.toString());
+     }
+     if (statusCode >= 300) {
+          return chalk.cyan(statusCode.toString());
+     }
+     if (statusCode >= 200) {
+          return chalk.green(statusCode.toString());
+     }
+     return chalk.white(statusCode.toString());
+}
+
+/**
+ * Format HTTP method with color.
+ */
+export function formatMethod(method: string): string {
+     const colors: Record<string, (str: string) => string> = {
+          GET: chalk.green,
+          POST: chalk.blue,
+          PUT: chalk.yellow,
+          PATCH: chalk.magenta,
+          DELETE: chalk.red,
+          HEAD: chalk.gray,
+          OPTIONS: chalk.cyan
+     };
+     const formatter = colors[method.toUpperCase()] || chalk.white;
+     return formatter(method.toUpperCase().padEnd(7));
+}
+
+/**
+ * Format response time with color based on duration.
+ */
+export function formatResponseTime(ms: number): string {
+     const formatted = `${ms.toFixed(2)}ms`;
+     if (ms > 1000) return chalk.red(formatted);
+     if (ms > 500) return chalk.yellow(formatted);
+     if (ms > 100) return chalk.cyan(formatted);
+     return chalk.green(formatted);
+}
+
+/**
+ * Format timestamp in readable format.
+ */
+export function formatTimestamp(date: Date): string {
+     const hours = date.getHours().toString().padStart(2, "0");
+     const minutes = date.getMinutes().toString().padStart(2, "0");
+     const seconds = date.getSeconds().toString().padStart(2, "0");
+     return chalk.gray(`[${hours}:${minutes}:${seconds}]`);
+}
+
+/**
+ * Format a log level with appropriate color.
+ */
+export function formatLogLevel(level: string): string {
+     const colors: Record<string, (str: string) => string> = {
+          trace: chalk.gray,
+          debug: chalk.cyan,
+          info: chalk.blue,
+          warn: chalk.yellow,
+          error: chalk.red,
+          fatal: chalk.bgRed.white
+     };
+     const formatter = colors[level.toLowerCase()] || chalk.white;
+     return formatter(level.toUpperCase().padEnd(5));
+}

package/src/logger/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Logger configuration options.
+ */
+export interface LoggerOptions {
+     /**
+      * Enable/disable logging.
+      */
+     enabled: boolean;
+
+     /**
+      * Log format: 'pretty' for colored console output, 'json' for structured logs.
+      */
+     format: "pretty" | "json";
+
+     /**
+      * Log level: 'trace', 'debug', 'info', 'warn', 'error', 'fatal'.
+      */
+     level: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+}
+
+/**
+ * Request log entry structure.
+ */
+export interface RequestLogEntry {
+     method: string;
+     url: string;
+     statusCode: number;
+     responseTime: number;
+     timestamp: string;
+}

package/src/openapi.ts

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

package/src/registerEndpoints.ts

@@ -1,183 +1,115 @@
-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, resolveDelay, type BehaviorOverrides, type DelayConfig } from "./behavior.js";
+import { logEndpointRegistered } from "./logger/customLogger.js";
+
+type ResponseSource = {
+     status?: number;
+     response: TemplateValue;
+     headers?: Record<string, string>;
+     delay?: DelayConfig;
+} & 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,
+                    headers: variant.headers,
+                    delay: variant.delay,
+                    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,
+          headers: endpoint.headers,
+          delay: endpoint.delay,
+          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
-                         };
-                    }
+          logEndpointRegistered(app.log, endpoint.method, endpoint.path, endpoint.status);
+     }
+}
 
-                    // 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;
-                    }
+          // Resolve delay (supports both delay and delayMs, with delay taking precedence)
+          const delayValue = source.delay ? resolveDelay(source.delay) : behavior.delayMs;
+          if (delayValue > 0) {
+               await sleep(delayValue);
+          }
 
-                    // 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;
+          // Apply custom headers (with template support)
+          const headers = source.headers ?? endpoint.headers;
+          if (headers) {
+               for (const [key, value] of Object.entries(headers)) {
+                    const renderedValue = typeof value === "string" 
+                         ? String(renderTemplateValue(value, renderContext))
+                         : String(value);
+                    reply.header(key, renderedValue);
                }
-          });
+          }
 
-          app.log.info(
-               `Registered ${endpoint.method} ${endpoint.path} -> ${endpoint.status} (delay=${endpoint.delayMs ?? spec.settings.delayMs}ms, errorRate=${endpoint.errorRate ?? spec.settings.errorRate})`
-          );
-     }
+          const rendered = renderTemplateValue(source.response, renderContext);
+
+          reply.code(source.status ?? endpoint.status ?? 200);
+          return rendered;
+     };
 }