feat(svelte-query): propagate errors to the nearest svelte:boundary when throwOnError is set

Author: sukvvon

.changeset/tame-parrots-shave.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/svelte-query': minor
+---
+
+feat(svelte-query): propagate errors to the nearest `<svelte:boundary>` when `throwOnError` is set

packages/svelte-query/src/createBaseQuery.svelte.ts

@@ -1,3 +1,4 @@
+import { shouldThrowError } from '@tanstack/query-core'
 import { useIsRestoring } from './useIsRestoring.js'
 import { useQueryClient } from './useQueryClient.js'
 import { createRawRef } from './containers.svelte.js'
@@ -71,10 +72,28 @@ export function createBaseQuery<
     createResult(),
   )
 
+  // A trigger separate from `query` itself: the throw-effect below needs to
+  // re-run whenever the result updates, but reading `query.isError`/
+  // `query.isFetching` there would mark them as tracked on the `trackResult`
+  // proxy (by default) the first time an error occurs — permanently widening
+  // `notifyOnChangeProps` for every consumer of this query from then on, even
+  // ones that only ever read `data`. Reading the untracked `getCurrentResult()`
+  // instead avoids this, matching how `useBaseQuery` reads the pre-`trackResult`
+  // result for its own error check.
+  //
+  // This still notifies reliably once `throwOnError` is set, because
+  // `QueryObserver` force-adds `'error'` to the notified props whenever
+  // `options.throwOnError` is set (see `queryObserver.ts`), regardless of what
+  // any consumer has read.
+  let resultVersion = $state(0)
+
   $effect(() => {
     const unsubscribe = isRestoring.current
       ? () => undefined
-      : observer.subscribe(() => update(createResult()))
+      : observer.subscribe(() => {
+          update(createResult())
+          resultVersion++
+        })
     observer.updateResult()
     return unsubscribe
   })
@@ -100,8 +119,32 @@ export function createBaseQuery<
       //
       // this could technically be its own effect but that doesn't seem necessary
       update(createResult())
+      resultVersion++
     },
   )
 
+  $effect(() => {
+    // Depend on `resultVersion`, NOT on `query` itself, so this reaction re-runs
+    // whenever the result updates without marking `isError`/`isFetching`/`error`
+    // as tracked props on `query` (see `resultVersion` above). Reads the actual
+    // values from `observer.getCurrentResult()`, which is untracked.
+    void resultVersion
+    const currentResult = observer.getCurrentResult()
+
+    // Must throw from inside this reaction (not from the `subscribe` callback
+    // above, which runs through notifyManager's batching outside any active
+    // Svelte reaction) — otherwise `<svelte:boundary>` never sees the error.
+    if (
+      currentResult.isError &&
+      !currentResult.isFetching &&
+      shouldThrowError(resolvedOptions.throwOnError, [
+        currentResult.error,
+        observer.getCurrentQuery(),
+      ])
+    ) {
+      throw currentResult.error
+    }
+  })
+
   return query
 }

