feat: support arbitrary sources in useQuery

This contains a non-breaking change to `useQuery` (and other hooks which
uses this under the hood) of accepting a `source` parameter. This can be
used to query datasets which are not part of the current context.

However, this has lead to some breaking changes to the `core` package:

- The QueryOptions no longer takes an _optional_ projectId/dataset, but
  rather a _required_ `source`. This will always represent the resource
  we'll be querying.
- The same applies to `perspective`. This is part of the work of
  decoupling the perspective setting from the SanityInstace.
- However, since we still want `useQuery` to have the same options we've
  now introduced a new UseQueryOptions.

Author: judofyr

packages/core/src/_exports/index.ts

@@ -52,11 +52,13 @@ export {
 export {
   type DatasetHandle,
   type DocumentHandle,
+  type DocumentSource,
   type DocumentTypeHandle,
   type PerspectiveHandle,
   type ProjectHandle,
   type ReleasePerspective,
   type SanityConfig,
+  sourceFor,
 } from '../config/sanityConfig'
 export {getDatasetsState, resolveDatasets} from '../datasets/datasets'
 export {

packages/core/src/config/sanityConfig.ts

@@ -81,3 +81,32 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
     enabled: boolean
   }
 }
+
+/**
+ * Represents a source which can be used by various functionality.
+ *
+ * @see sourceFor For how to initialize a new source for a dataset.
+ * @public
+ */
+export type DocumentSource = {
+  [__sourceData]: {
+    projectId: string
+    dataset: string
+  }
+}
+
+/**
+ * An internal symbol to avoid users to access data inside here.
+ *
+ * @internal
+ */
+export const __sourceData = Symbol('Sanity.DocumentSource')
+
+/**
+ * Creates a new {@link DocumentSource} object based on a projectId and dataset.
+ *
+ * @public
+ */
+export function sourceFor(data: {projectId: string; dataset: string}): DocumentSource {
+  return {[__sourceData]: data}
+}

packages/core/src/preview/subscribeToStateAndFetchBatches.ts

@@ -14,6 +14,7 @@ import {
   tap,
 } from 'rxjs'
 
