feat(custom client): allows to provide a custom JS client instance (#1948)

By passing createAlgoliaClient option to instantsearch() you can now provide your own client instance instead of relying on the one instantiated internally.

Usage:

```js
createAlgoliaClient: function(algoliasearch, appId, apiKey) {
  // return an algolia client here
}

Author: olance

src/lib/InstantSearch.js

@@ -13,6 +13,7 @@ import version from './version.js';
 import createHelpers from './createHelpers.js';
 
 function defaultCreateURL() { return '#'; }
+const defaultCreateAlgoliaClient = (defaultAlgoliasearch, appId, apiKey) => defaultAlgoliasearch(appId, apiKey);
 
 /**
  * @function instantsearch
@@ -24,6 +25,12 @@ function defaultCreateURL() { return '#'; }
  * @param  {function} [options.searchFunction] A hook that will be called each time a search needs to be done, with the
  * helper as a parameter. It's your responsibility to call helper.search(). This option allows you to avoid doing
  * searches at page load for example.
+ * @param   {function} [options.createAlgoliaClient] Allows you to provide your own algolia client instead of
+ * the one instantiated internally by instantsearch.js. Useful in situations where you need
+ * to setup complex options on the client or if you need to share it easily.
+ * Usage:
+ * `createAlgoliaClient: function(algoliasearch, appId, apiKey) { return anyCustomClient; }`
+ * We forward `algoliasearch` which is the original algoliasearch module imported inside instantsearch.js
  * @param  {Object} [options.searchParameters] Additional parameters to pass to
  * the Algolia API.
  * [Full documentation](https://community.algolia.com/algoliasearch-helper-js/reference.html#searchparameters)
@@ -60,6 +67,7 @@ class InstantSearch extends EventEmitter {
     searchParameters = {},
     urlSync = null,
     searchFunction,
+    createAlgoliaClient = defaultCreateAlgoliaClient,
   }) {
     super();
     if (appId === null || apiKey === null || indexName === null) {
@@ -72,7 +80,7 @@ Usage: instantsearch({
       throw new Error(usage);
     }
 
-    const client = algoliasearch(appId, apiKey);
+    const client = createAlgoliaClient(algoliasearch, appId, apiKey);
     client.addAlgoliaAgent(`instantsearch.js ${version}`);
 
     this.client = client;

src/lib/__tests__/InstantSearch-test.js

@@ -85,6 +85,42 @@ describe('InstantSearch lifecycle', () => {
     expect(algoliasearchHelper.notCalled).toBe(true, 'algoliasearchHelper not yet called');
   });
 
+  context('when providing a custom client module', () => {
+    let createAlgoliaClient;
+    let customAppID;
+    let customApiKey;
+
+    beforeEach(() => {
+      // InstantSearch is being called once at the top-level context, so reset the `algoliasearch` spy
+      algoliasearch.reset();
+
+      // Create a spy to act as a clientInstanceFunction that returns a custom client
+      createAlgoliaClient = sinon.stub().returns(client);
+      customAppID = 'customAppID';
+      customApiKey = 'customAPIKey';
+
+      // Create a new InstantSearch instance with custom client function
+      search = new InstantSearch({
+        appId: customAppID,
+        apiKey: customApiKey,
+        indexName,
+        searchParameters,
+        urlSync: {},
+        createAlgoliaClient,
+      });
+    });
+
+    it('does not call algoliasearch directly', () => {
+      expect(algoliasearch.calledOnce).toBe(false, 'algoliasearch not called');
+    });
+
+    it('calls createAlgoliaClient(appId, apiKey)', () => {
+      expect(createAlgoliaClient.calledOnce).toBe(true, 'clientInstanceFunction called once');
+      expect(createAlgoliaClient.args[0])
+        .toEqual([algoliasearch, customAppID, customApiKey]);
+    });
+  });
+
   context('when adding a widget without render and init', () => {
     let widget;