feat: introduce "source" concept

judofyr · judofyr · commit 5ef3accd3761 · 2025-09-16T13:14:26.000+02:00
The following introduces a "source" concept that can be used to query
different types of resources. The long-term vision here is:

- `SanityInstance` should no longer be an inherited tree structure.
  This will rather be a single object which contains global information
  (e.g. token). There will be no re-use of any state across `SanityInstance`.
- All hooks/functions which works on documents will also accept a
  `source` parameter. This is a single parameter (instead of the
  `projectId`/`dataset`) tuple that can easily be passed around.
  If you're making higher-order helpers you just need to accept a
  single source object.
- There are top-level functions which constructs these `source` objects.
  In the future these objects will also contain type information.
  These should also be owned by `@sanity/client`. In this PR we're
  mapping it to the existing experimental resource API, but the
  intention is for `@sanity/client` to provide a proper source-based API
  which we're re-exporting/using here in SDK.
- We'll introduce a new "default source" context as well. This is
  _outside_ of the `SanityInstance` so that you can change it.
- There will be no special support for placing multiple sources in the
  context. The user can always define their own context if they want to
  have access to multiple `source` objects. This gives them more
  flexibility in how to structure their applications.
- If you have fully static data sources you can always hard-code them in
  single file: `export const PRODUCTS = datasetSource(projectId, "datasets")`.
diff --git a/apps/kitchensink-react/src/AppRoutes.tsx b/apps/kitchensink-react/src/AppRoutes.tsx
@@ -17,8 +17,9 @@ import {ProtectedRoute} from './ProtectedRoute'
 import {DashboardContextRoute} from './routes/DashboardContextRoute'
 import {DashboardWorkspacesRoute} from './routes/DashboardWorkspacesRoute'
 import ExperimentalResourceClientRoute from './routes/ExperimentalResourceClientRoute'
-import {ProjectsRoute} from './routes/ProjectsRoute'
+import {MediaLibraryRoute} from './routes/MediaLibraryRoute'
 import {PerspectivesRoute} from './routes/PerspectivesRoute'
+import {ProjectsRoute} from './routes/ProjectsRoute'
 import {ReleasesRoute} from './routes/releases/ReleasesRoute'
 import {UserDetailRoute} from './routes/UserDetailRoute'
 import {UsersRoute} from './routes/UsersRoute'
@@ -72,6 +73,10 @@ const documentCollectionRoutes = [
     path: 'presence',
     element: <PresenceRoute />,
   },
