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

package/src/releases/observeReleases.ts

@@ -0,0 +1,102 @@
+import {type ReleaseDocument, type SyncTag} from '@sanity/client'
+import {
+  BehaviorSubject,
+  combineLatest,
+  distinctUntilChanged,
+  filter,
+  map,
+  type Observable,
+  startWith,
+  switchMap,
+  tap,
+} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {observeLiveEvents} from '../client/liveEvents'
+import {type DocumentResource} from '../config/sanityConfig'
+import {type SanityInstance} from '../store/createSanityInstance'
+
+const RELEASES_QUERY = 'releases::all()'
+const RELEASES_API_VERSION = 'v2025-05-06'
+
+/**
+ * Options for {@link observeReleases}.
+ * @internal
+ */
+export interface ObserveReleasesOptions {
+  /** Resource to scope the underlying client and live connection to. */
+  resource?: DocumentResource
+  /**
+   * Called when the live events connection fails due to a CORS
+   * misconfiguration. See `observeLiveEvents`.
+   */
+  onCorsError: (error: unknown) => void
+}
+
+/**
+ * Emits every release document (including archived and published), refetching
+ * whenever a Live Content API event matches the query's sync tags.
+ *
+ * This fetches directly through the client store — deliberately not via the
+ * query store — because release data is itself an input to query perspective
+ * resolution (`getPerspectiveState`); fetching through the query store would
+ * make the two stores mutually dependent.
+ *
+ * @internal
+ */
+export function observeReleases(
+  instance: SanityInstance,
+  {resource, onCorsError}: ObserveReleasesOptions,
+): Observable<ReleaseDocument[] | undefined> {
+  const client$ = getClientState(instance, {
+    apiVersion: RELEASES_API_VERSION,
+    resource,
+  }).observable
+
+  return client$.pipe(
+    switchMap((client) => {
+      const syncTags$ = new BehaviorSubject<SyncTag[] | undefined>(undefined)
+
+      // Pair the latest live message with the latest known sync tags so that
+      // a message arriving while a fetch is still in flight is re-evaluated
+      // (and refetched if it matches) once that fetch's tags land — instead
+      // of being dropped and leaving the store stale until the next event.
+      const refetchEventId$ = combineLatest([
+        observeLiveEvents(instance, {resource, onCorsError}).pipe(startWith(undefined)),
+        syncTags$,
+      ]).pipe(
+        filter(
+          ([message, syncTags]) =>
+            message === undefined || message.tags.some((tag) => syncTags?.includes(tag)),
+        ),
+        map(([message]) => message?.id),
+        distinctUntilChanged(),
+      )
+
+      return refetchEventId$.pipe(
+        switchMap((lastLiveEventId) =>
+          client.observable.fetch<ReleaseDocument[]>(
+            RELEASES_QUERY,
+            {},
+            {
+              perspective: 'raw',
+              filterResponse: false,
+              returnQuery: false,
+              lastLiveEventId,
+              tag: 'releases',
+            },
+          ),
+        ),
+        tap((response) => {
+          syncTags$.next(response.syncTags)
+        }),
+        map((response) => response.result),
+      )
+    }),
+    // Emit synchronously on subscribe (mirroring StateSource semantics, which
+    // the releases store previously consumed) so the store can immediately
+    // record an empty list: consumers distinguish "no releases yet" from
+    // "never loaded", and the React hooks don't suspend on first load.
+    startWith(undefined),
+  )
+}

package/src/releases/releasesStore.test.ts

@@ -1,13 +1,13 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {NEVER, Observable, type Observer, of, Subject} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {getQueryState, resolveQuery} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
-import {type StateSource} from '../store/createStateSourceAction'
-import {getActiveReleasesState, type ReleaseDocument} from './releasesStore'
+import {observeReleases} from './observeReleases'
+import {getActiveReleasesState, getAllReleasesState} from './releasesStore'
 
 // Mock dependencies
