json-server 1.0.0-beta.1 → 1.0.0-beta.12

package/LICENSE

@@ -1,44 +1,21 @@
-Fair Source License, version 0.9
-
-Copyright (C) 2023-present typicode
-
-Licensor: typicode
-
-Software: json-server
-
-Use Limitation: 2 users
-
-License Grant. Licensor hereby grants to each recipient of the
-Software ("you") a non-exclusive, non-transferable, royalty-free and
-fully-paid-up license, under all of the Licensor's copyright and
-patent rights, to use, copy, distribute, prepare derivative works of,
-publicly perform and display the Software, subject to the Use
-Limitation and the conditions set forth below.
-
-Use Limitation. The license granted above allows use by up to the
-number of users per entity set forth above (the "Use Limitation"). For
-determining the number of users, "you" includes all affiliates,
-meaning legal entities controlling, controlled by, or under common
-control with you. If you exceed the Use Limitation, your use is
-subject to payment of Licensor's then-current list price for licenses.
-
-Conditions. Redistribution in source code or other forms must include
-a copy of this license document to be provided in a reasonable
-manner. Any redistribution of the Software is only allowed subject to
-this license.
-
-Trademarks. This license does not grant you any right in the
-trademarks, service marks, brand names or logos of Licensor.
-
-DISCLAIMER. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OR
-CONDITION, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. LICENSORS HEREBY DISCLAIM ALL LIABILITY, WHETHER IN
-AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE.
-
-Termination. If you violate the terms of this license, your rights
-will terminate automatically and will not be reinstated without the
-prior written consent of Licensor. Any such termination will not
-affect the right of others who may have received copies of the
-Software from you.
+MIT License
+
+Copyright (c) 2026 typicode
+
+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

