@sanity/sdk 2.6.0 → 2.7.0

package/src/projection/subscribeToStateAndFetchBatches.test.ts

@@ -15,13 +15,18 @@ vi.mock('../query/queryStore')
 describe('subscribeToStateAndFetchBatches', () => {
   let instance: SanityInstance
   let state: StoreState<ProjectionStoreState>
-  const key = {name: 'test.test', projectId: 'test', dataset: 'test'}
+  const key = {
+    name: 'test.test:drafts',
+    source: {projectId: 'test', dataset: 'test'},
+    perspective: 'drafts' as const,
+  }
 
   beforeEach(() => {
     vi.clearAllMocks()
     instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     state = createStoreState<ProjectionStoreState>({
       documentProjections: {},
+      documentStatuses: {},
       subscriptions: {},
       values: {},
     })
@@ -65,19 +70,14 @@ describe('subscribeToStateAndFetchBatches', () => {
     // Wait for debounce
     await new Promise((resolve) => setTimeout(resolve, 100))
 
-    // Should still be 1 call because projections are identical
-    expect(getQueryState).toHaveBeenCalledTimes(1)
+    // only 2 calls (one for projection, one for status) even though we added 2 subscriptions
+    expect(getQueryState).toHaveBeenCalledTimes(2)
     expect(getQueryState).toHaveBeenCalledWith(
       instance,
       expect.objectContaining({
-        query: expect.any(String),
+        perspective: 'drafts',
         params: {
-          [`__ids_${projectionHash}`]: expect.arrayContaining([
-            'doc1',
-            'drafts.doc1',
-            'doc2',
-            'drafts.doc2',
-          ]),
+          [`__ids_${projectionHash}`]: expect.arrayContaining(['doc1', 'doc2']),
         },
       }),
     )
@@ -87,47 +87,43 @@ describe('subscribeToStateAndFetchBatches', () => {
 
   it('processes query results and updates state with resolved values', async () => {
     const teardown = vi.fn()
-    const subscriber = vi
-      .fn<(observer: Observer<ProjectionQueryResult[] | undefined>) => () => void>()
-      .mockReturnValue(teardown)
-
-    vi.mocked(getQueryState).mockReturnValue({
-      getCurrent: () => undefined,
-      observable: new Observable(subscriber),
-    } as StateSource<ProjectionQueryResult[] | undefined>)
+    const projectionObservers: Observer<ProjectionQueryResult[] | undefined>[] = []
+    const statusObservers: Observer<{_id: string; _updatedAt: string}[] | undefined>[] = []
+
+    vi.mocked(getQueryState).mockImplementation((_, options) => {
+      const isStatusQuery = options.perspective === 'raw'
+      const observers = isStatusQuery ? statusObservers : projectionObservers
+      const observable = new Observable<unknown>((observer) => {
+        observers.push(observer as Observer<ProjectionQueryResult[] | undefined>)
+        return teardown
+      })
+      return {
+        getCurrent: () => undefined,
+        observable,
+      } as StateSource<ProjectionQueryResult[] | undefined>
+    })
 
     const subscription = subscribeToStateAndFetchBatches({instance, state, key})
     const projection = '{title}'
     const projectionHash = hashString(projection)
 
-    expect(subscriber).not.toHaveBeenCalled()
-
     // Add a subscription
     state.set('addSubscription', {
       documentProjections: {doc1: {[projectionHash]: projection}},
       subscriptions: {doc1: {[projectionHash]: {sub1: true}}},
     })
 
-    expect(subscriber).not.toHaveBeenCalled()
-
-    // Wait for debounce
+    // Wait for debounce (combineLatest subscribes to both projection and status)
     await new Promise((resolve) => setTimeout(resolve, 100))
 
-    expect(subscriber).toHaveBeenCalled()
+    expect(projectionObservers.length).toBe(1)
+    expect(statusObservers.length).toBe(1)
     expect(teardown).not.toHaveBeenCalled()
 
-    const [observer] = subscriber.mock.lastCall!
-
     const timestamp = new Date().toISOString()
 
-    observer.next([
-      {
-        _id: 'doc1',
-        _type: 'doc',
-        _updatedAt: timestamp,
-        result: {title: 'resolved'},
-        __projectionHash: projectionHash,
-      },
+    // Emit projection results first
+    projectionObservers[0]!.next([
       {
         _id: 'drafts.doc1',
         _type: 'doc',
@@ -137,6 +133,12 @@ describe('subscribeToStateAndFetchBatches', () => {
       },
     ])
 
+    // Emit status results (raw query returns _id, _updatedAt per document variant)
+    statusObservers[0]!.next([
+      {_id: 'doc1', _updatedAt: timestamp},
+      {_id: 'drafts.doc1', _updatedAt: timestamp},
+    ])
+
     const {values} = state.get()
     expect(values['doc1']?.[projectionHash]).toEqual({
       isPending: false,
@@ -247,11 +249,9 @@ describe('subscribeToStateAndFetchBatches', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 100))
 
-    // Expected calls:
-    // 1. Initial fetch (doc1, hash1)
-    // 2. Adding doc2 subscription (optimistic update, no fetch)
-    // 3. Debounced fetch for (doc1, hash1) AND (doc2, hash2)
-    expect(getQueryState).toHaveBeenCalledTimes(initialQueryCallCount + 1)
+    // Expected calls: initial batch has 2 (projection + status). After adding doc2,
+    // debounced fetch triggers 2 more (projection + status for new batch).
+    expect(getQueryState).toHaveBeenCalledTimes(initialQueryCallCount + 2)
     // Abort should have been called because the required projections changed
     expect(abortSpy).toHaveBeenCalled()
 
@@ -259,13 +259,21 @@ describe('subscribeToStateAndFetchBatches', () => {
   })
 
   it('processes and applies fetch results correctly', async () => {
-    const subscriber =
-      vi.fn<(observer: Observer<ProjectionQueryResult[] | undefined>) => () => void>()
-
-    vi.mocked(getQueryState).mockReturnValue({
-      getCurrent: () => undefined,
-      observable: new Observable(subscriber),
-    } as StateSource<ProjectionQueryResult[] | undefined>)
+    const projectionObservers: Observer<ProjectionQueryResult[] | undefined>[] = []
+    const statusObservers: Observer<{_id: string; _updatedAt: string}[] | undefined>[] = []
+
+    vi.mocked(getQueryState).mockImplementation((_, options) => {
+      const isStatusQuery = options.perspective === 'raw'
+      const observers = isStatusQuery ? statusObservers : projectionObservers
+      const observable = new Observable<unknown>((observer) => {
+        observers.push(observer as Observer<ProjectionQueryResult[] | undefined>)
+        return () => {}
+      })
+      return {
+        getCurrent: () => undefined,
+        observable,
+      } as StateSource<ProjectionQueryResult[] | undefined>
+    })
 
     const subscription = subscribeToStateAndFetchBatches({instance, state, key})
     const projection = '{title, description}'
@@ -280,12 +288,12 @@ describe('subscribeToStateAndFetchBatches', () => {
 
     await new Promise((resolve) => setTimeout(resolve, 100))
 
-    expect(subscriber).toHaveBeenCalled()
-    const [observer] = subscriber.mock.lastCall!
+    expect(projectionObservers.length).toBe(1)
+    expect(statusObservers.length).toBe(1)
 
     // Emit fetch results
     const timestamp = '2024-01-01T00:00:00Z'
-    observer.next([
+    projectionObservers[0]!.next([
       {
         _id: 'doc1',
         _type: 'test',
@@ -294,13 +302,18 @@ describe('subscribeToStateAndFetchBatches', () => {
         __projectionHash: projectionHash,
       },
     ])
+    statusObservers[0]!.next([
+      {_id: 'doc1', _updatedAt: timestamp},
+      {_id: 'drafts.doc1', _updatedAt: timestamp},
+    ])
 
-    // Check that the state was updated
+    // Check that the state was updated (status query provides both draft and published _updatedAt)
     expect(state.get().values['doc1']?.[projectionHash]).toEqual({
       data: expect.objectContaining({
         title: 'Test Document',
         description: 'Test Description',
         _status: {
+          lastEditedDraftAt: timestamp,
           lastEditedPublishedAt: timestamp,
         },
       }),

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,
@@ -64,7 +74,6 @@ export interface QueryOptions<
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
-  source?: DocumentSource
 }
 
 /**
@@ -107,7 +116,7 @@ function normalizeOptionsWithPerspective(
   }
 }
 
-const queryStore = defineStore<QueryStoreState>({
+const queryStore = defineStore<QueryStoreState, BoundSourceKey>({
   name: 'QueryStore',
   getInitialState: () => ({queries: {}}),
   initialize(context) {
@@ -168,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,
@@ -179,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,
@@ -208,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(() =>