feat(useInstantSearch): expose status & error (#3645)

<!--
  Thanks for submitting a pull request!
Please provide enough information so that others can review your pull
request.
-->

**Summary**

<!--
  Explain the **motivation** for making this change.
  What existing problem does the pull request solve?
  Are there any linked issues?
-->

Introduces `status` and `error` in the response of `useInstantSearch`,
as well as a new option on `useInstantSearch` to indicate errors in the
search lifecycle should be caught.

built on top of algolia/instantsearch#5127


**Result**

<!--
  Demonstrate the code is solid.
  Example: The exact commands you ran and their output,
  screenshots / videos if the pull request changes UI.
-->


```jsx
function Status() {
  const { status, error } = useInstantSearch({ catchError: true });

  return (
    <>
      <span>Search status: {status}</span>
      {error && <span>a search error occurred: {error.message}</span>}
    </>
  );
}
```


FX-1769

Author: Haroenv

examples/hooks-e-commerce/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "algoliasearch": "4.11.0",
-    "instantsearch.js": "4.46.1",
+    "instantsearch.js": "4.47.0",
     "react": "18.1.0",
     "react-compound-slider": "3.4.0",
     "react-dom": "18.1.0",

examples/hooks-react-native/package.json

@@ -14,7 +14,7 @@
     "algoliasearch": "4.12.1",
     "expo": "~44.0.0",
     "expo-status-bar": "~1.2.0",
-    "instantsearch.js": "4.46.1",
+    "instantsearch.js": "4.47.0",
     "react": "17.0.1",
     "react-dom": "17.0.1",
     "react-instantsearch-hooks": "6.35.0",

examples/hooks/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "algoliasearch": "4.11.0",
-    "instantsearch.js": "4.46.1",
+    "instantsearch.js": "4.47.0",
     "react": "18.1.0",
     "react-dom": "18.1.0",
     "react-instantsearch-hooks-web": "6.35.0"

package.json

@@ -168,7 +168,7 @@
     },
     {
       "path": "packages/react-instantsearch-hooks-web/dist/umd/ReactInstantSearchHooksDOM.min.js",
-      "maxSize": "49.75 kB"
+      "maxSize": "50 kB"
     },
     {
       "path": "packages/react-instantsearch-dom/dist/umd/ReactInstantSearchDOM.min.js",

packages/react-instantsearch-hooks-server/package.json

@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.1.2",
-    "instantsearch.js": "^4.46.1",
+    "instantsearch.js": "^4.47.0",
     "react-instantsearch-hooks": "6.35.0"
   },
   "peerDependencies": {

packages/react-instantsearch-hooks-web/package.json

@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.1.2",
-    "instantsearch.js": "^4.46.1",
+    "instantsearch.js": "^4.47.0",
     "react-instantsearch-hooks": "6.35.0"
   },
   "peerDependencies": {

packages/react-instantsearch-hooks/package.json

@@ -48,7 +48,7 @@
   "dependencies": {
     "@babel/runtime": "^7.1.2",
     "algoliasearch-helper": "^3.11.1",
-    "instantsearch.js": "^4.46.1",
+    "instantsearch.js": "^4.47.0",
     "use-sync-external-store": "^1.0.0"
   },
   "peerDependencies": {

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

@@ -384,6 +384,8 @@ describe('useConnector', () => {
       searchMetadata: {
         isSearchStalled: false,
       },
+      status: 'idle',
+      error: undefined,
     });
   });
 

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

@@ -9,6 +9,7 @@ import { createSearchClient } from '../../../../../test/mock';
 import {
   createInstantSearchTestWrapper,
   InstantSearchHooksTestWrapper,
+  wait,
 } from '../../../../../test/utils';
 import { useInstantSearch } from '../useInstantSearch';
 
@@ -286,4 +287,124 @@ describe('useInstantSearch', () => {
       expect(result.current.refresh).toBe(ref);
     });
   });
+
+  describe('status', () => {
+    test('initial status: idle', () => {
+      const App = () => (
+        <InstantSearchHooksTestWrapper>
+          <SearchBox />
+          <Status />
+        </InstantSearchHooksTestWrapper>
+      );
+
+      const { getByTestId } = render(<App />);
+
+      expect(getByTestId('status')).toHaveTextContent('idle');
+    });
+
+    test('turns to loading and idle when searching', async () => {
+      const App = () => (
+        <InstantSearchHooksTestWrapper
+          searchClient={createDelayedSearchClient(20)}
+        >
+          <SearchBox placeholder="search here" />
+          <Status />
+        </InstantSearchHooksTestWrapper>
+      );
+
+      const { getByTestId, getByPlaceholderText } = render(<App />);
+
+      expect(getByTestId('status')).toHaveTextContent('idle');
+
+      userEvent.type(getByPlaceholderText('search here'), 'hey search');
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('loading');
+      });
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('idle');
+      });
+    });
+
+    test('turns to loading, stalled and idle when searching slowly', async () => {
+      const App = () => (
+        <InstantSearchHooksTestWrapper
+          searchClient={createDelayedSearchClient(300)}
+          stalledSearchDelay={200}
+        >
+          <SearchBox placeholder="search here" />
+          <Status />
+        </InstantSearchHooksTestWrapper>
+      );
+
+      const { getByTestId, getByPlaceholderText } = render(<App />);
+
+      expect(getByTestId('status')).toHaveTextContent('idle');
+
+      userEvent.type(getByPlaceholderText('search here'), 'h');
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('loading');
+      });
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('stalled');
+      });
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('idle');
+      });
+    });
+
+    test('turns to loading and error when searching', async () => {
+      const searchClient = createSearchClient({});
+      searchClient.search.mockImplementation(() =>
+        Promise.reject(new Error('API_ERROR'))
+      );
+
+      const App = () => (
+        <InstantSearchHooksTestWrapper searchClient={searchClient}>
+          <SearchBox placeholder="search here" />
+          {/* has catchError, as the real error can not be asserted upon */}
+          <Status catchError />
+        </InstantSearchHooksTestWrapper>
+      );
+
+      const { getByTestId, getByPlaceholderText } = render(<App />);
+
+      expect(getByTestId('status')).toHaveTextContent('idle');
+      expect(getByTestId('error')).toBeEmptyDOMElement();
+
+      userEvent.type(getByPlaceholderText('search here'), 'hey search');
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('loading');
+        expect(getByTestId('error')).toBeEmptyDOMElement();
+      });
+
+      await waitFor(() => {
+        expect(getByTestId('status')).toHaveTextContent('error');
+        expect(getByTestId('error')).toHaveTextContent('API_ERROR');
+      });
+    });
+
+    function Status(props) {
+      const { status, error } = useInstantSearch(props);
+
+      return (
+        <>
+          <span data-testid="status">{status}</span>
+          <span data-testid="error">{error?.message}</span>
+        </>
+      );
+    }
+
+    function createDelayedSearchClient(timeout: number) {
+      const searchFn = createSearchClient({}).search!;
+      return createSearchClient({
+        search: (requests) => wait(timeout).then(() => searchFn(requests)),
+      });
+    }
+  });
 });

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

@@ -115,8 +115,10 @@ export function useConnector<
         templatesConfig: search.templatesConfig,
         createURL: parentIndex.createURL,
         searchMetadata: {
-          isSearchStalled: search._isSearchStalled,
+          isSearchStalled: search.status === 'stalled',
         },
+        status: search.status,
+        error: search.error,
       });
 
       return renderState;