@@ -1,11 +1,12 @@
-# json-server
+# JSON-Server
 
 [![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)
 
-👋 _Hey! Using React, Vue or Astro? Check my new project [MistCSS](https://github.com/typicode/mistcss) to write 50% less code._
+> [!NOTE]
+> Using React ⚛️ and tired of CSS-in-JS? See [MistCSS](https://github.com/typicode/mistcss) 👀
 
 ## Install
 
@@ -19,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 }
@@ -40,15 +42,15 @@ Create a `db.json` or `db.json5` file
 ```json5
 {
   posts: [
-    { id: '1', title: 'a title', views: 100 },
-    { id: '2', title: 'another title', views: 200 },
+    { id: "1", title: "a title", views: 100 },
+    { id: "2", title: "another title", views: 200 },
   ],
   comments: [
-    { id: '1', text: 'a comment about post 1', postId: '1' },
-    { id: '2', text: 'another comment about post 1', postId: '1' },
+    { id: "1", text: "a comment about post 1", postId: "1" },
+    { id: "2", text: "another comment about post 1", postId: "1" },
   ],
   profile: {
-    name: 'typicode',
+    name: "typicode",
   },
 }
 ```
@@ -57,19 +59,30 @@ You can read more about JSON5 format [here](https://github.com/json5/json5).
 
 </details>
 
-Pass it to JSON Server CLI
+Start JSON Server
 
-```shell
-$ npx json-server db.json
+```bash
+npx json-server db.json
+```
+
+This starts the server at `http://localhost:3000`. You should see:
+```
+JSON Server started on PORT :3000
+http://localhost:3000
 ```
 
-Get a REST API
+Access your REST API:
 
-```shell
-$ curl http://localhost:3000/posts/1
+```bash
+curl http://localhost:3000/posts/1
+```
+
+**Response:**
+```json
 {
   "id": "1",
-  "title": "a title"
+  "title": "a title",
+  "views": 100
 }
 ```
 
@@ -77,135 +90,174 @@ Run `json-server --help` for a list of options
 
 ## Sponsors ✨
 
-| Sponsors |
-| :---: |
-| <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"><picture><source media="(prefers-color-scheme: dark)" srcset="https://github.com/typicode/json-server/assets/5502029/bb7abea9-fc54-4612-b7ab-0221c60b8ac7"><img alt="scalar" src="https://github.com/typicode/json-server/assets/5502029/51f5afed-7ba0-41bf-b9f2-ef9d8ab9dff7"></picture></a> |
+### Gold
 
+|                                                                                                                                                            |
+| :--------------------------------------------------------------------------------------------------------------------------------------------------------: |
+|               <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> |
+| <a href="https://serpapi.com/?utm_source=typicode"><img height="100px" src="https://github.com/user-attachments/assets/52b3039d-1e4c-4c68-951c-93f0f1e73611" /></a>
 
-| Sponsors |
-| :---: |
-| <a href="https://konghq.com/products/kong-konnect/register?utm_medium=referral&utm_source=github&utm_campaign=platform&utm_content=json-server"><img src="https://github.com/typicode/json-server/assets/5502029/e8d8ecb2-3c45-4f60-92d0-a060b820fa7f" height="75px"></a> |
 
-| Sponsors | |
-| :---: | :---: |
-| <a href="https://www.storyblok.com/" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/c6b10674-4ada-4616-91b8-59d30046b45a" height="35px"></a> | <a href="https://betterstack.com/" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/44679f8f-9671-470d-b77e-26d90b90cbdc" height="35px"></a> |
-| <a href="https://www.globalsoftwarecompanies.com" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/d0bb2e9b-9b74-4d91-9c9e-f3c87e152918" height="35px"></a> | <a href="https://beeceptor.com/?utm_source=json-server"><img src="https://github.com/typicode/json-server/assets/5502029/57b852a6-60b9-426b-986e-a148e82783c2" height="35px"></a> |
+### Silver
 
+|                                                                                                                                                                                                                                         |
+| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| <a href="https://requestly.com?utm_source=githubsponsor&utm_medium=jsonserver&utm_campaign=jsonserver"><img src="https://github.com/user-attachments/assets/f7e7b3cf-97e2-46b8-81c8-cb3992662a1c" style="height:70px; width:auto;"></a> |
 
+### Bronze
 
+|                                                                                                                                                                                |                                                                                                                                                                              |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| <a href="https://www.storyblok.com/" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/c6b10674-4ada-4616-91b8-59d30046b45a" height="35px"></a> | <a href="https://betterstack.com/" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/44679f8f-9671-470d-b77e-26d90b90cbdc" height="35px"></a> |
 
 [Become a sponsor and have your company logo here](https://github.com/users/typicode/sponsorship)
 
-## Sponsorware
+## Query Capabilities
 
-> [!NOTE]
-> This project uses the [Fair Source License](https://fair.io/). Only organizations with 3+ users are kindly asked to contribute a small amount through sponsorship [sponsor](https://github.com/sponsors/typicode) for usage. __This license helps keep the project sustainable and healthy, benefiting everyone.__
->
-> For more information, FAQs, and the rationale behind this, visit [https://fair.io/](https://fair.io/).
+JSON Server supports advanced querying out of the box:
+
+```http
+GET /posts?views:gt=100                  # Filter by condition
+GET /posts?_sort=-views                  # Sort by field (descending)
+GET /posts?_page=1&_per_page=10          # Pagination
+GET /posts?_embed=comments               # Include relations
+GET /posts?_where={"or":[...]}           # Complex queries
+```
+
+See detailed documentation below for each feature.
 
 ## Routes
 
-Based on the example `db.json`, you'll get the following routes:
+### Array Resources
 
-```
+For array resources like `posts` and `comments`:
+
+```http
 GET    /posts
 GET    /posts/:id
 POST   /posts
 PUT    /posts/:id
 PATCH  /posts/:id
 DELETE /posts/:id
-
-# Same for comments
 ```
 
-```
+### Object Resources
+
+For singular object resources like `profile`:
+
+```http
 GET   /profile
 PUT   /profile
 PATCH /profile
 ```
 
-## Params
+## Query params
 
 ### Conditions
 
-- ` ` → `==`
-- `lt` → `<`
-- `lte` → `<=`
-- `gt` → `>`
-- `gte` → `>=`
-- `ne` → `!=`
-
-```
-GET /posts?views_gt=9000
+Use `field:operator=value`.
+
+Operators:
+
+- 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
+- `in` included in comma-separated list
+- `contains` string contains (case-insensitive)
+- `startsWith` string starts with (case-insensitive)
+- `endsWith` string ends with (case-insensitive)
+
+Examples:
+
+```http
+GET /posts?views:gt=100
+GET /posts?title:eq=Hello
+GET /posts?id:in=1,2,3
+GET /posts?author.name:eq=typicode
+GET /posts?title:contains=hello
+GET /posts?title:startsWith=Hello
+GET /posts?title:endsWith=world
 ```
 
-### Range
-
-- `start`
-- `end`
-- `limit`
+### Sort
 
-```
-GET /posts?_start=10&_end=20
-GET /posts?_start=10&_limit=10
+```http
+GET /posts?_sort=title
+GET /posts?_sort=-views
+GET /posts?_sort=author.name,-views
 ```
 
-### Paginate
+### Pagination
 
-- `page`
-- `per_page` (default = 10)
-
-```
+```http
 GET /posts?_page=1&_per_page=25
 ```
 
-### Sort
-
-- `_sort=f1,f2`
-
-```
-GET /posts?_sort=id,-views
+**Response:**
+```json
+{
+  "first": 1,
+  "prev": null,
+  "next": 2,
+  "last": 4,
+  "pages": 4,
+  "items": 100,
+  "data": [
+    { "id": "1", "title": "...", "views": 100 },
+    { "id": "2", "title": "...", "views": 200 }
+  ]
+}
 ```
 
-### Nested and array fields
-
-- `x.y.z...`
-- `x.y.z[i]...`
-
-```
-GET /foo?a.b=bar
-GET /foo?x.y_lt=100
-GET /foo?arr[0]=bar
-```
+**Notes:**
+- `_per_page` defaults to `10` if not specified
+- Invalid `_page` or `_per_page` values are automatically normalized to valid ranges
 
 ### 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 Serve will serve its content in addition to the REST API.
+JSON Server automatically serves files from the `./public` directory.
 
-You can also add custom directories using `-s/--static` option.
+To serve additional static directories:
 
-```sh
-json-server -s ./static
-json-server -s ./static -s ./node_modules
+```bash
+json-server db.json -s ./static
+json-server db.json -s ./static -s ./node_modules
 ```
 
-## Notable differences with v0.17
+Static files are served with standard MIME types and can include HTML, CSS, JavaScript, images, and other assets.
+
+## Migration Notes (v0 → v1)
+
+If you are upgrading from json-server v0.x, note these behavioral changes:
+
+- **ID handling:** `id` is always a string and will be auto-generated if not provided
+- **Pagination:** Use `_per_page` with `_page` instead of the deprecated `_limit` parameter
+- **Relationships:** Use `_embed` instead of `_expand` for including related resources
+- **Request delays:** Use browser DevTools (Network tab > throttling) instead of the removed `--delay` CLI option
 
-- `id` is always a string and will be generated for you if missing
-- use `_per_page` with `_page` instead of `_limit`for pagination
-- use Chrome's `Network tab > throtling` to delay requests instead of `--delay` CLI option
+> **New to json-server?** These notes are for users migrating from v0. If this is your first time using json-server, you can ignore this section.

package/lib/adapters/normalized-adapter.js

@@ -0,0 +1,31 @@
+import { randomId } from "../random-id.js";
+export const DEFAULT_SCHEMA_PATH = './node_modules/json-server/schema.json';
+export class NormalizedAdapter {
+    #adapter;
+    constructor(adapter) {
+        this.#adapter = adapter;
+    }
+    async read() {
+        const data = await this.#adapter.read();
+        if (data === null) {
+            return null;
+        }
+        delete data['$schema'];
+        for (const value of Object.values(data)) {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (typeof item['id'] === 'number') {
+                        item['id'] = item['id'].toString();
+                    }
+                    if (item['id'] === undefined) {
+                        item['id'] = randomId();
+                    }
+                }
+            }
+        }
+        return data;
+    }
+    async write(data) {
+        await this.#adapter.write({ ...data, $schema: DEFAULT_SCHEMA_PATH });
+    }
+}

package/lib/app.js

@@ -3,15 +3,70 @@ import { fileURLToPath } from 'node:url';
 import { App } from '@tinyhttp/app';
 import { cors } from '@tinyhttp/cors';
 import { Eta } from 'eta';
+import { Low } from 'lowdb';
 import { json } from 'milliparsec';
 import sirv from 'sirv';
-import { isItem, Service } from './service.js';
+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';
 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);
