Merge #1258

1258: Expose a set of Meilisearch search parameters to be overridden/configured r=brunoocasali a=flevi29

# Pull Request

## Related issue
Fixes #1249 

## What does this PR do?
- Adds ability to configure and override a selection of Meilisearch search parameters
- Modifies some types, stronger type checking

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: F. Levi <55688616+flevi29@users.noreply.github.com>

Author: meili-bors[bot]

.changeset/metal-emus-pump.md

@@ -0,0 +1,42 @@
+---
+"@meilisearch/instant-meilisearch": major
+"@meilisearch/autocomplete-client": patch
+---
+
+Added ability to override a selection of Meilisearch search parameters.
+
+  ⚠️ The returned value of the core `instantMeiliSearch` function has changed!
+
+  This change was necessary for the aforementioned ability to be implemented and
+  applied in a clean manner.
+  The necessary migration should be of minimal impact.
+
+  ### Migration
+
+  Change the following
+
+  ```js
+  // 1.
+  const client = instantMeiliSearch(/*...*/)
+  // 2.
+  const searchClient = instantMeiliSearch(/*...*/)
+  // 3.
+  instantsearch({
+    indexName: 'movies',
+    searchClient: instantMeiliSearch(/*...*/),
+  })
+  ```
+
+  to the following
+
+  ```js
+  // 1.
+  const { searchClient: client } = instantMeiliSearch(/*...*/)
+  // 2.
+  const { searchClient } = instantMeiliSearch(/*...*/)
+  // 3.
+  instantsearch({
+    indexName: 'movies',
+    searchClient: instantMeiliSearch(/*...*/).searchClient,
+  })
+  ```

.code-samples.meilisearch.yaml