+import {sourceFor} from '../config/sanityConfig'
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {type BoundDatasetKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
@@ -66,8 +67,7 @@ export const subscribeToStateAndFetchBatches = ({
             params,
             tag: PREVIEW_TAG,
             perspective: PREVIEW_PERSPECTIVE,
-            projectId,
-            dataset,
+            source: sourceFor({projectId, dataset}),
           })
           const source$ = defer(() => {
             if (getCurrent() === undefined) {
@@ -78,8 +78,7 @@ export const subscribeToStateAndFetchBatches = ({
                   tag: PREVIEW_TAG,
                   perspective: PREVIEW_PERSPECTIVE,
                   signal: controller.signal,
-                  projectId,
-                  dataset,
+                  source: sourceFor({projectId, dataset}),
                 }),
               ).pipe(switchMap(() => observable))
             }

packages/core/src/projection/subscribeToStateAndFetchBatches.ts

@@ -16,6 +16,7 @@ import {
   tap,
 } from 'rxjs'
 
+import {sourceFor} from '../config/sanityConfig'
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {type BoundDatasetKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
@@ -96,8 +97,7 @@ export const subscribeToStateAndFetchBatches = ({
           const {getCurrent, observable} = getQueryState<ProjectionQueryResult[]>(instance, {
             query,
             params,
-            projectId,
-            dataset,
+            source: sourceFor({projectId, dataset}),
             tag: PROJECTION_TAG,
             perspective: PROJECTION_PERSPECTIVE,
           })
@@ -108,8 +108,7 @@ export const subscribeToStateAndFetchBatches = ({
                 resolveQuery<ProjectionQueryResult[]>(instance, {
                   query,
                   params,
-                  projectId,
-                  dataset,
+                  source: sourceFor({projectId, dataset}),
                   tag: PROJECTION_TAG,
                   perspective: PROJECTION_PERSPECTIVE,
                   signal: controller.signal,

packages/core/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 {sourceFor as getSource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getQueryState, resolveQuery} from './queryStore'
@@ -17,6 +18,7 @@ vi.mock('../client/clientStore', () => ({
 }))
 
 describe('queryStore', () => {
+  const source = getSource({projectId: 'test', dataset: 'test'})
   let instance: SanityInstance
   let liveEvents: Subject<LiveEvent>
   let fetch: SanityClient['observable']['fetch']
@@ -61,7 +63,7 @@ describe('queryStore', () => {
 
   it('initializes query state and cleans up after unsubscribe', async () => {
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
 
     // Initially undefined before subscription
     expect(state.getCurrent()).toBeUndefined()
@@ -90,7 +92,7 @@ describe('queryStore', () => {
 
   it('maintains state when multiple subscribers exist', async () => {
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
 
     // Add two subscribers
     const unsubscribe1 = state.subscribe()
@@ -127,13 +129,13 @@ describe('queryStore', () => {
   it('resolveQuery works without affecting subscriber cleanup', async () => {
     const query = '*[_type == "movie"]'
 
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
 
     // Check that getQueryState starts undefined
     expect(state.getCurrent()).toBeUndefined()
 
     // Use resolveQuery which should not add a subscriber
-    const result = await resolveQuery(instance, {query})
+    const result = await resolveQuery(instance, {query, source, perspective: 'drafts'})
     expect(result).toEqual([
       {_id: 'movie1', _type: 'movie', title: 'Movie 1'},
       {_id: 'movie2', _type: 'movie', title: 'Movie 2'},
@@ -160,7 +162,12 @@ describe('queryStore', () => {
     const abortController = new AbortController()
 
     // Create a promise that will reject when aborted
-    const queryPromise = resolveQuery(instance, {query, signal: abortController.signal})
+    const queryPromise = resolveQuery(instance, {
+      query,
+      source,
+      perspective: 'drafts',
+      signal: abortController.signal,
+    })
 
     // Abort the request
     abortController.abort()
@@ -169,7 +176,9 @@ describe('queryStore', () => {
     await expect(queryPromise).rejects.toThrow('The operation was aborted.')
 
     // Verify state is cleared after abort
-    expect(getQueryState(instance, {query}).getCurrent()).toBeUndefined()
+    expect(
+      getQueryState(instance, {query, source, perspective: 'drafts'}).getCurrent(),
+    ).toBeUndefined()
   })
 
   it('refetches query when receiving live event with matching sync tag', async () => {
@@ -188,7 +197,11 @@ describe('queryStore', () => {
     )
 
     const query = '*[_type == "movie"]'
-    const state = getQueryState<{_id: string; _type: string; title: string}[]>(instance, {query})
+    const state = getQueryState<{_id: string; _type: string; title: string}[]>(instance, {
+      query,
+      source,
+      perspective: 'drafts',
+    })
 
     const unsubscribe = state.subscribe()
     await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
@@ -219,7 +232,7 @@ describe('queryStore', () => {
     )
 
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
 
     const unsubscribe = state.subscribe()
     await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
@@ -252,7 +265,7 @@ describe('queryStore', () => {
     )
 
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
 
     const unsubscribe = state.subscribe()
     await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
@@ -289,7 +302,7 @@ describe('queryStore', () => {
     )
 
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
     const unsubscribe = state.subscribe()
 
     // Verify error is thrown when accessing state
@@ -300,7 +313,7 @@ describe('queryStore', () => {
 
   it('delays query state removal after unsubscribe', async () => {
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
     const unsubscribe = state.subscribe()
 
     await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
@@ -316,7 +329,7 @@ describe('queryStore', () => {
 
   it('preserves query state if a new subscriber subscribes before cleanup delay', async () => {
     const query = '*[_type == "movie"]'
-    const state = getQueryState(instance, {query})
+    const state = getQueryState(instance, {query, source, perspective: 'drafts'})
     const unsubscribe1 = state.subscribe()
 
     await firstValueFrom(state.observable.pipe(filter((i) => i !== undefined)))
@@ -352,22 +365,16 @@ describe('queryStore', () => {
         SanityClient['observable']['fetch']
       >
     }) as SanityClient['observable']['fetch'])
-
-    const draftsInstance = createSanityInstance({
-      projectId: 'test',
-      dataset: 'test',
+    // Same query/options, different implicit perspectives via instance.config
+    const sDrafts = getQueryState<{_id: string}[]>(instance, {
+      query: '*[_type == "movie"]',
+      source,
       perspective: 'drafts',
     })
-    const publishedInstance = createSanityInstance({
-      projectId: 'test',
-      dataset: 'test',
-      perspective: 'published',
-    })
-
-    // Same query/options, different implicit perspectives via instance.config
-    const sDrafts = getQueryState<{_id: string}[]>(draftsInstance, {query: '*[_type == "movie"]'})
-    const sPublished = getQueryState<{_id: string}[]>(publishedInstance, {
+    const sPublished = getQueryState<{_id: string}[]>(instance, {
       query: '*[_type == "movie"]',
+      source,
+      perspective: 'published',
     })
 
     const unsubDrafts = sDrafts.subscribe()
@@ -385,9 +392,6 @@ describe('queryStore', () => {
 
     unsubDrafts()
     unsubPublished()
-
-    draftsInstance.dispose()
-    publishedInstance.dispose()
   })
 
   it('separates cache entries by explicit perspective in options', async () => {
@@ -403,10 +407,12 @@ describe('queryStore', () => {
 
     const sDrafts = getQueryState<{_id: string}[]>(base, {
       query: '*[_type == "movie"]',
+      source,
       perspective: 'drafts',
     })
     const sPublished = getQueryState<{_id: string}[]>(base, {
       query: '*[_type == "movie"]',
+      source,
       perspective: 'published',
     })
 

packages/core/src/query/queryStore.ts

@@ -1,4 +1,4 @@
-import {CorsOriginError, type ResponseQueryOptions} from '@sanity/client'
+import {type ClientPerspective, CorsOriginError, type ResponseQueryOptions} from '@sanity/client'
 import {type SanityQueryResult} from 'groq'
 import {
   catchError,
@@ -23,7 +23,7 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type DatasetHandle} from '../config/sanityConfig'
+import {type DocumentSource, type ReleasePerspective} from '../config/sanityConfig'
 import {getPerspectiveState} from '../releases/getPerspectiveState'
 import {bindActionByDataset, type BoundDatasetKey} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
@@ -54,33 +54,28 @@ import {
 /**
  * @beta
  */
-export interface QueryOptions<
-  TQuery extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
-> extends Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>,
-    DatasetHandle<TDataset, TProjectId> {
+export interface QueryOptions<TQuery extends string = string>
+  extends Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'> {
   query: TQuery
   params?: Record<string, unknown>
+  source: DocumentSource
+  perspective: ClientPerspective | ReleasePerspective
 }
 
 /**
  * @beta
  */
-export interface ResolveQueryOptions<
-  TQuery extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
-> extends QueryOptions<TQuery, TDataset, TProjectId> {
+export interface ResolveQueryOptions<TQuery extends string = string> extends QueryOptions<TQuery> {
   signal?: AbortSignal
 }
 
 const EMPTY_ARRAY: never[] = []
 
 /** @beta */
-export const getQueryKey = (options: QueryOptions): string => JSON.stringify(options)
+export const getQueryKey = (options: Omit<QueryOptions, 'source'>): string =>
+  JSON.stringify(options)
 /** @beta */
-export const parseQueryKey = (key: string): QueryOptions => JSON.parse(key)
+export const parseQueryKey = (key: string): Omit<QueryOptions, 'source'> => JSON.parse(key)
 
 /**
  * Ensures the query key includes an effective perspective so that
@@ -276,7 +271,7 @@ export function getQueryState<
   TProjectId extends string = string,
 >(
   instance: SanityInstance,
-  queryOptions: QueryOptions<TQuery, TDataset, TProjectId>,
+  queryOptions: QueryOptions<TQuery>,
 ): StateSource<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`> | undefined>
 
 /** @beta */
@@ -334,7 +329,7 @@ const _getQueryState = bindActionByDataset(
  */
 export function getQueryErrorState(
   instance: SanityInstance,
-  options: {projectId?: string; dataset?: string} = {},
+  options: {source: DocumentSource},
 ): StateSource<unknown | undefined> {
   return _getQueryErrorState(instance, options)
 }
@@ -370,7 +365,7 @@ export function resolveQuery<
   TProjectId extends string = string,
 >(
   instance: SanityInstance,
-  queryOptions: ResolveQueryOptions<TQuery, TDataset, TProjectId>,
+  queryOptions: ResolveQueryOptions<TQuery>,
 ): Promise<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>>
 
 /** @beta */
@@ -428,10 +423,7 @@ const _resolveQuery = bindActionByDataset(
  * Clears the top-level query store error.
  * @beta
  */
-export function clearQueryError(
-  instance: SanityInstance,
-  options: {projectId?: string; dataset?: string} = {},
-): void {
+export function clearQueryError(instance: SanityInstance, options: {source: DocumentSource}): void {
   return _clearQueryError(instance, options)
 }