fix(vue-query/useBaseQuery): prevent dual error propagation when 'suspense()' and error watcher both handle the same error

.changeset/wide-camels-jog.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/vue-query': patch
+---
+
+fix(vue-query/useBaseQuery): prevent dual error propagation when 'suspense()' and error watcher both handle the same error
+

packages/vue-query/src/__tests__/useInfiniteQuery.test.ts

@@ -1,9 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getCurrentInstance } from 'vue-demi'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { useInfiniteQuery } from '../useInfiniteQuery'
 import { infiniteQueryOptions } from '../infiniteQueryOptions'
+import type { Mock } from 'vitest'
 
 vi.mock('../useQueryClient')
+vi.mock('../useBaseQuery')
 
 describe('useInfiniteQuery', () => {
   beforeEach(() => {
@@ -78,4 +81,98 @@ describe('useInfiniteQuery', () => {
     })
     expect(status.value).toStrictEqual('success')
   })
+
+  describe('throwOnError', () => {
+    it('should throw from error watcher when throwOnError is true and suspense is not used', async () => {
+      const throwOnErrorFn = vi.fn().mockReturnValue(true)
+      useInfiniteQuery({
+        queryKey: ['infiniteThrowOnErrorWithoutSuspense'],
+        queryFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        initialPageParam: 0,
+        getNextPageParam: () => 12,
+        retry: false,
+        throwOnError: throwOnErrorFn,
+      })
+
+      // The watcher rethrows, which Vue surfaces differently across versions:
+      // through console.error on Vue 2.x and as an unhandled rejection on Vue 3.
+      // Capture both channels so the assertion holds on every supported version.
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const rejectionHandler = vi.fn()
+      process.on('unhandledRejection', rejectionHandler)
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      process.off('unhandledRejection', rejectionHandler)
+
+      const reportedError = [
+        ...errorSpy.mock.calls,
+        ...rejectionHandler.mock.calls,
+      ].some((args) =>
+        args.some(
+          (arg) => arg instanceof Error && arg.message === 'Some error',
+        ),
+      )
+
+      errorSpy.mockRestore()
+
+      // throwOnError is evaluated and throw is attempted (not suppressed by suspense)
+      expect(throwOnErrorFn).toHaveBeenCalledTimes(1)
+      expect(throwOnErrorFn).toHaveBeenCalledWith(
+        Error('Some error'),
+        expect.objectContaining({
+          state: expect.objectContaining({ status: 'error' }),
+        }),
+      )
+      // The watcher rethrows, so Vue surfaces the error (console.error or an
+      // unhandled rejection depending on the version).
+      expect(reportedError).toBe(true)
+    })
+  })
+
+  describe('suspense', () => {
+    it('should not throw from error watcher when suspense is handling the error with throwOnError: true', async () => {
+      const getCurrentInstanceSpy = getCurrentInstance as Mock
+      getCurrentInstanceSpy.mockImplementation(() => ({ suspense: {} }))
+
+      // Spy on unhandled rejections so we can assert the watcher does not rethrow.
+      const rejectionHandler = vi.fn()
+      process.on('unhandledRejection', rejectionHandler)
+
+      const throwOnErrorFn = vi.fn().mockReturnValue(true)
+      const query = useInfiniteQuery({
+        queryKey: ['infiniteSuspenseThrowOnError'],
+        queryFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        initialPageParam: 0,
+        getNextPageParam: () => 12,
+        retry: false,
+        throwOnError: throwOnErrorFn,
+      })
+
+      let rejectedError: unknown
+      const promise = query.suspense().catch((error) => {
+        rejectedError = error
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      await promise
+
+      process.off('unhandledRejection', rejectionHandler)
+
+      expect(rejectedError).toBeInstanceOf(Error)
+      expect((rejectedError as Error).message).toBe('Some error')
+      // throwOnError is evaluated in both suspense() and the error watcher
+      expect(throwOnErrorFn).toHaveBeenCalledTimes(2)
+      // The error watcher must not rethrow when suspense is active, so no
+      // unhandled rejection should be observed.
+      expect(rejectionHandler).not.toHaveBeenCalled()
+      expect(query).toMatchObject({
+        status: { value: 'error' },
+        isError: { value: true },
+      })
+    })
+  })
 })

packages/vue-query/src/__tests__/useQuery.test.ts

@@ -478,6 +478,51 @@ describe('useQuery', () => {
         }),
       )
     })