packages/svelte-query/tests/createInfiniteQuery/ErrorBoundary.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  import { onDestroy, onMount } from 'svelte'
+  import type { QueryClient } from '@tanstack/query-core'
+  import { setQueryClientContext } from '../../src/index.js'
+  import type { Accessor, CreateInfiniteQueryOptions } from '../../src/types.js'
+  import ErrorBoundaryContent from './ErrorBoundaryContent.svelte'
+
+  type Props = {
+    queryClient: QueryClient
+    options: Accessor<CreateInfiniteQueryOptions>
+  }
+
+  let { queryClient, options }: Props = $props()
+
+  setQueryClientContext(queryClient)
+
+  onMount(() => queryClient.mount())
+  onDestroy(() => queryClient.unmount())
+</script>
+
+<svelte:boundary onerror={(_err, _reset) => {}}>
+  <ErrorBoundaryContent {options} />
+  {#snippet failed(error, _reset)}
+    <div data-testid="error-boundary">
+      {error instanceof Error ? error.message : String(error)}
+    </div>
+  {/snippet}
+</svelte:boundary>

packages/svelte-query/tests/createInfiniteQuery/ErrorBoundaryContent.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { createInfiniteQuery } from '../../src/index.js'
+  import type { Accessor, CreateInfiniteQueryOptions } from '../../src/types.js'
+
+  type Props = {
+    options: Accessor<CreateInfiniteQueryOptions>
+  }
+
+  let { options }: Props = $props()
+
+  const query = createInfiniteQuery(options)
+</script>
+
+<div data-testid="status">{query.status}</div>

packages/svelte-query/tests/createInfiniteQuery/createInfiniteQuery.svelte.test.ts

@@ -1,10 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { fireEvent, render } from '@testing-library/svelte'
 import { QueryClient } from '@tanstack/query-core'
+import { queryKey } from '@tanstack/query-test-utils'
 import { ref } from '../utils.svelte.js'
 import Base from './Base.svelte'
 import Select from './Select.svelte'
 import ChangeClient from './ChangeClient.svelte'
+import ErrorBoundary from './ErrorBoundary.svelte'
 import type { QueryObserverResult } from '@tanstack/query-core'
 
 describe('createInfiniteQuery', () => {
@@ -152,4 +154,32 @@ describe('createInfiniteQuery', () => {
       rendered.getByText('Data: {"pages":[7,8],"pageParams":[7,8]}'),
     ).toBeInTheDocument()
   })
+
+  it('should throw error to the nearest svelte:boundary when throwOnError is true', async () => {
+    const key = queryKey()
+    const consoleMock = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined)
+
+    const rendered = render(ErrorBoundary, {
+      props: {
+        queryClient,
+        options: () => ({
+          queryKey: key,
+          queryFn: () => Promise.reject(new Error('Error test')),
+          getNextPageParam: () => undefined,
+          initialPageParam: 0,
+          retry: false,
+          throwOnError: true,
+        }),
+      },
+    })
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(rendered.getByTestId('error-boundary')).toHaveTextContent(
+      'Error test',
+    )
+
+    consoleMock.mockRestore()
+  })
 })

packages/svelte-query/tests/createQuery/ErrorBoundary.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  import { onDestroy, onMount } from 'svelte'
+  import type { QueryClient } from '@tanstack/query-core'
+  import { setQueryClientContext } from '../../src/index.js'
+  import type { Accessor, CreateQueryOptions } from '../../src/index.js'
+  import ErrorBoundaryContent from './ErrorBoundaryContent.svelte'
+
+  type Props = {
+    queryClient: QueryClient
+    options: Accessor<CreateQueryOptions>
+  }
+
+  let { queryClient, options }: Props = $props()
+
+  setQueryClientContext(queryClient)
+
+  onMount(() => queryClient.mount())
+  onDestroy(() => queryClient.unmount())
+</script>
+
+<svelte:boundary onerror={(_err, _reset) => {}}>
+  <ErrorBoundaryContent {options} />
+  {#snippet failed(error, _reset)}
+    <div data-testid="error-boundary">
+      {error instanceof Error ? error.message : String(error)}
+    </div>
+  {/snippet}
+</svelte:boundary>

packages/svelte-query/tests/createQuery/ErrorBoundaryContent.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { createQuery } from '../../src/index.js'
+  import type { Accessor, CreateQueryOptions } from '../../src/index.js'
+
+  type Props = {
+    options: Accessor<CreateQueryOptions>
+  }
+
+  let { options }: Props = $props()
+
+  const query = createQuery(options)
+</script>
+
+<div data-testid="status">{query.status}</div>

packages/svelte-query/tests/createQuery/createQuery.svelte.test.ts

@@ -13,6 +13,7 @@ import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { QueryClient, createQuery, keepPreviousData } from '../../src/index.js'
 import { promiseWithResolvers, withEffectRoot } from '../utils.svelte.js'
 import Base from './Base.svelte'
+import ErrorBoundary from './ErrorBoundary.svelte'
 import Counter from './Counter.svelte'
 import IsRestoring from './IsRestoring.svelte'
 import Select from './Select.svelte'
@@ -1234,6 +1235,41 @@ describe('createQuery', () => {
     }),
   )
 
