Merge #378

378: Change instantMeiliSearch parameters r=bidoubiwa a=bidoubiwa

fixes: #379 
fixes: #380 

# Summary

Change `instantMeiliSearch` to make integration tests not dependent on creating an instance of MeiliSearch. Thus making integrations possible. 

Refactor of files to create an environment for easy testing but also for a very maintainable code.


## Breaking changes

This PR breaks the repository in two different ways: 

### 1. `client` object inside instantMeiliSearch instance is now called `MeiliSearchClient`

Probably the only important breaking change that could potentially affect some users.
Naming had to change as it was very confusing for users

```js
const searchClient = instantMeiliSearch(
  'https://demos.meilisearch.com',
  'dc3fedaf922de8937fdea01f0a7d59557f1fd31832cb8440ce94231cfdde7f25',
  {
    paginationTotalHits: 60,
    primaryKey: 'id',
  }
)
```

to access MeiliSearch client this is the way: 

Now: 
```js
searchClient.client.MeiliSearchClient
```

Before:
```js
searchClient.client.client
```


### 2. the `instantMeiliSearch` class instance has less parameters than before:

Before: 
```js
export type InstantMeiliSearchInstance = {
  page: number
  paginationTotalHits: number
  hitsPerPage: number
  primaryKey: string | undefined
  client: MStypes.MeiliSearch
  placeholderSearch: boolean

  transformToISResponse: (
    indexUid: string,
    meiliSearchResponse: MStypes.SearchResponse<any, any>,
    instantSearchParams: ISSearchParams
  ) => { results: SearchResponse[] }

  transformToMeiliSearchParams: (
    instantSearchParams: ISSearchParams
  ) => Record<string, any>

  transformToISHits: (
    meiliSearchHits: Array<Record<string, any>>,
    instantSearchParams: ISSearchParams
  ) => ISHits[]
  getNumberPages: (hitsLength: number) => number
  paginateHits: (
    meiliSearchHits: Array<Record<string, any>>
  ) => Array<Record<string, any>>
  search: (
    requests: IStypes.SearchRequest[]
  ) => Promise<{ results: SearchResponse[] }>
}
```

after

```js
export type InstantMeiliSearchInstance = {
  MeiliSearchClient: MStypes.MeiliSearch
  search: (
    requests: IStypes.SearchRequest[]
  ) => Promise<{ results: SearchResponse[] }>
}
```

This refactor was done to make testing independent and not need a instantMeiliSearch instance context to be usable. Before that, we wouldn't have been able to perform integration tests. Only e2e tests.

The other reason is that we want to have a searchClient as close to what `instantSearch` is requesting which is the following: 

```js
export declare type SearchClient = {
    addAlgoliaAgent?: (agent: string) => void;
    search: (requests: SearchRequest[]) => Promise<{
        results: SearchResponse[];
    }>;
    searchForFacetValues?: (requests: SearchForFacetValuesRequest[]) => Promise<{
        facetHits: SearchForFacetValuesResponse[];
    }[]>;
};
```

🚨 It is probably not going to affect any user as it has no purpose for users. 

### 3. MeiliSearch types and InstantSearch types are not exported anymore

These types were exported because I needed them in other files. But this is not a good way to do it since typing should happen in types files and not a bit in every other file. 

🚨 It's probably not going to affect any user as it has no purpose for users.


Co-authored-by: Charlotte Vermandel <[email protected]>
Co-authored-by: cvermand <[email protected]>

Author: bors[bot]

rollup.config.js