-vi.mock('../query/queryStore')
+vi.mock('./observeReleases')
 
 describe('releasesStore', () => {
   let instance: SanityInstance
@@ -15,32 +15,24 @@ describe('releasesStore', () => {
   beforeEach(() => {
     vi.clearAllMocks()
 
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
 
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: NEVER as Observable<ReleaseDocument[] | undefined>,
-    } as StateSource<ReleaseDocument[] | undefined>)
-
-    vi.mocked(resolveQuery).mockResolvedValue(undefined)
+    vi.mocked(observeReleases).mockReturnValue(NEVER as Observable<ReleaseDocument[] | undefined>)
   })
 
   afterEach(() => {
     instance.dispose()
   })
 
-  it('supports calls with explicit resource', () => {
-    const state = getActiveReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
+  it('supports calls without options', () => {
+    const state = getActiveReleasesState(instance)
 
     expect(state.getCurrent()).toBeUndefined()
-    expect(getQueryState).toHaveBeenCalledWith(
+    expect(observeReleases).toHaveBeenCalledWith(
       instance,
       expect.objectContaining({
-        query: 'releases::all()',
-        perspective: 'raw',
-        resource: {projectId: 'test', dataset: 'test'},
-        tag: 'releases',
+        resource: {dataset: 'test', projectId: 'test'},
+        onCorsError: expect.any(Function),
       }),
     )
   })
@@ -51,11 +43,7 @@ describe('releasesStore', () => {
       .fn<(observer: Observer<ReleaseDocument[] | undefined>) => () => void>()
       .mockReturnValue(teardown)
 
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: new Observable(subscriber),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(new Observable(subscriber))
 
     // note that the order of the releases is important here -- they get sorted
     const mockReleases: ReleaseDocument[] = [
@@ -86,11 +74,7 @@ describe('releasesStore', () => {
 
   it('should update active releases state when the query emits new data', async () => {
     const releasesSubject = new Subject<ReleaseDocument[]>()
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: releasesSubject.asObservable(),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(releasesSubject.asObservable())
 
     const state = getActiveReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
 
@@ -132,12 +116,8 @@ describe('releasesStore', () => {
   })
 
   it('should handle empty array from the query', async () => {
-    // Configure query to return an empty array
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => [],
-      observable: of([]),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    // Configure the releases source to return an empty array
+    vi.mocked(observeReleases).mockReturnValue(of([]))
 
     const state = getActiveReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
 
@@ -148,39 +128,106 @@ describe('releasesStore', () => {
 
   it('should handle null/undefined from the query by defaulting to empty array', async () => {
     // Test null case
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => null as unknown as ReleaseDocument[] | undefined,
-      observable: of(null as unknown as ReleaseDocument[] | undefined),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(of(null as unknown as ReleaseDocument[] | undefined))
     const state = getActiveReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
     await new Promise((resolve) => setTimeout(resolve, 0))
     expect(state.getCurrent()).toEqual([])
 
     // Test undefined case
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: of(undefined),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(of(undefined))
     await new Promise((resolve) => setTimeout(resolve, 0))
     expect(state.getCurrent()).toEqual([])
   })
 
-  it('should not crash when the releases query errors', async () => {
+  it('exposes archived/published releases through getAllReleasesState but filters them out of getActiveReleasesState', async () => {
+    const subject = new Subject<ReleaseDocument[]>()
+    vi.mocked(observeReleases).mockReturnValue(subject.asObservable())
+
+    const active = getActiveReleasesState(instance, {
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+    const all = getAllReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
+
+    const releases: ReleaseDocument[] = [
+      {
+        _id: 'r-active',
+        _type: 'system.release',
+        name: 'r-active',
+        state: 'active',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-archived',
+        _type: 'system.release',
+        name: 'r-archived',
+        state: 'archived',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-published',
+        _type: 'system.release',
+        name: 'r-published',
+        state: 'published',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+
+    subject.next(releases)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    const activeNames = active.getCurrent()?.map((r) => r.name) ?? []
+    const allNames = all.getCurrent()?.map((r) => r.name) ?? []
+
+    expect(activeNames).toEqual(['r-active'])
+    expect(allNames).toEqual(expect.arrayContaining(['r-active', 'r-archived', 'r-published']))
+    expect(allNames).toHaveLength(3)
+  })
+
+  it('surfaces CORS errors from the live connection as a store-wide error', async () => {
     const subject = new Subject<ReleaseDocument[]>()
-    vi.mocked(getQueryState).mockReturnValue({
-      subscribe: () => () => {},
-      getCurrent: () => undefined,
-      observable: subject.asObservable(),
-    } as StateSource<ReleaseDocument[] | undefined>)
+    vi.mocked(observeReleases).mockReturnValue(subject.asObservable())
 
     const state = getActiveReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
 
-    subject.error(new Error('Query failed'))
+    subject.next([
+      {
+        _id: 'r1',
+        _type: 'system.release',
+        name: 'r1',
+        state: 'active',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+    ])
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(state.getCurrent()).toHaveLength(1)
+
+    const [, options] = vi.mocked(observeReleases).mock.lastCall!
+    const corsError = new Error('CORS misconfiguration')
+    options.onCorsError(corsError)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    // the CORS error is recorded as store state so the releases selector
+    // rethrows it (handled by the Cors Error component)
+    expect(() => state.getCurrent()).toThrow(corsError)
+  })
+
+  it('should surface the error when the releases query errors', async () => {
+    const subject = new Subject<ReleaseDocument[]>()
+    vi.mocked(observeReleases).mockReturnValue(subject.asObservable())
+
+    const active = getActiveReleasesState(instance, {
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+    const all = getAllReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
+
+    const error = new Error('Query failed')
+    subject.error(error)
 
     await new Promise((resolve) => setTimeout(resolve, 0))
 
-    expect(state.getCurrent()).toEqual(undefined)
+    // The error must be surfaced (thrown) rather than silently swallowed,
+    // otherwise consumers just see an empty list with no signal.
+    expect(() => active.getCurrent()).toThrow(error)
+    expect(() => all.getCurrent()).toThrow(error)
   })
 })

package/src/releases/releasesStore.ts

@@ -1,43 +1,35 @@
-import {type SanityDocument} from '@sanity/types'
+import {type ReleaseDocument} from '@sanity/client'
 import {map} from 'rxjs'
 
 import {type DocumentResource} from '../config/sanityConfig'
-/*
- * Although this is an import dependency cycle, it is not a logical cycle:
- * 1. releasesStore uses queryStore as a data source
- * 2. queryStore calls getPerspectiveState for computing release perspectives
- * 3. getPerspectiveState uses releasesStore 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 {getQueryState} from '../query/queryStore'
 import {bindActionByResource, type BoundResourceKey} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {createStateSourceAction, type StateSource} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
+import {observeReleases} from './observeReleases'
 import {sortReleases} from './utils/sortReleases'
 
 const ARCHIVED_RELEASE_STATES = ['archived', 'published']
 const STABLE_EMPTY_RELEASES: ReleaseDocument[] = []
 
 /**
- * Represents a document in a Sanity dataset that represents release options.
- * @internal
+ * Lifecycle states a release document can be in. Mirrors the server's
+ * `ReleaseState`.
+ * @beta
  */
-export type ReleaseDocument = SanityDocument & {
-  name: string
-  publishAt?: string
-  state: 'active' | 'scheduled'
-  metadata: {
-    title: string
-    releaseType: 'asap' | 'scheduled' | 'undecided'
-    intendedPublishAt?: string
-    description?: string
-  }
-}
+export type ReleaseState =
+  | 'active'
+  | 'archiving'
+  | 'unarchiving'
+  | 'archived'
+  | 'published'
+  | 'publishing'
+  | 'scheduled'
+  | 'scheduling'
 
 export interface ReleasesStoreState {
   activeReleases?: ReleaseDocument[]
+  allReleases?: ReleaseDocument[]
   error?: unknown
 }
 
@@ -45,6 +37,7 @@ export const releasesStore = defineStore<ReleasesStoreState, BoundResourceKey>({
   name: 'Releases',
   getInitialState: (): ReleasesStoreState => ({
     activeReleases: undefined,
+    allReleases: undefined,
   }),
   initialize: (context) => {
     const subscription = subscribeToReleases(context)
@@ -59,7 +52,10 @@ export const releasesStore = defineStore<ReleasesStoreState, BoundResourceKey>({
 const _getActiveReleasesState = bindActionByResource(
   releasesStore,
   createStateSourceAction({
-    selector: ({state}, _?) => state.activeReleases,
+    selector: ({state}) => {
+      if (state.error) throw state.error
+      return state.activeReleases
+    },
   }),
 )
 
@@ -69,33 +65,62 @@ const _getActiveReleasesState = bindActionByResource(
  */
 export const getActiveReleasesState = (
   instance: SanityInstance,
-  options: {resource: DocumentResource},
-): StateSource<ReleaseDocument[] | undefined> => _getActiveReleasesState(instance, options)
+  options?: {resource?: DocumentResource},
+): StateSource<ReleaseDocument[] | undefined> =>
+  // bindActionByResource keyFn destructures { resource } from the first param, so pass {} when no options
+  _getActiveReleasesState(instance, options ?? {})
 
-const RELEASES_QUERY = 'releases::all()'
+/**
+ * Get every release in the store, including archived and published.
+ * @internal
+ */
+const _getAllReleasesState = bindActionByResource(
+  releasesStore,
+  createStateSourceAction({
+    selector: ({state}) => {
+      if (state.error) throw state.error
+      return state.allReleases
+    },
+  }),
+)
+
+/**
+ * Get every release in the store, including archived and published.
+ * @internal
+ */
+export const getAllReleasesState = (
+  instance: SanityInstance,
+  options?: {resource?: DocumentResource},
+): StateSource<ReleaseDocument[] | undefined> => _getAllReleasesState(instance, options ?? {})
 
 const subscribeToReleases = ({
   instance,
   state,
   key: {resource},
 }: StoreContext<ReleasesStoreState, BoundResourceKey>) => {
-  const {observable: releases$} = getQueryState<ReleaseDocument[]>(instance, {
-    query: RELEASES_QUERY,
-    perspective: 'raw',
+  const releases$ = observeReleases(instance, {
     resource,
-    tag: 'releases',
+    // Surface CORS errors as store state instead of erroring the stream so
+    // they can be handled by the Cors Error component
+    onCorsError: (error) => state.set('setError', {error}),
   })
-  return releases$
-    .pipe(
-      map((releases) => {
-        // logic here mirrors that of studio:
-        // https://github.com/sanity-io/sanity/blob/156e8fa482703d99219f08da7bacb384517f1513/packages/sanity/src/core/releases/store/useActiveReleases.ts#L29
-        state.set('setActiveReleases', {
-          activeReleases: sortReleases(releases ?? STABLE_EMPTY_RELEASES)
-            .filter((release) => !ARCHIVED_RELEASE_STATES.includes(release.state))
-            .reverse(),
-        })
-      }),
-    )
-    .subscribe({error: (error) => state.set('setError', {error})})
+  return (
+    releases$
+      .pipe(
+        map((releases) => {
+          // logic here mirrors that of studio:
+          // https://github.com/sanity-io/sanity/blob/156e8fa482703d99219f08da7bacb384517f1513/packages/sanity/src/core/releases/store/useActiveReleases.ts#L29
+          const sorted = sortReleases(releases ?? STABLE_EMPTY_RELEASES).reverse()
+          state.set('setReleases', {
+            allReleases: sorted,
+            activeReleases: sorted.filter(
+              (release) => !ARCHIVED_RELEASE_STATES.includes(release.state),
+            ),
+          })
+        }),
+      )
+      // live-connection errors are already retried inside observeLiveEvents;
+      // a fetch error is terminal and surfaced via setError
+      .subscribe({error: (error) => state.set('setError', {error})})
+  )
 }

package/src/releases/utils/sortReleases.test.ts

@@ -1,6 +1,6 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {describe, expect, it} from 'vitest'
 
-import {type ReleaseDocument} from '../releasesStore'
 import {sortReleases} from './sortReleases'
 
 // Mock function to create a release document
@@ -15,7 +15,7 @@ function createReleaseMock(
   return {
     _id: id,
     _rev: 'rev',
-    _type: 'release',
+    _type: 'system.release',
     _createdAt: new Date().toISOString(),
     _updatedAt: new Date().toISOString(),
     state: 'active',
@@ -333,4 +333,40 @@ describe('sortReleases()', () => {
       expect(sorted[idx]['_id']).toContain(expectedName)
     })
   })
+
+  it('should not throw when a release has no metadata', () => {
+    // Releases created without a title/type can come back from the API with no
+    // `metadata` object at all. Sorting must not throw on these, otherwise the
+    // whole releases subscription errors and the list comes back empty.
+    const releaseWithoutMetadata = {
+      _id: '_.releases.rnometa',
+      _rev: 'rev',
+      _type: 'system.release',
+      _createdAt: '2024-10-24T00:00:00Z',
+      _updatedAt: '2024-10-24T00:00:00Z',
+      state: 'active',
+      name: 'rnometa',
+    } as unknown as ReleaseDocument
+
+    const releases: ReleaseDocument[] = [
+      createReleaseMock({
+        _id: '_.releases.rasap1',
+        _createdAt: '2024-10-25T00:00:00Z',
+        metadata: {releaseType: 'asap'},
+      }),
+      releaseWithoutMetadata,
+      createReleaseMock({
+        _id: '_.releases.rundecided1',
+        _createdAt: '2024-10-26T00:00:00Z',
+        metadata: {releaseType: 'undecided'},
+      }),
+    ]
+
+    let sorted: ReleaseDocument[] = []
+    expect(() => {
+      sorted = sortReleases(releases)
+    }).not.toThrow()
+    expect(sorted).toHaveLength(3)
+    expect(sorted.map((r) => r._id)).toContain('_.releases.rnometa')
+  })
 })

package/src/releases/utils/sortReleases.ts

@@ -1,4 +1,4 @@
-import {type ReleaseDocument} from '../releasesStore'
+import {type ReleaseDocument} from '@sanity/client'
 
 // mirrors the order of the releases in the releases list in Studio
 // https://github.com/sanity-io/sanity/blob/main/packages/sanity/src/core/releases/hooks/utils.ts
@@ -6,25 +6,30 @@ export function sortReleases(releases: ReleaseDocument[] = []): ReleaseDocument[
   // The order should always be:
   // [undecided (sortByCreatedAt), scheduled(sortBy publishAt || metadata.intendedPublishAt), asap(sortByCreatedAt)]
   return [...releases].sort((a, b) => {
+    // metadata is optional on a release document; guard against releases that
+    // have no metadata at all so sorting can't throw and wipe out the list.
+    const aType = a.metadata?.releaseType
+    const bType = b.metadata?.releaseType
+
     // undecided are always first, then by createdAt descending
-    if (a.metadata.releaseType === 'undecided' && b.metadata.releaseType !== 'undecided') {
+    if (aType === 'undecided' && bType !== 'undecided') {
       return -1
     }
-    if (a.metadata.releaseType !== 'undecided' && b.metadata.releaseType === 'undecided') {
+    if (aType !== 'undecided' && bType === 'undecided') {
       return 1
     }
-    if (a.metadata.releaseType === 'undecided' && b.metadata.releaseType === 'undecided') {
+    if (aType === 'undecided' && bType === 'undecided') {
       // Sort by createdAt
       return new Date(b._createdAt).getTime() - new Date(a._createdAt).getTime()
     }
 
     // Scheduled are always at the middle, then by publishAt descending
-    if (a.metadata.releaseType === 'scheduled' && b.metadata.releaseType === 'scheduled') {
-      const aPublishAt = a['publishAt'] || a.metadata['intendedPublishAt']
+    if (aType === 'scheduled' && bType === 'scheduled') {
+      const aPublishAt = a['publishAt'] || a.metadata?.['intendedPublishAt']
       if (!aPublishAt) {
         return 1
       }
-      const bPublishAt = b['publishAt'] || b.metadata['intendedPublishAt']
+      const bPublishAt = b['publishAt'] || b.metadata?.['intendedPublishAt']
       if (!bPublishAt) {
         return -1
       }
@@ -32,13 +37,13 @@ export function sortReleases(releases: ReleaseDocument[] = []): ReleaseDocument[
     }
 
     // ASAP are always last, then by createdAt descending
-    if (a.metadata.releaseType === 'asap' && b.metadata.releaseType !== 'asap') {
+    if (aType === 'asap' && bType !== 'asap') {
       return 1
     }
-    if (a.metadata.releaseType !== 'asap' && b.metadata.releaseType === 'asap') {
+    if (aType !== 'asap' && bType === 'asap') {
       return -1
     }
-    if (a.metadata.releaseType === 'asap' && b.metadata.releaseType === 'asap') {
+    if (aType === 'asap' && bType === 'asap') {
       // Sort by createdAt
       return new Date(b._createdAt).getTime() - new Date(a._createdAt).getTime()
     }