json-server 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -3,10 +3,10 @@
 [![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/json-server/actions/workflows/node.js.yml)
 
 > [!IMPORTANT]
-> Viewing beta v1 documentation – usable but expect breaking changes. For stable version, see [here](https://github.com/typicode/json-server/tree/v0)
+> Viewing beta v1 documentation – usable but expect breaking changes. For stable version, see [here](https://github.com/typicode/json-server/tree/v0.17.4)
 
 > [!NOTE]
-> Using React ⚛️ ? Check my new project [MistCSS](https://github.com/typicode/mistcss) to write type-safe styles (works with TailwindCSS)
+> Using React ⚛️ and tired of CSS-in-JS? See [MistCSS](https://github.com/typicode/mistcss) 👀
 
 ## Install
 
@@ -20,6 +20,7 @@ Create a `db.json` or `db.json5` file
 
 ```json
 {
+  "$schema": "./node_modules/json-server/schema.json",
   "posts": [
     { "id": "1", "title": "a title", "views": 100 },
     { "id": "2", "title": "another title", "views": 200 }
@@ -86,6 +87,7 @@ Run `json-server --help` for a list of options
 |               <a href="https://mockend.com/" target="_blank"><img src="https://jsonplaceholder.typicode.com/mockend.svg" height="100px"></a>               |
 | <a href="https://zuplo.link/json-server-gh"><img src="https://github.com/user-attachments/assets/adfee31f-a8b6-4684-9a9b-af4f03ac5b75" height="100px"></a> |
 |     <a href="https://www.mintlify.com/"><img src="https://github.com/user-attachments/assets/bcc8cc48-b2d9-4577-8939-1eb4196b7cc5" height="100px"></a>     |
+| <a href="http://git-tower.com/?utm_source=husky&utm_medium=referral"><img height="100px" alt="tower-dock-icon-light" src="https://github.com/user-attachments/assets/b6b4ab20-beff-4e5c-9845-bb9d60057196" /></a>
 
 ### Silver
 
@@ -108,108 +110,110 @@ Run `json-server --help` for a list of options
 >
 > For more information, FAQs, and the rationale behind this, visit [https://fair.io/](https://fair.io/).
 
+## Query capabilities overview
+
+```http
+GET /posts?views:gt=100
+GET /posts?_sort=-views
+GET /posts?_page=1&_per_page=10
+GET /posts?_embed=comments
+GET /posts?_where={"or":[{"views":{"gt":100}},{"title":{"eq":"Hello"}}]}
+```
+
 ## Routes
 
-Based on the example `db.json`, you'll get the following routes:
+For array resources (`posts`, `comments`):
 
-```
+```text
 GET    /posts
 GET    /posts/:id
 POST   /posts
 PUT    /posts/:id
 PATCH  /posts/:id
 DELETE /posts/:id
-
-# Same for comments
 ```
 
-```
+For object resources (`profile`):
+
+```text
 GET   /profile
 PUT   /profile
 PATCH /profile
 ```
 
-## Params
+## Query params
 
 ### Conditions
 
-- ` ` → `==`
-- `lt` → `<`
-- `lte` → `<=`
-- `gt` → `>`
-- `gte` → `>=`
-- `ne` → `!=`
+Use `field:operator=value`.
 
-```
-GET /posts?views_gt=9000
-```
+Operators:
 
-### Range
+- no operator -> `eq` (equal)
+- `lt` less than, `lte` less than or equal
+- `gt` greater than, `gte` greater than or equal
+- `eq` equal, `ne` not equal
 
-- `start`
-- `end`
-- `limit`
+Examples:
 
-```
-GET /posts?_start=10&_end=20
-GET /posts?_start=10&_limit=10
-```
-
-### Paginate
-
-- `page`
-- `per_page` (default = 10)
-
-```
-GET /posts?_page=1&_per_page=25
+```http
+GET /posts?views:gt=100
+GET /posts?title:eq=Hello
+GET /posts?author.name:eq=typicode
 ```
 
 ### Sort
 
-- `_sort=f1,f2`
-
+```http
+GET /posts?_sort=title
+GET /posts?_sort=-views
+GET /posts?_sort=author.name,-views
 ```
-GET /posts?_sort=id,-views
-```
-
-### Nested and array fields
 
-- `x.y.z...`
-- `x.y.z[i]...`
+### Pagination
 
+```http
+GET /posts?_page=1&_per_page=25
 ```
-GET /foo?a.b=bar
-GET /foo?x.y_lt=100
-GET /foo?arr[0]=bar
-```
+
+- `_per_page` default is `10`
+- invalid page/per_page values are normalized
 
 ### Embed
 
-```
+```http
 GET /posts?_embed=comments
 GET /comments?_embed=post
 ```
 
-## Delete
+### Complex filter with `_where`
 
+`_where` accepts a JSON object and overrides normal query params when valid.
+
+```http
+GET /posts?_where={"or":[{"views":{"gt":100}},{"author":{"name":{"lt":"m"}}}]}
 ```
-DELETE /posts/1
+
+## Delete dependents
+
+```http
 DELETE /posts/1?_dependent=comments
 ```
 
-## Serving static files
+## Static files
 
-If you create a `./public` directory, JSON Server will serve its content in addition to the REST API.
+JSON Server serves `./public` automatically.
 
-You can also add custom directories using `-s/--static` option.
+Add more static dirs:
 
 ```sh
 json-server -s ./static
 json-server -s ./static -s ./node_modules
 ```
 
-## Notable differences with v0.17
+## Behavior notes
 
 - `id` is always a string and will be generated for you if missing
 - use `_per_page` with `_page` instead of `_limit`for pagination
+- use `_embed` instead of `_expand`
 - use Chrome's `Network tab > throtling` to delay requests instead of `--delay` CLI option

package/lib/app.js

@@ -6,6 +6,7 @@ import { Eta } from 'eta';
 import { Low } from 'lowdb';
 import { json } from 'milliparsec';
 import sirv from 'sirv';
+import { parseWhere } from "./parse-where.js";
 import { isItem, Service } from "./service.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const isProduction = process.env['NODE_ENV'] === 'production';
@@ -13,6 +14,59 @@ const eta = new Eta({
     views: join(__dirname, '../views'),
     cache: isProduction,
 });
+const RESERVED_QUERY_KEYS = new Set(['_sort', '_page', '_per_page', '_embed', '_where']);
+function parseListParams(req) {
+    const queryString = req.url.split('?')[1] ?? '';
+    const params = new URLSearchParams(queryString);
+    const filterParams = new URLSearchParams();
+    for (const [key, value] of params.entries()) {
+        if (!RESERVED_QUERY_KEYS.has(key)) {
+            filterParams.append(key, value);
+        }
+    }
+    let where = parseWhere(filterParams.toString());
+    const rawWhere = params.get('_where');
+    if (typeof rawWhere === 'string') {
+        try {
+            const parsed = JSON.parse(rawWhere);
+            if (typeof parsed === 'object' && parsed !== null) {
+                where = parsed;
+            }
+        }
+        catch {
+            // Ignore invalid JSON and fallback to parsed query params
+        }
+    }
+    const pageRaw = params.get('_page');
+    const perPageRaw = params.get('_per_page');
+    const page = pageRaw === null ? undefined : Number.parseInt(pageRaw, 10);
+    const perPage = perPageRaw === null ? undefined : Number.parseInt(perPageRaw, 10);
+    return {
+        where,
+        sort: params.get('_sort') ?? undefined,
+        page: Number.isNaN(page) ? undefined : page,
+        perPage: Number.isNaN(perPage) ? undefined : perPage,
+        embed: req.query['_embed'],
+    };
+}
+function withBody(action) {
+    return async (req, res, next) => {
+        const { name = '' } = req.params;
+        if (isItem(req.body)) {
+            res.locals['data'] = await action(name, req.body);
+        }
+        next?.();
+    };
+}
+function withIdAndBody(action) {
+    return async (req, res, next) => {
+        const { name = '', id = '' } = req.params;
+        if (isItem(req.body)) {
+            res.locals['data'] = await action(name, id, req.body);
+        }
+        next?.();
+    };
+}
 export function createApp(db, options = {}) {
     // Create service
     const service = new Service(db);
@@ -38,18 +92,14 @@ export function createApp(db, options = {}) {
     app.get('/', (_req, res) => res.send(eta.render('index.html', { data: db.data })));
     app.get('/:name', (req, res, next) => {
         const { name = '' } = req.params;
-        const query = {};
-        Object.keys(req.query).forEach((key) => {
-            let value = req.query[key];
-            if (['_start', '_end', '_limit', '_page', '_per_page'].includes(key) &&
-                typeof value === 'string') {
-                value = parseInt(value);
-            }
-            if (!Number.isNaN(value)) {
-                query[key] = value;
-            }
+        const { where, sort, page, perPage, embed } = parseListParams(req);
+        res.locals['data'] = service.find(name, {
+            where,
+            sort,
+            page,
+            perPage,
+            embed,
         });
-        res.locals['data'] = service.find(name, query);
         next?.();
     });
     app.get('/:name/:id', (req, res, next) => {
@@ -57,41 +107,11 @@ export function createApp(db, options = {}) {
         res.locals['data'] = service.findById(name, id, req.query);
         next?.();
     });
-    app.post('/:name', async (req, res, next) => {
-        const { name = '' } = req.params;
-        if (isItem(req.body)) {
-            res.locals['data'] = await service.create(name, req.body);
-        }
-        next?.();
-    });
-    app.put('/:name', async (req, res, next) => {
-        const { name = '' } = req.params;
-        if (isItem(req.body)) {
-            res.locals['data'] = await service.update(name, req.body);
-        }
-        next?.();
-    });
-    app.put('/:name/:id', async (req, res, next) => {
-        const { name = '', id = '' } = req.params;
-        if (isItem(req.body)) {
-            res.locals['data'] = await service.updateById(name, id, req.body);
-        }
-        next?.();
-    });
-    app.patch('/:name', async (req, res, next) => {
-        const { name = '' } = req.params;
-        if (isItem(req.body)) {
-            res.locals['data'] = await service.patch(name, req.body);
-        }
-        next?.();
-    });
-    app.patch('/:name/:id', async (req, res, next) => {
-        const { name = '', id = '' } = req.params;
-        if (isItem(req.body)) {
-            res.locals['data'] = await service.patchById(name, id, req.body);
-        }
-        next?.();
-    });
+    app.post('/:name', withBody(service.create.bind(service)));
+    app.put('/:name', withBody(service.update.bind(service)));
+    app.put('/:name/:id', withIdAndBody(service.updateById.bind(service)));
+    app.patch('/:name', withBody(service.patch.bind(service)));
+    app.patch('/:name/:id', withIdAndBody(service.patchById.bind(service)));
     app.delete('/:name/:id', async (req, res, next) => {
         const { name = '', id = '' } = req.params;
         res.locals['data'] = await service.destroyById(name, id, req.query['_dependent']);

package/lib/matches-where.js

@@ -0,0 +1,64 @@
+import { WHERE_OPERATORS } from "./where-operators.js";
+function isJSONObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getKnownOperators(value) {
+    if (!isJSONObject(value))
+        return [];
+    const ops = [];
+    for (const op of WHERE_OPERATORS) {
+        if (op in value) {
+            ops.push(op);
+        }
+    }
+    return ops;
+}
+export function matchesWhere(obj, where) {
+    for (const [key, value] of Object.entries(where)) {
+        if (key === 'or') {
+            if (!Array.isArray(value) || value.length === 0)
+                return false;
+            let matched = false;
+            for (const subWhere of value) {
+                if (isJSONObject(subWhere) && matchesWhere(obj, subWhere)) {
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched)
+                return false;
+            continue;
+        }
+        const field = obj[key];
+        if (isJSONObject(value)) {
+            const knownOps = getKnownOperators(value);
+            if (knownOps.length > 0) {
+                if (field === undefined)
+                    return false;
+                const op = value;
+                if (knownOps.includes('lt') && !(field < op.lt))
+                    return false;
+                if (knownOps.includes('lte') && !(field <= op.lte))
+                    return false;
+                if (knownOps.includes('gt') && !(field > op.gt))
+                    return false;
+                if (knownOps.includes('gte') && !(field >= op.gte))
+                    return false;
+                if (knownOps.includes('eq') && !(field === op.eq))
+                    return false;
+                if (knownOps.includes('ne') && !(field !== op.ne))
+                    return false;
+                continue;
+            }
+            if (isJSONObject(field)) {
+                if (!matchesWhere(field, value))
+                    return false;
+            }
+            continue;
+        }
+        if (field === undefined)
+            return false;
+        return false;
+    }
+    return true;
+}

package/lib/paginate.js

@@ -0,0 +1,24 @@
+export function paginate(items, page, perPage) {
+    const totalItems = items.length;
+    const safePerPage = Number.isFinite(perPage) && perPage > 0 ? Math.floor(perPage) : 1;
+    const pages = Math.max(1, Math.ceil(totalItems / safePerPage));
+    // Ensure page is within the valid range
+    const safePage = Number.isFinite(page) ? Math.floor(page) : 1;
+    const currentPage = Math.max(1, Math.min(safePage, pages));
+    const first = 1;
+    const prev = currentPage > 1 ? currentPage - 1 : null;
+    const next = currentPage < pages ? currentPage + 1 : null;
+    const last = pages;
+    const start = (currentPage - 1) * safePerPage;
+    const end = start + safePerPage;
+    const data = items.slice(start, end);
+    return {
+        first,
+        prev,
+        next,
+        last,
+        pages,
+        items: totalItems,
+        data,
+    };
+}

package/lib/parse-where.js

@@ -0,0 +1,52 @@
+import { setProperty } from 'dot-prop';
+import { isWhereOperator } from "./where-operators.js";
+function splitKey(key) {
+    const colonIdx = key.lastIndexOf(':');
+    if (colonIdx !== -1) {
+        const path = key.slice(0, colonIdx);
+        const op = key.slice(colonIdx + 1);
+        if (!op) {
+            return { path: key, op: 'eq' };
+        }
+        return isWhereOperator(op) ? { path, op } : { path, op: null };
+    }
+    // Compatibility with v0.17 operator style (e.g. _lt, _gt)
+    const underscoreMatch = key.match(/^(.*)_([a-z]+)$/);
+    if (underscoreMatch) {
+        const path = underscoreMatch[1];
+        const op = underscoreMatch[2];
+        if (path && isWhereOperator(op)) {
+            return { path, op };
+        }
+    }
+    return { path: key, op: 'eq' };
+}
+function setPathOp(root, path, op, value) {
+    const fullPath = `${path}.${op}`;
+    setProperty(root, fullPath, coerceValue(value));
+}
+function coerceValue(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null')
+        return null;
+    if (value.trim() === '')
+        return value;
+    const num = Number(value);
+    if (Number.isFinite(num))
+        return num;
+    return value;
+}
+export function parseWhere(query) {
+    const out = {};
+    const params = new URLSearchParams(query);
+    for (const [rawKey, rawValue] of params.entries()) {
+        const { path, op } = splitKey(rawKey);
+        if (op === null)
+            continue;
+        setPathOp(out, path, op, rawValue);
+    }
+    return out;
+}

package/lib/service.js

@@ -1,28 +1,18 @@
 import { randomBytes } from 'node:crypto';
-import { getProperty } from 'dot-prop';
 import inflection from 'inflection';
 import { Low } from 'lowdb';
 import sortOn from 'sort-on';
+import { matchesWhere } from "./matches-where.js";
+import { paginate } from "./paginate.js";
 export function isItem(obj) {
-    return typeof obj === 'object' && obj !== null;
+    return typeof obj === 'object' && obj !== null && !Array.isArray(obj);
 }
 export function isData(obj) {
     if (typeof obj !== 'object' || obj === null) {
         return false;
     }
     const data = obj;
-    return Object.values(data).every((value) => Array.isArray(value) && value.every(isItem));
-}
-const Condition = {
-    lt: 'lt',
-    lte: 'lte',
-    gt: 'gt',
-    gte: 'gte',
-    ne: 'ne',
-    default: '',
-};
-function isCondition(value) {
-    return Object.values(Condition).includes(value);
+    return Object.values(data).every((value) => Array.isArray(value) ? value.every(isItem) : isItem(value));
 }
 function ensureArray(arg = []) {
     return Array.isArray(arg) ? arg : [arg];
@@ -120,148 +110,24 @@ export class Service {
         }
         return;
     }
-    find(name, query = {}) {
-        let items = this.#get(name);
+    find(name, opts) {
+        const items = this.#get(name);
         if (!Array.isArray(items)) {
             return items;
         }
+        let results = items;
         // Include
-        ensureArray(query._embed).forEach((related) => {
-            if (items !== undefined && Array.isArray(items)) {
-                items = items.map((item) => embed(this.#db, name, item, related));
-            }
+        ensureArray(opts.embed).forEach((related) => {
+            results = results.map((item) => embed(this.#db, name, item, related));
         });
-        // Return list if no query params
-        if (Object.keys(query).length === 0) {
-            return items;
-        }
-        // Convert query params to conditions
-        const conds = [];
-        for (const [key, value] of Object.entries(query)) {
-            if (value === undefined || typeof value !== 'string') {
-                continue;
-            }
-            const re = /_(lt|lte|gt|gte|ne)$/;
-            const reArr = re.exec(key);
-            const op = reArr?.at(1);
-            if (op && isCondition(op)) {
-                const field = key.replace(re, '');
-                conds.push([field, op, value]);
-                continue;
-            }
-            if (['_embed', '_sort', '_start', '_end', '_limit', '_page', '_per_page'].includes(key)) {
-                continue;
-            }
-            conds.push([key, Condition.default, value]);
-        }
-        // Loop through conditions and filter items
-        let filtered = items;
-        for (const [key, op, paramValue] of conds) {
-            filtered = filtered.filter((item) => {
-                if (paramValue && !Array.isArray(paramValue)) {
-                    // https://github.com/sindresorhus/dot-prop/issues/95
-                    const itemValue = getProperty(item, key);
-                    switch (op) {
-                        // item_gt=value
-                        case Condition.gt: {
-                            if (!(typeof itemValue === 'number' && itemValue > parseInt(paramValue))) {
-                                return false;
-                            }
-                            break;
-                        }
-                        // item_gte=value
-                        case Condition.gte: {
-                            if (!(typeof itemValue === 'number' && itemValue >= parseInt(paramValue))) {
-                                return false;
-                            }
-                            break;
-                        }
-                        // item_lt=value
-                        case Condition.lt: {
-                            if (!(typeof itemValue === 'number' && itemValue < parseInt(paramValue))) {
-                                return false;
-                            }
-                            break;
-                        }
-                        // item_lte=value
-                        case Condition.lte: {
-                            if (!(typeof itemValue === 'number' && itemValue <= parseInt(paramValue))) {
-                                return false;
-                            }
-                            break;
-                        }
-                        // item_ne=value
-                        case Condition.ne: {
-                            switch (typeof itemValue) {
-                                case 'number':
-                                    return itemValue !== parseInt(paramValue);
-                                case 'string':
-                                    return itemValue !== paramValue;
-                                case 'boolean':
-                                    return itemValue !== (paramValue === 'true');
-                            }
-                            break;
-                        }
-                        // item=value
-                        case Condition.default: {
-                            switch (typeof itemValue) {
-                                case 'number':
-                                    return itemValue === parseInt(paramValue);
-                                case 'string':
-                                    return itemValue === paramValue;
-                                case 'boolean':
-                                    return itemValue === (paramValue === 'true');
-                                case 'undefined':
-                                    return false;
-                            }
-                        }
-                    }
-                }
-                return true;
-            });
-        }
-        // Sort
-        const sort = query._sort || '';
-        const sorted = sortOn(filtered, sort.split(','));
-        // Slice
-        const start = query._start;
-        const end = query._end;
-        const limit = query._limit;
-        if (start !== undefined) {
-            if (end !== undefined) {
-                return sorted.slice(start, end);
-            }
-            return sorted.slice(start, start + (limit || 0));
-        }
-        if (limit !== undefined) {
-            return sorted.slice(0, limit);
+        results = results.filter((item) => matchesWhere(item, opts.where));
+        if (opts.sort) {
+            results = sortOn(results, opts.sort.split(','));
         }
-        // Paginate
-        let page = query._page;
-        const perPage = query._per_page || 10;
-        if (page) {
-            const items = sorted.length;
-            const pages = Math.ceil(items / perPage);
-            // Ensure page is within the valid range
-            page = Math.max(1, Math.min(page, pages));
-            const first = 1;
-            const prev = page > 1 ? page - 1 : null;
-            const next = page < pages ? page + 1 : null;
-            const last = pages;
-            const start = (page - 1) * perPage;
-            const end = start + perPage;
-            const data = sorted.slice(start, end);
-            return {
-                first,
-                prev,
-                next,
-                last,
-                pages,
-                items,
-                data,
-            };
+        if (opts.page !== undefined) {
+            return paginate(results, opts.page, opts.perPage ?? 10);
         }
-        return sorted.slice(start, end);
+        return results;
     }
     async create(name, data = {}) {
         const items = this.#get(name);

package/lib/where-operators.js

@@ -0,0 +1,4 @@
+export const WHERE_OPERATORS = ['lt', 'lte', 'gt', 'gte', 'eq', 'ne'];
+export function isWhereOperator(value) {
+    return WHERE_OPERATORS.includes(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-server",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "",
   "keywords": [],
   "license": "SEE LICENSE IN ./LICENSE",
@@ -14,7 +14,8 @@
   },
   "files": [
     "lib",
-    "views"
+    "views",
+    "schema.json"
   ],
   "type": "module",
   "dependencies": {

package/schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": {
+    "oneOf": [
+      { "type": "array" },
+      { "type": "object" }
+    ]
+  }
+}