fix(useInstantSearch): deprecate use function (#5781)

examples/react-hooks/e-commerce/components/ScrollTo.tsx

@@ -3,7 +3,7 @@ import React, { useEffect, useRef } from 'react';
 import { useInstantSearch } from 'react-instantsearch-hooks-web';
 
 export function ScrollTo({ children }: { children: React.ReactNode }) {
-  const { use } = useInstantSearch();
+  const { addMiddlewares } = useInstantSearch();
   const containerRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -24,8 +24,8 @@ export function ScrollTo({ children }: { children: React.ReactNode }) {
       };
     };
 
-    return use(middleware);
-  }, [use]);
+    return addMiddlewares(middleware);
+  }, [addMiddlewares]);
 
   return (
     <div ref={containerRef} className="ais-ScrollTo">

packages/react-instantsearch-hooks/src/hooks/__tests__/useInstantSearch.test.tsx

@@ -173,7 +173,7 @@ describe('useInstantSearch', () => {
   });
 
   describe('middleware', () => {
-    test('gives access to the use function', async () => {
+    test('gives access to the addMiddlewares function', async () => {
       const subscribe = jest.fn();
       const onStateChange = jest.fn();
       const unsubscribe = jest.fn();
@@ -184,8 +184,8 @@ describe('useInstantSearch', () => {
       }));
 
       function Middleware() {
-        const { use } = useInstantSearch();
-        useEffect(() => use(middleware), [use]);
+        const { addMiddlewares } = useInstantSearch();
+        useEffect(() => addMiddlewares(middleware), [addMiddlewares]);
 
         return null;
       }
@@ -232,13 +232,40 @@ describe('useInstantSearch', () => {
         wrapper,
       });
 
-      expect(result.current.use).toBeInstanceOf(Function);
+      expect(result.current.addMiddlewares).toBeInstanceOf(Function);
 
-      const ref = result.current.use;
+      const ref = result.current.addMiddlewares;
 
       rerender();
 
-      expect(result.current.use).toBe(ref);
+      expect(result.current.addMiddlewares).toBe(ref);
+    });
+
+    test('warns when using the deprecated use function', () => {
+      function Middleware() {
+        const { use } = useInstantSearch();
+        useEffect(
+          () =>
+            use(() => ({
+              subscribe() {},
+            })),
+          [use]
+        );
+
+        return null;
+      }
+
+      function App() {
+        return (
+          <InstantSearchHooksTestWrapper>
+            <Middleware />
+          </InstantSearchHooksTestWrapper>
+        );
+      }
+
+      expect(() => render(<App />)).toWarnDev(
+        '[InstantSearch] The `use` function is deprecated and will be removed in the next major version. Please use `addMiddlewares` instead.'
+      );
     });
   });
 

packages/react-instantsearch-hooks/src/hooks/useInstantSearch.ts

@@ -4,6 +4,7 @@ import { useInstantSearchContext } from '../lib/useInstantSearchContext';
 import { useIsomorphicLayoutEffect } from '../lib/useIsomorphicLayoutEffect';
 import { useSearchResults } from '../lib/useSearchResults';
 import { useSearchState } from '../lib/useSearchState';
+import { warn } from '../lib/warn';
 
 import type { SearchResultsApi } from '../lib/useSearchResults';
 import type { SearchStateApi } from '../lib/useSearchState';
@@ -12,9 +13,29 @@ import type { InstantSearch, Middleware, UiState } from 'instantsearch.js';
 export type InstantSearchApi<TUiState extends UiState = UiState> =
   SearchStateApi<TUiState> &
     SearchResultsApi & {
+      /**
+       * Adds middlewares to InstantSearch. It returns its own cleanup function.
+       */
+      addMiddlewares: (...middlewares: Middleware[]) => () => void;
+      /**
+       * @deprecated Use `addMiddlewares` instead.
+       */
       use: (...middlewares: Middleware[]) => () => void;
+      /**
+       * Clears the search client’s cache and performs a new search.
+       *
+       * This is useful to update the results once an indexing operation has finished.
+       */
       refresh: InstantSearch['refresh'];
+      /**
+       * The status of the search happening.
+       */
       status: InstantSearch['status'];
+      /**
+       * The error that occurred during the search.
+       *
+       * This is only valid when status is 'error'.
+       */
       error: InstantSearch['error'];
     };
 
@@ -33,15 +54,28 @@ export function useInstantSearch<TUiState extends UiState = UiState>({
     useSearchState<TUiState>();
   const { results, scopedResults } = useSearchResults();
 
+  const addMiddlewares: InstantSearchApi<TUiState>['addMiddlewares'] =
+    useCallback(
+      (...middlewares: Middleware[]) => {
+        search.use(...middlewares);
+
+        return () => {
+          search.unuse(...middlewares);
+        };
+      },
+      [search]
+    );
+
+  // @MAJOR: Remove in v7
   const use: InstantSearchApi<TUiState>['use'] = useCallback(
     (...middlewares: Middleware[]) => {
-      search.use(...middlewares);
-
-      return () => {
-        search.unuse(...middlewares);
-      };
+      warn(
+        false,
+        'The `use` function is deprecated and will be removed in the next major version. Please use `addMiddlewares` instead.'
+      );
+      return addMiddlewares(...middlewares);
     },
-    [search]
+    [addMiddlewares]
   );
 
   const refresh: InstantSearchApi<TUiState>['refresh'] = useCallback(() => {
@@ -64,6 +98,7 @@ export function useInstantSearch<TUiState extends UiState = UiState>({
     setUiState,
     indexUiState,
     setIndexUiState,
+    addMiddlewares,
     use,
     refresh,
     status: search.status,