@xirconsss/zero-mock 0.1.0 → 0.2.0

package/README.md

@@ -2,16 +2,20 @@
 
 [![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/@xircons/zero-mock.svg)](https://www.npmjs.com/package/@xircons/zero-mock)
+[![npm version](https://img.shields.io/npm/v/@xirconsss/zero-mock.svg)](https://www.npmjs.com/package/@xirconsss/zero-mock)
 
 **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.
 
+## Demo
+
+![Terminal demo](docs/demo.gif)
+
 ## Installation
 
 ### Global
 
 ```bash
-npm install -g @xircons/zero-mock
+npm install -g @xirconsss/zero-mock
 ```
 
 Run the CLI as **`zero-mock`** (see [Usage](#usage)).
@@ -19,17 +23,39 @@ Run the CLI as **`zero-mock`** (see [Usage](#usage)).
 ### One-off with npx
 
 ```bash
-npx @xircons/zero-mock -f ./data.json -p 3000
+npx @xirconsss/zero-mock -f ./example/db.json -p 3000
 ```
 
-Flags: **`-f`** / **`--file`** (required JSON path), **`-p`** / **`--port`** (optional, default `3000`). If your shell or npm version forwards extra flags to npm instead of the CLI, insert **`--`** before **`-f`** (e.g. `npx @xircons/zero-mock -- -f ./data.json`).
+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 @xircons/zero-mock -f ./example/db.json -p 3000
+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:
@@ -41,12 +67,26 @@ 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
 
@@ -54,7 +94,7 @@ Each **top-level key** in your JSON (e.g. `users`, `posts`) becomes a **resource
 
 | Method   | Path                 | Description |
 | -------- | -------------------- | ----------- |
-| `GET`    | `/{resource}`        | List all items in the collection. |
+| `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. |
@@ -63,13 +103,43 @@ Each **top-level key** in your JSON (e.g. `users`, `posts`) becomes a **resource
 
 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)
+
+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. Log in locally: `npm login` (or `npm login --auth-type=web`).
+3. Install deps and build: `npm install` (so `tsc` is available), then bump **`version`** in `package.json` when releasing.
+4. Publish: `npm publish` (`publishConfig.access` is already `public` for this scoped package).
+
+**GitHub Actions:** the workflow [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) runs on **workflow_dispatch** or when a **GitHub Release** is published. It uses the GitHub **Environment** named **`NPM_TOKEN`** with a secret also named **`NPM_TOKEN`** (repo → **Settings** → **Environments** → **NPM_TOKEN** → **Environment secrets**).
+
+**Token on npm (required):**
+
+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, then run the workflow.
+
+**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).
+MIT - see [LICENSE](LICENSE).
 
 ## Links
 

package/dist/index.js

@@ -1,15 +1,54 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
 const commander_1 = require("commander");
 const jsonStore_1 = require("./store/jsonStore");
 const bootstrap_1 = require("./server/bootstrap");
+function parseDelayMs(raw) {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        return null;
+    }
+    return Number.parseInt(trimmed, 10);
+}
+function startFileWatcher(filePath) {
+    let reloadInFlight = false;
+    const reload = async () => {
+        if (reloadInFlight) {
+            return;
+        }
+        reloadInFlight = true;
+        try {
+            await jsonStore_1.JsonStore.load(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}`);
+    }
+}
 const program = new commander_1.Command();
 program
     .name("zero-mock")
     .description("Generate a REST API from a JSON file")
     .requiredOption("-f, --file <path>", "path to the source JSON file")
     .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)
     .action(async (opts) => {
     const port = Number.parseInt(opts.port, 10);
     if (Number.isNaN(port) || port < 1 || port > 65535) {
@@ -17,6 +56,12 @@ program
         process.exit(1);
         return;
     }
+    const delayMs = parseDelayMs(opts.delay);
+    if (delayMs === null) {
+        console.error("error: --delay must be a non-negative integer");
+        process.exit(1);
+        return;
+    }
     const filePath = opts.file;
     try {
         await jsonStore_1.JsonStore.load(filePath);
@@ -28,12 +73,16 @@ program
         return;
     }
     try {
-        await (0, bootstrap_1.bootstrap)(port);
+        await (0, bootstrap_1.bootstrap)(port, { delayMs });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         console.error(`Failed to start server: ${message}`);
         process.exit(1);
+        return;
+    }
+    if (opts.watch) {
+        startFileWatcher(filePath);
     }
 });
 program.parse(process.argv);

package/dist/server/app.js

@@ -14,10 +14,27 @@ const errorHandler = (err, _req, res, _next) => {
     const message = err instanceof Error ? err.message : String(err);
     res.status(500).json({ error: message });
 };
-function createApp() {
+function requestLoggingMiddleware(req, res, next) {
+    res.on("finish", () => {
+        console.log(`[${req.method}] ${req.path} - ${res.statusCode}`);
+    });
+    next();
+}
+function delayMiddleware(delayMs) {
+    return (_req, _res, next) => {
+        if (delayMs <= 0) {
+            next();
+            return;
+        }
+        setTimeout(() => next(), delayMs);
+    };
+}
+function createApp(options) {
     const app = (0, express_1.default)();
     app.use((0, cors_1.default)());
     app.use(express_1.default.json());
+    app.use(requestLoggingMiddleware);
+    app.use(delayMiddleware(options.delayMs));
     app.use("/", (0, dynamicRouter_1.buildDynamicRouter)());
     app.use(errorHandler);
     return app;

package/dist/server/bootstrap.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.bootstrap = bootstrap;
 const app_1 = require("./app");
 const jsonStore_1 = require("../store/jsonStore");
-async function bootstrap(port) {
-    const app = (0, app_1.createApp)();
+async function bootstrap(port, appOptions) {
+    const app = (0, app_1.createApp)(appOptions);
     await new Promise((resolve, reject) => {
         const server = app.listen(port, () => {
             resolve();

package/dist/server/routes/dynamicRouter.js

@@ -10,6 +10,65 @@ const jsonStore_1 = require("../../store/jsonStore");
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function firstQueryValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return firstQueryValue(value[0]);
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "object") {
+        return undefined;
+    }
+    return String(value);
+}
+function parsePagination(query) {
+    const pageRaw = firstQueryValue(query["_page"]);
+    const limitRaw = firstQueryValue(query["_limit"]);
+    if (pageRaw === undefined || limitRaw === undefined) {
+        return null;
+    }
+    const pageTrim = pageRaw.trim();
+    const limitTrim = limitRaw.trim();
+    if (!/^\d+$/.test(pageTrim) || !/^\d+$/.test(limitTrim)) {
+        return null;
+    }
+    const page = Number.parseInt(pageTrim, 10);
+    const limit = Number.parseInt(limitTrim, 10);
+    if (page < 1 || limit < 1) {
+        return null;
+    }
+    return { page, limit };
+}
+function filterCollection(items, query) {
+    const filterEntries = Object.entries(query).filter(([k]) => k !== "_page" && k !== "_limit");
+    if (filterEntries.length === 0) {
+        return items;
+    }
+    return items.filter((item) => {
+        if (!isPlainObject(item)) {
+            return false;
+        }
+        const rec = item;
+        for (const [key, qVal] of filterEntries) {
+            const want = firstQueryValue(qVal);
+            if (want === undefined) {
+                continue;
+            }
+            if (!Object.prototype.hasOwnProperty.call(rec, key)) {
+                return false;
+            }
+            if (rec[key] == want) {
+                continue;
+            }
+            return false;
+        }
+        return true;
+    });
+}
 function isRecordWithId(item) {
     if (item === null || typeof item !== "object" || Array.isArray(item)) {
         return false;
@@ -88,8 +147,16 @@ function buildDynamicRouter() {
             }
             res.json(item);
         }));
-        router.get(`/${resource}`, (_req, res) => {
-            res.json(jsonStore_1.JsonStore.getData()[resource]);
+        router.get(`/${resource}`, (req, res) => {
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const query = req.query;
+            let rows = filterCollection(collection, query);
+            const pageInfo = parsePagination(query);
+            if (pageInfo !== null) {
+                const start = (pageInfo.page - 1) * pageInfo.limit;
+                rows = rows.slice(start, start + pageInfo.limit);
+            }
+            res.json(rows);
         });
         router.post(`/${resource}`, asyncHandler(async (req, res) => {
             if (!isPlainObject(req.body)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xirconsss/zero-mock",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-config CLI that generates REST APIs from JSON files",
   "license": "MIT",
   "keywords": [
@@ -41,6 +41,7 @@
   "bugs": {
     "url": "https://github.com/xircons/zero-mock/issues"
   },
+  "homepage": "https://github.com/xircons/zero-mock#readme",
   "dependencies": {
     "commander": "^13.1.0",
     "cors": "^2.8.5",