feat: add _where filtering, use new op separator, drop _start, _end, _limit (#1696)

* feat: add _where filtering and new op separator

* Restore original README content above Query capabilities overview (#1697)

* test: refactor service tests to lightweight table cases

* chore: document underscore where operator compatibility

* refactor: clarify blank-string handling in where coercion

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: typicode

README.md

@@ -110,107 +110,108 @@ 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

src/app.test.ts

@@ -118,4 +118,28 @@ await test('createApp', async (t) => {
       )
     })
   }
+
+  await t.test('GET /posts?_where=... uses JSON query', async () => {
+    // Reset data since previous tests may have modified it
+    db.data = {
+      posts: [{ id: '1', title: 'foo' }],
+      comments: [{ id: '1', postId: '1' }],
+      object: { f1: 'foo' },
+    }
+    const where = encodeURIComponent(JSON.stringify({ title: { eq: 'foo' } }))
+    const response = await fetch(`http://localhost:${port}/posts?_where=${where}`)
+    assert.equal(response.status, 200)
+    const data = await response.json()
+    assert.deepEqual(data, [{ id: '1', title: 'foo' }])
+  })
+
+  await t.test('GET /posts?_where=... overrides query params', async () => {
+    const where = encodeURIComponent(JSON.stringify({ title: { eq: 'foo' } }))
+    const response = await fetch(
+      `http://localhost:${port}/posts?title:eq=bar&_where=${where}`,
+    )
+    assert.equal(response.status, 200)
+    const data = await response.json()
+    assert.deepEqual(data, [{ id: '1', title: 'foo' }])
+  })
 })

src/app.ts

@@ -1,22 +1,20 @@
 import { dirname, isAbsolute, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { App, type Request } from '@tinyhttp/app'
+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 { parseWhere } from './parse-where.ts'
 import type { Data } from './service.ts'
 import { isItem, Service } from './service.ts'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const isProduction = process.env['NODE_ENV'] === 'production'
 
-type QueryValue = Request['query'][string] | number
-type Query = Record<string, QueryValue>
-
 export type AppOptions = {
   logger?: boolean
   static?: string[]
@@ -27,6 +25,68 @@ const eta = new Eta({
   cache: isProduction,
 })
 
+const RESERVED_QUERY_KEYS = new Set(['_sort', '_page', '_per_page', '_embed', '_where'])
+
+function parseListParams(req: any) {
+  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: (name: string, body: Record<string, unknown>) => Promise<unknown>) {
+  return async (req: any, res: any, next: any) => {
+    const { name = '' } = req.params
+    if (isItem(req.body)) {
+      res.locals['data'] = await action(name, req.body)
+    }
+    next?.()
+  }
+}
+
+function withIdAndBody(
+  action: (name: string, id: string, body: Record<string, unknown>) => Promise<unknown>,
+) {
+  return async (req: any, res: any, next: any) => {
+    const { name = '', id = '' } = req.params
+    if (isItem(req.body)) {
+      res.locals['data'] = await action(name, id, req.body)
+    }
+    next?.()
+  }
+}
+
 export function createApp(db: Low<Data>, options: AppOptions = {}) {
   // Create service
   const service = new Service(db)
@@ -58,23 +118,15 @@ export function createApp(db: Low<Data>, options: AppOptions = {}) {
 
   app.get('/:name', (req, res, next) => {
     const { name = '' } = req.params
-    const query: Query = {}
-
-    Object.keys(req.query).forEach((key) => {
-      let value: QueryValue = 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?.()
   })
 
@@ -84,45 +136,15 @@ export function createApp(db: Low<Data>, options: AppOptions = {}) {
     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.post('/:name', withBody(service.create.bind(service)))
 
-  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', withBody(service.update.bind(service)))
 
-  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.put('/:name/:id', withIdAndBody(service.updateById.bind(service)))
 
-  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', withBody(service.patch.bind(service)))
 
-  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.patch('/:name/:id', withIdAndBody(service.patchById.bind(service)))
 
   app.delete('/:name/:id', async (req, res, next) => {
     const { name = '', id = '' } = req.params