@@ -13,6 +13,7 @@ function getOutputFileName(fileName, isProd = false) {
 
 const env = process.env.NODE_ENV || 'development'
 const ROOT = resolve(__dirname, '.')
+const INPUT = 'src/index.ts'
 
 const PLUGINS = [
   typescript({
@@ -27,7 +28,7 @@ const PLUGINS = [
 module.exports = [
   // browser-friendly IIFE build
   {
-    input: 'src/index.ts', // directory to transpilation of typescript
+    input: INPUT, // directory to transpilation of typescript
     output: {
       name: 'window',
       extend: true,
@@ -56,7 +57,7 @@ module.exports = [
     ],
   },
   {
-    input: 'src/index.ts',
+    input: INPUT,
     external: ['meilisearch'],
     output: [
       {

src/client/index.ts

@@ -0,0 +1,60 @@
+import { MeiliSearch } from 'meilisearch'
+import { InstantMeiliSearchOptions, InstantMeiliSearchInstance } from '../types'
+
+import {
+  transformToMeiliSearchParams,
+  transformToISResponse,
+} from '../transformers'
+
+export function instantMeiliSearch(
+  hostUrl: string,
+  apiKey: string,
+  options: InstantMeiliSearchOptions = {}
+): InstantMeiliSearchInstance {
+  return {
+    MeiliSearchClient: new MeiliSearch({ host: hostUrl, apiKey: apiKey }),
+    search: async function ([isSearchRequest]) {
+      try {
+        // Params got from InstantSearch
+        const {
+          params: instantSearchParams,
+          indexName: indexUid,
+        } = isSearchRequest
+
+        const { paginationTotalHits, primaryKey, placeholderSearch } = options
+        const { page, hitsPerPage } = instantSearchParams
+        const client = this.MeiliSearchClient
+        const context = {
+          client,
+          paginationTotalHits: paginationTotalHits || 200,
+          primaryKey: primaryKey || undefined,
+          placeholderSearch: placeholderSearch !== false, // true by default
+          hitsPerPage: hitsPerPage || 20, // 20 is the MeiliSearch's default limit value. `hitsPerPage` can be changed with `InsantSearch.configure`.
+          page: page || 0, // default page is 0 if none is provided
+        }
+
+        // Transform IS params to MeiliSearch params
+        const msSearchParams = transformToMeiliSearchParams(
+          instantSearchParams,
+          context
+        )
+
+        // Executes the search with MeiliSearch
+        const searchResponse = await client
+          .index(indexUid)
+          .search(msSearchParams.q, msSearchParams)
+
+        // Parses the MeiliSearch response and returns it for InstantSearch
+        return transformToISResponse(
+          indexUid,
+          searchResponse,
+          instantSearchParams,
+          context
+        )
+      } catch (e) {
+        console.error(e)
+        throw new Error(e)
+      }
+    },
+  }
+}

src/index.ts

@@ -1,162 +1,3 @@
-import { MeiliSearch } from 'meilisearch'
-import { createHighlighResult, createSnippetResult } from './format'
-import {
-  InstantMeiliSearchOptions,
-  InstantMeiliSearchInstance,
-  InstantSearchTypes,
-} from './types'
-
-export function instantMeiliSearch(
-  hostUrl: string,
-  apiKey: string,
-  options: InstantMeiliSearchOptions = {}
-): InstantMeiliSearchInstance {
-  return {
-    client: new MeiliSearch({ host: hostUrl, apiKey: apiKey }),
-    paginationTotalHits: options.paginationTotalHits || 200,
-    primaryKey: options.primaryKey || undefined,
-    placeholderSearch: options.placeholderSearch !== false, // true by default
-    hitsPerPage: 20,
-    page: 0,
-
-    /*
-      REQUEST
-    */
-
-    transformToMeiliSearchParams: function ({
-      query,
-      facets,
-      facetFilters,
-      attributesToSnippet: attributesToCrop,
-      attributesToRetrieve,
-      attributesToHighlight,
-      filters = '',
-      numericFilters = [],
-    }) {
-      const limit = this.paginationTotalHits
-
-      const filter = [numericFilters.join(' AND '), filters.trim()]
-        .filter((x) => x)
-        .join(' AND ')
-        .trim()
-
-      // Creates search params object compliant with MeiliSearch
-      return {
-        q: query,
-        ...(facets?.length && { facetsDistribution: facets }),
-        ...(facetFilters && { facetFilters }),
-        ...(attributesToCrop && { attributesToCrop }),
-        ...(attributesToRetrieve && { attributesToRetrieve }),
-        ...(filter && { filters: filter }),
-        attributesToHighlight: attributesToHighlight || ['*'],
-        limit: (!this.placeholderSearch && query === '') || !limit ? 0 : limit,
-      }
-    },
-
-    /*
-      RESPONSE
-    */
-
-    getNumberPages: function (hitsLength) {
-      const adjust = hitsLength % this.hitsPerPage! === 0 ? 0 : 1
-      return Math.floor(hitsLength / this.hitsPerPage!) + adjust // total number of pages
-    },
-
-    paginateHits: function (hits) {
-      const start = this.page * this.hitsPerPage!
-      return hits.splice(start, this.hitsPerPage)
-    },
-
-    transformToISHits: function (meiliSearchHits, instantSearchParams) {
-      const paginatedHits = this.paginateHits(meiliSearchHits)
-
-      return paginatedHits.map((hit: Record<string, any>) => {
-        const { _formatted: formattedHit, ...restOfHit } = hit
-
-        // Creates Hit object compliant with InstantSearch
-        return {
-          ...restOfHit,
-          _highlightResult: createHighlighResult({
-            formattedHit,
-            ...instantSearchParams,
-          }),
-          _snippetResult: createSnippetResult({
-            formattedHit,
-            ...instantSearchParams,
-          }),
-          ...(this.primaryKey && { objectID: hit[this.primaryKey] }),
-        }
-      })
-    },
-
-    transformToISResponse: function (
-      indexUid,
-      {
-        exhaustiveFacetsCount,
-        exhaustiveNbHits,
-        facetsDistribution: facets,
-        nbHits,
-        processingTimeMs,
-        query,
-        hits,
-      },
-      instantSearchParams
-    ) {
-      // Create response object compliant with InstantSearch
-      const ISResponse = {
-        index: indexUid,
-        hitsPerPage: this.hitsPerPage,
-        ...(facets && { facets }),
-        ...(exhaustiveFacetsCount && { exhaustiveFacetsCount }),
-        page: this.page,
-        nbPages: this.getNumberPages(hits.length),
-        exhaustiveNbHits,
-        nbHits,
-        processingTimeMS: processingTimeMs,
-        query,
-        hits: this.transformToISHits(hits, instantSearchParams),
-      }
-      return {
-        results: [ISResponse],
-      }
-    },
-
-    /*
-      SEARCH
-    */
-    search: async function ([
-      isSearchRequest,
-    ]: InstantSearchTypes.SearchRequest[]) {
-      try {
-        // Params got from InstantSearch
-        const {
-          params: instantSearchParams,
-          indexName: indexUid,
-        } = isSearchRequest
-        const { page, hitsPerPage } = instantSearchParams
-
-        this.page = page || 0 // default page is 0 if none is provided
-        this.hitsPerPage = hitsPerPage || 20 // 20 is the MeiliSearch's default limit value. `hitsPerPage` can be changed with `InsantSearch.configure`.
-
-        // Transform IS params to MeiliSearch params
-        const msSearchParams = this.transformToMeiliSearchParams(
-          instantSearchParams
-        )
-        // Executes the search with MeiliSearch
-        const searchResponse = await this.client
-          .index(indexUid)
-          .search(msSearchParams.q, msSearchParams)
-
-        // Parses the MeiliSearch response and returns it for InstantSearch
-        return this.transformToISResponse(
-          indexUid,
-          searchResponse,
-          instantSearchParams
-        )
-      } catch (e) {
-        console.error(e)
-        throw new Error(e)
-      }
-    },
-  }
-}
+export * from './client'
+export * from './transformers'
+export * from './types'

src/transformers/index.ts

@@ -0,0 +1,5 @@
+export * from './to-meilisearch-params'
+export * from './to-instantsearch-response'
+export * from './to-instantsearch-hits'
+export * from './to-instantsearch-highlight'
+export * from './pagination'

src/transformers/pagination.ts

@@ -0,0 +1,17 @@
+import { PaginateHits, GetNumberPages } from '../types'
+
+export const getNumberPages: GetNumberPages = function (
+  hitsLength,
+  { hitsPerPage }
+) {
+  const adjust = hitsLength % hitsPerPage! === 0 ? 0 : 1
+  return Math.floor(hitsLength / hitsPerPage!) + adjust // total number of pages
+}
+
+export const paginateHits: PaginateHits = function (
+  hits,
+  { page, hitsPerPage }
+) {
+  const start = page * hitsPerPage!
+  return hits.splice(start, hitsPerPage)
+}

src/format.ts renamed to src/transformers/to-instantsearch-highlight.ts

@@ -1,11 +1,16 @@
-import { ISSearchParams } from './types'
-import { isString } from './utils'
+import {
+  CreateHighlighResult,
+  ReplaceHighlightTags,
+  SnippetValue,
+  CreateSnippetResult,
+  isString,
+} from '../types'
 
-function replaceHighlightTags(
+export const replaceHighlightTags: ReplaceHighlightTags = (
   value: string,
   highlightPreTag?: string,
   highlightPostTag?: string
-): string {
+): string => {
   // Value has to be a string to have highlight.
   // Highlight is applied by MeiliSearch (<em> tags)
   // We replace the <em> by the expected tag for InstantSearch
@@ -20,11 +25,11 @@ function replaceHighlightTags(
   return JSON.stringify(value)
 }
 
-function createHighlighResult<T extends Record<string, any>>({
+export const createHighlighResult: CreateHighlighResult = ({
   formattedHit,
   highlightPreTag,
   highlightPostTag,
-}: { formattedHit: T } & ISSearchParams) {
+}) => {
   // formattedHit is the `_formatted` object returned by MeiliSearch.
   // It contains all the highlighted and croped attributes
   return Object.keys(formattedHit).reduce((result, key) => {
@@ -36,15 +41,15 @@ function createHighlighResult<T extends Record<string, any>>({
       ),
     }
     return result
-  }, {} as T)
+  }, {} as any)
 }
 
-function snippetFinalValue(
+export const snippetValue: SnippetValue = (
   value: string,
   snippetEllipsisText?: string,
   highlightPreTag?: string,
   highlightPostTag?: string
-) {
+) => {
   let newValue = value
   // manage a kind of `...` for the crop until this issue is solved: https://github.com/meilisearch/MeiliSearch/issues/923
   // `...` is put if we are at the middle of a sentence (instead at the middle of the document field)
@@ -63,28 +68,25 @@ function snippetFinalValue(
   return replaceHighlightTags(newValue, highlightPreTag, highlightPostTag)
 }
 
-function createSnippetResult<
-  T extends Record<string, any>,
-  K extends keyof T & string
->({
+export const createSnippetResult: CreateSnippetResult = ({
   formattedHit,
   attributesToSnippet,
   snippetEllipsisText,
   highlightPreTag,
   highlightPostTag,
-}: { formattedHit: T } & ISSearchParams) {
+}) => {
   if (attributesToSnippet === undefined) {
     return null
   }
   attributesToSnippet = attributesToSnippet.map(
     (attribute) => attribute.split(':')[0]
-  ) as K[]
+  ) as any[]
   // formattedHit is the `_formatted` object returned by MeiliSearch.
   // It contains all the highlighted and croped attributes
-  return (Object.keys(formattedHit) as K[]).reduce((result, key) => {
+  return (Object.keys(formattedHit) as any[]).reduce((result, key) => {
     if (attributesToSnippet!.includes(key)) {
       ;(result[key] as any) = {
-        value: snippetFinalValue(
+        value: snippetValue(
           formattedHit[key],
           snippetEllipsisText,
           highlightPreTag,
@@ -93,7 +95,5 @@ function createSnippetResult<
       }
     }
     return result
-  }, {} as T)
+  }, {} as any)
 }
-
-export { createHighlighResult, createSnippetResult }