api-json-server 1.0.1 → 1.2.0

package/dist/requestMatch.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRecord = toRecord;
+exports.matchRequest = matchRequest;
+/**
+ * Safely coerce a value to a plain object record.
+ */
+/**
+ * Safely coerce a value to a plain object record.
+ */
+function toRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    return {};
+}
+/**
+ * Check if the request query matches the expected values.
+ */
+function queryMatches(req, expected) {
+    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, expected) {
+    if (!expected)
+        return true;
+    const body = req.body;
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return false;
+    const record = body;
+    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, expected) {
+    if (!expected)
+        return true;
+    // Normalize header keys to lowercase for case-insensitive matching
+    const headers = new Map();
+    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, expected) {
+    if (!expected)
+        return true;
+    const cookies = req.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.
+ */
+function matchRequest(req, match) {
+    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/dist/responseRenderer.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRenderContext = createRenderContext;
+exports.renderTemplateValue = renderTemplateValue;
+const faker_1 = require("@faker-js/faker");
+const stringTemplate_js_1 = require("./stringTemplate.js");
+/**
+ * Create a render context with an optional faker seed applied.
+ */
+function createRenderContext(ctx, fakerSeed) {
+    if (typeof fakerSeed === "number") {
+        faker_1.faker.seed(fakerSeed);
+    }
+    return { ...ctx, faker: faker_1.faker };
+}
+/**
+ * Check if a template value is a faker directive.
+ */
+function isFakerTemplate(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "__faker" in value;
+}
+/**
+ * Check if a template value is a repeat directive.
+ */
+function isRepeatTemplate(value) {
+    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, methodPath) {
+    const parts = methodPath.split(".");
+    let current = 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;
+        current = record[part];
+    }
+    if (typeof current !== "function") {
+        throw new Error(`Faker method is not callable: ${methodPath}`);
+    }
+    return current;
+}
+/**
+ * Render a faker directive to a concrete value.
+ */
+function renderFakerTemplate(template, ctx) {
+    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, ctx) {
+    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.
+ */
+function renderTemplateValue(value, ctx) {
+    if (typeof value === "string")
+        return (0, stringTemplate_js_1.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 = {};
+    for (const [key, item] of Object.entries(value)) {
+        output[key] = renderTemplateValue(item, ctx);
+    }
+    return output;
+}

package/dist/server.js

@@ -0,0 +1,210 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+const fastify_1 = __importDefault(require("fastify"));
+const registerEndpoints_js_1 = require("./registerEndpoints.js");
+const swagger_ui_dist_1 = __importDefault(require("swagger-ui-dist"));
+const openapi_js_1 = require("./openapi.js");
+const static_1 = __importDefault(require("@fastify/static"));
+const cookie_1 = __importDefault(require("@fastify/cookie"));
+const cors_1 = __importDefault(require("@fastify/cors"));
+const yaml_1 = __importDefault(require("yaml"));
+const historyRecorder_js_1 = require("./history/historyRecorder.js");
+/**
+ * Resolve the path to swagger-ui-dist assets.
+ */
+function getSwaggerUiRoot() {
+    // 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 = swagger_ui_dist_1.default;
+    if (typeof mod === "function")
+        return mod();
+    if (mod && typeof mod.getAbsoluteFSPath === "function") {
+        return mod.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, baseUrl) {
+    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.
+ */
+function buildServer(spec, meta) {
+    const app = (0, fastify_1.default)({
+        logger: meta?.logger ?? true,
+        trustProxy: true,
+        disableRequestLogging: false
+    });
+    // Register CORS if configured
+    if (spec.settings.cors) {
+        app.register(cors_1.default, {
+            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(cookie_1.default);
+    // Create history recorder
+    const history = new historyRecorder_js_1.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.startTime = startTime;
+        history.record({
+            method: req.method,
+            url: req.url,
+            path: req.routeOptions?.url ?? req.url.split("?")[0],
+            query: req.query,
+            headers: req.headers,
+            body: req.body
+        });
+    });
+    // Update history with response details in onResponse hook
+    app.addHook("onResponse", async (req, reply) => {
+        const startTime = req.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) {
+        return openApiJsonHandler(req, spec, meta?.baseUrl);
+    }
+    /**
+     * Handler for the /__openapi.yaml route.
+     */
+    function openApiYamlRouteHandler(req, reply) {
+        return openApiYamlHandler(req, reply, spec, meta?.baseUrl);
+    }
+    /**
+     * Handler for the /docs route.
+     */
+    function docsRouteHandler(req, reply) {
+        return docsHandler(req, reply);
+    }
+    // Basic sanity route
+    app.get("/health", healthHandler);
+    // Internal inspection endpoint
+    app.get("/__spec", specRouteHandler);
+    app.get("/__openapi.json", openApiJsonRouteHandler);
+    app.get("/__openapi.yaml", openApiYamlRouteHandler);
+    app.register(static_1.default, {
+        root: getSwaggerUiRoot(),
+        prefix: "/docs/assets/",
+        decorateReply: false
+    });
+    app.get("/docs", docsRouteHandler);
+    // History endpoints
+    app.get("/__history", async (req) => {
+        const query = req.query;
+        const filter = {
+            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" };
+    });
+    (0, registerEndpoints_js_1.registerEndpoints)(app, spec);
+    return app;
+}
+/**
+ * Health check handler.
+ */
+function healthHandler() {
+    return { ok: true };
+}
+/**
+ * Debug handler that exposes the current spec and metadata.
+ */
+function specHandler(spec, meta) {
+    return {
+        meta: {
+            specPath: meta?.specPath ?? null,
+            loadedAt: meta?.loadedAt ?? null
+        },
+        spec
+    };
+}
+/**
+ * Serve the OpenAPI document as JSON.
+ */
+function openApiJsonHandler(req, spec, baseUrl) {
+    const serverUrl = resolveServerUrl(req, baseUrl);
+    return (0, openapi_js_1.generateOpenApi)(spec, serverUrl);
+}
+/**
+ * Serve the OpenAPI document as YAML.
+ */
+function openApiYamlHandler(req, reply, spec, baseUrl) {
+    const serverUrl = resolveServerUrl(req, baseUrl);
+    const doc = (0, openapi_js_1.generateOpenApi)(spec, serverUrl);
+    const yaml = yaml_1.default.stringify(doc);
+    reply.type("application/yaml; charset=utf-8").send(yaml);
+}
+/**
+ * Serve the Swagger UI HTML page.
+ */
+function docsHandler(_req, reply) {
+    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/dist/spec.js

@@ -0,0 +1,146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockSpecSchema = exports.EndpointSchema = exports.VariantSchema = exports.MatchSchema = void 0;
+const z = __importStar(require("zod"));
+const PrimitiveSchema = z.union([z.string(), z.number(), z.boolean()]);
+const TemplateValueSchema = 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)
+]));
+exports.MatchSchema = z.object({
+    query: z.record(z.string(), PrimitiveSchema).optional(),
+    // Exact match for top-level body fields only (keeps v1 simple)
+    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)
+    })
+]);
+exports.VariantSchema = z.object({
+    name: z.string().min(1).optional(),
+    match: exports.MatchSchema.optional(),
+    status: z.number().int().min(100).max(599).optional(),
+    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: TemplateValueSchema.optional()
+});
+exports.EndpointSchema = z.object({
+    method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
+    path: z.string().min(1),
+    match: exports.MatchSchema.optional(),
+    variants: z.array(exports.VariantSchema).min(1).optional(),
+    // Response behavior:
+    status: z.number().int().min(200).max(599).default(200),
+    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: TemplateValueSchema.optional()
+});
+exports.MockSpecSchema = z.object({
+    version: z.literal(1),
+    settings: 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: 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(exports.EndpointSchema).min(1)
+});

package/dist/stringTemplate.js

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

package/examples/auth-variants.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../mockserve.spec.schema.json",
+  "version": 1,
+  "settings": {
+    "delayMs": 100,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" }
+  },
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/login",
+      "response": { "ok": true, "token": "tok_{{body.email}}" },
+      "variants": [
+        {
+          "name": "invalid password",
+          "match": { "body": { "password": "wrong" } },
+          "status": 401,
+          "response": { "ok": false, "error": "Invalid credentials" }
+        },
+        {
+          "name": "admin login",
+          "match": { "body": { "email": "admin@example.com" } },
+          "status": 200,
+          "response": { "ok": true, "role": "admin", "token": "tok_admin" }
+        }
+      ]
+    }
+  ]
+}

package/examples/basic-crud.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../mockserve.spec.schema.json",
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" }
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/users",
+      "response": {
+        "users": [
+          { "id": "u1", "name": "Ada Lovelace" },
+          { "id": "u2", "name": "Alan Turing" }
+        ]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/users/:id",
+      "response": {
+        "id": "{{params.id}}",
+        "message": "User fetched"
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/users",
+      "status": 201,
+      "response": {
+        "id": "u_{{body.email}}",
+        "name": "{{body.name}}",
+        "created": true
+      }
+    },
+    {
+      "method": "DELETE",
+      "path": "/users/:id",
+      "status": 204,
+      "response": { "deleted": "{{params.id}}" }
+    }
+  ]
+}