@xirconsss/zero-mock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xircons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# zero-mock
+
+[![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)
+
+**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.
+
+## Installation
+
+### Global
+
+```bash
+npm install -g @xircons/zero-mock
+```
+
+Run the CLI as **`zero-mock`** (see [Usage](#usage)).
+
+### One-off with npx
+
+```bash
+npx @xircons/zero-mock -f ./data.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`).
+
+## Quick start
+
+From the repo root (or any directory containing the example file):
+
+```bash
+npx @xircons/zero-mock -f ./example/db.json -p 3000
+```
+
+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.
+
+## 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**.
+
+## 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 all items in the collection. |
+| `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`**.
+
+## 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).
+
+## 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

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const jsonStore_1 = require("./store/jsonStore");
+const bootstrap_1 = require("./server/bootstrap");
+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")
+    .action(async (opts) => {
+    const port = Number.parseInt(opts.port, 10);
+    if (Number.isNaN(port) || port < 1 || port > 65535) {
+        console.error("error: --port must be a number between 1 and 65535");
+        process.exit(1);
+        return;
+    }
+    const filePath = opts.file;
+    try {
+        await jsonStore_1.JsonStore.load(filePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(message);
+        process.exit(1);
+        return;
+    }
+    try {
+        await (0, bootstrap_1.bootstrap)(port);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Failed to start server: ${message}`);
+        process.exit(1);
+    }
+});
+program.parse(process.argv);

package/dist/server/app.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
+const cors_1 = __importDefault(require("cors"));
+const express_1 = __importDefault(require("express"));
+const dynamicRouter_1 = require("./routes/dynamicRouter");
+const errorHandler = (err, _req, res, _next) => {
+    if (res.headersSent) {
+        return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    res.status(500).json({ error: message });
+};
+function createApp() {
+    const app = (0, express_1.default)();
+    app.use((0, cors_1.default)());
+    app.use(express_1.default.json());
+    app.use("/", (0, dynamicRouter_1.buildDynamicRouter)());
+    app.use(errorHandler);
+    return app;
+}

package/dist/server/bootstrap.js

@@ -0,0 +1,22 @@
+"use strict";
+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)();
+    await new Promise((resolve, reject) => {
+        const server = app.listen(port, () => {
+            resolve();
+        });
+        server.on("error", reject);
+    });
+    const base = `http://localhost:${port}`;
+    console.log(`🚀 Server is running at ${base}`);
+    console.log("Read/write API: GET, POST, PUT, PATCH, DELETE are active for each resource below.\n");
+    for (const resource of Object.keys(jsonStore_1.JsonStore.getData())) {
+        console.log(`  ${resource}`);
+        console.log(`    GET    POST              ${base}/${resource}`);
+        console.log(`    GET    PUT   PATCH DELETE  ${base}/${resource}/:id`);
+    }
+}

package/dist/server/routes/dynamicRouter.js

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDynamicRouter = buildDynamicRouter;
+const crypto_1 = require("crypto");
+const express_1 = __importDefault(require("express"));
+const jsonStore_1 = require("../../store/jsonStore");
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRecordWithId(item) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+        return false;
+    }
+    const rec = item;
+    return Object.prototype.hasOwnProperty.call(rec, "id");
+}
+function findItemById(items, idParam) {
+    return items.find((item) => {
+        if (!isRecordWithId(item)) {
+            return false;
+        }
+        return item.id == idParam;
+    });
+}
+function findIndexById(items, idParam) {
+    return items.findIndex((item) => {
+        if (!isRecordWithId(item)) {
+            return false;
+        }
+        return item.id == idParam;
+    });
+}
+function itemNotFound(res, resource, id) {
+    res.status(404).json({ error: `No item with id "${id}" in "${resource}".` });
+}
+function badBody(res) {
+    res.status(400).json({ error: "Request body must be a JSON object." });
+}
+function numericIdValue(id) {
+    if (typeof id === "number" && Number.isFinite(id) && Number.isInteger(id)) {
+        return id;
+    }
+    if (typeof id === "string" && /^\d+$/.test(id)) {
+        const n = Number.parseInt(id, 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+/**
+ * Next id: max numeric id + 1 among items with integer or all-digit string ids;
+ * otherwise a new UUID string.
+ */
+function nextIdForCollection(items) {
+    let max = Number.NEGATIVE_INFINITY;
+    for (const item of items) {
+        if (!isRecordWithId(item)) {
+            continue;
+        }
+        const n = numericIdValue(item.id);
+        if (n !== null && n > max) {
+            max = n;
+        }
+    }
+    if (max !== Number.NEGATIVE_INFINITY) {
+        return max + 1;
+    }
+    return (0, crypto_1.randomUUID)();
+}
+function asyncHandler(fn) {
+    return (req, res, next) => {
+        void fn(req, res, next).catch(next);
+    };
+}
+function buildDynamicRouter() {
+    const router = express_1.default.Router();
+    const resources = Object.keys(jsonStore_1.JsonStore.getData());
+    for (const resource of resources) {
+        router.get(`/${resource}/:id`, asyncHandler(async (req, res) => {
+            const { id } = req.params;
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const item = findItemById(collection, id);
+            if (item === undefined) {
+                itemNotFound(res, resource, id);
+                return;
+            }
+            res.json(item);
+        }));
+        router.get(`/${resource}`, (_req, res) => {
+            res.json(jsonStore_1.JsonStore.getData()[resource]);
+        });
+        router.post(`/${resource}`, asyncHandler(async (req, res) => {
+            if (!isPlainObject(req.body)) {
+                badBody(res);
+                return;
+            }
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const newId = nextIdForCollection(collection);
+            const rawBody = req.body;
+            const rest = { ...rawBody };
+            delete rest["id"];
+            const newItem = { ...rest, id: newId };
+            collection.push(newItem);
+            await jsonStore_1.JsonStore.save();
+            res.status(201).json(newItem);
+        }));
+        router.put(`/${resource}/:id`, asyncHandler(async (req, res) => {
+            if (!isPlainObject(req.body)) {
+                badBody(res);
+                return;
+            }
+            const { id: idParam } = req.params;
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const index = findIndexById(collection, idParam);
+            if (index === -1) {
+                itemNotFound(res, resource, idParam);
+                return;
+            }
+            const previous = collection[index];
+            const preservedId = isRecordWithId(previous) ? previous.id : idParam;
+            const rawBody = req.body;
+            const rest = { ...rawBody };
+            delete rest["id"];
+            const updated = { ...rest, id: preservedId };
+            collection[index] = updated;
+            await jsonStore_1.JsonStore.save();
+            res.json(updated);
+        }));
+        router.patch(`/${resource}/:id`, asyncHandler(async (req, res) => {
+            if (!isPlainObject(req.body)) {
+                badBody(res);
+                return;
+            }
+            const { id: idParam } = req.params;
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const index = findIndexById(collection, idParam);
+            if (index === -1) {
+                itemNotFound(res, resource, idParam);
+                return;
+            }
+            const current = collection[index];
+            if (!isPlainObject(current)) {
+                res.status(400).json({ error: "Existing item must be an object to PATCH." });
+                return;
+            }
+            const preservedId = isRecordWithId(current) ? current.id : idParam;
+            const rawBody = req.body;
+            const patch = { ...rawBody };
+            delete patch["id"];
+            const updated = { ...current, ...patch, id: preservedId };
+            collection[index] = updated;
+            await jsonStore_1.JsonStore.save();
+            res.json(updated);
+        }));
+        router.delete(`/${resource}/:id`, asyncHandler(async (req, res) => {
+            const { id: idParam } = req.params;
+            const collection = jsonStore_1.JsonStore.getData()[resource];
+            const index = findIndexById(collection, idParam);
+            if (index === -1) {
+                itemNotFound(res, resource, idParam);
+                return;
+            }
+            collection.splice(index, 1);
+            await jsonStore_1.JsonStore.save();
+            res.status(204).send();
+        }));
+    }
+    return router;
+}

package/dist/store/jsonStore.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonStore = void 0;
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const promises_1 = require("fs/promises");
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJsonStorePayload(raw, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in "${filePath}": ${message}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error(`JSON root in "${filePath}" must be a non-null object (got ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed}).`);
+    }
+    const data = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!Array.isArray(value)) {
+            throw new Error(`Invalid mock database shape in "${filePath}": property "${key}" must be an array.`);
+        }
+        data[key] = value;
+    }
+    return data;
+}
+class JsonStoreImpl {
+    data = {};
+    backingPath = null;
+    /** Serializes concurrent save() calls so writes are not interleaved. */
+    saveChain = Promise.resolve();
+    async load(filePath) {
+        let raw;
+        try {
+            raw = await (0, promises_1.readFile)(filePath, "utf8");
+        }
+        catch (err) {
+            const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(code
+                ? `Could not read JSON file "${filePath}" (${code}): ${message}`
+                : `Could not read JSON file "${filePath}": ${message}`);
+        }
+        this.data = parseJsonStorePayload(raw, filePath);
+        this.backingPath = filePath;
+    }
+    getData() {
+        return this.data;
+    }
+    /**
+     * Writes the current in-memory state to the backing file using a temp file + rename
+     * for an atomic-style replace on POSIX; serializes overlapping saves.
+     */
+    async save() {
+        if (this.backingPath === null) {
+            throw new Error("JsonStore.save() called before load(); no file path is set.");
+        }
+        const run = async () => {
+            const target = this.backingPath;
+            const dir = (0, path_1.dirname)(target);
+            const tmp = (0, path_1.join)(dir, `.zero-mock-${(0, crypto_1.randomBytes)(8).toString("hex")}.tmp`);
+            const payload = `${JSON.stringify(this.data, null, 2)}\n`;
+            try {
+                await (0, promises_1.writeFile)(tmp, payload, "utf8");
+                await (0, promises_1.rename)(tmp, target);
+            }
+            catch (err) {
+                await (0, promises_1.unlink)(tmp).catch(() => { });
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`Could not write JSON file "${target}": ${message}`);
+            }
+        };
+        const next = this.saveChain.then(run, run);
+        this.saveChain = next.catch(() => { });
+        await next;
+    }
+}
+/** Singleton store for the backing JSON file (system of record). */
+exports.JsonStore = new JsonStoreImpl();

package/dist/types.js

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

package/example/db.json

@@ -0,0 +1,45 @@
+{
+  "users": [
+    {
+      "id": 1,
+      "name": "Ada Lovelace",
+      "email": "ada@example.com",
+      "role": "admin"
+    },
+    {
+      "id": 2,
+      "name": "Grace Hopper",
+      "email": "grace@example.com",
+      "role": "editor"
+    },
+    {
+      "id": 3,
+      "name": "Margaret Hamilton",
+      "email": "margaret@example.com",
+      "role": "viewer"
+    }
+  ],
+  "posts": [
+    {
+      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "title": "Shipping a mock API in minutes",
+      "body": "Point zero-mock at a JSON file and iterate on your UI without waiting on backend tickets.",
+      "userId": 1,
+      "published": true
+    },
+    {
+      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+      "title": "Why atomic writes matter",
+      "body": "Your JSON file stays the source of truth—even when multiple tabs hit the API at once.",
+      "userId": 2,
+      "published": false
+    },
+    {
+      "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
+      "title": "Frontend-first workflows",
+      "body": "Prototype with realistic CRUD, then swap the mock for a production API when you are ready.",
+      "userId": 1,
+      "published": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@xirconsss/zero-mock",
+  "version": "0.1.0",
+  "description": "Zero-config CLI that generates REST APIs from JSON files",
+  "license": "MIT",
+  "keywords": [
+    "mock",
+    "api",
+    "server",
+    "cli",
+    "rest",
+    "json-database",
+    "frontend-tool",
+    "express",
+    "zero-config",
+    "json"
+  ],
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "example"
+  ],
+  "bin": {
+    "zero-mock": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xircons/zero-mock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xircons/zero-mock/issues"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.14.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}