@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.1

package/src/query/queryStore.ts

@@ -1,8 +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,
@@ -23,15 +23,8 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type ResourceHandle} 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 {observeLiveEvents} from '../client/liveEvents'
+import {type DatasetHandle} from '../config/sanityConfig'
 import {getPerspectiveState} from '../releases/getPerspectiveState'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
@@ -44,6 +37,7 @@ import {
 import {type StoreState} from '../store/createStoreState'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
+import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {
   QUERY_STATE_CLEAR_DELAY,
   QUERY_STORE_API_VERSION,
@@ -51,8 +45,6 @@ import {
 } from './queryStoreConstants'
 import {
   addSubscriber,
-  cancelQuery,
-  initializeQuery,
   type QueryStoreState,
   removeSubscriber,
   setLastLiveEventId,
@@ -70,7 +62,7 @@ export interface QueryOptions<
 >
   extends
     Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
-    ResourceHandle<TDataset, TProjectId> {
+    DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
 }
@@ -136,11 +128,7 @@ const errorHandler = (state: StoreState<{error?: unknown}>) => {
   return (error: unknown): void => state.set('setError', {error})
 }
 
-const listenForNewSubscribersAndFetch = ({
-  state,
-  instance,
-  key: {resource: boundResource},
-}: StoreContext<QueryStoreState, BoundResourceKey>) => {
+const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QueryStoreState>) => {
   return state.observable
     .pipe(
       map((s) => new Set(Object.keys(s.queries))),
@@ -172,6 +160,8 @@ const listenForNewSubscribersAndFetch = ({
             const {
               query,
               params,
+              projectId,
+              dataset,
               tag,
               resource,
               perspective: perspectiveFromOptions,
@@ -183,19 +173,15 @@ const listenForNewSubscribersAndFetch = ({
             const perspective$ = isReleasePerspective(perspectiveFromOptions)
               ? getPerspectiveState(instance, {
                   perspective: perspectiveFromOptions,
-                  resource: resource ?? boundResource,
+                  resource,
                 }).observable.pipe(filter(Boolean))
               : of(perspectiveFromOptions ?? QUERY_STORE_DEFAULT_PERSPECTIVE)
 
-            // Use the store's bound resource as fallback when the query key
-            // doesn't include an explicit resource. The store is scoped to a
-            // specific resource via bindActionByResource, but the captured
-            // `instance` may have a different default resource (e.g. when the
-            // store was first created by a caller that passed an explicit
-            // resource while using the root app instance).
             const client$ = getClientState(instance, {
               apiVersion: QUERY_STORE_API_VERSION,
-              resource: resource ?? boundResource,
+              projectId,
+              dataset,
+              resource,
             }).observable
 
             return combineLatest({
@@ -213,15 +199,19 @@ const listenForNewSubscribersAndFetch = ({
                   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))
-          }),
         ),
       ),
     )
@@ -233,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(
@@ -293,6 +270,16 @@ const listenToLiveClientAndSetLastLiveEventIds = ({
  *
  * @beta
  */
+export function getQueryState<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  queryOptions: QueryOptions<TQuery, TDataset, TProjectId>,
+): StateSource<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`> | undefined>
+
+/** @beta */
 export function getQueryState<TData>(
   instance: SanityInstance,
   queryOptions: QueryOptions,
@@ -328,7 +315,7 @@ const _getQueryState = bindActionByResource(
 
       return () => {
         // this runs on unsubscribe
-        setTimeout(
+        setCleanupTimeout(
           () => state.set('removeSubscriber', removeSubscriber(key, subscriptionId)),
           QUERY_STATE_CLEAR_DELAY,
         )
@@ -341,16 +328,27 @@ 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
  */
+export function resolveQuery<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  queryOptions: ResolveQueryOptions<TQuery, TDataset, TProjectId>,
+): Promise<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>>
+
+/** @beta */
 export function resolveQuery<TData>(
   instance: SanityInstance,
   queryOptions: ResolveQueryOptions,
@@ -366,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 = () => {
@@ -383,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
   },
 )

package/src/query/reducers.test.ts

@@ -2,8 +2,6 @@ import {describe, expect, it} from 'vitest'
 
 import {
   addSubscriber,
-  cancelQuery,
-  initializeQuery,
   type QueryStoreState,
   removeSubscriber,
   setLastLiveEventId,
@@ -109,44 +107,4 @@ describe('Query Reducers', () => {
       expect(newState.queries).not.toHaveProperty('q8')
     })
   })
-
-  describe('cancelQuery', () => {
-    it('should return state unchanged if key does not exist', () => {
-      const state: QueryStoreState = {queries: {}}
-      const reducer = cancelQuery('nonexistent')
-      const newState = reducer(state)
-      expect(newState).toBe(state)
-    })
-
-    it('should return state unchanged if query has subscribers', () => {
-      const state: QueryStoreState = {queries: {q9: {subscribers: ['sub1']}}}
-      const reducer = cancelQuery('q9')
-      const newState = reducer(state)
-      expect(newState).toBe(state)
-    })
-
-    it('should remove the query if no subscribers exist', () => {
-      const state: QueryStoreState = {queries: {q10: {subscribers: []}}}
-      const reducer = cancelQuery('q10')
-      const newState = reducer(state)
-      expect(newState.queries).not.toHaveProperty('q10')
-    })
-  })
-
-  describe('initializeQuery', () => {
-    it('should return state unchanged if query already exists', () => {
-      const existing = {subscribers: ['sub1']}
-      const state: QueryStoreState = {queries: {q11: existing}}
-      const reducer = initializeQuery('q11')
-      const newState = reducer(state)
-      expect(newState).toBe(state)
-    })
-
-    it('should add the query with empty subscribers if it does not exist', () => {
-      const state: QueryStoreState = {queries: {}}
-      const reducer = initializeQuery('q12')
-      const newState = reducer(state)
-      expect(newState.queries['q12']).toEqual({subscribers: []})
-    })
-  })
 })

package/src/query/reducers.ts

@@ -1,4 +1,4 @@
-import {omit} from 'lodash-es'
+import {omitProperty} from '../utils/object'
 
 interface QueryState {
   syncTags?: string[]
@@ -54,22 +54,6 @@ export const removeSubscriber =
     const prevQuery = prev.queries[key]
     if (!prevQuery) return prev
     const subscribers = prevQuery.subscribers.filter((id) => id !== subscriptionId)
-    if (!subscribers.length) return {...prev, queries: omit(prev.queries, key)}
+    if (!subscribers.length) return {...prev, queries: omitProperty(prev.queries, key)}
     return {...prev, queries: {...prev.queries, [key]: {...prevQuery, subscribers}}}
   }
-
-export const cancelQuery =
-  (key: string) =>
-  (prev: QueryStoreState): QueryStoreState => {
-    const prevQuery = prev.queries[key]
-    if (!prevQuery) return prev
-    if (prevQuery.subscribers.length) return prev
-    return {...prev, queries: omit(prev.queries, key)}
-  }
-
-export const initializeQuery =
-  (key: string) =>
-  (prev: QueryStoreState): QueryStoreState => {
-    if (prev.queries[key]) return prev
-    return {...prev, queries: {...prev.queries, [key]: {subscribers: []}}}
-  }

package/src/releases/getPerspectiveState.test.ts

@@ -1,14 +1,13 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {filter, firstValueFrom, of, Subject, take} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
-import {type ReleasePerspective, type ResourceHandle} from '../config/sanityConfig'
-import {getQueryState} from '../query/queryStore'
+import {type PerspectiveHandle, type ReleasePerspective} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
-import {type StateSource} from '../store/createStateSourceAction'
 import {getPerspectiveState} from './getPerspectiveState'
-import {type ReleaseDocument} from './releasesStore'
+import {observeReleases} from './observeReleases'
 
-vi.mock('../query/queryStore')
+vi.mock('./observeReleases')
 
 vi.mock('../client/clientStore', () => ({
   getClientState: vi.fn(() => ({
@@ -39,17 +38,12 @@ describe('getPerspectiveState', () => {
 
   // the release store is reversed in getActiveReleases to match UI elsewhere
   const activeReleases = [release2, release1]
-  const resource: ResourceHandle['resource'] = {projectId: 'p', dataset: 'd'}
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
 
     mockReleasesQuerySubject = new Subject<ReleaseDocument[] | undefined>()
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: mockReleasesQuerySubject.asObservable(),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(mockReleasesQuerySubject.asObservable())
   })
 
   afterEach(() => {
@@ -58,7 +52,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should return default perspective if no options or instance perspective is provided', async () => {
-    const state = getPerspectiveState(instance, {resource})
+    const state = getPerspectiveState(instance)
     mockReleasesQuerySubject.next([])
     const perspective = await firstValueFrom(state.observable)
     expect(perspective).toBe('drafts')
@@ -66,14 +60,14 @@ describe('getPerspectiveState', () => {
 
   it('should return instance perspective if provided and no options perspective', async () => {
     instance.config.perspective = 'published'
-    const state = getPerspectiveState(instance, {resource})
+    const state = getPerspectiveState(instance)
     mockReleasesQuerySubject.next([])
     const perspective = await firstValueFrom(state.observable)
     expect(perspective).toBe('published')
   })
 
   it('should return options perspective if provided', async () => {
-    const options = {perspective: 'raw' as const, resource}
+    const options: PerspectiveHandle = {perspective: 'raw'}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next([])
     const perspective = await firstValueFrom(state.observable)
@@ -81,7 +75,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should return undefined if release perspective is requested but no active releases', async () => {
-    const options = {perspective: {releaseName: 'release1'}, resource}
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next([])
     const perspective = await firstValueFrom(state.observable)
@@ -89,7 +83,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should calculate perspective based on active releases and releaseName', async () => {
-    const options = {perspective: {releaseName: 'release1'}, resource}
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next(activeReleases)
 
@@ -103,7 +97,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should calculate perspective including multiple releases up to the specified releaseName', async () => {
-    const options = {perspective: {releaseName: 'release2'}, resource}
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release2'}}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next(activeReleases)
     const perspective = await firstValueFrom(
@@ -120,7 +114,7 @@ describe('getPerspectiveState', () => {
       releaseName: 'release2',
       excludedPerspectives: ['release1', 'drafts'],
     }
-    const options = {perspective: perspectiveConfig, resource}
+    const options: PerspectiveHandle = {perspective: perspectiveConfig}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next(activeReleases)
     const perspective = await firstValueFrom(
@@ -133,7 +127,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should throw if the specified releaseName is not found in active releases', async () => {
-    const options = {perspective: {releaseName: 'nonexistent'}, resource}
+    const options: PerspectiveHandle = {perspective: {releaseName: 'nonexistent'}}
     const state = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next(activeReleases)
 
@@ -148,8 +142,8 @@ describe('getPerspectiveState', () => {
   })
 
   it('should reuse the same options object for identical inputs (cache test)', async () => {
-    const options1 = {perspective: {releaseName: 'release1'}, resource}
-    const options2 = {perspective: {releaseName: 'release1'}, resource}
+    const options1: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+    const options2: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
 
     const state1 = getPerspectiveState(instance, options1)
     mockReleasesQuerySubject.next(activeReleases)
@@ -167,7 +161,7 @@ describe('getPerspectiveState', () => {
   })
 
   it('should handle changes in activeReleases (cache test)', async () => {
-    const options = {perspective: {releaseName: 'release1'}, resource}
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
 
     const state1 = getPerspectiveState(instance, options)
     mockReleasesQuerySubject.next(activeReleases)

package/src/releases/getPerspectiveState.ts

@@ -3,14 +3,6 @@ import {createSelector} from 'reselect'
 import {type DocumentResource, type PerspectiveHandle} from '../config/sanityConfig'
 import {bindActionByResource, type BoundStoreAction} from '../store/createActionBinder'
 import {createStateSourceAction, type SelectorContext} from '../store/createStateSourceAction'
-/*
- * Although this is an import dependency cycle, it is not a logical cycle:
- * 1. getPerspectiveState uses releasesStore as a data source
- * 2. releasesStore uses queryStore as a data source
- * 3. queryStore calls getPerspectiveState for computing release perspectives
- * 4. however, queryStore does not use getPerspectiveState for the perspective used in releasesStore ("raw")
- */
-// eslint-disable-next-line import/no-cycle
 import {releasesStore, type ReleasesStoreState} from './releasesStore'
 import {isReleasePerspective} from './utils/isReleasePerspective'
 import {sortReleases} from './utils/sortReleases'
@@ -26,7 +18,7 @@ const selectActiveReleases = (context: SelectorContext<ReleasesStoreState>) =>
   context.state.activeReleases
 const selectOptions = (
   _context: SelectorContext<ReleasesStoreState>,
-  options: PerspectiveHandle & {resource?: DocumentResource},
+  options: PerspectiveHandle & {projectId?: string; dataset?: string; resource?: DocumentResource},
 ) => options
 
 const memoizedOptionsSelector = createSelector(
@@ -53,7 +45,6 @@ const memoizedOptionsSelector = createSelector(
   },
 )
 
-// Lazily bind the action itself to avoid circular import initialization issues with `releasesStore`
 const _getPerspectiveStateSelector = createStateSourceAction({
   selector: createSelector(
     [selectInstancePerspective, selectActiveReleases, memoizedOptionsSelector],
@@ -89,7 +80,10 @@ type BoundGetPerspectiveState = BoundStoreAction<
   ReturnType<typeof _getPerspectiveStateSelector>
 >
 
-let _boundGetPerspectiveState: BoundGetPerspectiveState | undefined
+const _boundGetPerspectiveState = bindActionByResource(
+  releasesStore,
+  _getPerspectiveStateSelector,
+) as BoundGetPerspectiveState
 
 /**
  * Provides a subscribable state source for a "perspective" for the Sanity client,
@@ -103,12 +97,6 @@ let _boundGetPerspectiveState: BoundGetPerspectiveState | undefined
  *
  * @public
  */
-export const getPerspectiveState: BoundGetPerspectiveState = (instance, ...rest) => {
-  if (!_boundGetPerspectiveState) {
-    _boundGetPerspectiveState = bindActionByResource(
-      releasesStore,
-      _getPerspectiveStateSelector,
-    ) as BoundGetPerspectiveState
-  }
-  return _boundGetPerspectiveState(instance, ...rest)
-}
+export const getPerspectiveState: BoundGetPerspectiveState = (instance, ...rest) =>
+  // bindActionByResource keyFn destructures { resource } from the first param, so pass {} when no options
+  _boundGetPerspectiveState(instance, ...(rest.length ? rest : [{}]))

package/src/releases/observeReleases.test.ts

@@ -0,0 +1,127 @@
+import {type LiveEventMessage, type ReleaseDocument, type SanityClient} from '@sanity/client'
+import {of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {observeLiveEvents} from '../client/liveEvents'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {observeReleases} from './observeReleases'
+
+vi.mock('../client/clientStore', () => ({getClientState: vi.fn()}))
+vi.mock('../client/liveEvents', () => ({observeLiveEvents: vi.fn()}))
+
+describe('observeReleases', () => {
+  let instance: SanityInstance
+  let liveMessages: Subject<LiveEventMessage>
+  let fetch: ReturnType<typeof vi.fn>
+
+  const release = {
+    _id: 'r1',
+    _type: 'system.release',
+    name: 'r1',
+    metadata: {title: 'R1', releaseType: 'asap'},
+  } as ReleaseDocument
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+    liveMessages = new Subject<LiveEventMessage>()
+
+    fetch = vi.fn().mockReturnValue(of({result: [release], syncTags: ['s1:tag']}))
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of({observable: {fetch}} as unknown as SanityClient),
+    } as StateSource<SanityClient>)
+    vi.mocked(observeLiveEvents).mockReturnValue(liveMessages.asObservable())
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('emits undefined synchronously, then fetches releases through the raw perspective', () => {
+    const releases$ = observeReleases(instance, {onCorsError: vi.fn()})
+    const emissions: (ReleaseDocument[] | undefined)[] = []
+    const subscription = releases$.subscribe((releases) => emissions.push(releases))
+
+    // the synchronous undefined lets the releases store immediately record an
+    // empty list, so consumers (e.g. suspending React hooks) never hang on a
+    // fetch that has not resolved yet
+    expect(emissions).toEqual([undefined, [release]])
+    expect(fetch).toHaveBeenCalledWith(
+      'releases::all()',
+      {},
+      expect.objectContaining({
+        perspective: 'raw',
+        tag: 'releases',
+        lastLiveEventId: undefined,
+      }),
+    )
+    subscription.unsubscribe()
+  })
+
+  it('refetches with the live event id when a message matches the sync tags', () => {
+    const releases$ = observeReleases(instance, {onCorsError: vi.fn()})
+    const emissions: (ReleaseDocument[] | undefined)[] = []
+    const subscription = releases$.subscribe((releases) => emissions.push(releases))
+
+    liveMessages.next({type: 'message', id: 'event-1', tags: ['s1:tag']} as LiveEventMessage)
+
+    expect(fetch).toHaveBeenCalledTimes(2)
+    expect(fetch).toHaveBeenLastCalledWith(
+      'releases::all()',
+      {},
+      expect.objectContaining({lastLiveEventId: 'event-1'}),
+    )
+    expect(emissions).toHaveLength(3) // initial undefined + two fetch results
+    subscription.unsubscribe()
+  })
+
+  it('ignores live events that do not match the sync tags', () => {
+    const releases$ = observeReleases(instance, {onCorsError: vi.fn()})
+    const subscription = releases$.subscribe()
+
+    liveMessages.next({type: 'message', id: 'event-1', tags: ['s1:other']} as LiveEventMessage)
+
+    expect(fetch).toHaveBeenCalledTimes(1)
+    subscription.unsubscribe()
+  })
+
+  it('refetches for a matching message that arrived while a fetch was still in flight', () => {
+    const fetchResponses: Subject<{result: ReleaseDocument[]; syncTags: string[]}>[] = []
+    fetch.mockImplementation(() => {
+      const response$ = new Subject<{result: ReleaseDocument[]; syncTags: string[]}>()
+      fetchResponses.push(response$)
+      return response$
+    })
+
+    const releases$ = observeReleases(instance, {onCorsError: vi.fn()})
+    const emissions: (ReleaseDocument[] | undefined)[] = []
+    const subscription = releases$.subscribe((releases) => emissions.push(releases))
+
+    expect(fetch).toHaveBeenCalledTimes(1)
+
+    // A message lands while the initial fetch is in flight — its sync tags are
+    // not known yet, so it can't be evaluated right away…
+    liveMessages.next({type: 'message', id: 'event-1', tags: ['s1:tag']} as LiveEventMessage)
+    expect(fetch).toHaveBeenCalledTimes(1)
+
+    // …but once the fetch completes with matching tags, it must trigger a
+    // refetch instead of being dropped (which would leave the store stale)
+    fetchResponses[0].next({result: [release], syncTags: ['s1:tag']})
+    fetchResponses[0].complete()
+
+    expect(fetch).toHaveBeenCalledTimes(2)
+    expect(fetch).toHaveBeenLastCalledWith(
+      'releases::all()',
+      {},
+      expect.objectContaining({lastLiveEventId: 'event-1'}),
+    )
+
+    fetchResponses[1].next({result: [release], syncTags: ['s1:tag']})
+    fetchResponses[1].complete()
+    expect(emissions).toHaveLength(3) // initial undefined + two fetch results
+
+    subscription.unsubscribe()
+  })
+})