+  {
+    path: 'media-library',
+    element: <MediaLibraryRoute />,
+  },
 ]
 
 const dashboardInteractionRoutes = [
diff --git a/apps/kitchensink-react/src/routes/MediaLibraryRoute.tsx b/apps/kitchensink-react/src/routes/MediaLibraryRoute.tsx
@@ -0,0 +1,76 @@
+import {mediaLibrarySource, useQuery} from '@sanity/sdk-react'
+import {Card, Spinner, Text} from '@sanity/ui'
+import {type JSX, useState} from 'react'
+
+// for now, hardcoded. should be inferred from org later on
+const MEDIA = mediaLibrarySource('mlPGY7BEqt52')
+
+export function MediaLibraryRoute(): JSX.Element {
+  const [query] = useState('*[_type == "sanity.asset"][0...10] | order(_id desc)')
+  const [isLoading] = useState(false)
+
+  const {data, isPending} = useQuery({
+    query,
+    source: MEDIA,
+  })
+
+  return (
+    <div style={{padding: '2rem', maxWidth: '800px', margin: '0 auto'}}>
+      <Text size={4} weight="bold" style={{marginBottom: '2rem', color: 'white'}}>
+        Media Library Query Demo
+      </Text>
+
+      <Text size={2} style={{marginBottom: '2rem'}}>
+        This route demonstrates querying against a Sanity media library. The MediaLibraryProvider is
+        automatically created by SanityApp when a media library config is present. The query runs
+        against: <code>https://api.sanity.io/v2025-03-24/media-libraries/mlPGY7BEqt52/query</code>
+      </Text>
+
+      <Card padding={3} style={{marginBottom: '2rem', backgroundColor: '#1a1a1a'}}>
+        <div style={{marginBottom: '1rem'}}>
+          <Text size={1} style={{color: '#ccc', marginBottom: '0.5rem'}}>
+            Current query:
+          </Text>
+          <code
+            style={{
+              display: 'block',
+              padding: '0.5rem',
+              backgroundColor: '#2a2a2a',
+              borderRadius: '4px',
+              fontFamily: 'monospace',
+              fontSize: '0.875rem',
+              color: '#fff',
+              wordBreak: 'break-all',
+            }}
+          >
+            {query}
+          </code>
+        </div>
+      </Card>
+
+      <Card padding={3} style={{backgroundColor: '#1a1a1a'}}>
+        <div style={{display: 'flex', alignItems: 'center', marginBottom: '1rem'}}>
+          <Text size={1} weight="medium" style={{color: '#fff'}}>
+            Query Results:
+          </Text>
+          {(isPending || isLoading) && <Spinner style={{marginLeft: '0.5rem'}} />}
+        </div>
+
+        <pre
+          style={{
+            backgroundColor: '#2a2a2a',
+            padding: '1rem',
+            borderRadius: '4px',
+            overflow: 'auto',
+            maxHeight: '400px',
+            fontSize: '0.875rem',
+            color: '#fff',
+            whiteSpace: 'pre-wrap',
+          }}
+        >
+          {JSON.stringify(data, null, 2)}
+        </pre>
+      </Card>
+    </div>
+  )
+}
diff --git a/packages/core/src/_exports/index.ts b/packages/core/src/_exports/index.ts
@@ -51,8 +51,11 @@ export {
 } from '../config/handles'
 export {
   type DatasetHandle,
+  datasetSource,
   type DocumentHandle,
+  type DocumentSource,
   type DocumentTypeHandle,
+  mediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
   type ReleasePerspective,
diff --git a/packages/core/src/client/clientStore.ts b/packages/core/src/client/clientStore.ts
@@ -2,6 +2,7 @@ import {type ClientConfig, createClient, type SanityClient} from '@sanity/client
 import {pick} from 'lodash-es'
 
 import {getAuthMethodState, getTokenState} from '../auth/authStore'
+import {type DocumentSource, SOURCE_ID} from '../config/sanityConfig'
 import {bindActionGlobally} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
@@ -39,6 +40,7 @@ const allowedKeys = Object.keys({
   'requestTagPrefix': null,
   'useProjectHostname': null,
   '~experimental_resource': null,
+  'source': null,
 } satisfies Record<keyof ClientOptions, null>) as (keyof ClientOptions)[]
 
 const DEFAULT_CLIENT_CONFIG: ClientConfig = {
@@ -90,6 +92,11 @@ export interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey
    * @internal
    */
   '~experimental_resource'?: ClientConfig['~experimental_resource']
+
+  /**
+   * @internal
+   */
+  'source'?: DocumentSource
 }
 
 const clientStore = defineStore<ClientStoreState>({
@@ -156,8 +163,16 @@ export const getClient = bindActionGlobally(
 
     const tokenFromState = state.get().token
     const {clients, authMethod} = state.get()
-    const projectId = options.projectId ?? instance.config.projectId
-    const dataset = options.dataset ?? instance.config.dataset
+    let sourceId = options.source?.[SOURCE_ID]
+
+    let resource
+    if (Array.isArray(sourceId)) {
+      resource = {type: sourceId[0], id: sourceId[1]}
+      sourceId = undefined
+    }
+
+    const projectId = options.projectId ?? instance.config.projectId ?? sourceId?.projectId
+    const dataset = options.dataset ?? instance.config.dataset ?? sourceId?.dataset
     const apiHost = options.apiHost ?? instance.config.auth?.apiHost
 
     const effectiveOptions: ClientOptions = {
@@ -168,6 +183,7 @@ export const getClient = bindActionGlobally(
       ...(projectId && {projectId}),
       ...(dataset && {dataset}),
       ...(apiHost && {apiHost}),
+      ...(resource && {'~experimental_resource': resource}),
     }
 
     if (effectiveOptions.token === null || typeof effectiveOptions.token === 'undefined') {
diff --git a/packages/core/src/config/sanityConfig.ts b/packages/core/src/config/sanityConfig.ts
@@ -81,3 +81,34 @@ export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
     enabled: boolean
   }
 }
+
+export const SOURCE_ID = '__sanity_internal_sourceId'
+
+/**
+ * A document source can be used for querying.
+ *
+ * @beta
+ * @see datasetSource Construct a document source for a given projectId and dataset.
+ * @see mediaLibrarySource Construct a document source for a mediaLibraryId.
+ */
+export type DocumentSource = {
+  [SOURCE_ID]: ['media-library', string] | {projectId: string; dataset: string}
+}
+
+/**
+ * Returns a document source for a projectId and dataset.
+ *
+ * @beta
+ */
+export function datasetSource(projectId: string, dataset: string): DocumentSource {
+  return {[SOURCE_ID]: {projectId, dataset}}
+}
+
+/**
+ * Returns a document source for a Media Library.
+ *
+ * @beta
+ */
+export function mediaLibrarySource(id: string): DocumentSource {
+  return {[SOURCE_ID]: ['media-library', id]}
+}
diff --git a/packages/core/src/query/queryStore.ts b/packages/core/src/query/queryStore.ts
@@ -22,9 +22,9 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type DatasetHandle} from '../config/sanityConfig'
+import {type DatasetHandle, type DocumentSource} from '../config/sanityConfig'
 import {getPerspectiveState} from '../releases/getPerspectiveState'
-import {bindActionByDataset} from '../store/createActionBinder'
+import {bindActionBySource} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {
   createStateSourceAction,
@@ -61,6 +61,7 @@ export interface QueryOptions<
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
+  source?: DocumentSource
 }
 
 /**
@@ -159,6 +160,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               projectId,
               dataset,
               tag,
+              source,
               perspective: perspectiveFromOptions,
               ...restOptions
             } = parseQueryKey(group$.key)
@@ -171,6 +173,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               apiVersion: QUERY_STORE_API_VERSION,
               projectId,
               dataset,
+              source,
             }).observable
 
             return combineLatest([lastLiveEventId$, client$, perspective$]).pipe(
@@ -278,7 +281,7 @@ export function getQueryState(
 ): ReturnType<typeof _getQueryState> {
   return _getQueryState(...args)
 }
-const _getQueryState = bindActionByDataset(
+const _getQueryState = bindActionBySource(
   queryStore,
   createStateSourceAction({
     selector: ({state, instance}: SelectorContext<QueryStoreState>, options: QueryOptions) => {
@@ -337,7 +340,7 @@ export function resolveQuery<TData>(
 export function resolveQuery(...args: Parameters<typeof _resolveQuery>): Promise<unknown> {
   return _resolveQuery(...args)
 }
-const _resolveQuery = bindActionByDataset(
+const _resolveQuery = bindActionBySource(
   queryStore,
   ({state, instance}, {signal, ...options}: ResolveQueryOptions) => {
     const normalized = normalizeOptionsWithPerspective(instance, options)
diff --git a/packages/core/src/store/createActionBinder.ts b/packages/core/src/store/createActionBinder.ts
@@ -1,4 +1,4 @@
-import {type SanityConfig} from '../config/sanityConfig'
+import {type DocumentSource, type SanityConfig, SOURCE_ID} from '../config/sanityConfig'
 import {type SanityInstance} from './createSanityInstance'
 import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
@@ -43,7 +43,9 @@ export type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (
  * )
  * ```
  */
-export function createActionBinder(keyFn: (config: SanityConfig) => string) {
+export function createActionBinder<TKeyParams extends unknown[]>(
+  keyFn: (config: SanityConfig, ...params: TKeyParams) => string,
+) {
   const instanceRegistry = new Map<string, Set<string>>()
   const storeRegistry = new Map<string, StoreInstance<unknown>>()
 
@@ -54,12 +56,12 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
    * @param action - The action to bind
    * @returns A function that executes the action with a Sanity instance
    */
-  return function bindAction<TState, TParams extends unknown[], TReturn>(
+  return function bindAction<TState, TParams extends TKeyParams, TReturn>(
     storeDefinition: StoreDefinition<TState>,
     action: StoreAction<TState, TParams, TReturn>,
   ): BoundStoreAction<TState, TParams, TReturn> {
     return function boundAction(instance: SanityInstance, ...params: TParams) {
-      const keySuffix = keyFn(instance.config)
+      const keySuffix = keyFn(instance.config, ...params)
       const compositeKey = storeDefinition.name + (keySuffix ? `:${keySuffix}` : '')
 
       // Get or create instance set for this composite key
@@ -128,13 +130,32 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
  * fetchDocument(sanityInstance, 'doc123')
  * ```
  */
-export const bindActionByDataset = createActionBinder(({projectId, dataset}) => {
+export const bindActionByDataset = createActionBinder<unknown[]>(({projectId, dataset}) => {
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
   }
   return `${projectId}.${dataset}`
 })
 
+/**
+ * Binds an action to a store that's scoped to a specific document source.
+ **/
+export const bindActionBySource = createActionBinder<[{source?: DocumentSource}, ...unknown[]]>(
+  ({projectId, dataset}, {source}) => {
+    if (source) {
+      const id = source[SOURCE_ID]
+      if (!id) throw new Error('Invalid source (missing ID information)')
+      if (Array.isArray(id)) return id.join(':')
+      return `${id.projectId}.${id.dataset}`
+    }
+
+    if (!projectId || !dataset) {
+      throw new Error('This API requires a project ID and dataset configured.')
+    }
+    return `${projectId}.${dataset}`
+  },
+)
+
 /**
  * Binds an action to a global store that's shared across all Sanity instances
  *
@@ -173,4 +194,4 @@ export const bindActionByDataset = createActionBinder(({projectId, dataset}) =>
  * getCurrentUser(sanityInstance)
  * ```
  */
-export const bindActionGlobally = createActionBinder(() => 'global')
+export const bindActionGlobally = createActionBinder<unknown[]>(() => 'global')
