Merge pull request #99 from aave/fix/read-hooks-error

fix: error handling in read hooks

Author: cesarenaldi

.changeset/funny-waves-argue.md

@@ -0,0 +1,5 @@
+---
+"@aave/react": patch
+---
+
+**fix:** error handling in read hooks with suspense enabled

.github/workflows/release.yml

@@ -0,0 +1,31 @@
+permissions:
+  contents: read
+  pull-requests: write
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Create Release Pull Request
+        uses: changesets/action@v1
+        with:
+          branchName: 'release/packages'
+          title: 'chore: release packages'
+          commit: 'chore: bump package versions'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+ 
+## Dev environment tips
+
+- Use `nvm use` to use the correct Node.js version.
+- Use `corepack enable` to install the correct version of pnpm.
+- Use `pnpm install` to install the dependencies.
+- Use `pnpm build` to build the project.
+
+## Testing instructions
+
+- Use `pnpm test:client --run` to run `@aave/client` tests.
+- Use `pnpm test:react --run` to run `@aave/react` tests.
+- Use `pnpm vitest --run --project <project-name> <path-to-test-file> -t "<test-name>"` to focus on one single test.

packages/react/README.md

@@ -50,10 +50,12 @@ function MarketData() {
 }
 
 function UserPositions() {
-  const { data: supplies } = useUserSupplies({
+  const { data: supplies, loading } = useUserSupplies({
     markets: [evmAddress('0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2')],
     user: evmAddress('0x742d35cc6e5c4ce3b69a2a8c7c8e5f7e9a0b1234'),
   });
+
+  if (loading) return <div>Loading...</div>;
 
   return <div>Supplies: {supplies?.length || 0}</div>;
 }

packages/react/package.json

@@ -69,6 +69,7 @@
     "@types/react": "^19.1.8",
     "ethers": "^6.14.4",
     "happy-dom": "^18.0.1",
+    "msw": "^2.10.5",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "thirdweb": "^5.105.25",

packages/react/src/helpers/reads.test.ts

@@ -0,0 +1,131 @@
+import { UnexpectedError } from '@aave/client';
+import { HealthQuery } from '@aave/graphql';
+import { graphql, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+import { renderHookWithinContext } from '../test-utils';
+import { useSuspendableQuery } from './reads';
+
+const server = setupServer(
+  graphql.query(HealthQuery, () => {
+    return HttpResponse.json({
+      data: {
+        value: true,
+      },
+    });
+  }),
+);
+
+describe(`Given the '${useSuspendableQuery.name}' hook`, () => {
+  beforeAll(() => {
+    server.listen();
+  });
+
+  afterEach(() => {
+    server.resetHandlers();
+  });
+
+  afterAll(() => {
+    server.close();
+  });
+
+  describe('When rendering with suspense disabled', () => {
+    it('Then it should return data after a loading state', async () => {
+      const { result } = renderHookWithinContext(() =>
+        useSuspendableQuery({
+          document: HealthQuery,
+          variables: {},
+          suspense: false,
+        }),
+      );
+
+      await vi.waitUntil(() => !result.current.loading);
+
+      expect(result.current.loading).toBe(false);
+      expect(result.current.data).toBe(true);
+      expect(result.current.error).toBeUndefined();
+    });
+
+    it('Then it should return any error as component state', async () => {
+      server.use(
+        graphql.query(HealthQuery, () => {
+          return HttpResponse.json({
+            errors: [
+              { message: 'Test error', extensions: { code: 'TEST_ERROR' } },
+            ],
+          });
+        }),
+      );
+
+      const { result } = renderHookWithinContext(() =>
+        useSuspendableQuery({
+          document: HealthQuery,
+          variables: {},
+          suspense: false,
+        }),
+      );
+
+      await vi.waitUntil(() => !result.current.loading);
+
+      expect(result.current.loading).toBe(false);
+      expect(result.current.data).toBeUndefined();
+      expect(result.current.error).toBeDefined();
+    });
+  });
+
+  describe('When rendering with suspense enabled', () => {
+    it('Then it should suspend and render once the query is resolved', async () => {
+      const { result } = renderHookWithinContext(() =>
+        useSuspendableQuery({
+          document: HealthQuery,
+          variables: {},
+          suspense: true,
+        }),
+      );
+
+      await vi.waitUntil(() => result.current);
+
+      expect(result.current.data).toBe(true);
+    });
+
+    it('Then it should throw any error so that can be captured via an Error Boundary', async () => {
+      server.use(
+        graphql.query(HealthQuery, () => {
+          return HttpResponse.json({
+            errors: [
+              { message: 'Test error', extensions: { code: 'TEST_ERROR' } },
+            ],
+          });
+        }),
+      );
+
+      const onError = vi.fn();
+      renderHookWithinContext(
+        () =>
+          useSuspendableQuery({
+            document: HealthQuery,
+            variables: {},
+            suspense: true,
+          }),
+        // biome-ignore lint/suspicious/noExplicitAny: not worth the effort
+        { onCaughtError: onError as any },
+      );
+
+      // Wait for the error boundary to catch the error
+      await vi.waitFor(() => expect(onError).toHaveBeenCalled());
+
+      expect(onError).toHaveBeenCalledWith(
+        expect.any(UnexpectedError),
+        expect.any(Object),
+      );
+    });
+  });
+});

packages/react/src/helpers/reads.ts

@@ -1,8 +1,13 @@
+import { UnexpectedError } from '@aave/client';
 import type { AnyVariables, StandardData } from '@aave/graphql';
 import { invariant } from '@aave/types';
 import { useMemo } from 'react';
 import { type TypedDocumentNode, useQuery } from 'urql';
-import { ReadResult, type SuspendableResult } from './results';
+import {
+  ReadResult,
+  type SuspendableResult,
+  type SuspenseResult,
+} from './results';
 
 /**
  * @internal
@@ -12,15 +17,40 @@ export type Suspendable = { suspense: true };
 /**
  * @internal
  */
-export type UseSuspendableQueryArgs<Value, Variables extends AnyVariables> = {
+export type UseSuspendableQueryArgs<
+  Value,
+  Variables extends AnyVariables,
+  Suspense extends boolean = boolean,
+> = {
   document: TypedDocumentNode<StandardData<Value>, Variables>;
   variables: Variables;
-  suspense: boolean;
+  suspense: Suspense;
 };
 
 /**
  * @internal
  */
+export function useSuspendableQuery<Value, Variables extends AnyVariables>({
+  document,
+  variables,
+  suspense,
+}: UseSuspendableQueryArgs<Value, Variables, false>): ReadResult<Value>;
+/**
+ * @internal
+ */
+export function useSuspendableQuery<Value, Variables extends AnyVariables>({
+  document,
+  variables,
+  suspense,
+}: UseSuspendableQueryArgs<Value, Variables, true>): SuspenseResult<Value>;
+/**
+ * @internal
+ */
+export function useSuspendableQuery<Value, Variables extends AnyVariables>({
+  document,
+  variables,
+  suspense,
+}: UseSuspendableQueryArgs<Value, Variables>): SuspendableResult<Value>;
 export function useSuspendableQuery<Value, Variables extends AnyVariables>({
   document,
   variables,
@@ -37,8 +67,12 @@ export function useSuspendableQuery<Value, Variables extends AnyVariables>({
   }
 
   if (error) {
-    // biome-ignore lint/suspicious/noExplicitAny: temporary workaround
-    return ReadResult.Failure(error) as any;
+    const unexpected = UnexpectedError.from(error);
+    if (suspense) {
+      throw unexpected;
+    }
+
+    return ReadResult.Failure(unexpected);
   }
 
   invariant(data, 'No data returned');

packages/react/src/helpers/results.ts

@@ -1,3 +1,5 @@
+import type { UnexpectedError } from '@aave/client';
+
 /**
  * A read hook result.
  *
@@ -48,4 +50,6 @@ export const ReadResult = {
  */
 export type SuspenseResult<T> = { data: T };
 
-export type SuspendableResult<T> = ReadResult<T> | SuspenseResult<T>;
+export type SuspendableResult<T, E extends UnexpectedError = UnexpectedError> =
+  | ReadResult<T, E>
+  | SuspenseResult<T>;

packages/react/src/markets.ts

@@ -32,7 +32,7 @@ export function useAaveMarket(
  * Fetch a single Aave Market.
  *
  * ```tsx
- * const { data, loading } = useAaveMarket({
+ * const { data, error, loading } = useAaveMarket({
  *   address: evmAddress('0x8787…'),
  *   chainId: chainId(1),
  * });
@@ -84,7 +84,7 @@ export function useAaveMarkets(
  * Fetch all Aave Markets for the specified chains.
  *
  * ```tsx
- * const { data, loading } = useAaveMarkets({
+ * const { data, error, loading } = useAaveMarkets({
  *   chainIds: [chainId(1), chainId(8453)],
  *   user: evmAddress('0x742d35cc...'),
  * });

packages/react/src/misc.ts

@@ -45,7 +45,7 @@ export function useAaveChains(
  * Fetch all supported Aave chains.
  *
  * ```tsx
- * const { data, loading } = useAaveChains({
+ * const { data, error, loading } = useAaveChains({
  *   filter: ChainsFilter.MAINNET_ONLY,
  * });
  * ```
@@ -84,7 +84,7 @@ export function useAaveHealth(args: Suspendable): SuspenseResult<boolean>;
  * Health check query.
  *
  * ```tsx
- * const { data, loading } = useAaveHealth();
+ * const { data, error, loading } = useAaveHealth();
  * ```
  */
 export function useAaveHealth(): ReadResult<boolean>;
@@ -125,7 +125,7 @@ export function useUsdExchangeRates(
  * Fetch USD exchange rates for different tokens on a given market.
  *
  * ```tsx
- * const { data, loading } = useUsdExchangeRates({
+ * const { data, error, loading } = useUsdExchangeRates({
  *   market: evmAddress('0x1234…'),
  *   underlyingTokens: [evmAddress('0x5678…'), evmAddress('0x90ab…')],
  *   chainId: chainId(1),