Changes related to the next MeiliSearch release (v0.24.0)

README.md

@@ -181,7 +181,7 @@ This package only guarantees the compatibility with the [version v4 of InstantSe
 
 **Supported MeiliSearch versions**:
 
-This package only guarantees the compatibility with the [version v0.23.0 of MeiliSearch](https://github.com/meilisearch/MeiliSearch/releases/tag/v0.23.0).
+This package only guarantees the compatibility with the [version v0.24.0 of MeiliSearch](https://github.com/meilisearch/MeiliSearch/releases/tag/v0.24.0).
 
 **Node / NPM versions**:
 

package.json

@@ -54,7 +54,7 @@
     "url": "https://github.com/meilisearch/instant-meilisearch.git"
   },
   "dependencies": {
-    "meilisearch": "^0.22.3"
+    "meilisearch": "^0.23.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.16.0",

playgrounds/angular/src/app/app.component.html

@@ -10,8 +10,7 @@ <h1 class="header-title">MeiliSearch + Angular InstantSearch</h1>
     <div class="search-panel">
       <div class="search-panel__filters">
         <ais-clear-refinements></ais-clear-refinements>
-        <ais-sort-by
-          [items]="[
+        <ais-sort-by [items]="[
           { value: 'steam-video-games', label: 'Relevant' },
           {
             value: 'steam-video-games:recommendationCount:desc',
@@ -21,17 +20,18 @@ <h1 class="header-title">MeiliSearch + Angular InstantSearch</h1>
             value: 'steam-video-games:recommendationCount:asc',
             label: 'Least Recommended'
           }
-          ]"
-        ></ais-sort-by>
-        <ais-configure [searchParameters]="{ hitsPerPage: 6 }"></ais-configure>
+          ]"></ais-sort-by>
+        <ais-configure
+          [searchParameters]="{ hitsPerPage: 6, attributesToSnippet: ['description:10'], snippetEllipsisText:'...' }">
+        </ais-configure>
         <h2>Genres</h2>
-        <ais-refinement-list attribute="genres" ></ais-refinement-list>
+        <ais-refinement-list attribute="genres"></ais-refinement-list>
         <h2>Players</h2>
-        <ais-refinement-list attribute="players" ></ais-refinement-list>
+        <ais-refinement-list attribute="players"></ais-refinement-list>
         <h2>Platforms</h2>
-        <ais-refinement-list attribute="platforms" ></ais-refinement-list>
+        <ais-refinement-list attribute="platforms"></ais-refinement-list>
         <h2>Misc</h2>
-        <ais-refinement-list attribute="misc" ></ais-refinement-list>
+        <ais-refinement-list attribute="misc"></ais-refinement-list>
       </div>
 
       <div class="search-panel__results">
@@ -51,7 +51,8 @@ <h2>Misc</h2>
                   <ais-highlight attribute="name" [hit]="hit"></ais-highlight>
                 </div>
                 <div class="hit-description">
-                  <ais-highlight attribute="description" [hit]="hit"></ais-highlight>
+                  <ais-snippet attribute="description" [hit]="hit">
+                  </ais-snippet>
                 </div>
                 <div class="hit-info">price: ${{hit.price}}</div>
                 <div class="hit-info">Release date: {{hit.releaseDate}}</div>

src/adapter/search-response-adapter/format-adapter/format-adapter.ts

@@ -0,0 +1,37 @@
+import { adaptHighlight } from './highlight-adapter'
+import { adaptSnippet } from './snippet-adapter'
+import { SearchContext } from '../../../types'
+
+/**
+ * Adapt MeiliSearch formating to formating compliant with instantsearch.js.
+ *
+ * @param  {Record<string} formattedHit
+ * @param  {SearchContext} searchContext
+ * @returns {Record}
+ */
+export function adaptFormating(
+  hit: Record<string, any>,
+  searchContext: SearchContext
+): Record<string, any> {
+  const attributesToSnippet = searchContext?.attributesToSnippet
+  const ellipsis = searchContext?.snippetEllipsisText
+  const preTag = searchContext?.highlightPreTag
+  const postTag = searchContext?.highlightPostTag
+
+  if (!hit._formatted) return {}
+  const _highlightResult = adaptHighlight(hit, preTag, postTag)
+
+  // what is ellipsis by default
+  const _snippetResult = adaptHighlight(
+    adaptSnippet(hit, attributesToSnippet, ellipsis),
+    preTag,
+    postTag
+  )
+
+  const highlightedHit = {
+    _highlightResult,
+    _snippetResult,
+  }
+
+  return highlightedHit
+}

src/adapter/search-response-adapter/format-adapter/highlight-adapter.ts

@@ -0,0 +1,76 @@
+import { isString } from '../../../utils'
+/**
+ * Replace `em` tags in highlighted MeiliSearch hits to
+ * provided tags by instantsearch.js.
+ *
+ * @param  {string} value
+ * @param  {string} highlightPreTag?
+ * @param  {string} highlightPostTag?
+ * @returns {string}
+ */
+function replaceDefaultEMTag(
+  value: any,
+  preTag = '__ais-highlight__',
+  postTag = '__/ais-highlight__'
+): string {
+  // Highlight is applied by MeiliSearch (<em> tags)
+  // We replace the <em> by the expected tag for InstantSearch
+  const stringifiedValue = isString(value) ? value : JSON.stringify(value)
+
+  return stringifiedValue.replace(/<em>/g, preTag).replace(/<\/em>/g, postTag)
+}
+
+function addHighlightTags(
+  value: any,
+  preTag?: string,
+  postTag?: string
+): string {
+  if (typeof value === 'string') {
+    // String
+    return replaceDefaultEMTag(value, preTag, postTag)
+  } else if (value === undefined) {
+    // undefined
+    return JSON.stringify(null)
+  } else {
+    // Other
+    return JSON.stringify(value)
+  }
+}
+
+export function resolveHighlightValue(
+  value: any,
+  preTag?: string,
+  postTag?: string
+): { value: string } | Array<{ value: string }> {
+  if (Array.isArray(value)) {
+    // Array
+    return value.map((elem) => ({
+      value: addHighlightTags(elem, preTag, postTag),
+    }))
+  } else {
+    return { value: addHighlightTags(value, preTag, postTag) }
+  }
+}
+
+/**
+ * @param  {Record<string} formattedHit
+ * @param  {string} highlightPreTag?
+ * @param  {string} highlightPostTag?
+ * @returns {Record}
+ */
+export function adaptHighlight(
+  hit: Record<string, any>,
+  preTag?: string,
+  postTag?: string
+): Record<string, any> {
+  // hit is the `_formatted` object returned by MeiliSearch.
+  // It contains all the highlighted and croped attributes
+
+  if (!hit._formatted) return hit._formatted
+  return Object.keys(hit._formatted).reduce((result, key) => {
+    const value = hit._formatted[key]
+
+    result[key] = resolveHighlightValue(value, preTag, postTag)
+    return result
+  }, {} as any)
+}

src/adapter/search-response-adapter/format-adapter/index.ts

@@ -0,0 +1 @@
+export * from './format-adapter'

src/adapter/search-response-adapter/format-adapter/snippet-adapter.ts

@@ -0,0 +1,95 @@
+import { isString } from '../../../utils'
+
+function nakedOfTags(str: string) {
+  return str.replace(/<em>/g, '').replace(/<\/em>/g, '')
+}
+
+function addEllipsis(value: any, formatValue: string, ellipsis: string): any {
+  // Manage ellpsis on cropped values until this feature is implemented https://roadmap.meilisearch.com/c/69-policy-for-cropped-values?utm_medium=social&utm_source=portal_share in MeiliSearch
+
+  let ellipsedValue = formatValue
+
+  if (
+    isString(formatValue) &&
+    value.toString().length > nakedOfTags(formatValue).length
+  ) {
+    if (
+      formatValue[0] === formatValue[0].toLowerCase() && // beginning of a sentence
+      formatValue.startsWith('<em>') === false // beginning of the document field, otherwise MeiliSearch would crop around the highlight
+    ) {
+      ellipsedValue = `${ellipsis}${formatValue.trim()}`
+    }
+    if (!!formatValue.match(/[.!?]$/) === false) {
+      // end of the sentence
+      ellipsedValue = `${formatValue.trim()}${ellipsis}`
+    }
+  }
+  return ellipsedValue
+}
+
+/**
+ * @param  {string} value
+ * @param  {string} ellipsis?
+ * @returns {string}
+ */
+function resolveSnippet(value: any, formatValue: any, ellipsis?: string): any {
+  if (!ellipsis || !(typeof formatValue === 'string')) {
+    return formatValue
+  } else if (Array.isArray(value)) {
+    // Array
+    return value.map((elem) => addEllipsis(elem, formatValue, ellipsis))
+  }
+  return addEllipsis(value, formatValue, ellipsis)
+}
+
+/**
+ * @param  {Record<string} hit
+ * @param  {readonlystring[]|undefined} attributes
+ * @param  {string|undefined} ellipsis
+ */
+export function adaptSnippet(
+  hit: Record<string, any>,
+  attributes: readonly string[] | undefined,
+  ellipsis: string | undefined
+): Record<string, any> {
+  // hit is the `_formatted` object returned by MeiliSearch.
+  // It contains all the highlighted and croped attributes
+
+  const formattedHit = hit._formatted
+  const newHit = hit._formatted
+
+  if (attributes === undefined) {
+    return hit
+  }
+
+  // All attributes that should be snippeted and their snippet size
+  const snippets = attributes.map(
+    (attribute) => attribute.split(':')[0]
+  ) as any[]
+
+  // Find presence of a wildcard *
+  const wildCard = snippets.includes('*')
+
+  if (wildCard) {
+    // In case of *
+    for (const attribute in formattedHit) {
+      newHit[attribute] = resolveSnippet(
+        hit[attribute],
+        formattedHit[attribute],
+        ellipsis
+      )
+    }
+  } else {
+    // Itterate on all attributes that needs snippeting
+    for (const attribute of snippets) {
+      newHit[attribute] = resolveSnippet(
+        hit[attribute],
+        formattedHit[attribute],
+        ellipsis
+      )
+    }
+  }
+  hit._formatted = newHit
+
+  return hit
+}