poc: warn added widgets require missing clients

examples/js/multi-clients/src/algolia.js

@@ -1,9 +1,12 @@
 import algoliasearch from 'algoliasearch/lite';
-import recommend from '@algolia/recommend';
+// import recommend from '@algolia/recommend';
 
 export function algolia(appID, apiKey) {
   const searchClient = algoliasearch(appID, apiKey);
-  const recommendClient = recommend(appID, apiKey);
-
-  return { searchClient, recommendClient };
+  // const recommendClient = recommend(appID, apiKey);
+
+  return {
+    searchClient,
+    // recommendClient,
+  };
 }

examples/js/multi-clients/src/search.js

@@ -1,5 +1,6 @@
 import instantsearch from 'instantsearch.js';
-import { algolia } from '@algolia/client';
+
+import { algolia } from './algolia';
 
 const client = algolia('XX85YRZZMV', '098f71f9e2267178bdfc08cc986d2999');
 

packages/instantsearch.js/src/connectors/frequently-bought-together/connectFrequentlyBoughtTogether.ts

@@ -1,12 +1,13 @@
 import { getFrequentlyBoughtTogether } from '@algolia/recommend-core';
+
 import {
-  SendEventForHits,
   checkRendering,
   createDocumentationMessageGenerator,
   createSendEventForHits,
   noop,
 } from '../../lib/utils';
 
