@sanity/sdk 2.5.0 → 2.7.0

package/src/projection/subscribeToStateAndFetchBatches.ts

@@ -16,27 +16,34 @@ import {
   tap,
 } from 'rxjs'
 
+import {isDatasetSource} from '../config/sanityConfig'
 import {getQueryState, resolveQuery} from '../query/queryStore'
-import {type BoundDatasetKey} from '../store/createActionBinder'
+import {type BoundPerspectiveKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
 import {
   createProjectionQuery,
   processProjectionQuery,
   type ProjectionQueryResult,
 } from './projectionQuery'
+import {buildStatusQueryIds, processStatusQueryResults} from './statusQuery'
 import {type ProjectionStoreState} from './types'
-import {PROJECTION_PERSPECTIVE, PROJECTION_TAG} from './util'
+import {PROJECTION_TAG} from './util'
 
 const BATCH_DEBOUNCE_TIME = 50
 
 const isSetEqual = <T>(a: Set<T>, b: Set<T>) =>
   a.size === b.size && Array.from(a).every((i) => b.has(i))
 
+interface StatusQueryResult {
+  _id: string
+  _updatedAt: string
+}
+
 export const subscribeToStateAndFetchBatches = ({
   state,
   instance,
-  key: {projectId, dataset},
-}: StoreContext<ProjectionStoreState, BoundDatasetKey>): Subscription => {
+  key: {source, perspective},
+}: StoreContext<ProjectionStoreState, BoundPerspectiveKey>): Subscription => {
   const documentProjections$ = state.observable.pipe(
     map((s) => s.documentProjections),
     distinctUntilChanged(isEqual),
@@ -92,34 +99,43 @@ export const subscribeToStateAndFetchBatches = ({
         const {query, params} = createProjectionQuery(ids, documentProjections)
         const controller = new AbortController()
 
-        return new Observable<ProjectionQueryResult[]>((observer) => {
+        // Build status query IDs and query
+        const statusQueryIds = buildStatusQueryIds(ids, perspective)
+        const statusQuery = `*[_id in $statusIds]{_id, _updatedAt}`
+        const statusParams = {statusIds: statusQueryIds}
+
+        const projectionQuery$ = new Observable<ProjectionQueryResult[]>((observer) => {
           const {getCurrent, observable} = getQueryState<ProjectionQueryResult[]>(instance, {
-            query,
-            params,
-            projectId,
-            dataset,
-            tag: PROJECTION_TAG,
-            perspective: PROJECTION_PERSPECTIVE,
+            ...{
+              query,
+              params,
+              tag: PROJECTION_TAG,
+              perspective,
+            },
+            // temporary guard here until we're ready for everything to be queried via global API
+            ...(source && !isDatasetSource(source) ? {source} : {}),
           })
 
-          const source$ = defer(() => {
+          const querySource$ = defer(() => {
             if (getCurrent() === undefined) {
               return from(
                 resolveQuery<ProjectionQueryResult[]>(instance, {
-                  query,
-                  params,
-                  projectId,
-                  dataset,
-                  tag: PROJECTION_TAG,
-                  perspective: PROJECTION_PERSPECTIVE,
-                  signal: controller.signal,
+                  ...{
+                    query,
+                    params,
+                    tag: PROJECTION_TAG,
+                    signal: controller.signal,
+                    perspective,
+                  },
+                  // temporary guard here until we're ready for everything to be queried via global API in v3
+                  ...(source && !isDatasetSource(source) ? {source} : {}),
                 }),
               ).pipe(switchMap(() => observable))
             }
             return observable
           }).pipe(filter((result): result is ProjectionQueryResult[] => result !== undefined))
 
-          const subscription = source$.subscribe(observer)
+          const subscription = querySource$.subscribe(observer)
 
           return () => {
             if (!controller.signal.aborted) {
@@ -127,16 +143,79 @@ export const subscribeToStateAndFetchBatches = ({
             }
             subscription.unsubscribe()
           }
-        }).pipe(map((data) => ({data, ids})))
+        })
+
+        const statusQuery$ = new Observable<StatusQueryResult[]>((observer) => {
+          const {getCurrent, observable} = getQueryState<StatusQueryResult[]>(instance, {
+            ...{
+              query: statusQuery,
+              params: statusParams,
+              tag: PROJECTION_TAG,
+              perspective: 'raw',
+            },
+            // temporary guard here until we're ready for everything to be queried via global API
+            ...(source && !isDatasetSource(source) ? {source} : {}),
+          })
+
+          const statusQuerySource$ = defer(() => {
+            if (getCurrent() === undefined) {
+              return from(
+                resolveQuery<StatusQueryResult[]>(instance, {
+                  ...{
+                    query: statusQuery,
+                    params: statusParams,
+                    tag: PROJECTION_TAG,
+                    signal: controller.signal,
+                    perspective: 'raw',
+                  },
+                  // temporary guard here until we're ready for everything to be queried via global API
+                  ...(source && !isDatasetSource(source) ? {source} : {}),
+                }),
+              ).pipe(switchMap(() => observable))
+            }
+            return observable
+          }).pipe(filter((result): result is StatusQueryResult[] => result !== undefined))
+
+          const subscription = statusQuerySource$.subscribe(observer)
+
+          return () => {
+            subscription.unsubscribe()
+          }
+        })
+
+        // Combine both streams: emit whenever either has a new value (after both have
+        // emitted at least one defined value). This keeps reacting to query store updates.
+        return combineLatest([projectionQuery$, statusQuery$]).pipe(
+          filter(
+            (pair): pair is [ProjectionQueryResult[], StatusQueryResult[]] =>
+              pair[0] !== undefined && pair[1] !== undefined,
+          ),
+          map(([projection, status]) => ({
+            data: projection,
+            ids,
+            statusResults: status,
+          })),
+        )
       }),
-      map(({ids, data}) =>
-        processProjectionQuery({
-          projectId,
-          dataset,
+      map(({ids, data, statusResults}) => {
+        // Process status results into documentStatuses (same shape as _status returned to users)
+        const documentStatuses = processStatusQueryResults(statusResults)
+        state.set('updateStatuses', (prev) => ({
+          documentStatuses: {
+            ...prev.documentStatuses,
+            ...documentStatuses,
+          },
+        }))
+
+        // Assemble projection values with _status (buildStatusForDocument in statusQuery)
+        const currentState = state.get()
+        return processProjectionQuery({
           ids,
           results: data,
-        }),
-      ),
+          documentStatuses: currentState.documentStatuses,
+          perspective: perspective,
+        })
+      }),
     )
     .subscribe({
       next: (processedValues) => {

package/src/projection/types.ts

@@ -29,6 +29,11 @@ interface DocumentProjectionSubscriptions {
   }
 }
 
+interface DocumentStatus {
+  lastEditedDraftAt?: string
+  lastEditedPublishedAt?: string
+  lastEditedVersionAt?: string
+}
 export interface ProjectionStoreState<TValue extends object = object> {
   /**
    * A map of document IDs to their projection values, organized by projection hash
@@ -50,4 +55,11 @@ export interface ProjectionStoreState<TValue extends object = object> {
   subscriptions: {
     [documentId: string]: DocumentProjectionSubscriptions
   }
+
+  /**
+   * A map of document IDs to their status information (same shape as _status returned to users)
+   */
+  documentStatuses: {
+    [documentId: string]: DocumentStatus
+  }
 }

package/src/projection/util.ts

@@ -1,5 +1,4 @@
 export const PROJECTION_TAG = 'projection'
-export const PROJECTION_PERSPECTIVE = 'raw'
 export const PROJECTION_STATE_CLEAR_DELAY = 1000
 
 export const STABLE_EMPTY_PROJECTION = {

package/src/query/queryStore.test.ts

@@ -3,6 +3,7 @@ import {delay, filter, firstValueFrom, Observable, of, Subject} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getClientState} from '../client/clientStore'
+import {isCanvasSource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getQueryState, resolveQuery} from './queryStore'
@@ -16,6 +17,23 @@ vi.mock('../client/clientStore', () => ({
   getClientState: vi.fn(),
 }))
 
+// Avoid initializing releases store/perspectives in these tests to prevent
+// side-effect queries (e.g. releases::all()) that would duplicate fetch calls
+vi.mock('../releases/getPerspectiveState', async () => {
+  const actual = await vi.importActual('../releases/getPerspectiveState')
+  return {
+    ...actual,
+    getPerspectiveState: vi.fn(
+      (_instance, options?: {perspective?: unknown}) =>
+        ({
+          subscribe: () => () => {},
+          getCurrent: () => (options?.perspective ?? 'drafts') as unknown,
+          observable: of((options?.perspective ?? 'drafts') as unknown),
+        }) as unknown as StateSource<unknown>,
+    ),
+  }
+})
+
 describe('queryStore', () => {
   let instance: SanityInstance
   let liveEvents: Subject<LiveEvent>
@@ -56,6 +74,7 @@ describe('queryStore', () => {
   })
 
   afterEach(() => {
+    vi.mocked(getClientState).mockClear()
     instance.dispose()
   })
 
@@ -428,4 +447,49 @@ describe('queryStore', () => {
 
     base.dispose()
   })
+
+  it('uses source from params when passed in query options (listenForNewSubscribersAndFetch)', async () => {
+    const query = '*[_type == "movie"]'
+    const mediaLibrarySource = {mediaLibraryId: 'ml123'}
+
+    const state = getQueryState(instance, {query, source: mediaLibrarySource})
+    const unsubscribe = state.subscribe()
+
+    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+
+    // Verify getClientState was called with the source from params in listenForNewSubscribersAndFetch
+    // This call includes projectId, dataset, and source
+    expect(getClientState).toHaveBeenCalledWith(
+      instance,
+      expect.objectContaining({
+        source: expect.objectContaining({
+          mediaLibraryId: 'ml123',
+        }),
+      }),
+    )
+
+    unsubscribe()
+  })
+
+  it('uses source from store context key when not a dataset source (listenToLiveClientAndSetLastLiveEventIds)', async () => {
+    const query = '*[_type == "movie"]'
+    const canvasSource = {canvasId: 'canvas456'}
+
+    const state = getQueryState(instance, {query, source: canvasSource})
+    const unsubscribe = state.subscribe()
+
+    await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
+
+    // Verify getClientState was called with the canvas source for live events
+    // The source is extracted from the store key and passed when it's not a dataset source
+    // This call only has apiVersion and source (no projectId/dataset)
+    const calls = vi.mocked(getClientState).mock.calls
+    const liveClientCall = calls.find(
+      ([_instance, options]) =>
+        isCanvasSource(options.source!) && options.source.canvasId === 'canvas456',
+    )
+    expect(liveClientCall).toBeDefined()
+
+    unsubscribe()
+  })
 })

package/src/query/queryStore.ts

@@ -14,6 +14,7 @@ import {
   mergeMap,
   NEVER,
   Observable,
+  of,
   pairwise,
   race,
   share,
@@ -23,9 +24,18 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type DatasetHandle, type DocumentSource} from '../config/sanityConfig'
+import {type DatasetHandle, isDatasetSource} 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 {bindActionBySource} from '../store/createActionBinder'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
+import {bindActionBySource, type BoundSourceKey} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {
   createStateSourceAction,
@@ -58,11 +68,12 @@ export interface QueryOptions<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
+>
+  extends
+    Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
-  source?: DocumentSource
 }
 
 /**
@@ -105,7 +116,7 @@ function normalizeOptionsWithPerspective(
   }
 }
 
-const queryStore = defineStore<QueryStoreState>({
+const queryStore = defineStore<QueryStoreState, BoundSourceKey>({
   name: 'QueryStore',
   getInitialState: () => ({queries: {}}),
   initialize(context) {
@@ -166,9 +177,13 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               ...restOptions
             } = parseQueryKey(group$.key)
 
-            const perspective$ = getPerspectiveState(instance, {
-              perspective: perspectiveFromOptions,
-            }).observable.pipe(filter(Boolean))
+            // Short-circuit perspective resolution for non-release perspectives to avoid
+            // touching the releases store (and its initialization) unnecessarily.
+            const perspective$ = isReleasePerspective(perspectiveFromOptions)
+              ? getPerspectiveState(instance, {
+                  perspective: perspectiveFromOptions,
+                }).observable.pipe(filter(Boolean))
+              : of(perspectiveFromOptions ?? QUERY_STORE_DEFAULT_PERSPECTIVE)
 
             const client$ = getClientState(instance, {
               apiVersion: QUERY_STORE_API_VERSION,
@@ -177,8 +192,12 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               source,
             }).observable
 
-            return combineLatest([lastLiveEventId$, client$, perspective$]).pipe(
-              switchMap(([lastLiveEventId, client, perspective]) =>
+            return combineLatest({
+              lastLiveEventId: lastLiveEventId$,
+              client: client$,
+              perspective: perspective$,
+            }).pipe(
+              switchMap(({lastLiveEventId, client, perspective}) =>
                 client.observable.fetch(query, params, {
                   ...restOptions,
                   perspective,
@@ -206,9 +225,12 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
 const listenToLiveClientAndSetLastLiveEventIds = ({
   state,
   instance,
-}: StoreContext<QueryStoreState>) => {
+  key: {source},
+}: StoreContext<QueryStoreState, BoundSourceKey>) => {
   const liveMessages$ = getClientState(instance, {
     apiVersion: QUERY_STORE_API_VERSION,
+    // temporary guard here until we're ready for everything to be queried via global api
+    ...(source && !isDatasetSource(source) ? {source} : {}),
   }).observable.pipe(
     switchMap((client) =>
       defer(() =>

package/src/releases/getPerspectiveState.test.ts

@@ -2,14 +2,13 @@ import {filter, firstValueFrom, of, Subject, take} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
 import {type PerspectiveHandle, type ReleasePerspective} from '../config/sanityConfig'
+import {getQueryState} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
-import {listenQuery as mockListenQuery} from '../utils/listenQuery'
+import {type StateSource} from '../store/createStateSourceAction'
 import {getPerspectiveState} from './getPerspectiveState'
 import {type ReleaseDocument} from './releasesStore'
 
-vi.mock('../utils/listenQuery', () => ({
-  listenQuery: vi.fn(),
-}))
+vi.mock('../query/queryStore')
 
 vi.mock('../client/clientStore', () => ({
   getClientState: vi.fn(() => ({
@@ -21,7 +20,7 @@ vi.mock('../client/clientStore', () => ({
 
 describe('getPerspectiveState', () => {
   let instance: SanityInstance
-  let mockReleasesQuerySubject: Subject<ReleaseDocument[]>
+  let mockReleasesQuerySubject: Subject<ReleaseDocument[] | undefined>
 
   const release1 = {
     _id: 'release-1',
@@ -44,8 +43,12 @@ describe('getPerspectiveState', () => {
   beforeEach(() => {
     instance = createSanityInstance({projectId: 'test', dataset: 'test'})
 
-    mockReleasesQuerySubject = new Subject<ReleaseDocument[]>()
-    vi.mocked(mockListenQuery).mockReturnValue(mockReleasesQuerySubject.asObservable())
+    mockReleasesQuerySubject = new Subject<ReleaseDocument[] | undefined>()
+    vi.mocked(getQueryState).mockReturnValue({
+      subscribe: () => () => {},
+      getCurrent: () => undefined,
+      observable: mockReleasesQuerySubject.asObservable(),
+    } as StateSource<ReleaseDocument[] | undefined>)
   })
 
   afterEach(() => {
@@ -95,7 +98,7 @@ describe('getPerspectiveState', () => {
         take(1),
       ),
     )
-    expect(perspective).toEqual(['drafts', 'release1'])
+    expect(perspective).toEqual(['release1', 'drafts'])
   })
 
   it('should calculate perspective including multiple releases up to the specified releaseName', async () => {
@@ -108,13 +111,13 @@ describe('getPerspectiveState', () => {
         take(1),
       ),
     )
-    expect(perspective).toEqual(['drafts', 'release1', 'release2'])
+    expect(perspective).toEqual(['release2', 'release1', 'drafts'])
   })
 
   it('should filter excluded perspectives', async () => {
     const perspectiveConfig: ReleasePerspective = {
       releaseName: 'release2',
-      excludedPerspectives: ['drafts', 'release1'],
+      excludedPerspectives: ['release1', 'drafts'],
     }
     const options: PerspectiveHandle = {perspective: perspectiveConfig}
     const state = getPerspectiveState(instance, options)
@@ -159,7 +162,7 @@ describe('getPerspectiveState', () => {
     const state2 = getPerspectiveState(instance, options2)
     const perspective2 = state2.getCurrent()
 
-    expect(perspective2).toEqual(['drafts', 'release1'])
+    expect(perspective2).toEqual(['release1', 'drafts'])
   })
 
   it('should handle changes in activeReleases (cache test)', async () => {
@@ -173,7 +176,7 @@ describe('getPerspectiveState', () => {
         take(1),
       ),
     )
-    expect(perspective1).toEqual(['drafts', 'release1'])
+    expect(perspective1).toEqual(['release1', 'drafts'])
 
     const updatedActiveReleases = [release1]
     mockReleasesQuerySubject.next(updatedActiveReleases)
@@ -184,10 +187,10 @@ describe('getPerspectiveState', () => {
         take(1),
       ),
     )
-    expect(perspectiveAfterUpdate).toEqual(['drafts', 'release1'])
+    expect(perspectiveAfterUpdate).toEqual(['release1', 'drafts'])
 
     const state2 = getPerspectiveState(instance, options)
     const perspectiveNewCall = state2.getCurrent()
-    expect(perspectiveNewCall).toEqual(['drafts', 'release1'])
+    expect(perspectiveNewCall).toEqual(['release1', 'drafts'])
   })
 })

package/src/releases/getPerspectiveState.ts

@@ -1,17 +1,20 @@
 import {createSelector} from 'reselect'
 
-import {type PerspectiveHandle, type ReleasePerspective} from '../config/sanityConfig'
-import {bindActionByDataset} from '../store/createActionBinder'
+import {type PerspectiveHandle} from '../config/sanityConfig'
+import {bindActionByDataset, 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'
 
-function isReleasePerspective(
-  perspective: PerspectiveHandle['perspective'],
-): perspective is ReleasePerspective {
-  return typeof perspective === 'object' && perspective !== null && 'releaseName' in perspective
-}
-
 const DEFAULT_PERSPECTIVE = 'drafts'
 
 // Cache for options
@@ -50,6 +53,44 @@ const memoizedOptionsSelector = createSelector(
   },
 )
 
+// Lazily bind the action itself to avoid circular import initialization issues with `releasesStore`
+const _getPerspectiveStateSelector = createStateSourceAction({
+  selector: createSelector(
+    [selectInstancePerspective, selectActiveReleases, memoizedOptionsSelector],
+    (instancePerspective, activeReleases, memoizedOptions) => {
+      const perspective = memoizedOptions?.perspective ?? instancePerspective ?? DEFAULT_PERSPECTIVE
+
+      if (!isReleasePerspective(perspective)) return perspective
+
+      // if there are no active releases we can't compute the release perspective
+      if (!activeReleases || activeReleases.length === 0) return undefined
+
+      const releaseNames = sortReleases(activeReleases).map((release) => release.name)
+      const index = releaseNames.findIndex((name) => name === perspective.releaseName)
+
+      if (index < 0) {
+        throw new Error(`Release "${perspective.releaseName}" not found in active releases`)
+      }
+
+      const filteredReleases = releaseNames.slice(0, index + 1) // Include the release itself
+
+      return ['drafts', ...filteredReleases]
+        .filter((name) => !perspective.excludedPerspectives?.includes(name))
+        .reverse()
+    },
+  ),
+})
+
+type OmitFirst<T extends unknown[]> = T extends [unknown, ...infer R] ? R : never
+type SelectorParams = OmitFirst<Parameters<typeof _getPerspectiveStateSelector>>
+type BoundGetPerspectiveState = BoundStoreAction<
+  ReleasesStoreState,
+  SelectorParams,
+  ReturnType<typeof _getPerspectiveStateSelector>
+>
+
+let _boundGetPerspectiveState: BoundGetPerspectiveState | undefined
+
 /**
  * Provides a subscribable state source for a "perspective" for the Sanity client,
  * which is used to fetch documents as though certain Content Releases are active.
@@ -62,33 +103,12 @@ const memoizedOptionsSelector = createSelector(
  *
  * @public
  */
-export const getPerspectiveState = bindActionByDataset(
-  releasesStore,
-  createStateSourceAction({
-    selector: createSelector(
-      [selectInstancePerspective, selectActiveReleases, memoizedOptionsSelector],
-      (instancePerspective, activeReleases, memoizedOptions) => {
-        const perspective =
-          memoizedOptions?.perspective ?? instancePerspective ?? DEFAULT_PERSPECTIVE
-
-        if (!isReleasePerspective(perspective)) return perspective
-
-        // if there are no active releases we can't compute the release perspective
-        if (!activeReleases || activeReleases.length === 0) return undefined
-
-        const releaseNames = sortReleases(activeReleases).map((release) => release.name)
-        const index = releaseNames.findIndex((name) => name === perspective.releaseName)
-
-        if (index < 0) {
-          throw new Error(`Release "${perspective.releaseName}" not found in active releases`)
-        }
-
-        const filteredReleases = releaseNames.slice(0, index + 1) // Include the release itself
-
-        return ['drafts', ...filteredReleases].filter(
-          (name) => !perspective.excludedPerspectives?.includes(name),
-        )
-      },
-    ),
-  }),
-)
+export const getPerspectiveState: BoundGetPerspectiveState = (...args) => {
+  if (!_boundGetPerspectiveState) {
+    _boundGetPerspectiveState = bindActionByDataset(
+      releasesStore,
+      _getPerspectiveStateSelector,
+    ) as BoundGetPerspectiveState
+  }
+  return _boundGetPerspectiveState(...args)
+}