@xirconsss/zero-mock 1.0.0 → 1.1.0

package/README.md

@@ -1,37 +1,146 @@
-# Frontend Consumer Test
+# zero-mock
 
-This branch tests `zero-mock` as an end-user using the published npm package.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript&logoColor=white)](tsconfig.json)
+[![npm version](https://img.shields.io/npm/v/@xirconsss/zero-mock.svg)](https://www.npmjs.com/package/@xirconsss/zero-mock)
 
-## How to run
+**zero-mock** is a zero-config Node.js CLI that turns a JSON file into a local REST API. Point it at a file whose top-level keys are **collection names** and whose values are **arrays of records**—it serves full CRUD routes and writes changes back to disk. Built for **frontend developers** who need a quick, realistic backend for prototypes, demos, and integration tests without standing up a database or bespoke server.
 
-1. **Install the CLI globally (or run via npx):**
-   ```bash
-   npm install -g @xirconsss/zero-mock
-   ```
+## Demo
 
-2. **Start the mock server:**
-   ```bash
-   npx @xirconsss/zero-mock -- --file ./data.json --port 3000
-   ```
+![Terminal demo](docs/demo.gif)
 
-   With simulated delay (2s) and watch, use **long flags** so `npx`/`npm` never treats `-d` as its own debug flag:
+## Installation
 
-   ```bash
-   npx @xirconsss/zero-mock -- --file ./data.json --port 3000 --delay 2000 --watch
-   ```
+### Global
 
-   If you still see `required option '-f, --file' not specified`, use **`npm exec`** instead:
+```bash
+npm install -g @xirconsss/zero-mock
+```
 
-   ```bash
-   npm exec -- @xirconsss/zero-mock -- --file ./data.json --port 3000 --delay 2000
-   ```
+Run the CLI as **`zero-mock`** (see [Usage](#usage)).
 
-   Or install globally and avoid `npx` parsing entirely:
+### One-off with npx
 
-   ```bash
-   zero-mock --file ./data.json --port 3000 --delay 2000
-   ```
+```bash
+npx @xirconsss/zero-mock -f ./example/db.json -p 3000
+```
 
-3. **Run the Frontend:**
-   Simply open `index.html` in your browser.
+If your shell or npm version forwards extra flags to npm instead of the CLI, insert **`--`** before the first CLI flag (e.g. `npx @xirconsss/zero-mock -- -f ./data.json -p 3000 -w`).
 
+## Usage
+
+| Flag | Description |
+| ---- | ----------- |
+| **`-f` / `--file`** | Required. Path to the JSON file. |
+| **`-p` / `--port`** | HTTP port (default `3000`, must be 1–65535). |
+| **`-d` / `--delay`** | Optional. Delay every request by this many milliseconds. Must be a non-negative integer using digits only (default `0`). |
+| **`-w` / `--watch`** | Optional. Watch the JSON file and reload the in-memory data when it changes. If a save produces invalid JSON, the server prints `[watch] Could not reload "<path>": ...` to stderr and keeps the last good data until the file is valid again. Only one reload runs at a time. When watch starts, you also get `[watch] Watching "<path>" for changes.` on stdout. |
+
+Examples:
+
+```bash
+zero-mock -f ./data.json -p 3000 -d 200
+zero-mock -f ./data.json -w
+```
+
+## Quick start
+
+From the repo root (or any directory containing the example file):
+
+```bash
+npx @xirconsss/zero-mock -f ./example/db.json -p 3000
+```
+
+Optional:
+
+```bash
+npx @xirconsss/zero-mock -f ./example/db.json -p 3000 -d 200 -w
+```
+
+In another terminal:
+
+```bash
+curl http://localhost:3000/users
+curl http://localhost:3000/users/1
+```
+
+The server logs the exact URLs for each collection when it starts.
+
+## Development
+
+From a clone: `npm install`, then `npm run build` (or `npm run dev` with `ts-node`). Run the built CLI with:
+
+```bash
+node dist/index.js -f ./example/db.json -p 3000
+```
+
+Add `-d` / `-w` the same way as the published CLI.
+
+## Features
+
+- **Zero-config** — one JSON file defines your API surface; no schemas or generators to run.
+- **Full CRUD REST API** — `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` per collection, with CORS and JSON bodies enabled.
+- **Atomic file persistence** — writes go through a temp file and rename, with serialized saves so concurrent requests do not corrupt the file.
+- **Smart ID generation** — new rows get the next **numeric** id when existing ids are integers or all-digit strings; otherwise new ids use a **UUID**.
+- **Request logging** — each finished request logs as `[METHOD] <path> - <status>` (path is Express `req.path`, no query string).
+- **Optional delay** — `-d` adds a fixed pause before route handling (after JSON body parsing).
+- **List filtering and pagination** — see [List GET](#list-get) on `GET /{resource}`.
+- **Watch mode** — `-w` reloads data from disk on file change without restarting the process (see [Usage](#usage)).
+
+## Auto-generated API
+
+Each **top-level key** in your JSON (e.g. `users`, `posts`) becomes a **resource** name. Replace `{resource}` with that key and `{id}` with a row’s `id` (string params match numeric ids loosely).
+
+| Method   | Path                 | Description |
+| -------- | -------------------- | ----------- |
+| `GET`    | `/{resource}`        | List items (optionally [filtered and paginated](#list-get)). |
+| `POST`   | `/{resource}`        | Create an item; server assigns `id` and returns `201` with the new body. |
+| `GET`    | `/{resource}/{id}`   | Return one item by `id`; `404` if missing. |
+| `PUT`    | `/{resource}/{id}`   | Replace the item; `id` in the URL wins; `404` if missing. |
+| `PATCH`  | `/{resource}/{id}`   | Shallow-merge fields into the item; `404` if missing. |
+| `DELETE` | `/{resource}/{id}`   | Remove the item; `204` on success; `404` if missing. |
+
+Invalid JSON bodies (non-objects for write routes) receive **`400`** with a JSON error message. Persistence failures surface as **`500`**.
+
+### List GET
+
+**Filtering:** Every query parameter except `_page` and `_limit` is a filter. Only plain-object rows are kept. For each filter key, the row must have that property, and the value must match the query value with loose equality (`==`). Query values are strings (first value wins if repeated). Rows missing a filter key are dropped.
+
+**Pagination:** If **both** `_page` and `_limit` are present and are positive integers (digit strings only), the list is sliced after filtering. `_page` is 1-based. If either is missing or invalid, the full filtered list is returned (no error).
+
+Examples using [example/db.json](example/db.json):
+
+```bash
+curl 'http://localhost:3000/users?role=admin'
+curl 'http://localhost:3000/users?_page=1&_limit=2'
+```
+
+## JSON file shape
+
+The root must be a JSON **object**. Each property must be an **array** (your “tables”). Each item you want to address by URL should include an **`id`** field (number or string).
+
+## Publishing to npm (maintainers)
+
+**Release flow (recommended):** Automated via `semantic-release`. Commits following the conventional commit format (e.g., `feat:`, `fix:`) pushed to `main` will automatically trigger a version bump, changelog generation, and NPM publish via the [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) workflow. Avoid running `npm publish` on your machine.
+
+1. Use an [npmjs.com](https://www.npmjs.com/) account with **2FA** enabled and permission to publish the **`@xirconsss`** scope (user or org on npm).
+2. **GitHub:** repo → **Settings** → **Environments** → **`NPM_TOKEN`** → add secret **`NPM_TOKEN`** (see token steps below). The workflow uses that environment on each run.
+3. Push conventional commits to **`main`**, wait for **Publish to npm** to finish. Check with `npm view @xirconsss/zero-mock version`.
+
+**Token on npm (required for CI):**
+
+1. Create a classic **[Automation](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-classic-tokens)** token, **or** a **[granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens)** with **read and write** on **`@xirconsss/zero-mock`** (and org **`xirconsss`** if npm asks).
+2. For granular tokens: turn **Bypass two-factor authentication (2FA)** **on** so CI does not hit **`EOTP`**. Do **not** use **`NPM_OTP`** secrets (codes expire in ~30 seconds).
+3. Paste the token into the **`NPM_TOKEN`** environment secret on GitHub.
+
+**Optional — OIDC trusted publishing:** You can later move to [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) and drop the secret; if you see **`E404`** on `PUT` with OIDC, the Trusted Publisher settings on npm (repo, workflow filename, environment name) do not match this workflow—token auth avoids that until it is configured correctly.
+
+## License
+
+MIT - see [LICENSE](LICENSE).
+
+## Links
+
+- **Repository:** [github.com/xircons/zero-mock](https://github.com/xircons/zero-mock)
+- **Issues:** [github.com/xircons/zero-mock/issues](https://github.com/xircons/zero-mock/issues)

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = require("fs");
+const chokidar_1 = __importDefault(require("chokidar"));
 const commander_1 = require("commander");
 const jsonStore_1 = require("./store/jsonStore");
 const bootstrap_1 = require("./server/bootstrap");
@@ -13,33 +16,29 @@ function parseDelayMs(raw) {
     return Number.parseInt(trimmed, 10);
 }
 function startFileWatcher(filePath) {
-    let reloadInFlight = false;
+    let reloadTimeout = null;
     const reload = async () => {
-        if (reloadInFlight) {
-            return;
-        }
-        reloadInFlight = true;
         try {
             await jsonStore_1.JsonStore.load(filePath);
+            console.log(`[watch] Reloaded "${filePath}".`);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             console.error(`[watch] Could not reload "${filePath}": ${message}`);
         }
-        finally {
-            reloadInFlight = false;
-        }
     };
-    try {
-        (0, fs_1.watch)(filePath, { persistent: true }, () => {
-            void reload();
-        });
-        console.log(`[watch] Watching "${filePath}" for changes.`);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`[watch] Failed to watch "${filePath}": ${message}`);
-    }
+    chokidar_1.default
+        .watch(filePath, { persistent: true, ignoreInitial: true })
+        .on("change", () => {
+        if (reloadTimeout)
+            clearTimeout(reloadTimeout);
+        reloadTimeout = setTimeout(() => void reload(), 100);
+    })
+        .on("error", (err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[watch] Watcher error: ${msg}`);
+    });
+    console.log(`[watch] Watching "${filePath}" for changes.`);
 }
 const program = new commander_1.Command();
 program
@@ -49,6 +48,9 @@ program
     .option("-p, --port <number>", "HTTP port", "3000")
     .option("-d, --delay <ms>", "delay each request by this many ms (0 = off)", "0")
     .option("-w, --watch", "reload JSON from disk when the file changes", false)
+    .option("--cors-origin <origins>", "comma-separated list of allowed origins (e.g., http://localhost:3000)", "*")
+    .option("--cors-methods <methods>", "comma-separated list of allowed HTTP methods", "GET,HEAD,PUT,PATCH,POST,DELETE")
+    .option("--cors-credentials", "enable CORS credentials (cookies, authorization headers)", false)
     .action(async (opts) => {
     const port = Number.parseInt(opts.port, 10);
     if (Number.isNaN(port) || port < 1 || port > 65535) {
@@ -73,7 +75,12 @@ program
         return;
     }
     try {
-        await (0, bootstrap_1.bootstrap)(port, { delayMs });
+        await (0, bootstrap_1.bootstrap)(port, {
+            delayMs,
+            corsOrigin: opts.corsOrigin,
+            corsMethods: opts.corsMethods,
+            corsCredentials: opts.corsCredentials,
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/server/app.js

@@ -12,7 +12,7 @@ const errorHandler = (err, _req, res, _next) => {
         return;
     }
     const message = err instanceof Error ? err.message : String(err);
-    res.status(500).json({ error: message });
+    res.status(500).json({ error: "INTERNAL_SERVER_ERROR", message, statusCode: 500 });
 };
 function requestLoggingMiddleware(req, res, next) {
     res.on("finish", () => {
@@ -31,7 +31,11 @@ function delayMiddleware(delayMs) {
 }
 function createApp(options) {
     const app = (0, express_1.default)();
-    app.use((0, cors_1.default)());
+    app.use((0, cors_1.default)({
+        origin: options.corsOrigin && options.corsOrigin !== "*" ? options.corsOrigin.split(",") : "*",
+        methods: options.corsMethods || "GET,HEAD,PUT,PATCH,POST,DELETE",
+        credentials: options.corsCredentials || false,
+    }));
     app.use(express_1.default.json());
     app.use(requestLoggingMiddleware);
     app.use(delayMiddleware(options.delayMs));

package/dist/server/routes/dynamicRouter.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildDynamicRouter = buildDynamicRouter;
 const crypto_1 = require("crypto");
 const express_1 = __importDefault(require("express"));
+const zod_1 = require("zod");
 const jsonStore_1 = require("../../store/jsonStore");
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -44,27 +45,73 @@ function parsePagination(query) {
     return { page, limit };
 }
 function filterCollection(items, query) {
-    const filterEntries = Object.entries(query).filter(([k]) => k !== "_page" && k !== "_limit");
+    let result = items;
+    // Sorting
+    const sort = firstQueryValue(query["_sort"]);
+    const order = firstQueryValue(query["_order"])?.toLowerCase() === "desc" ? -1 : 1;
+    if (sort) {
+        result = [...result].sort((a, b) => {
+            if (!isPlainObject(a) || !isPlainObject(b))
+                return 0;
+            const valA = a[sort];
+            const valB = b[sort];
+            if (valA === valB)
+                return 0;
+            if (valA === undefined)
+                return order;
+            if (valB === undefined)
+                return -order;
+            if (typeof valA === "number" && typeof valB === "number")
+                return (valA - valB) * order;
+            return String(valA).localeCompare(String(valB)) * order;
+        });
+    }
+    const filterEntries = Object.entries(query).filter(([k]) => !["_page", "_limit", "_sort", "_order"].includes(k));
     if (filterEntries.length === 0) {
-        return items;
+        return result;
     }
-    return items.filter((item) => {
+    return result.filter((item) => {
         if (!isPlainObject(item)) {
             return false;
         }
         const rec = item;
         for (const [key, qVal] of filterEntries) {
             const want = firstQueryValue(qVal);
-            if (want === undefined) {
+            if (want === undefined)
                 continue;
+            let field = key;
+            let op = "eq";
+            if (key.endsWith("_gte")) {
+                field = key.slice(0, -4);
+                op = "gte";
             }
-            if (!Object.prototype.hasOwnProperty.call(rec, key)) {
-                return false;
+            else if (key.endsWith("_lte")) {
+                field = key.slice(0, -4);
+                op = "lte";
             }
-            if (rec[key] == want) {
-                continue;
+            else if (key.endsWith("_like")) {
+                field = key.slice(0, -5);
+                op = "like";
+            }
+            const actual = rec[field];
+            if (op === "eq") {
+                if (actual != want)
+                    return false;
+            }
+            else if (op === "gte") {
+                if (Number(actual) < Number(want))
+                    return false;
+            }
+            else if (op === "lte") {
+                if (Number(actual) > Number(want))
+                    return false;
+            }
+            else if (op === "like") {
+                if (actual === undefined || actual === null)
+                    return false;
+                if (!String(actual).toLowerCase().includes(String(want).toLowerCase()))
+                    return false;
             }
-            return false;
         }
         return true;
     });
@@ -98,6 +145,43 @@ function itemNotFound(res, resource, id) {
 function badBody(res) {
     res.status(400).json({ error: "Request body must be a JSON object." });
 }
+/**
+ * Infer a zod schema from the first item in a collection.
+ * Returns null if the collection is empty (skip validation).
+ * The schema is "partial" so that POST/PATCH with missing optional fields still pass —
+ * only fields that ARE present are type-checked.
+ */
+function inferSchema(collection) {
+    const first = collection.find(isPlainObject);
+    if (!first)
+        return null;
+    const shape = {};
+    for (const [key, value] of Object.entries(first)) {
+        if (key === "id")
+            continue;
+        if (typeof value === "string")
+            shape[key] = zod_1.z.string();
+        else if (typeof value === "number")
+            shape[key] = zod_1.z.number();
+        else if (typeof value === "boolean")
+            shape[key] = zod_1.z.boolean();
+        else
+            shape[key] = zod_1.z.unknown();
+    }
+    return zod_1.z.object(shape).partial();
+}
+function validateBody(res, collection, body) {
+    const schema = inferSchema(collection);
+    if (!schema)
+        return true; // empty collection → skip
+    const result = schema.safeParse(body);
+    if (!result.success) {
+        const messages = result.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`);
+        res.status(400).json({ error: "Validation failed.", details: messages });
+        return false;
+    }
+    return true;
+}
 function numericIdValue(id) {
     if (typeof id === "number" && Number.isFinite(id) && Number.isInteger(id)) {
         return id;
@@ -164,6 +248,8 @@ function buildDynamicRouter() {
                 return;
             }
             const collection = jsonStore_1.JsonStore.getData()[resource];
+            if (!validateBody(res, collection, req.body))
+                return;
             const newId = nextIdForCollection(collection);
             const rawBody = req.body;
             const rest = { ...rawBody };
@@ -180,6 +266,8 @@ function buildDynamicRouter() {
             }
             const { id: idParam } = req.params;
             const collection = jsonStore_1.JsonStore.getData()[resource];
+            if (!validateBody(res, collection, req.body))
+                return;
             const index = findIndexById(collection, idParam);
             if (index === -1) {
                 itemNotFound(res, resource, idParam);
@@ -202,6 +290,8 @@ function buildDynamicRouter() {
             }
             const { id: idParam } = req.params;
             const collection = jsonStore_1.JsonStore.getData()[resource];
+            if (!validateBody(res, collection, req.body))
+                return;
             const index = findIndexById(collection, idParam);
             if (index === -1) {
                 itemNotFound(res, resource, idParam);

package/dist/store/jsonStore.js

@@ -31,9 +31,22 @@ function parseJsonStorePayload(raw, filePath) {
 class JsonStoreImpl {
     data = {};
     backingPath = null;
+    lockPath = null;
     /** Serializes concurrent save() calls so writes are not interleaved. */
     saveChain = Promise.resolve();
     async load(filePath) {
+        const lockPath = filePath + ".zero-mock.lock";
+        try {
+            await (0, promises_1.access)(lockPath);
+            console.warn(`[warn] Lock file found: "${lockPath}". ` +
+                `Another zero-mock process may be running on this file. ` +
+                `If not, delete the lock file and retry.`);
+        }
+        catch {
+            await (0, promises_1.writeFile)(lockPath, String(process.pid), "utf8");
+            this.lockPath = lockPath;
+            this._registerLockCleanup();
+        }
         let raw;
         try {
             raw = await (0, promises_1.readFile)(filePath, "utf8");
@@ -48,6 +61,19 @@ class JsonStoreImpl {
         this.data = parseJsonStorePayload(raw, filePath);
         this.backingPath = filePath;
     }
+    _registerLockCleanup() {
+        const cleanup = () => {
+            if (this.lockPath) {
+                try {
+                    require("fs").unlinkSync(this.lockPath);
+                }
+                catch (_) { }
+            }
+        };
+        process.once("exit", cleanup);
+        process.once("SIGINT", () => { cleanup(); process.exit(130); });
+        process.once("SIGTERM", () => { cleanup(); process.exit(143); });
+    }
     getData() {
         return this.data;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xirconsss/zero-mock",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-config CLI that generates REST APIs from JSON files",
   "license": "MIT",
   "keywords": [
@@ -47,9 +47,11 @@
   },
   "homepage": "https://github.com/xircons/zero-mock#readme",
   "dependencies": {
+    "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.5",
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.0.2",