api-json-server 1.0.1 → 1.2.0

package/dist/history/historyRecorder.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistoryRecorder = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * In-memory request history recorder.
+ */
+class HistoryRecorder {
+    entries = [];
+    maxEntries;
+    /**
+     * Create a new history recorder.
+     * @param maxEntries Maximum number of entries to keep (default 1000).
+     */
+    constructor(maxEntries = 1000) {
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * Record a new request.
+     */
+    record(entry) {
+        const fullEntry = {
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date().toISOString(),
+            ...entry
+        };
+        this.entries.push(fullEntry);
+        // Keep only the most recent entries
+        if (this.entries.length > this.maxEntries) {
+            this.entries.shift();
+        }
+        return fullEntry;
+    }
+    /**
+     * Get all history entries, optionally filtered.
+     */
+    query(filter) {
+        let results = this.entries;
+        if (filter?.endpoint) {
+            results = results.filter((e) => e.path === filter.endpoint);
+        }
+        if (filter?.method) {
+            results = results.filter((e) => e.method.toUpperCase() === filter.method?.toUpperCase());
+        }
+        if (filter?.statusCode !== undefined) {
+            results = results.filter((e) => e.statusCode === filter.statusCode);
+        }
+        if (filter?.limit && filter.limit > 0) {
+            results = results.slice(-filter.limit);
+        }
+        return results;
+    }
+    /**
+     * Clear all history entries.
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Get the total number of recorded entries.
+     */
+    count() {
+        return this.entries.length;
+    }
+}
+exports.HistoryRecorder = HistoryRecorder;

package/dist/history/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -2,6 +2,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const customLogger_js_1 = require("./logger/customLogger.js");
 const program = new commander_1.Command();
 program
     .name("mockserve")
@@ -12,10 +14,129 @@ program
     .description("Start the mock server.")
     .option("-p, --port <number>", "Port to run the server on", "3000")
     .option("-s, --spec <path>", "Path to the spec JSON file", "mock.spec.json")
-    .action((opts) => {
-    console.log("mockserve serve called with:");
-    console.log(`- port: ${opts.port}`);
-    console.log(`- spec: ${opts.spec}`);
-    console.log("Server not implemented yet.");
+    .option("--watch", "Reload when spec file changes", true)
+    .option("--no-watch", "Disable reload when spec file changes")
+    .option("--base-url <url>", "Public base URL used in OpenAPI servers[] (e.g. https://example.com)")
+    .option("--log-format <format>", "Log format: pretty or json", "pretty")
+    .option("--log-level <level>", "Log level: trace, debug, info, warn, error, fatal", "info")
+    .action(async (opts) => {
+    await startCommand(opts);
 });
+/**
+ * Run the mock server CLI command.
+ */
+async function startCommand(opts) {
+    const port = Number(opts.port);
+    if (!Number.isFinite(port) || port <= 0) {
+        console.error(`Invalid port: ${opts.port}`);
+        process.exit(1);
+    }
+    const specPath = opts.spec;
+    // Create logger based on CLI options
+    const logFormat = opts.logFormat === "json" ? "json" : "pretty";
+    const logLevel = ["trace", "debug", "info", "warn", "error", "fatal"].includes(opts.logLevel)
+        ? opts.logLevel
+        : "info";
+    const logger = (0, customLogger_js_1.createLogger)({
+        enabled: true,
+        format: logFormat,
+        level: logLevel
+    });
+    const { loadSpecFromFile } = await import("./loadSpec.js");
+    const { buildServer } = await import("./server.js");
+    let app = null;
+    let isReloading = false;
+    let debounceTimer = null;
+    /**
+     * Build and start a server using the current spec file.
+     */
+    async function startWithSpec() {
+        const loadedAt = new Date().toISOString();
+        const spec = await loadSpecFromFile(specPath);
+        logger.info(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
+        const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl, logger: true });
+        try {
+            await nextApp.listen({ port, host: "0.0.0.0" });
+        }
+        catch (err) {
+            nextApp.log.error(err);
+            throw err;
+        }
+        (0, customLogger_js_1.logServerStart)(nextApp.log, port, specPath);
+        return nextApp;
+    }
+    /**
+     * Reload the server when the spec changes.
+     */
+    async function reload() {
+        if (isReloading)
+            return;
+        isReloading = true;
+        try {
+            logger.info("Reloading spec...");
+            // 1) Stop accepting requests on the old server FIRST
+            if (app) {
+                logger.debug("Closing current server...");
+                await app.close();
+                logger.debug("Current server closed.");
+                app = null;
+            }
+            // 2) Start a new server on the same port with the updated spec
+            app = await startWithSpec();
+            (0, customLogger_js_1.logServerReload)(logger, true);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            (0, customLogger_js_1.logServerReload)(logger, false, errorMsg);
+            // Optional: try to start again to avoid being down
+            try {
+                if (!app) {
+                    logger.info("Attempting to start server again after reload failure...");
+                    app = await startWithSpec();
+                    logger.info("Recovery start succeeded.");
+                }
+            }
+            catch (err2) {
+                logger.error("Recovery start failed. Server is down until next successful reload.");
+                logger.error(err2);
+            }
+        }
+        finally {
+            isReloading = false;
+        }
+    }
+    // Initial start
+    try {
+        app = await startWithSpec();
+    }
+    catch (err) {
+        logger.error(err);
+        process.exit(1);
+    }
+    // Watch spec for changes
+    /**
+     * Handle file changes with a debounced reload.
+     */
+    function onSpecChange() {
+        debounceTimer = scheduleReload(reload, debounceTimer);
+    }
+    if (opts.watch) {
+        logger.info(`Watching spec file for changes: ${specPath}`);
+        // fs.watch emits multiple events; debounce to avoid rapid reload loops
+        (0, node_fs_1.watch)(specPath, onSpecChange);
+    }
+    else {
+        logger.info("Watch disabled (--no-watch).");
+    }
+}
+/**
+ * Schedule a debounced reload when the spec changes.
+ */
+function scheduleReload(reload, debounceTimer) {
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    return setTimeout(() => {
+        void reload();
+    }, 200);
+}
 program.parse(process.argv);

package/dist/loadSpec.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSpecFromFile = loadSpecFromFile;
+const promises_1 = require("node:fs/promises");
+const spec_js_1 = require("./spec.js");
+/**
+ * Load and validate a mock spec from disk.
+ */
+async function loadSpecFromFile(specPath) {
+    let raw;
+    try {
+        raw = await (0, promises_1.readFile)(specPath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Failed to read spec file ${specPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse spec file ${specPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = spec_js_1.MockSpecSchema.safeParse(json);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new Error(`Invalid spec file ${specPath}: ${issues}`);
+    }
+    return parsed.data;
+}

package/dist/logger/customLogger.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+exports.logRequest = logRequest;
+exports.logServerStart = logServerStart;
+exports.logServerReload = logServerReload;
+exports.logEndpointRegistered = logEndpointRegistered;
+const pino_1 = __importDefault(require("pino"));
+const formatters_js_1 = require("./formatters.js");
+/**
+ * Create a custom logger for the mock server.
+ */
+function createLogger(options) {
+    if (!options.enabled) {
+        return (0, pino_1.default)({ level: "silent" });
+    }
+    if (options.format === "json") {
+        return (0, pino_1.default)({
+            level: options.level,
+            timestamp: pino_1.default.stdTimeFunctions.isoTime
+        });
+    }
+    // Pretty format with custom output (simplified to avoid serialization issues in tests)
+    return (0, pino_1.default)({
+        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.
+ */
+function logRequest(logger, method, url, statusCode, responseTime) {
+    const formattedMethod = (0, formatters_js_1.formatMethod)(method);
+    const formattedStatus = (0, formatters_js_1.formatStatusCode)(statusCode);
+    const formattedTime = (0, formatters_js_1.formatResponseTime)(responseTime);
+    logger.info(`${formattedMethod} ${url} ${formattedStatus} ${formattedTime}`);
+}
+/**
+ * Log server startup.
+ */
+function logServerStart(logger, port, specPath) {
+    logger.info(`🚀 Mock server running on http://localhost:${port}`);
+    logger.info(`📄 Spec: ${specPath}`);
+    logger.info(`📖 Docs: http://localhost:${port}/docs`);
+}
+/**
+ * Log server reload.
+ */
+function logServerReload(logger, success, error) {
+    if (success) {
+        logger.info("✅ Spec reloaded successfully");
+    }
+    else {
+        logger.error(`❌ Reload failed: ${error}`);
+    }
+}
+/**
+ * Log endpoint registration.
+ */
+function logEndpointRegistered(logger, method, path, status) {
+    const formattedMethod = (0, formatters_js_1.formatMethod)(method);
+    const statusInfo = status ? ` → ${status}` : "";
+    logger.debug(`Registered ${formattedMethod} ${path}${statusInfo}`);
+}

package/dist/logger/formatters.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatStatusCode = formatStatusCode;
+exports.formatMethod = formatMethod;
+exports.formatResponseTime = formatResponseTime;
+exports.formatTimestamp = formatTimestamp;
+exports.formatLogLevel = formatLogLevel;
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Format HTTP status code with color based on status range.
+ */
+function formatStatusCode(statusCode) {
+    if (statusCode >= 500) {
+        return chalk_1.default.red(statusCode.toString());
+    }
+    if (statusCode >= 400) {
+        return chalk_1.default.yellow(statusCode.toString());
+    }
+    if (statusCode >= 300) {
+        return chalk_1.default.cyan(statusCode.toString());
+    }
+    if (statusCode >= 200) {
+        return chalk_1.default.green(statusCode.toString());
+    }
+    return chalk_1.default.white(statusCode.toString());
+}
+/**
+ * Format HTTP method with color.
+ */
+function formatMethod(method) {
+    const colors = {
+        GET: chalk_1.default.green,
+        POST: chalk_1.default.blue,
+        PUT: chalk_1.default.yellow,
+        PATCH: chalk_1.default.magenta,
+        DELETE: chalk_1.default.red,
+        HEAD: chalk_1.default.gray,
+        OPTIONS: chalk_1.default.cyan
+    };
+    const formatter = colors[method.toUpperCase()] || chalk_1.default.white;
+    return formatter(method.toUpperCase().padEnd(7));
+}
+/**
+ * Format response time with color based on duration.
+ */
+function formatResponseTime(ms) {
+    const formatted = `${ms.toFixed(2)}ms`;
+    if (ms > 1000)
+        return chalk_1.default.red(formatted);
+    if (ms > 500)
+        return chalk_1.default.yellow(formatted);
+    if (ms > 100)
+        return chalk_1.default.cyan(formatted);
+    return chalk_1.default.green(formatted);
+}
+/**
+ * Format timestamp in readable format.
+ */
+function formatTimestamp(date) {
+    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_1.default.gray(`[${hours}:${minutes}:${seconds}]`);
+}
+/**
+ * Format a log level with appropriate color.
+ */
+function formatLogLevel(level) {
+    const colors = {
+        trace: chalk_1.default.gray,
+        debug: chalk_1.default.cyan,
+        info: chalk_1.default.blue,
+        warn: chalk_1.default.yellow,
+        error: chalk_1.default.red,
+        fatal: chalk_1.default.bgRed.white
+    };
+    const formatter = colors[level.toLowerCase()] || chalk_1.default.white;
+    return formatter(level.toUpperCase().padEnd(5));
+}

package/dist/logger/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/openapi.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateOpenApi = generateOpenApi;
+/**
+ * Convert Fastify-style route params to OpenAPI style.
+ */
+function toOpenApiPath(fastifyPath) {
+    // 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) {
+    const matches = [...fastifyPath.matchAll(/:([A-Za-z0-9_]+)/g)];
+    return matches.map((m) => m[1]);
+}
+/**
+ * Deduplicate values while preserving order.
+ */
+function uniq(items) {
+    return [...new Set(items)];
+}
+/**
+ * Convert a list of values into a list of string enums.
+ */
+function asStringEnum(values) {
+    return uniq(values
+        .filter((v) => v !== undefined && v !== null)
+        .map((v) => String(v)));
+}
+/**
+ * Generate a minimal OpenAPI document for the mock spec.
+ */
+function generateOpenApi(spec, serverUrl) {
+    const paths = {};
+    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 = {};
+        const bodyMatchKeys = new Set();
+        /**
+         * Collect query match values into a set for documentation.
+         */
+        const collectQuery = (obj) => {
+            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) => {
+            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 = [];
+        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 = 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 = {};
+        /**
+         * Add a response example to the OpenAPI response map.
+         */
+        const addResponseExample = (status, name, example) => {
+            const key = String(status);
+            if (!responses[key]) {
+                responses[key] = {
+                    description: "Mock response",
+                    content: { "application/json": { examples: {} } }
+                };
+            }
+            const examples = responses[key].content["application/json"].examples;
+            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 = {
+            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/dist/registerEndpoints.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEndpoints = registerEndpoints;
+const requestMatch_js_1 = require("./requestMatch.js");
+const responseRenderer_js_1 = require("./responseRenderer.js");
+const behavior_js_1 = require("./behavior.js");
+const customLogger_js_1 = require("./logger/customLogger.js");
+/**
+ * Select a response source from the first matching variant.
+ */
+function selectVariant(req, endpoint) {
+    if (!endpoint.variants || endpoint.variants.length === 0)
+        return null;
+    for (const variant of endpoint.variants) {
+        if ((0, requestMatch_js_1.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
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Build a response source from the endpoint itself.
+ */
+function selectEndpointSource(endpoint) {
+    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.
+ */
+function registerEndpoints(app, spec) {
+    for (const endpoint of spec.endpoints) {
+        app.route({
+            method: endpoint.method,
+            url: endpoint.path,
+            handler: buildEndpointHandler(spec, endpoint)
+        });
+        (0, customLogger_js_1.logEndpointRegistered)(app.log, endpoint.method, endpoint.path, endpoint.status);
+    }
+}
+/**
+ * Build a Fastify handler for a single endpoint definition.
+ */
+function buildEndpointHandler(spec, endpoint) {
+    return async (req, reply) => {
+        const variant = selectVariant(req, endpoint);
+        if (!variant && !(0, requestMatch_js_1.matchRequest)(req, endpoint.match)) {
+            reply.code(404);
+            return { error: "No matching mock for request" };
+        }
+        const source = variant ?? selectEndpointSource(endpoint);
+        const behavior = (0, behavior_js_1.resolveBehavior)(spec.settings, endpoint, source);
+        // Resolve delay (supports both delay and delayMs, with delay taking precedence)
+        const delayValue = source.delay ? (0, behavior_js_1.resolveDelay)(source.delay) : behavior.delayMs;
+        if (delayValue > 0) {
+            await (0, behavior_js_1.sleep)(delayValue);
+        }
+        const params = (0, requestMatch_js_1.toRecord)(req.params);
+        const query = (0, requestMatch_js_1.toRecord)(req.query);
+        const body = req.body;
+        const renderContext = (0, responseRenderer_js_1.createRenderContext)({ params, query, body }, spec.settings.fakerSeed);
+        if ((0, behavior_js_1.shouldFail)(behavior.errorRate)) {
+            reply.code(behavior.errorStatus);
+            return (0, responseRenderer_js_1.renderTemplateValue)(behavior.errorResponse, renderContext);
+        }
+        // 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((0, responseRenderer_js_1.renderTemplateValue)(value, renderContext))
+                    : String(value);
+                reply.header(key, renderedValue);
+            }
+        }
+        const rendered = (0, responseRenderer_js_1.renderTemplateValue)(source.response, renderContext);
+        reply.code(source.status ?? endpoint.status ?? 200);
+        return rendered;
+    };
+}