+  it(
+    'should not widen tracked props for unrelated data-only consumers after an error occurs',
+    withEffectRoot(async () => {
+      const key = queryKey()
+      const dataOnlyRuns: Array<string | undefined> = []
+
+      const query = createQuery<string>(
+        () => ({
+          queryKey: key,
+          queryFn: () => Promise.reject(new Error('fail')),
+          retry: false,
+          // `false` never satisfies `shouldThrowError`, so the query settles
+          // into an error state without throwing — this is the case where
+          // the throw-effect's `!query.isFetching` check (guarded behind
+          // `query.isError`) reads `isFetching` and, unless read from the
+          // untracked result, would mark it tracked from then on.
+          throwOnError: false,
+        }),
+        () => queryClient,
+      )
+
+      // This effect only ever reads `data`. Once the query above has settled
+      // into an error state, `isFetching` transitions on a later refetch must
+      // not cause this unrelated, data-only effect to re-run.
+      $effect(() => {
+        dataOnlyRuns.push(query.data)
+      })
+
+      await vi.advanceTimersByTimeAsync(0)
+      await query.refetch()
+
+      expect(dataOnlyRuns).toHaveLength(1)
+    }),
+  )
+
   it(
     'should always re-render if we are tracking props but not using any',
     withEffectRoot(async () => {
@@ -1580,6 +1616,102 @@ describe('createQuery', () => {
     expect(rendered.getByTestId('error')).toHaveTextContent('Local Error')
   })
 
+  it('should throw error to the nearest svelte:boundary when throwOnError is true', async () => {
+    const key = queryKey()
+    const consoleMock = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined)
+
+    const rendered = render(ErrorBoundary, {
+      props: {
+        queryClient,
+        options: () => ({
+          queryKey: key,
+          queryFn: () => Promise.reject(new Error('Error test')),
+          retry: false,
+          throwOnError: true,
+        }),
+      },
+    })
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(rendered.getByTestId('error-boundary')).toHaveTextContent(
+      'Error test',
+    )
+
+    consoleMock.mockRestore()
+  })
+
+  it('should throw error to the nearest svelte:boundary when throwOnError function returns true', async () => {
+    const key = queryKey()
+    const consoleMock = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined)
+
+    const rendered = render(ErrorBoundary, {
+      props: {
+        queryClient,
+        options: () => ({
+          queryKey: key,
+          queryFn: () => Promise.reject(new Error('Local Error')),
+          retry: false,
+          throwOnError: (err: Error) => err.message === 'Local Error',
+        }),
+      },
+    })
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(rendered.getByTestId('error-boundary')).toHaveTextContent(
+      'Local Error',
+    )
+
+    consoleMock.mockRestore()
+  })
+
+  it('should throw error to the nearest svelte:boundary when queryFn rejects with a falsy error and throwOnError is in use', async () => {
+    const key = queryKey()
+    const consoleMock = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined)
+
+    const rendered = render(ErrorBoundary, {
+      props: {
+        queryClient,
+        options: () => ({
+          queryKey: key,
+          queryFn: () => Promise.reject(),
+          retry: false,
+          throwOnError: true,
+        }),
+      },
+    })
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(rendered.getByTestId('error-boundary')).toBeInTheDocument()
+
+    consoleMock.mockRestore()
+  })
+
+  it(
+    'should update with data if we observe no properties and throwOnError',
+    withEffectRoot(async () => {
+      const key = queryKey()
+
+      const query = createQuery<string>(
+        () => ({
+          queryKey: key,
+          queryFn: () => Promise.resolve('data'),
+          throwOnError: true,
+        }),
+        () => queryClient,
+      )
+
+      await vi.advanceTimersByTimeAsync(0)
+      expect(queryClient.isFetching()).toBe(0)
+      expect(query.data).toBe('data')
+    }),
+  )
+
   it(
     'should support changing provided query client',
     withEffectRoot(() => {