@@ -23,69 +78,44 @@ export function createApp(db, options = {}) {
         ?.map((path) => (isAbsolute(path) ? path : join(process.cwd(), path)))
         .forEach((dir) => app.use(sirv(dir, { dev: !isProduction })));
     // CORS
-    app.use(cors()).options('*', cors());
+    app
+        .use((req, res, next) => {
+        return cors({
+            allowedHeaders: req.headers['access-control-request-headers']
+                ?.split(',')
+                .map((h) => h.trim()),
+        })(req, res, next);
+    })
+        .options('*', cors());
     // Body parser
     app.use(json());
     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.fromEntries(Object.entries(req.query)
-            .map(([key, value]) => {
-            if (['_start', '_end', '_limit', '_page', '_per_page'].includes(key) && typeof value === 'string') {
-                return [key, parseInt(value)];
-            }
-            else {
-                return [key, value];
-            }
-        })
-            .filter(([_, value]) => !Number.isNaN(value)));
-        res.locals['data'] = service.find(name, query);
-        next();
+        const { where, sort, page, perPage, embed } = parseListParams(req);
+        res.locals['data'] = service.find(name, {
+            where,
+            sort,
+            page,
+            perPage,
+            embed,
+        });
+        next?.();
     });
     app.get('/:name/:id', (req, res, next) => {
         const { name = '', id = '' } = req.params;
         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();
+        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']);
-        next();
+        next?.();
     });
     app.use('/:name', (req, res) => {
         const { data } = res.locals;