+import type { SendEventForHits } from '../../lib/utils';
 import type { Connector, Hit, WidgetRenderState } from '../../types';
 
 const withUsage = createDocumentationMessageGenerator({
@@ -52,6 +53,8 @@ const connectFrequentlyBoughtTogether: FrequentlyBoughtTogetherConnector =
       return {
         $$type: 'ais.frequentlyBoughtTogether',
 
+        requires: ['recommendClient'],
+
         init(initOptions) {
           const { state, instantSearchInstance } = initOptions;
 

packages/instantsearch.js/src/lib/InstantSearch.ts

@@ -54,6 +54,11 @@ function defaultCreateURL() {
 // source: https://github.com/Microsoft/TypeScript/issues/14829#issuecomment-504042546
 type NoInfer<T> = T extends infer S ? S : never;
 
+export type InstantSearchClients = {
+  searchClient: SearchClient;
+  recommendClient: any;
+};
+
 /**
  * Global options for an InstantSearch instance.
  */
@@ -95,7 +100,7 @@ export type InstantSearchOptions<
    */
   searchClient?: SearchClient;
 
-  client?: { searchClient: SearchClient; recommendClient: any };
+  client?: InstantSearchClients;
 
   /**
    * The locale used to display numbers. This will be passed
@@ -191,6 +196,7 @@ class InstantSearch<
   TUiState extends UiState = UiState,
   TRouteState = TUiState
 > extends EventEmitter {
+  public clients: NonNullable<InstantSearchOptions['client']>;
   public client: NonNullable<InstantSearchOptions['searchClient']>;
   public recommendClient: any;
   public indexName: string;
@@ -334,8 +340,12 @@ See documentation: ${createDocumentationLink({
           `);
     }
 
-    this.client = (client?.searchClient || searchClient) as SearchClient;
-    this.recommendClient = client?.recommendClient!;
+    this.clients = client || {
+      searchClient: searchClient!,
+      recommendClient: undefined,
+    };
+    this.client = this.clients.searchClient;
+    this.recommendClient = this.clients.recommendClient!;
     this.future = future;
     this.insightsClient = insightsClient;
     this.indexName = indexName;

packages/instantsearch.js/src/types/widget.ts

@@ -1,3 +1,4 @@
+import type { InstantSearchClients } from '../lib/InstantSearch';
 import type { IndexWidget } from '../widgets/index/index';
 import type { InstantSearch } from './instantsearch';
 import type { IndexRenderState, WidgetRenderState } from './render-state';
@@ -140,6 +141,8 @@ type RequiredWidgetLifeCycle<TWidgetDescription extends WidgetDescription> = {
    */
   $$type: TWidgetDescription['$$type'];
 
+  requires?: Array<keyof InstantSearchClients>;
+
   /**
    * Called once before the first search.
    */

packages/instantsearch.js/src/widgets/index/index.ts

@@ -9,6 +9,7 @@ import {
   isIndexWidget,
   createInitArgs,
   createRenderArgs,
+  warn,
 } from '../../lib/utils';
 
 import type {
@@ -323,6 +324,16 @@ const index = (widgetParams: IndexWidgetParams): IndexWidget => {
       localWidgets = localWidgets.concat(widgets);
 
       if (localInstantSearchInstance && Boolean(widgets.length)) {
+        const [validWidgets, invalidWidgets] = satisfyWidgetRequirements(
+          localInstantSearchInstance,
+          widgets
+        );
+        if (invalidWidgets.length > 0) {
+          localWidgets = localWidgets.filter(
+            (widget) => invalidWidgets.indexOf(widget) === -1
+          );
+        }
+
         privateHelperSetState(helper!, {
           state: getLocalWidgetsSearchParameters(localWidgets, {
             uiState: localUiState,
@@ -334,7 +345,7 @@ const index = (widgetParams: IndexWidgetParams): IndexWidget => {
         // We compute the render state before calling `init` in a separate loop
         // to construct the whole render state object that is then passed to
         // `init`.
-        widgets.forEach((widget) => {
+        validWidgets.forEach((widget) => {
           if (widget.getRenderState) {
             const renderState = widget.getRenderState(
               localInstantSearchInstance!.renderState[this.getIndexId()] || {},
@@ -353,7 +364,7 @@ const index = (widgetParams: IndexWidgetParams): IndexWidget => {
           }
         });
 
-        widgets.forEach((widget) => {
+        validWidgets.forEach((widget) => {
           if (widget.init) {
             widget.init(
               createInitArgs(
@@ -444,6 +455,17 @@ const index = (widgetParams: IndexWidgetParams): IndexWidget => {
       localParent = parent;
       localUiState = uiState[indexId] || {};
 
+      // Ensure widgets requirements are available
+      const [, invalidWidgets] = satisfyWidgetRequirements(
+        localInstantSearchInstance,
+        localWidgets
+      );
+      if (invalidWidgets.length > 0) {
+        localWidgets = localWidgets.filter(
+          (widget) => invalidWidgets.indexOf(widget) === -1
+        );
+      }
+
       // The `mainHelper` is already defined at this point. The instance is created
       // inside InstantSearch at the `start` method, which occurs before the `init`
       // step.
@@ -784,3 +806,39 @@ function storeRenderState({
     },
   };
 }
+
+function satisfyWidgetRequirements(
+  instantSearchInstance: InstantSearch,
+  widgets: Array<Widget | IndexWidget>
+): [Array<Widget | IndexWidget>, Array<Widget | IndexWidget>] {
+  const clients = Object.keys(instantSearchInstance.clients);
+  const [widgetsToKeep, widgetsToSkip] = widgets.reduce(
+    ([keep, skip], widget) => {
+      if (
+        (widget.requires || ['searchClient']).some(
+          (requirement) => !clients.includes(requirement)
+        )
+      ) {
+        skip.push(widget);
+      } else {
+        keep.push(widget);
+      }
+
+      return [keep, skip];
+    },
+    [[] as Array<Widget | IndexWidget>, [] as Array<Widget | IndexWidget>]
+  );
+
+  if (widgetsToSkip.length > 0) {
+    warn(`Some widgets cannot be added to your InstantSearch application, because they require clients that are not configured:
+
+${widgetsToSkip
+  .map((widget) => `- ${widget.$$type} requires ${widget.requires}`)
+  .join('\n')}
+
+See: https://alg.li/instantsearch-multi-clients
+    `);
+  }
+
+  return [widgetsToKeep, widgetsToSkip];
+}