+
+    it('should throw from error watcher when throwOnError is true and suspense is not used', async () => {
+      const throwOnErrorFn = vi.fn().mockReturnValue(true)
+      useQuery({
+        queryKey: ['throwOnErrorWithoutSuspense'],
+        queryFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        retry: false,
+        throwOnError: throwOnErrorFn,
+      })
+
+      // The watcher rethrows, which Vue surfaces differently across versions:
+      // through console.error on Vue 2.x and as an unhandled rejection on Vue 3.
+      // Capture both channels so the assertion holds on every supported version.
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const rejectionHandler = vi.fn()
+      process.on('unhandledRejection', rejectionHandler)
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      process.off('unhandledRejection', rejectionHandler)
+
+      const reportedError = [
+        ...errorSpy.mock.calls,
+        ...rejectionHandler.mock.calls,
+      ].some((args) =>
+        args.some(
+          (arg) => arg instanceof Error && arg.message === 'Some error',
+        ),
+      )
+
+      errorSpy.mockRestore()
+
+      // throwOnError is evaluated and throw is attempted (not suppressed by suspense)
+      expect(throwOnErrorFn).toHaveBeenCalledTimes(1)
+      expect(throwOnErrorFn).toHaveBeenCalledWith(
+        Error('Some error'),
+        expect.objectContaining({
+          state: expect.objectContaining({ status: 'error' }),
+        }),
+      )
+      // The watcher rethrows, so Vue surfaces the error (console.error or an
+      // unhandled rejection depending on the version).
+      expect(reportedError).toBe(true)
+    })
   })
 
   describe('outside scope warning', () => {
@@ -615,5 +660,46 @@ describe('useQuery', () => {
         }),
       )
     })
+
+    it('should not throw from error watcher when suspense is handling the error with throwOnError: true', async () => {
+      const getCurrentInstanceSpy = getCurrentInstance as Mock
+      getCurrentInstanceSpy.mockImplementation(() => ({ suspense: {} }))
+
+      // Spy on unhandled rejections so we can assert the watcher does not rethrow.
+      const rejectionHandler = vi.fn()
+      process.on('unhandledRejection', rejectionHandler)
+
+      const throwOnErrorFn = vi.fn().mockReturnValue(true)
+      const query = useQuery({
+        queryKey: ['suspense6'],
+        queryFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        retry: false,
+        throwOnError: throwOnErrorFn,
+      })
+
+      let rejectedError: unknown
+      const promise = query.suspense().catch((error) => {
+        rejectedError = error
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      await promise
+
+      process.off('unhandledRejection', rejectionHandler)
+
+      expect(rejectedError).toBeInstanceOf(Error)
+      expect((rejectedError as Error).message).toBe('Some error')
+      // throwOnError is evaluated in both suspense() and the error watcher
+      expect(throwOnErrorFn).toHaveBeenCalledTimes(2)
+      // The error watcher must not rethrow when suspense is active, so no
+      // unhandled rejection should be observed.
+      expect(rejectionHandler).not.toHaveBeenCalled()
+      expect(query).toMatchObject({
+        status: { value: 'error' },
+        isError: { value: true },
+      })
+    })
   })
 })

packages/vue-query/src/useBaseQuery.ts

@@ -149,6 +149,8 @@ export function useBaseQuery<
     return state.refetch(...args)
   }
 
+  let suspenseFetchCount = 0
+
   const suspense = () => {
     return new Promise<QueryObserverResult<TData, TError>>(
       (resolve, reject) => {
@@ -164,9 +166,14 @@ export function useBaseQuery<
             )
             if (optimisticResult.isStale) {
               stopWatch()
-              observer
-                .fetchOptimistic(defaultedOptions.value)
-                .then(resolve, (error: TError) => {
+              suspenseFetchCount += 1
+              observer.fetchOptimistic(defaultedOptions.value).then(
+                (result) => {
+                  suspenseFetchCount -= 1
+                  resolve(result)
+                },
+                (error: TError) => {
+                  suspenseFetchCount -= 1
                   if (
                     shouldThrowError(defaultedOptions.value.throwOnError, [
                       error,
@@ -177,7 +184,8 @@ export function useBaseQuery<
                   } else {
                     resolve(observer.getCurrentResult())
                   }
-                })
+                },
+              )
             } else {
               stopWatch()
               resolve(optimisticResult)
@@ -196,15 +204,15 @@ export function useBaseQuery<
   watch(
     () => state.error,
     (error) => {
-      if (
-        state.isError &&
-        !state.isFetching &&
-        shouldThrowError(defaultedOptions.value.throwOnError, [
-          error as TError,
-          observer.getCurrentQuery(),
-        ])
-      ) {
-        throw error
+      if (state.isError && !state.isFetching) {
+        const shouldThrow = shouldThrowError(
+          defaultedOptions.value.throwOnError,
+          [error as TError, observer.getCurrentQuery()],
+        )
+
+        if (shouldThrow && suspenseFetchCount === 0) {
+          throw error
+        }
       }
     },
   )