@sanity/sdk 2.15.0 → 2.16.0

package/src/query/queryStore.test.ts

@@ -1,17 +1,21 @@
-import {type LiveEvent, type SanityClient, type SyncTag} from '@sanity/client'
+import {
+  ConnectionFailedError,
+  CorsOriginError,
+  DisconnectError,
+  type LiveEvent,
+  type SanityClient,
+  type SyncTag,
+} from '@sanity/client'
 import {delay, filter, firstValueFrom, Observable, of, Subject} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getClientState} from '../client/clientStore'
+import {LIVE_EVENTS_RETRY_DELAY} from '../client/liveEvents'
 import {isCanvasResource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getQueryState, resolveQuery} from './queryStore'
-
-vi.mock('./queryStoreConstants', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('./queryStoreConstants')>()),
-  QUERY_STATE_CLEAR_DELAY: 10,
-}))
+import {QUERY_STATE_CLEAR_DELAY} from './queryStoreConstants'
 
 vi.mock('../client/clientStore', () => ({
   getClientState: vi.fn(),
@@ -34,6 +38,14 @@ vi.mock('../releases/getPerspectiveState', async () => {
   }
 })
 
+// With fake timers, an emission gated on a pending rxjs delay or cleanup
+// timeout never arrives on its own: create the promise first, advance the
+// clock, then await it.
+async function advanceAndAwait<T>(promise: Promise<T>, ms = 0): Promise<T> {
+  await vi.advanceTimersByTimeAsync(ms)
+  return promise
+}
+
 describe('queryStore', () => {
   let instance: SanityInstance
   let liveEvents: Subject<LiveEvent>
@@ -48,6 +60,7 @@ describe('queryStore', () => {
   }
 
   beforeEach(() => {
+    vi.useFakeTimers()
     instance = createSanityInstance({projectId: 'test', dataset: 'test'})
 
     fetch = vi
@@ -76,6 +89,7 @@ describe('queryStore', () => {
   afterEach(() => {
     vi.mocked(getClientState).mockClear()
     instance.dispose()
+    vi.useRealTimers()
   })
 
   it('initializes query state and cleans up after unsubscribe', async () => {
@@ -89,7 +103,7 @@ describe('queryStore', () => {
     const unsubscribe = state.subscribe()
 
     // Wait for data to be fetched
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Verify data is present
     expect(state.getCurrent()).toEqual([
@@ -101,7 +115,7 @@ describe('queryStore', () => {
     unsubscribe()
 
     // Wait for the cleanup delay
-    await new Promise((resolve) => setTimeout(resolve, 20))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
 
     // Verify state is cleared
     expect(state.getCurrent()).toBeUndefined()
@@ -116,7 +130,7 @@ describe('queryStore', () => {
     const unsubscribe2 = state.subscribe()
 
     // Wait for data to be fetched
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Verify data is present
     expect(state.getCurrent()).toEqual([
@@ -137,7 +151,7 @@ describe('queryStore', () => {
     unsubscribe2()
 
     // Wait for cleanup delay
-    await new Promise((resolve) => setTimeout(resolve, 20))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
 
     // Verify state is cleared after all subscribers are gone
     expect(state.getCurrent()).toBeUndefined()
@@ -151,17 +165,17 @@ describe('queryStore', () => {
     // Check that getQueryState starts undefined
     expect(state.getCurrent()).toBeUndefined()
 
-    // Use resolveQuery which should not add a subscriber
-    const result = await resolveQuery(instance, {query})
+    // resolveQuery holds only a temporary subscriber (released after the
+    // clear delay once the promise settles)
+    const result = await advanceAndAwait(resolveQuery(instance, {query}))
     expect(result).toEqual([
       {_id: 'movie1', _type: 'movie', title: 'Movie 1'},
       {_id: 'movie2', _type: 'movie', title: 'Movie 2'},
     ])
 
-    // Check that getQueryState starts resolved now.
-    // Note that this behavior is important for supporting suspense.
-    // `resolveQuery` is the only way to resolve state without adding a
-    // subscriber that can trigger a clean up
+    // Check that getQueryState is resolved now. This behavior is important
+    // for supporting suspense: the resolved state must remain readable while
+    // React re-renders and attaches a lasting subscriber
     expect(state.getCurrent()).toEqual([
       {_id: 'movie1', _type: 'movie', title: 'Movie 1'},
       {_id: 'movie2', _type: 'movie', title: 'Movie 2'},
@@ -170,7 +184,7 @@ describe('queryStore', () => {
     // Subscribing and unsubscribing should nuke the state now
     const unsubscribe = state.subscribe()
     unsubscribe()
-    await new Promise((resolve) => setTimeout(resolve, 20))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
     expect(state.getCurrent()).toBeUndefined()
   })
 
@@ -189,6 +203,13 @@ describe('queryStore', () => {
 
     // Verify state is cleared after abort
     expect(getQueryState(instance, {query}).getCurrent()).toBeUndefined()
+
+    // The key must be removed immediately (not after the clear delay): a new
+    // resolveQuery re-adds it, which only triggers a fresh fetch if the abort
+    // actually released the previous temporary subscriber
+    const callsBefore = vi.mocked(fetch).mock.calls.length
+    await expect(advanceAndAwait(resolveQuery(instance, {query}))).resolves.toEqual(mockData.movies)
+    expect(vi.mocked(fetch).mock.calls.length).toBe(callsBefore + 1)
   })
 
   it('refetches query when receiving live event with matching sync tag', async () => {
@@ -210,7 +231,7 @@ describe('queryStore', () => {
     const state = getQueryState<{_id: string; _type: string; title: string}[]>(instance, {query})
 
     const unsubscribe = state.subscribe()
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Emit live event with matching sync tag
     liveEvents.next({
@@ -222,7 +243,9 @@ describe('queryStore', () => {
     } as LiveEvent)
 
     // Wait for updated data
-    const result = await firstValueFrom(state.observable.pipe(filter((data) => data?.length === 3)))
+    const result = await advanceAndAwait(
+      firstValueFrom(state.observable.pipe(filter((data) => data?.length === 3))),
+    )
 
     expect(fetch).toHaveBeenCalledTimes(2)
     expect(vi.mocked(fetch).mock.calls[1][2]?.lastLiveEventId).toBe('event1')
@@ -241,7 +264,7 @@ describe('queryStore', () => {
     const state = getQueryState(instance, {query})
 
     const unsubscribe = state.subscribe()
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Emit event with different tag
     liveEvents.next({
@@ -252,7 +275,7 @@ describe('queryStore', () => {
       event: 'created',
     } as LiveEvent)
 
-    await new Promise((resolve) => setTimeout(resolve, 50)) // Allow time for potential refetch
+    await vi.advanceTimersByTimeAsync(50) // Allow time for potential refetch
     expect(fetch).toHaveBeenCalledTimes(1)
 
     unsubscribe()
@@ -274,7 +297,7 @@ describe('queryStore', () => {
     const state = getQueryState(instance, {query})
 
     const unsubscribe = state.subscribe()
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Emit two events with same tag
     liveEvents.next({
@@ -289,7 +312,7 @@ describe('queryStore', () => {
       tags: mockSyncTags,
     })
 
-    await new Promise((resolve) => setTimeout(resolve, 0))
+    await vi.advanceTimersByTimeAsync(0)
     expect(fetch).toHaveBeenCalledTimes(3)
     expect(vi.mocked(fetch).mock.calls[1][2]?.lastLiveEventId).toBe('event1')
     expect(vi.mocked(fetch).mock.calls[2][2]?.lastLiveEventId).toBe('event2')
@@ -317,19 +340,190 @@ describe('queryStore', () => {
     unsubscribe()
   })
 
+  it('refetches when a query key is re-added after an error', async () => {
+    // First fetch fails (e.g. transient network failure)
+    vi.mocked(fetch).mockReturnValueOnce(
+      new Observable((observer) => {
+        observer.error(new Error('transient network failure'))
+      }),
+    )
+
+    const query = '*[_type == "movie"]'
+    const state1 = getQueryState(instance, {query})
+    const unsub1 = state1.subscribe()
+    expect(() => state1.getCurrent()).toThrow('transient network failure')
+    unsub1()
+
+    // Wait for the clear delay so the key is fully removed from state
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
+
+    // Retry with the same key — must trigger a fresh fetch
+    const state2 = getQueryState(instance, {query})
+    const unsub2 = state2.subscribe()
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(vi.mocked(fetch)).toHaveBeenCalledTimes(2)
+
+    const result = await advanceAndAwait(
+      firstValueFrom(state2.observable.pipe(filter((i) => i !== undefined))),
+    )
+    expect(result).toEqual(mockData.movies)
+    unsub2()
+  })
+
+  it('releases an errored key created by resolveQuery so a retry can refetch', async () => {
+    vi.mocked(fetch).mockReturnValueOnce(
+      new Observable((observer) => {
+        observer.error(new Error('network down'))
+      }),
+    )
+
+    const query = '*[_type == "movie"]'
+    // This is how React drives a suspended query: resolveQuery creates the
+    // key without any subscriber (the component never commits when it throws)
+    await expect(resolveQuery(instance, {query})).rejects.toThrow('network down')
+
+    // While the errored key exists, the error surfaces to error boundaries
+    const state = getQueryState(instance, {query})
+    expect(() => state.getCurrent()).toThrow('network down')
+
+    // After the clear delay, the errored key must be released — otherwise it
+    // has no subscribers, nothing ever removes it, and every future mount
+    // rethrows the stored error without ever fetching
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
+    expect(state.getCurrent()).toBeUndefined()
+
+    // A retry now creates a fresh key and fetches
+    await expect(advanceAndAwait(resolveQuery(instance, {query}))).resolves.toEqual(mockData.movies)
+  })
+
+  it('stops live updates without retrying or erroring on a 4xx connection rejection', async () => {
+    const query = '*[_type == "movie"]'
+    const state = getQueryState(instance, {query})
+    const unsub = state.subscribe()
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
+
+    const clientState = vi.mocked(getClientState).mock.results[0]
+      ?.value as StateSource<SanityClient>
+    const client = await firstValueFrom(clientState.observable)
+    const eventsMock = vi.mocked(client.live.events)
+    const callsBefore = eventsMock.mock.calls.length
+
+    // The server rejected the connection with a 401 (e.g. expired token). The
+    // client surfaces this as a fatal ConnectionFailedError with the status —
+    // retrying would reconnect once per second forever against a server that
+    // keeps rejecting
+    liveEvents.error(new ConnectionFailedError('EventSource connection failed', {status: 401}))
+    await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY * 5)
+
+    expect(() => state.getCurrent()).not.toThrow()
+    expect(eventsMock.mock.calls.length).toBe(callsBefore)
+    unsub()
+  })
+
+  it('retries a connection failure without a status (transient network failure)', async () => {
+    const query = '*[_type == "movie"]'
+    const state = getQueryState(instance, {query})
+    const unsub = state.subscribe()
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
+
+    const clientState = vi.mocked(getClientState).mock.results[0]
+      ?.value as StateSource<SanityClient>
+    const client = await firstValueFrom(clientState.observable)
+    const eventsMock = vi.mocked(client.live.events)
+    const callsBefore = eventsMock.mock.calls.length
+
+    // No status means the failure could be transient (native EventSource
+    // exposes no status) — reconnecting is correct here
+    liveEvents.error(new ConnectionFailedError('EventSource connection failed'))
+    await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY * 2)
+
+    expect(() => state.getCurrent()).not.toThrow()
+    expect(eventsMock.mock.calls.length).toBeGreaterThan(callsBefore)
+    unsub()
+  })
+
+  it('surfaces CORS errors on the live connection as a store-wide error', async () => {
+    const query = '*[_type == "movie"]'
+    const state = getQueryState(instance, {query})
+    const unsub = state.subscribe()
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
+
+    liveEvents.error(new CorsOriginError({projectId: 'test'}))
+    await vi.advanceTimersByTimeAsync(0)
+
+    // the swallowed CORS error is recorded as store state so the query
+    // selector rethrows it (handled by the Cors Error component)
+    expect(() => state.getCurrent()).toThrow(CorsOriginError)
+    unsub()
+  })
+
+  it('stops live updates without retrying or erroring on DisconnectError', async () => {
+    const query = '*[_type == "movie"]'
+    const state = getQueryState(instance, {query})
+    const unsub = state.subscribe()
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
+
+    // Grab the live events factory from the client the store is subscribed to
+    const clientState = vi.mocked(getClientState).mock.results[0]
+      ?.value as StateSource<SanityClient>
+    const client = await firstValueFrom(clientState.observable)
+    const eventsMock = vi.mocked(client.live.events)
+    const callsBefore = eventsMock.mock.calls.length
+
+    // The server instructed the client to stop reconnecting
+    liveEvents.error(new DisconnectError('Server disconnected client'))
+    // Advance past several retry delays
+    await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY * 5)
+
+    // No store-wide error, and no reconnect attempts (a retry would call
+    // live.events again)
+    expect(() => state.getCurrent()).not.toThrow()
+    expect(eventsMock.mock.calls.length).toBe(callsBefore)
+    unsub()
+  })
+
+  it('keeps queries working after the live events connection errors', async () => {
+    const query = '*[_type == "movie"]'
+    const state = getQueryState(instance, {query})
+    const unsub = state.subscribe()
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
+
+    // The live connection drops (e.g. network goes offline)
+    liveEvents.error(new Error('live connection lost'))
+    await vi.advanceTimersByTimeAsync(0)
+
+    // Existing query state must remain readable — a lost live connection must
+    // not poison the whole store
+    expect(() => state.getCurrent()).not.toThrow()
+    expect(state.getCurrent()).toEqual(mockData.movies)
+    unsub()
+
+    // Wait for the clear delay so the key is fully removed, then re-add it —
+    // fetching must still work
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
+    const state2 = getQueryState(instance, {query})
+    const unsub2 = state2.subscribe()
+    const result = await advanceAndAwait(
+      firstValueFrom(state2.observable.pipe(filter((i) => i !== undefined))),
+    )
+    expect(result).toEqual(mockData.movies)
+    unsub2()
+  })
+
   it('delays query state removal after unsubscribe', async () => {
     const query = '*[_type == "movie"]'
     const state = getQueryState(instance, {query})
     const unsubscribe = state.subscribe()
 
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     unsubscribe()
     // Immediately after unsubscription, state should still be present due to delay
     expect(state.getCurrent()).not.toBeUndefined()
 
     // Wait for the cleanup delay and then state should be removed
-    await new Promise((resolve) => setTimeout(resolve, 20))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
     expect(state.getCurrent()).toBeUndefined()
   })
 
@@ -338,7 +532,7 @@ describe('queryStore', () => {
     const state = getQueryState(instance, {query})
     const unsubscribe1 = state.subscribe()
 
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
     expect(state.getCurrent()).toEqual([
       {_id: 'movie1', _type: 'movie', title: 'Movie 1'},
       {_id: 'movie2', _type: 'movie', title: 'Movie 2'},
@@ -346,13 +540,13 @@ describe('queryStore', () => {
 
     unsubscribe1()
     // Wait less than the cleanup delay
-    await new Promise((resolve) => setTimeout(resolve, 5))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY / 2)
 
     // Subscribe again before cleanup occurs
     const unsubscribe2 = state.subscribe()
 
     // Wait for cleanup delay to pass
-    await new Promise((resolve) => setTimeout(resolve, 20))
+    await vi.advanceTimersByTimeAsync(QUERY_STATE_CLEAR_DELAY)
 
     // Since a subscriber now exists, state should still be present
     expect(state.getCurrent()).toEqual([
@@ -392,11 +586,11 @@ describe('queryStore', () => {
     const unsubDrafts = sDrafts.subscribe()
     const unsubPublished = sPublished.subscribe()
 
-    const draftsResult = await firstValueFrom(
-      sDrafts.observable.pipe(filter((i) => i !== undefined)),
+    const draftsResult = await advanceAndAwait(
+      firstValueFrom(sDrafts.observable.pipe(filter((i) => i !== undefined))),
     )
-    const publishedResult = await firstValueFrom(
-      sPublished.observable.pipe(filter((i) => i !== undefined)),
+    const publishedResult = await advanceAndAwait(
+      firstValueFrom(sPublished.observable.pipe(filter((i) => i !== undefined))),
     )
 
     expect(draftsResult).toEqual([{_id: 'drafts'}])
@@ -432,11 +626,11 @@ describe('queryStore', () => {
     const unsubDrafts = sDrafts.subscribe()
     const unsubPublished = sPublished.subscribe()
 
-    const draftsResult = await firstValueFrom(
-      sDrafts.observable.pipe(filter((i) => i !== undefined)),
+    const draftsResult = await advanceAndAwait(
+      firstValueFrom(sDrafts.observable.pipe(filter((i) => i !== undefined))),
     )
-    const publishedResult = await firstValueFrom(
-      sPublished.observable.pipe(filter((i) => i !== undefined)),
+    const publishedResult = await advanceAndAwait(
+      firstValueFrom(sPublished.observable.pipe(filter((i) => i !== undefined))),
     )
 
     expect(draftsResult).toEqual([{_id: 'drafts'}])
@@ -455,7 +649,7 @@ describe('queryStore', () => {
     const state = getQueryState(instance, {query, resource: mediaLibrarySource})
     const unsubscribe = state.subscribe()
 
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Verify getClientState was called with the resource from params in listenForNewSubscribersAndFetch
     // This call includes projectId, dataset, and resource
@@ -478,7 +672,7 @@ describe('queryStore', () => {
     const state = getQueryState(instance, {query, resource: canvasSource})
     const unsubscribe = state.subscribe()
 
-    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+    await advanceAndAwait(firstValueFrom(state.observable.pipe(filter((i) => i !== undefined))))
 
     // Verify getClientState was called with the canvas resource for live events
     // The resource is extracted from the store key and passed when it's not a dataset resource

package/src/query/queryStore.ts

@@ -1,9 +1,8 @@
-import {CorsOriginError, type ResponseQueryOptions} from '@sanity/client'
+import {type ResponseQueryOptions} from '@sanity/client'
 import {type SanityQueryResult} from 'groq'
 import {
   catchError,
   combineLatest,
-  defer,
   distinctUntilChanged,
   EMPTY,
   filter,
@@ -24,15 +23,8 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
+import {observeLiveEvents} from '../client/liveEvents'
 import {type DatasetHandle} from '../config/sanityConfig'
-/*
- * Although this is an import dependency cycle, it is not a logical cycle:
- * 1. queryStore uses getPerspectiveState when resolving release perspectives
- * 2. getPerspectiveState uses releasesStore as a data source
- * 3. releasesStore uses queryStore as a data source
- * 4. however, queryStore does not use getPerspectiveState for the perspective used in releasesStore ("raw")
- */
-// eslint-disable-next-line import/no-cycle
 import {getPerspectiveState} from '../releases/getPerspectiveState'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
@@ -53,8 +45,6 @@ import {
 } from './queryStoreConstants'
 import {
   addSubscriber,
-  cancelQuery,
-  initializeQuery,
   type QueryStoreState,
   removeSubscriber,
   setLastLiveEventId,
@@ -183,6 +173,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
             const perspective$ = isReleasePerspective(perspectiveFromOptions)
               ? getPerspectiveState(instance, {
                   perspective: perspectiveFromOptions,
+                  resource,
                 }).observable.pipe(filter(Boolean))
               : of(perspectiveFromOptions ?? QUERY_STORE_DEFAULT_PERSPECTIVE)
 
@@ -208,15 +199,19 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
                   tag,
                 }),
               ),
+              tap(({result, syncTags}) => {
+                state.set('setQueryData', setQueryData(group$.key, result, syncTags))
+              }),
+              // Catch inside the per-event stream: erroring the group pipe would
+              // complete the group's subscription, and since `groupBy` above never
+              // removes its group subjects, re-adding the key would emit into a
+              // subject with no subscribers — the key could never be fetched again.
+              catchError((error) => {
+                state.set('setQueryError', setQueryError(group$.key, error))
+                return EMPTY
+              }),
             )
           }),
-          catchError((error) => {
-            state.set('setQueryError', setQueryError(group$.key, error))
-            return EMPTY
-          }),
-          tap(({result, syncTags}) => {
-            state.set('setQueryData', setQueryData(group$.key, result, syncTags))
-          }),
         ),
       ),
     )
@@ -228,27 +223,14 @@ const listenToLiveClientAndSetLastLiveEventIds = ({
   instance,
   key: {resource},
 }: StoreContext<QueryStoreState, BoundResourceKey>) => {
-  const liveMessages$ = getClientState(instance, {
-    apiVersion: QUERY_STORE_API_VERSION,
+  const liveMessages$ = observeLiveEvents(instance, {
     resource,
-  }).observable.pipe(
-    switchMap((client) =>
-      defer(() =>
-        client.live.events({includeDrafts: !!client.config().token, tag: 'query-store'}),
-      ).pipe(
-        catchError((error) => {
-          if (error instanceof CorsOriginError) {
-            // Swallow only CORS errors in store without bubbling up so that they are handled by the Cors Error component
-            state.set('setError', {error})
-            return EMPTY
-          }
-          throw error
-        }),
-      ),
-    ),
-    share(),
-    filter((e) => e.type === 'message'),
-  )
+    // Surface CORS errors as store state (handled by the Cors Error
+    // component) instead of erroring the stream: a stream error here would
+    // reach the outer subscription's errorHandler, set the store-wide
+    // `state.error`, and permanently brick every query selector.
+    onCorsError: (error) => state.set('setError', {error}),
+  }).pipe(share())
 
   return state.observable
     .pipe(
@@ -346,13 +328,14 @@ const _getQueryState = bindActionByResource(
  * Resolves the result of a query without registering a lasting subscriber.
  *
  * This function fetches the result of a GROQ query and returns a promise that resolves with the query result.
- * Unlike `getQueryState`, which registers subscribers to keep the query live and performs automatic cleanup,
- * `resolveQuery` does not track subscribers. This makes it ideal for use with React Suspense, where the returned
- * promise is thrown to delay rendering until the query result becomes available.
+ * It registers a temporary subscriber for the lifetime of the resolution (released shortly after the promise
+ * settles), so the query state participates in normal cleanup even when no lasting subscriber ever attaches —
+ * e.g. when a suspended component errors before committing. This makes it ideal for use with React Suspense,
+ * where the returned promise is thrown to delay rendering until the query result becomes available.
  * Once the promise resolves, it is expected that a real subscriber will be added via `getQueryState` to manage ongoing updates.
  *
  * Additionally, an optional AbortSignal can be provided to cancel the query and immediately clear the associated state
- * if there are no active subscribers.
+ * if there are no other active subscribers.
  *
  * @beta
  */
@@ -381,6 +364,14 @@ const _resolveQuery = bindActionByResource(
     const {getCurrent} = getQueryState(instance, normalized)
     const key = getQueryKey(normalized)
 
+    // Hold a temporary subscription for the lifetime of this resolution so the
+    // key participates in normal cleanup. Without one, a fetch that errors
+    // while a component is suspended leaves a subscriber-less key behind — the
+    // component never commits, so no other subscriber exists — and its stored
+    // error would be rethrown on every future mount without ever refetching.
+    const subscriptionId = insecureRandomId()
+    state.set('addSubscriber', addSubscriber(key, subscriptionId))
+
     const aborted$ = signal
       ? new Observable<void>((observer) => {
           const cleanup = () => {
@@ -398,20 +389,29 @@ const _resolveQuery = bindActionByResource(
         }).pipe(
           catchError((error) => {
             if (error instanceof Error && error.name === 'AbortError') {
-              state.set('cancelQuery', cancelQuery(key))
+              // Release immediately (not after the clear delay) so that when
+              // this was the only subscriber, the key removal tears down the
+              // in-flight request right away — e.g. when useQuery switches
+              // to a different query
+              state.set('removeSubscriber', removeSubscriber(key, subscriptionId))
             }
             throw error
           }),
         )
       : NEVER
 
-    state.set('initializeQuery', initializeQuery(key))
-
     const resolved$ = state.observable.pipe(
       map(getCurrent),
       first((i) => i !== undefined),
     )
 
-    return firstValueFrom(race([resolved$, aborted$]))
+    const promise = firstValueFrom(race([resolved$, aborted$]))
+    const releaseSubscriber = () => {
+      setCleanupTimeout(() => {
+        state.set('removeSubscriber', removeSubscriber(key, subscriptionId))
+      }, QUERY_STATE_CLEAR_DELAY)
+    }
+    promise.then(releaseSubscriber, releaseSubscriber)
+    return promise
   },
 )