@@ -13,7 +13,7 @@ landing_getting_started_1: |-
         searchClient: instantMeiliSearch(
           'http://localhost:7700',
           'searchKey'
-        ),
+        ).searchClient,
       })
 
       search.addWidgets([
@@ -59,7 +59,7 @@ getting_started_front_end_integration_md: |-
         indexName: "movies",
         searchClient: instantMeiliSearch(
           "http://localhost:7700"
-        )
+        ).searchClient
         });
         search.addWidgets([
           instantsearch.widgets.searchBox({

packages/autocomplete-client/src/client/createSearchClient.ts

@@ -16,7 +16,7 @@ export function createSearchClient({ userAgent }: { userAgent: string }) {
     options = { clientAgents: [] },
   }: ClientConfig): SearchClient => {
     const clientAgents = options.clientAgents || []
-    const searchClient = instantMeiliSearch(url, apiKey, {
+    const { searchClient } = instantMeiliSearch(url, apiKey, {
       ...options,
       clientAgents: concatUserAgents([userAgent, ...clientAgents]),
     })

packages/instant-meilisearch/README.md

@@ -80,12 +80,14 @@ To be able to create a search interface, you'll need to [install `instantsearch.
 ```js
 import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
 
-const searchClient = instantMeiliSearch(
+const { searchClient, setMeiliSearchParams } = instantMeiliSearch(
   'https://ms-adf78ae33284-106.lon.meilisearch.io', // Host
   'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303' // API key
 )
 ```
 
+where `searchClient` is to be passed to instantsearch.js or its many framework adaptations, and [`setMeiliSearchParams`](#modify-meilisearch-search-parameters) is a function used to set/modify certain Meilisearch search parameters to be overridden.
+
 ### Parameters
 
 - `Host` - URL of Meilisearch instance
@@ -96,19 +98,19 @@ const searchClient = instantMeiliSearch(
 `instant-meilisearch` offers some options you can set to further fit your needs.
 
 - [`placeholderSearch`](#placeholder-search): Enable or disable placeholder search (default: `true`).
-- [`finitePagination`](#finite-pagination): Enable finite pagination when using the the [`pagination`](#-pagination) widget (default: `false`) .
+- [`finitePagination`](#finite-pagination): Enable finite pagination when using the [`pagination`](#-pagination) widget (default: `false`) .
 - [`primaryKey`](#primary-key): Specify the primary key of your documents (default `undefined`).
 - [`keepZeroFacets`](#keep-zero-facets): Show the facets value even when they have 0 matches (default `false`).
-- [`matchingStrategy`](#matching-strategy): Determine the search strategy on words matching (default `last`).
 - [`requestConfig`](#request-config): Use custom request configurations.
-- ['httpClient'](#custom-http-client): Use a custom HTTP client.
+- [`httpClient`](#custom-http-client): Use a custom HTTP client.
+- [`meiliSearchParams`](#meilisearch-search-parameters): Override a selection of Meilisearch search parameters (default `undefined`).
 
 The options are added as the third parameter of the `instantMeilisearch` function.
 
 ```js
 import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
 
-const searchClient = instantMeiliSearch(
+const { searchClient } = instantMeiliSearch(
   'https://ms-adf78ae33284-106.lon.meilisearch.io',
   'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303',
   {
@@ -172,20 +174,6 @@ genres:
 { keepZeroFacets : true } // default: false
 ```
 
-### Matching strategy
-
-`matchingStrategy` gives you the possibility to choose how Meilisearch should handle the presence of multiple query words, see [documentation](https://www.meilisearch.com/docs/reference/api/search#matching-strategy).
-
-For example, if your query is `hello world` by default Meilisearch returns documents containing either both `hello` and `world` or documents that only contain `hello`. This is the `last` strategy, where words are stripped from the right.
-The other strategy is `all`, where both `hello` and `world` **must** be present in a document for it to be returned.
-
-
-```js
-{
-  matchingStrategy: 'all' // default last
-}
-```
-
 ### Request Config
 
 You can provide a custom request configuration. Available field can be [found here](https://fetch.spec.whatwg.org/#requestinit).
@@ -221,6 +209,66 @@ You can use your own HTTP client, for example, with [`axios`](https://github.com
 }
 ```
 
+### Meilisearch search parameters
+
+`meiliSearchParams` lets you override a set of search parameters that are sent off to Meilisearch.
+The following options can be overridden:
+[`attributesToRetrieve`](https://www.meilisearch.com/docs/reference/api/search#attributes-to-retrieve),
+[`attributesToCrop`](https://www.meilisearch.com/docs/reference/api/search#attributes-to-crop),
+[`cropLength`](https://www.meilisearch.com/docs/reference/api/search#crop-length),
+[`cropMarker`](https://www.meilisearch.com/docs/reference/api/search#crop-marker),
+[`attributesToHighlight`](https://www.meilisearch.com/docs/reference/api/search#attributes-to-highlight),
+[`highlightPreTag`, `highlightPostTag`](https://www.meilisearch.com/docs/reference/api/search#highlight-tags),
+[`showMatchesPosition`](https://www.meilisearch.com/docs/reference/api/search#show-matches-position),
+[`matchingStrategy`](https://www.meilisearch.com/docs/reference/api/search#matching-strategy),
+[`showRankingScore`](https://www.meilisearch.com/docs/reference/api/search#ranking-score),
+[`attributesToSearchOn`](https://www.meilisearch.com/docs/reference/api/search#customize-attributes-to-search-on-at-search-time).
+
+```js
+instantMeiliSearch(
+  // ...
+  {
+    meiliSearchParams: {
+      attributesToHighlight: ['overview'],
+      highlightPreTag: '<em>',
+      highlightPostTag: '</em>',
+      attributesToSearchOn: ['overview'],
+    },
+  }
+)
+```
+
+### Modify Meilisearch search parameters
+
+`instantMeiliSearch` returns an instance with two properties on it, one of them being `setMeiliSearchParams`.
+
+```js
+const { searchClient, setMeiliSearchParams } = instantMeiliSearch(/*...*/)
+```
+
+It modifies (or sets if not already set) the [overridden Meilisearch search parameters](#meilisearch-search-parameters).
+It only modifies parameters that are defined on the provided object, the following will not change `attributesToHighlight`.
+
+```js
+const { setMeiliSearchParams } = instantMeiliSearch(
+  // ...
+  {
+    meiliSearchParams: {
+      attributesToHighlight: ['overview'],
+      highlightPreTag: '<em>',
+      highlightPostTag: '</em>',
+      attributesToSearchOn: ['overview'],
+    },
+  }
+)
+
+setMeiliSearchParams({
+  highlightPreTag: '<mark>',
+  highlightPostTag: '</mark>',
+  attributesToSearchOn: ['overview', 'title'],
+})
+```
+
 ## 🪡 Example with InstantSearch
 
 The open-source [InstantSearch](https://www.algolia.com/doc/api-reference/widgets/js/) library powered by Algolia provides all the front-end tools you need to highly customize your search bar environment.
@@ -252,12 +300,14 @@ In `index.html`:
 In `app.js`:
 
 ```js
+const { searchClient } = instantMeiliSearch(
+  'https://ms-adf78ae33284-106.lon.meilisearch.io',
+  'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303'
+)
+
 const search = instantsearch({
   indexName: 'steam-video-games',
-  searchClient: instantMeiliSearch(
-    'https://ms-adf78ae33284-106.lon.meilisearch.io',
-    'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303'
-  ),
+  searchClient,
 })
 
 search.addWidgets([
@@ -381,7 +431,7 @@ const search = instantsearch({
     {
       // ... InstantMeiliSearch options
     }
-  ),
+  ).searchClient,
   // ... InstantSearch options
   routing: true // for example
 })

packages/instant-meilisearch/__tests__/assets/utils.ts

@@ -228,8 +228,11 @@ export type Movies = {
   _highlightResult?: Movies
 }
 
-const searchClient = instantMeiliSearch('http://localhost:7700', 'masterKey')
-const wrongSearchClient = instantMeiliSearch(
+const { searchClient } = instantMeiliSearch(
+  'http://localhost:7700',
+  'masterKey'
+)
+const { searchClient: wrongSearchClient } = instantMeiliSearch(
   'http://localhost:7777',
   'masterKey'
 )

packages/instant-meilisearch/__tests__/custom-http-client.test.ts

@@ -18,7 +18,7 @@ describe('Custom HTTP client tests', () => {
       return await result.json()
     })
 
-    const searchClient = instantMeiliSearch(
+    const { searchClient } = instantMeiliSearch(
       'http://localhost:7700',
       'masterKey',
       {