api-json-server 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,286 @@
+# mockserve
+
+A mock API server driven by a JSON spec. It is designed for fast development, repeatable mock data, and clear documentation with OpenAPI output and Swagger UI.
+
+## Highlights
+
+- JSON spec defines endpoints, responses, and matching rules.
+- Built-in templating for request params, query, and body.
+- Faker-powered data generation with arrays and ranges.
+- Variants with match rules for alternate responses.
+- Error and latency simulation.
+- OpenAPI JSON/YAML plus Swagger UI out of the box.
+
+## Installation
+
+```
+npm install
+```
+
+## Quick Start
+
+1) Create a spec file (example `mock.spec.json`):
+
+```
+{
+  "version": 1,
+  "settings": {
+    "delayMs": 0,
+    "errorRate": 0,
+    "errorStatus": 500,
+    "errorResponse": { "error": "Mock error" }
+  },
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/users/:id",
+      "response": {
+        "id": "{{params.id}}",
+        "type": "{{query.type}}"
+      }
+    }
+  ]
+}
+```
+
+2) Start the server:
+
+```
+npm run dev -- serve --spec mock.spec.json
+```
+
+3) Test the endpoint:
+
+```
+curl "http://localhost:3000/users/42?type=basic"
+```
+
+## CLI
+
+```
+mockserve serve --spec mock.spec.json --port 3000 --watch
+```
+
+Options:
+
+- `--spec <path>`: Path to the JSON spec (default `mock.spec.json`).
+- `--port <number>`: Port to run on (default `3000`).
+- `--watch` / `--no-watch`: Reload when spec changes (default: watch enabled).
+- `--base-url <url>`: Base URL used in OpenAPI `servers[]`.
+
+## Spec Reference
+
+The spec is validated by `mockserve.spec.schema.json`. It is composed of:
+
+```
+{
+  "version": 1,
+  "settings": { ... },
+  "endpoints": [ ... ]
+}
+```
+
+### Settings
+
+```
+{
+  "delayMs": 0,
+  "errorRate": 0,
+  "errorStatus": 500,
+  "errorResponse": { "error": "Mock error" },
+  "fakerSeed": 123
+}
+```
+
+- `delayMs`: Adds artificial latency in milliseconds.
+- `errorRate`: Probability of returning `errorResponse` (0.0 to 1.0).
+- `errorStatus`: HTTP status code for errors.
+- `errorResponse`: Response used when errors are triggered (supports templates).
+- `fakerSeed`: Optional seed for deterministic faker output.
+
+### Endpoints
+
+```
+{
+  "method": "GET",
+  "path": "/users/:id",
+  "match": { "query": { "type": "premium" } },
+  "status": 200,
+  "response": { ... },
+  "delayMs": 0,
+  "errorRate": 0,
+  "errorStatus": 500,
+  "errorResponse": { "error": "Mock error" },
+  "variants": [ ... ]
+}
+```
+
+- `method`: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
+- `path`: Fastify style params (`/users/:id`).
+- `match`: Optional match rules (query and body).
+- `status`: Default status (default `200`).
+- `response`: Response body template.
+- `delayMs`, `errorRate`, `errorStatus`, `errorResponse`: Optional overrides per endpoint.
+- `variants`: Optional array of alternative responses with their own match rules.
+
+### Match Rules
+
+```
+"match": {
+  "query": { "type": "premium" },
+  "body": { "password": "secret" }
+}
+```
+
+Matching is exact at the top level (strings, numbers, booleans). If a request does not satisfy match rules, the endpoint returns a `404` with `{ "error": "No matching mock for request" }`.
+
+### Variants
+
+Variants let you specify alternate responses based on match rules. The first matching variant wins.
+
+```
+"variants": [
+  {
+    "name": "invalid password",
+    "match": { "body": { "password": "wrong" } },
+    "status": 401,
+    "response": { "ok": false, "error": "Invalid credentials" }
+  }
+]
+```
+
+### Response Templates
+
+Responses support a mix of static values, request placeholders, faker directives, and repeat directives.
+
+#### String placeholders
+
+- `{{params.id}}`
+- `{{query.type}}`
+- `{{body.email}}`
+
+```
+{
+  "id": "{{params.id}}",
+  "type": "{{query.type}}",
+  "email": "{{body.email}}"
+}
+```
+
+#### Faker directives
+
+Use any `@faker-js/faker` method via a dotted path:
+
+```
+{ "__faker": "person.firstName" }
+{ "__faker": "internet.email" }
+{ "__faker": { "method": "string.alpha", "args": [16] } }
+```
+
+#### Repeat directives
+
+Repeat directives generate arrays of items:
+
+```
+{
+  "__repeat": {
+    "min": 10,
+    "max": 15,
+    "template": { "id": { "__faker": "string.uuid" } }
+  }
+}
+```
+
+You can also use a fixed `count`:
+
+```
+{
+  "__repeat": {
+    "count": 3,
+    "template": { "name": { "__faker": "company.name" } }
+  }
+}
+```
+
+Notes:
+
+- If `count` is provided, it is used as-is.
+- If `min` is omitted, it defaults to `0`.
+- If `max` is missing, `min` is used.
+- If `max < min`, the server returns a `500` error.
+
+## Example: Users List with Faker
+
+```
+{
+  "method": "GET",
+  "path": "/users",
+  "response": {
+    "users": {
+      "__repeat": {
+        "min": 10,
+        "max": 15,
+        "template": {
+          "id": { "__faker": "string.uuid" },
+          "firstName": { "__faker": "person.firstName" },
+          "lastName": { "__faker": "person.lastName" },
+          "avatarUrl": { "__faker": "image.avatar" },
+          "phone": { "__faker": "phone.number" },
+          "email": { "__faker": "internet.email" },
+          "company": { "__faker": "company.name" },
+          "joinedAt": { "__faker": { "method": "date.recent", "args": [30] } }
+        }
+      }
+    }
+  }
+}
+```
+
+## OpenAPI and Swagger UI
+
+Endpoints available:
+
+- `GET /__openapi.json`
+- `GET /__openapi.yaml`
+- `GET /docs`
+- `GET /__spec`
+- `GET /health`
+
+`/docs` serves Swagger UI backed by the generated OpenAPI document.
+
+## Examples Folder
+
+See `examples/` for ready-to-use specs:
+
+- `examples/basic-crud.json`
+- `examples/auth-variants.json`
+- `examples/users-faker.json`
+- `examples/companies-nested.json`
+- `examples/orders-and-matches.json`
+
+## Programmatic Usage
+
+```
+import { buildServer } from "./dist/server.js";
+import { loadSpecFromFile } from "./dist/loadSpec.js";
+
+const spec = await loadSpecFromFile("mock.spec.json");
+const app = buildServer(spec, { specPath: "mock.spec.json", loadedAt: new Date().toISOString() });
+await app.listen({ port: 3000 });
+```
+
+## Running Tests
+
+```
+npm test
+```
+
+## Tips
+
+- Use `fakerSeed` for deterministic outputs in demos and tests.
+- Combine placeholders with faker for realistic and contextual data.
+- Keep variant rules specific; the first match wins.
+
+## License
+
+ISC

