From af1b696af89fb4afab4f0e0fd034099adda61168 Mon Sep 17 00:00:00 2001
From: Brian Kulyk <brian.kulyk@sterlingcapitalbrokers.com>
Date: Mon, 19 Dec 2022 10:11:53 -0800
Subject: [PATCH] add filter for getting first result

---
 README.md                   | 22 +++++++++++++++++++---
 __tests__/server/plural.js  | 10 ++++++++++
 src/server/router/plural.js |  6 ++++++
 3 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index a8763cbfc..d2fe696a9 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,7 @@ __Please help me build OSS__ 👉 [GitHub Sponsors](https://github.com/sponsors/
   * [Paginate](#paginate)
   * [Sort](#sort)
   * [Slice](#slice)
+  * [First](#first)
   * [Operators](#operators)
   * [Full-text search](#full-text-search)
   * [Relationships](#relationships)
@@ -106,12 +107,11 @@ __Please help me build OSS__ 👉 [GitHub Sponsors](https://github.com/sponsors/
   * [Articles](#articles)
   * [Third-party tools](#third-party-tools)
 - [License](#license)
-
 <!-- tocstop -->
 
 ## Getting started
 
-Install JSON Server 
+Install JSON Server
 
 ```
 npm install -g json-server
@@ -148,7 +148,7 @@ Also when doing requests, it's good to know that:
 - If you make POST, PUT, PATCH or DELETE requests, changes will be automatically and safely saved to `db.json` using [lowdb](https://github.com/typicode/lowdb).
 - Your request body JSON should be object enclosed, just like the GET output. (for example `{"name": "Foobar"}`)
 - Id values are not mutable. Any `id` value in the body of your PUT or PATCH request will be ignored. Only a value set in a POST request will be respected, but only if not already taken.
-- A POST, PUT or PATCH request should include a `Content-Type: application/json` header to use the JSON in the request body. Otherwise it will return a 2XX status code, but without changes being made to the data. 
+- A POST, PUT or PATCH request should include a `Content-Type: application/json` header to use the JSON in the request body. Otherwise it will return a 2XX status code, but without changes being made to the data.
 
 ## Routes
 
@@ -225,6 +225,22 @@ GET /posts/1/comments?_start=20&_limit=10
 
 _Works exactly as [Array.slice](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) (i.e. `_start` is inclusive and `_end` exclusive)_
 
+### First
+
+Add `_first=true`
+
+```
+GET /posts?_first=true
+```
+
+more useful when combined with other filters.
+
+Example: get the first post by the author
+
+```
+GET /posts?author=typicode&_sort=title&_first=true
+```
+
 ### Operators
 
 Add `_gte` or `_lte` for getting a range
diff --git a/__tests__/server/plural.js b/__tests__/server/plural.js
index 67043cc9b..59a30251d 100644
--- a/__tests__/server/plural.js
+++ b/__tests__/server/plural.js
@@ -208,6 +208,16 @@ describe('Server', () => {
         .expect(200, db.comments.slice(0, 2)))
   })
 
+  describe('GET /:resource?_first=true', () => {
+    test('should respond with the first matching resource', () => {
+      const buyer = db.buyers[3]
+      return request(server)
+        .get('/buyers?country=Belize&_sort=total&_order=desc,desc&_first=true')
+        .expect('Content-Type', /json/)
+        .expect(200, buyer)
+    })
+  })
+
   describe('GET /:resource?_sort=', () => {
     test('should respond with json and sort on a field', () =>
       request(server)
diff --git a/src/server/router/plural.js b/src/server/router/plural.js
index b3695d9ee..20ba41122 100644
--- a/src/server/router/plural.js
+++ b/src/server/router/plural.js
@@ -58,6 +58,7 @@ module.exports = (db, name, opts) => {
     let _start = req.query._start
     let _end = req.query._end
     let _page = req.query._page
+    const _first = req.query._first
     const _sort = req.query._sort
     const _order = req.query._order
     let _limit = req.query._limit
@@ -71,6 +72,7 @@ module.exports = (db, name, opts) => {
     delete req.query._limit
     delete req.query._embed
     delete req.query._expand
+    delete req.query._first
 
     // Automatically delete query parameters that can't be found
     // in the database
@@ -223,6 +225,10 @@ module.exports = (db, name, opts) => {
       expand(element, _expand)
     })
 
+    if (_first) {
+      chain = chain.first()
+    }
+
     res.locals.data = chain.value()
     next()
   }