feat(search-client): Add support for Custom Search Clients (#432)

* feat: Add `search-client` support

* feat: Call `addAlgoliaAgent` only if exists

* test: Add tests for `search-client`

* docs: Add `search-client` prop to Index documentation

* refactor: Remove `Object.create()` to create client

* refactor: Use `else if` for ESLint

* docs: Add section on store with custom search client

docs/src/components/index.md

@@ -54,6 +54,7 @@ Provide search query parameters:
 | cache            | Boolean | `true`  | Whether to cache results or not. See [the documentation](https://www.algolia.com/doc/tutorials/getting-started/quick-start-with-the-api-client/javascript/#cache)       |
 | auto-search      | Boolean | `true`  | Whether to initiate a query to Algolia when this component is mounted                                                                               |
 | stalledSearchDelay | number | `200`  | Time before the search is considered unresponsive. Used to display a loading indicator. |
+| search-client | Object | `` | The search client to plug to InstantSearch |
 
 ## Slots
 

docs/src/getting-started/search-store.md

@@ -66,6 +66,42 @@ const searchStore = createFromAlgoliaClient(client);
 
 Note that there is no reason to provide your own client if you are not reusing it elsewhere.
 
+### Create a search store from a custom search client
+
+If you want to use the [official JavaScript API Client](https://github.com/algolia/algoliasearch-client-javascript) on your backend, or even a custom search client, you can create an object implementing the `search()` method (and `searchForFacetValues()` if needed).
+
+The search client can be passed to the [`search-client`](../components/index.html#props) prop of the [`Index`](../components/index.html):
+
+```html
+<template>
+  <ais-index
+    index-name="your_indexName"
+    :search-client="searchClient"
+  >
+    <!-- Add your InstantSearch components here. -->
+  </ais-index>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        searchClient: {
+          search(requests) {
+            // perform the requests
+            return response;
+          },
+          searchForFacetValues(requests) {
+            // perform the requests
+            return response;
+          },
+        },
+      },
+    },
+  };
+</script>
+```
+
 ### Create a search store from an Algolia helper instance
 
 The [Algolia helper](https://github.com/algolia/algoliasearch-helper-js) is a JavaScript library that is built on top of the Algolia API client. Its goal is to enable a simple API to achieve advanced queries while also providing utility methods and behavior like keeping track of the last result.

src/components/Index.vue

@@ -5,7 +5,10 @@
 </template>
 
 <script>
-import { createFromAlgoliaCredentials } from '../store';
+import {
+  createFromAlgoliaCredentials,
+  createFromAlgoliaClient,
+} from '../store';
 import algoliaComponent from '../component';
 
 export default {
@@ -17,6 +20,9 @@ export default {
         return this._searchStore;
       },
     },
+    searchClient: {
+      type: Object,
+    },
     apiKey: {
       type: String,
       default() {
@@ -73,7 +79,37 @@ export default {
     };
   },
   provide() {
-    if (!this.searchStore) {
+    if (this.searchClient) {
+      if (!this.indexName) {
+        throw new Error(
+          'vue-instantsearch: `indexName` is required with `searchClient`'
+        );
+      }
+
+      if (this.searchStore) {
+        throw new Error('`searchStore` cannot be used with `searchClient`');
+      }
+
+      if (this.appId) {
+        throw new Error(
+          'vue-instantsearch: `appId` cannot be used with `searchClient`'
+        );
+      }
+
+      if (this.apiKey) {
+        throw new Error(
+          'vue-instantsearch: `apiKey` cannot be used with `searchClient`'
+        );
+      }
+
+      if (typeof this.searchClient.search !== 'function') {
+        throw new Error(
+          'vue-instantsearch: `searchClient` must implement a method `search(requests)`'
+        );
+      }
+
+      this._localSearchStore = createFromAlgoliaClient(this.searchClient);
+    } else if (!this.searchStore) {
       this._localSearchStore = createFromAlgoliaCredentials(
         this.appId,
         this.apiKey,

src/components/__tests__/__snapshots__/index.js.snap

@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Search Client API collision and apiKey 1`] = `"vue-instantsearch: \`apiKey\` cannot be used with \`searchClient\`"`;
+
+exports[`Search Client API collision and appId 1`] = `"vue-instantsearch: \`appId\` cannot be used with \`searchClient\`"`;
+
+exports[`Search Client API collision and searchStore 1`] = `"\`searchStore\` cannot be used with \`searchClient\`"`;
+
+exports[`Search Client API collision without indexName 1`] = `"vue-instantsearch: \`indexName\` is required with \`searchClient\`"`;
+
+exports[`Search Client Properties throws if no \`search()\` method 1`] = `"vue-instantsearch: \`searchClient\` must implement a method \`search(requests)\`"`;

src/components/__tests__/index.js

@@ -0,0 +1,120 @@
+import Vue from 'vue';
+import Index from '../Index.vue';
+
+describe('Search Client', () => {
+  describe('Properties', () => {
+    it('throws if no `search()` method', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            indexName: 'indexName',
+            searchClient: {},
+          },
+        });
+
+        vm.$mount();
+      }).toThrowErrorMatchingSnapshot();
+    });
+  });
+
+  describe('API collision', () => {
+    test('and indexName', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            indexName: 'indexName',
+            searchClient: {
+              search() {
+                return Promise.resolve({ results: [{ hits: [] }] });
+              },
+            },
+          },
+        });
+
+        vm.$mount();
+      }).not.toThrow();
+    });
+
+    test('without indexName', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            searchClient: {
+              search() {
+                return Promise.resolve({ results: [{ hits: [] }] });
+              },
+            },
+          },
+        });
+
+        vm.$mount();
+      }).toThrowErrorMatchingSnapshot();
+    });
+
+    test('and appId', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            indexName: 'indexName',
+            appId: 'appId',
+            searchClient: {
+              search() {
+                return Promise.resolve({ results: [{ hits: [] }] });
+              },
+            },
+          },
+        });
+
+        vm.$mount();
+      }).toThrowErrorMatchingSnapshot();
+    });
+
+    test('and apiKey', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            indexName: 'indexName',
+            apiKey: 'apiKey',
+            searchClient: {
+              search() {
+                return Promise.resolve({ results: [{ hits: [] }] });
+              },
+            },
+          },
+        });
+
+        vm.$mount();
+      }).toThrowErrorMatchingSnapshot();
+    });
+
+    test('and searchStore', () => {
+      expect(() => {
+        const Component = Vue.extend(Index);
+
+        const vm = new Component({
+          propsData: {
+            indexName: 'indexName',
+            searchStore: {},
+            searchClient: {
+              search() {
+                return Promise.resolve({ results: [{ hits: [] }] });
+              },
+            },
+          },
+        });
+
+        vm.$mount();
+      }).toThrowErrorMatchingSnapshot();
+    });
+  });
+});

src/store.js

@@ -86,7 +86,11 @@ export class Store {
     this._helper.on('result', onHelperResult.bind(this));
     this._helper.on('search', onHelperSearch.bind(this));
 
-    this._helper.getClient().addAlgoliaAgent(`vue-instantsearch ${version}`);
+    const client = this._helper.getClient();
+
+    if (typeof client.addAlgoliaAgent === 'function') {
+      client.addAlgoliaAgent(`vue-instantsearch ${version}`);
+    }
 
     this._stalledSearchTimer = null;
     this.isSearchStalled = true;