Add placeholder search doc and tests (#544)

* Add placeholder doc and tests

* build(deps-dev): bump rollup-plugin-terser from 6.1.0 to 7.0.0

Bumps [rollup-plugin-terser](https://github.com/TrySound/rollup-plugin-terser) from 6.1.0 to 7.0.0.
- [Release notes](https://github.com/TrySound/rollup-plugin-terser/releases)
- [Commits](TrySound/rollup-plugin-terser@v6.1.0...v7.0.0)

Signed-off-by: dependabot-preview[bot] <[email protected]>

* Update README.md

Co-authored-by: Clémentine Urquizar <[email protected]>

* Update tests/search_tests.ts

* Add placeholder doc and tests

* Update README.md

Co-authored-by: Clémentine Urquizar <[email protected]>

* Update tests/search_tests.ts

Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com>
Co-authored-by: Clémentine Urquizar <[email protected]>

Author: 3 people

README.md

@@ -300,6 +300,44 @@ await index.search('prince', { limit: 1, attributesToHighlight: '*' })
 }
 ```
 
+#### Placeholder Search
+
+Placeholder search makes it possible to receive hits based on your parameters without having any query (`q`).
+To enable this behavior, instead of sending an empty string, the query should be `null` or `undefined`.
+
+```javascript
+await index.search(null, {
+  facetFilters: ['genre:fantasy'],
+  facetsDistribution: ['genre']
+})
+```
+
+```json
+{
+  "hits": [
+    {
+      "genre": "fantasy",
+      "id": 4,
+      "title": "Harry Potter and the Half-Blood Prince",
+      "comment": "The best book"
+    },
+    {
+      "genre": "fantasy",
+      "id": 42,
+      "title": "The Hitchhiker's Guide to the Galaxy"
+    }
+  ],
+  "offset": 0,
+  "limit": 20,
+  "nbHits": 2,
+  "exhaustiveNbHits": false,
+  "processingTimeMs": 0,
+  "query": "",
+  "facetsDistribution": { "genre": { "fantasy": 2, "romance": 0, "sci fi": 0, "adventure": 0 } },
+  "exhaustiveFacetsCount": true
+}
+```
+
 ## ⚙️ Development Workflow and Contributing
 
 Any new contribution is more than welcome in this project!

src/index.ts

@@ -74,7 +74,7 @@ class Index<T> extends MeiliAxiosWrapper implements Types.IndexInterface<T> {
    * @method search
    */
   async search<P extends Types.SearchParams<T>>(
-    query?: string,
+    query?: string | null,
     options?: P,
     method: Types.Methods = 'POST'
   ): Promise<Types.SearchResponse<T, P>> {

src/types.ts

@@ -69,7 +69,7 @@ export interface SearchParams<T> {
 }
 
 export interface SearchRequest {
-  q?: string
+  q?: string | null
   offset?: number
   limit?: number
   cropLength?: number
@@ -83,7 +83,7 @@ export interface SearchRequest {
 }
 
 export interface GetSearchRequest {
-  q?: string
+  q?: string | null
   offset?: number
   limit?: number
   attributesToRetrieve?: string
@@ -258,7 +258,7 @@ export interface IndexInterface<T = any> extends MeiliAxiosWrapperInterface {
   getUpdateStatus: (updateId: number) => Promise<Update>
   getAllUpdateStatus: () => Promise<Update[]>
   search: <P extends SearchParams<T>>(
-    query: string,
+    query?: string | null,
     options?: P,
     method?: Methods
   ) => Promise<SearchResponse<T, P>>

tests/search_tests.ts

@@ -344,7 +344,7 @@ describe.each([
         })
     })
 
-    test(`${permission} key: ${method} search with facetFilters and facetDistribution`, async () => {
+    test(`${permission} key: ${method} search with facetFilters and facetsDistribution`, async () => {
       await client
         .getIndex(index.uid)
         .search(
@@ -402,6 +402,44 @@ describe.each([
         })
     })
 
+    test(`${permission} key: ${method} search with multiple facetFilters and placeholder search`, async () => {
+      await client
+        .getIndex(index.uid)
+        .search(
+          undefined,
+          {
+            facetFilters: ['genre:fantasy'],
+            facetsDistribution: ['genre'],
+          },
+          method
+        )
+        .then((response) => {
+          expect(response).toHaveProperty('facetsDistribution', {
+            genre: { adventure: 0, fantasy: 2, romance: 0, 'sci fi': 0 },
+          })
+          expect(response.hits.length).toEqual(2)
+        })
+    })
+
+    test(`${permission} key: ${method} search with multiple facetFilters and placeholder search`, async () => {
+      await client
+        .getIndex(index.uid)
+        .search(
+          null,
+          {
+            facetFilters: ['genre:fantasy'],
+            facetsDistribution: ['genre'],
+          },
+          method
+        )
+        .then((response) => {
+          expect(response).toHaveProperty('facetsDistribution', {
+            genre: { adventure: 0, fantasy: 2, romance: 0, 'sci fi': 0 },
+          })
+          expect(response.hits.length).toEqual(2)
+        })
+    })
+
     test(`${permission} key: ${method} search on index with no documents and no primary key`, async () => {
       await client
         .getIndex(emptyIndex.uid)

tests/typed_search_tests.ts

@@ -350,7 +350,7 @@ describe.each([
         })
     })
 
-    test(`${permission} key: Search with facetFilters and facetDistribution`, async () => {
+    test(`${permission} key: Search with facetFilters and facetsDistribution`, async () => {
       await client
         .getIndex<Movie>(index.uid)
         .search(
@@ -408,6 +408,44 @@ describe.each([
         })
     })
 
+    test(`${permission} key: ${method} search with multiple facetFilters and placeholder search`, async () => {
+      await client
+        .getIndex<Movie>(index.uid)
+        .search(
+          undefined,
+          {
+            facetFilters: ['genre:fantasy'],
+            facetsDistribution: ['genre'],
+          },
+          method
+        )
+        .then((response) => {
+          expect(response).toHaveProperty('facetsDistribution', {
+            genre: { adventure: 0, fantasy: 2, romance: 0, 'sci fi': 0 },
+          })
+          expect(response.hits.length).toEqual(2)
+        })
+    })
+
+    test(`${permission} key: ${method} search with multiple facetFilters and placeholder search`, async () => {
+      await client
+        .getIndex<Movie>(index.uid)
+        .search(
+          null,
+          {
+            facetFilters: ['genre:fantasy'],
+            facetsDistribution: ['genre'],
+          },
+          method
+        )
+        .then((response) => {
+          expect(response).toHaveProperty('facetsDistribution', {
+            genre: { adventure: 0, fantasy: 2, romance: 0, 'sci fi': 0 },
+          })
+          expect(response.hits.length).toEqual(2)
+        })
+    })
+
     test(`${permission} key: Search on index with no documents and no primary key`, async () => {
       await client
         .getIndex(emptyIndex.uid)