package/dist/behavior.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+exports.shouldFail = shouldFail;
+exports.resolveBehavior = resolveBehavior;
+/**
+ * Pause for the given number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Decide whether a request should fail based on an error rate.
+ */
+function shouldFail(errorRate) {
+    if (errorRate <= 0)
+        return false;
+    if (errorRate >= 1)
+        return true;
+    return Math.random() < errorRate;
+}
+/**
+ * Resolve behavior settings with precedence: chosen overrides -> endpoint overrides -> global settings.
+ */
+function resolveBehavior(settings, endpointOverrides, chosenOverrides) {
+    return {
+        delayMs: chosenOverrides?.delayMs ?? endpointOverrides?.delayMs ?? settings.delayMs,
+        errorRate: chosenOverrides?.errorRate ?? endpointOverrides?.errorRate ?? settings.errorRate,
+        errorStatus: chosenOverrides?.errorStatus ?? endpointOverrides?.errorStatus ?? settings.errorStatus,
+        errorResponse: chosenOverrides?.errorResponse ?? endpointOverrides?.errorResponse ?? settings.errorResponse
+    };
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
 const program = new commander_1.Command();
 program
     .name("mockserve")
@@ -12,10 +13,119 @@ 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)")
+    .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;
+    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);
+        console.log(`Loaded spec v${spec.version} with ${spec.endpoints.length} endpoint(s).`);
+        const nextApp = buildServer(spec, { specPath, loadedAt, baseUrl: opts.baseUrl });
+        try {
+            await nextApp.listen({ port, host: "0.0.0.0" });
+        }
+        catch (err) {
+            nextApp.log.error(err);
+            throw err;
+        }
+        nextApp.log.info(`Mock server running on http://localhost:${port}`);
+        nextApp.log.info(`Spec: ${specPath} (loadedAt=${loadedAt})`);
+        return nextApp;
+    }
+    /**
+     * Reload the server when the spec changes.
+     */
+    async function reload() {
+        if (isReloading)
+            return;
+        isReloading = true;
+        try {
+            console.log("Reloading spec...");
+            // 1) Stop accepting requests on the old server FIRST
+            if (app) {
+                console.log("Closing current server...");
+                await app.close();
+                console.log("Current server closed.");
+                app = null;
+            }
+            // 2) Start a new server on the same port with the updated spec
+            app = await startWithSpec();
+            console.log("Reload complete.");
+        }
+        catch (err) {
+            console.error("Reload failed.");
+            // At this point the old server may already be closed. We want visibility.
+            console.error(String(err));
+            // Optional: try to start again to avoid being down
+            try {
+                if (!app) {
+                    console.log("Attempting to start server again after reload failure...");
+                    app = await startWithSpec();
+                    console.log("Recovery start succeeded.");
+                }
+            }
+            catch (err2) {
+                console.error("Recovery start failed. Server is down until next successful reload.");
+                console.error(String(err2));
+            }
+        }
+        finally {
+            isReloading = false;
+        }
+    }
+    // Initial start
+    try {
+        app = await startWithSpec();
+    }
+    catch (err) {
+        console.error(String(err));
+        process.exit(1);
+    }
+    // Watch spec for changes
+    /**
+     * Handle file changes with a debounced reload.
+     */
+    function onSpecChange() {
+        debounceTimer = scheduleReload(reload, debounceTimer);
+    }
+    if (opts.watch) {
+        console.log(`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 {
+        console.log("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/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
+    };
+}