@sanity/sdk 2.3.0 → 2.4.0

package/src/client/clientStore.test.ts

@@ -3,6 +3,7 @@ import {Subject} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getAuthMethodState, getTokenState} from '../auth/authStore'
+import {canvasSource, datasetSource, mediaLibrarySource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {getClient, getClientState} from './clientStore'
 
@@ -75,6 +76,20 @@ describe('clientStore', () => {
       ).toThrowError(/unsupported properties: illegalKey/)
     })
 
+    it('should throw a helpful error when called without options', () => {
+      expect(() =>
+        // @ts-expect-error Testing missing options
+        getClient(instance, undefined),
+      ).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+    })
+
+    it('should throw a helpful error when called with null options', () => {
+      expect(() =>
+        // @ts-expect-error Testing null options
+        getClient(instance, null),
+      ).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+    })
+
     it('should reuse clients with identical configurations', () => {
       const options = {apiVersion: '2024-11-12', useCdn: true}
       const client1 = getClient(instance, options)
@@ -158,4 +173,140 @@ describe('clientStore', () => {
       subscription.unsubscribe()
     })
   })
+
+  describe('source handling', () => {
+    it('should create client when source is provided', () => {
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiVersion: '2024-11-12',
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+    })
+
+    it('should create resource when source has array sourceId and be projectless', () => {
+      const source = mediaLibrarySource('media-lib-123')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
+          'apiVersion': '2024-11-12',
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'media-library', id: 'media-lib-123'},
+        }),
+      )
+    })
+
+    it('should create resource when canvas source is provided and be projectless', () => {
+      const source = canvasSource('canvas-123')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
+          'apiVersion': '2024-11-12',
+        }),
+      )
+      // Client should be projectless - no projectId/dataset in config
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          '~experimental_resource': {type: 'canvas', id: 'canvas-123'},
+        }),
+      )
+    })
+
+    it('should create projectless client when source is provided, ignoring instance config', () => {
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {apiVersion: '2024-11-12', source})
+
+      // Client should be projectless - source takes precedence, instance config is ignored
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          source: expect.objectContaining({
+            __sanity_internal_sourceId: {
+              projectId: 'source-project',
+              dataset: 'source-dataset',
+            },
+          }),
+        }),
+      )
+    })
+
+    it('should warn when both source and explicit projectId/dataset are provided', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const source = datasetSource('source-project', 'source-dataset')
+      const client = getClient(instance, {
+        apiVersion: '2024-11-12',
+        source,
+        projectId: 'explicit-project',
+        dataset: 'explicit-dataset',
+      })
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Both source and explicit projectId/dataset are provided. The source will be used and projectId/dataset will be ignored.',
+      )
+      // Client should still be projectless despite explicit projectId/dataset
+      expect(client.config()).not.toHaveProperty('projectId')
+      expect(client.config()).not.toHaveProperty('dataset')
+      consoleSpy.mockRestore()
+    })
+
+    it('should create different clients for different sources', () => {
+      const source1 = datasetSource('project-1', 'dataset-1')
+      const source2 = datasetSource('project-2', 'dataset-2')
+      const source3 = mediaLibrarySource('media-lib-1')
+
+      const client1 = getClient(instance, {apiVersion: '2024-11-12', source: source1})
+      const client2 = getClient(instance, {apiVersion: '2024-11-12', source: source2})
+      const client3 = getClient(instance, {apiVersion: '2024-11-12', source: source3})
+
+      expect(client1).not.toBe(client2)
+      expect(client2).not.toBe(client3)
+      expect(client1).not.toBe(client3)
+      expect(vi.mocked(createClient)).toHaveBeenCalledTimes(3)
+    })
+
+    it('should reuse clients with identical source configurations', () => {
+      const source = datasetSource('same-project', 'same-dataset')
+      const options = {apiVersion: '2024-11-12', source}
+
+      const client1 = getClient(instance, options)
+      const client2 = getClient(instance, options)
+
+      expect(client1).toBe(client2)
+      expect(vi.mocked(createClient)).toHaveBeenCalledTimes(1)
+    })
+  })
 })

package/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>({
@@ -142,6 +149,13 @@ const getClientConfigKey = (options: ClientOptions) => JSON.stringify(pick(optio
 export const getClient = bindActionGlobally(
   clientStore,
   ({state, instance}, options: ClientOptions) => {
+    if (!options || typeof options !== 'object') {
+      throw new Error(
+        'getClient() requires a configuration object with at least an "apiVersion" property. ' +
+          'Example: getClient(instance, { apiVersion: "2024-11-12" })',
+      )
+    }
+
     // Check for disallowed keys
     const providedKeys = Object.keys(options) as (keyof ClientOptions)[]
     const disallowedKeys = providedKeys.filter((key) => !allowedKeys.includes(key))
@@ -156,18 +170,42 @@ export const getClient = bindActionGlobally(
 
     const tokenFromState = state.get().token
     const {clients, authMethod} = state.get()
+    const hasSource = !!options.source
+    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
     const dataset = options.dataset ?? instance.config.dataset
     const apiHost = options.apiHost ?? instance.config.auth?.apiHost
 
     const effectiveOptions: ClientOptions = {
       ...DEFAULT_CLIENT_CONFIG,
-      ...((options.scope === 'global' || !projectId) && {useProjectHostname: false}),
+      ...((options.scope === 'global' || !projectId || hasSource) && {useProjectHostname: false}),
       token: authMethod === 'cookie' ? undefined : (tokenFromState ?? undefined),
       ...options,
       ...(projectId && {projectId}),
       ...(dataset && {dataset}),
       ...(apiHost && {apiHost}),
+      ...(resource && {'~experimental_resource': resource}),
+    }
+
+    // When a source is provided, don't use projectId/dataset - the client should be "projectless"
+    // The client code itself will ignore the non-source config, so we do this to prevent confusing the user.
+    // (ref: https://github.com/sanity-io/client/blob/5c23f81f5ab93a53f5b22b39845c867988508d84/src/data/dataMethods.ts#L691)
+    if (hasSource) {
+      if (options.projectId || options.dataset) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          'Both source and explicit projectId/dataset are provided. The source will be used and projectId/dataset will be ignored.',
+        )
+      }
+      delete effectiveOptions.projectId
+      delete effectiveOptions.dataset
     }
 
     if (effectiveOptions.token === null || typeof effectiveOptions.token === 'undefined') {

package/src/config/sanityConfig.ts

@@ -81,3 +81,44 @@ 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.
+ * @see canvasSource Construct a document source for a canvasId.
+ */
+export type DocumentSource = {
+  [SOURCE_ID]: ['media-library', string] | ['canvas', 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]}
+}
+
+/**
+ * Returns a document source for a Canvas.
+ *
+ * @beta
+ */
+export function canvasSource(id: string): DocumentSource {
+  return {[SOURCE_ID]: ['canvas', id]}
+}

package/src/document/actions.test.ts

@@ -42,6 +42,40 @@ describe('document actions', () => {
         documentType: typeHandle.documentType,
       })
     })
+
+    it('creates a document action with initial values', () => {
+      const initialValue = {
+        title: 'Test Title',
+        author: 'John Doe',
+        count: 42,
+      }
+      const action = createDocument(dummyDocHandle, initialValue)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue,
+      })
+    })
+
+    it('creates a document action without initialValue when not provided', () => {
+      const action = createDocument(dummyDocHandle, undefined)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+      })
+    })
+
+    it('creates a document action with empty initialValue object', () => {
+      const action = createDocument(dummyDocHandle, {})
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue: {},
+      })
+    })
   })
 
   describe('deleteDocument', () => {

package/src/document/actions.ts

@@ -1,6 +1,7 @@
 import {SanityEncoder} from '@sanity/mutate'
 import {type PatchMutation as SanityMutatePatchMutation} from '@sanity/mutate/_unstable_store'
 import {type PatchMutation, type PatchOperations} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 
 import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
 import {getPublishedId} from '../utils/ids'
@@ -24,6 +25,17 @@ export interface CreateDocumentAction<
   TProjectId extends string = string,
 > extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.create'
+  /**
+   * Optional initial field values for the document.
+   * These values will be set when the document is created.
+   * System fields (_id, _type, _rev, _createdAt, _updatedAt) are omitted as they are set automatically.
+   */
+  initialValue?: Partial<
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
+  >
 }
 
 /**
@@ -111,6 +123,7 @@ export type DocumentAction<
 /**
  * Creates a `CreateDocumentAction` object.
  * @param doc - A handle identifying the document type, dataset, and project. An optional `documentId` can be provided.
+ * @param initialValue - Optional initial field values for the document. (System fields are omitted as they are set automatically.)
  * @returns A `CreateDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -120,11 +133,18 @@ export function createDocument<
   TProjectId extends string = string,
 >(
   doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
+  initialValue?: Partial<
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
+  >,
 ): CreateDocumentAction<TDocumentType, TDataset, TProjectId> {
   return {
     type: 'document.create',
     ...doc,
     ...(doc.documentId && {documentId: getPublishedId(doc.documentId)}),
+    ...(initialValue && {initialValue}),
   }
 }
 

package/src/document/documentStore.test.ts

@@ -110,6 +110,34 @@ it('creates, edits, and publishes a document', async () => {
   unsubscribe()
 })
 
+it('creates a document with initial values', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-with-initial', documentType: 'article'})
+  const documentState = getDocumentState(instance, doc)
+
+  expect(documentState.getCurrent()).toBeUndefined()
+
+  const unsubscribe = documentState.subscribe()
+
+  // Create a new document with initial field values
+  const {appeared} = await applyDocumentActions(
+    instance,
+    createDocument(doc, {
+      title: 'Article with Initial Values',
+      author: 'Jane Doe',
+      count: 42,
+    }),
+  )
+  expect(appeared).toContain(getDraftId(doc.documentId))
+
+  const currentDoc = documentState.getCurrent()
+  expect(currentDoc?._id).toEqual(getDraftId(doc.documentId))
+  expect(currentDoc?.title).toEqual('Article with Initial Values')
+  expect(currentDoc?.['author']).toEqual('Jane Doe')
+  expect(currentDoc?.['count']).toEqual(42)
+
+  unsubscribe()
+})
+
 it('edits existing documents', async () => {
   const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article'})
   const state = getDocumentState(instance, doc)

package/src/document/processActions.test.ts

@@ -138,6 +138,103 @@ describe('processActions', () => {
         processActions({actions, transactionId, base, working, timestamp, grants}),
       ).toThrow(/You do not have permission to create a draft for document "doc1"/)
     })
+
+    it('should create a draft document with initial values', () => {
+      const base: DocumentSet = {}
+      const working: DocumentSet = {}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {
+            title: 'New Article',
+            author: 'John Doe',
+            count: 42,
+          },
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      expect(draftDoc?._id).toBe(draftId)
+      expect(draftDoc?._type).toBe('article')
+      expect(draftDoc?._rev).toBe(transactionId)
+      // Should have the initial values:
+      expect(draftDoc?.['title']).toBe('New Article')
+      expect(draftDoc?.['author']).toBe('John Doe')
+      expect(draftDoc?.['count']).toBe(42)
+    })
+
+    it('should create a draft with initial values that override published document values', () => {
+      const published = createDoc('doc1', 'Original Title')
+      const base: DocumentSet = {doc1: published}
+      const working: DocumentSet = {doc1: published}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {
+            title: 'Overridden Title',
+            newField: 'New Value',
+          },
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      // Should have the overridden title from initialValue:
+      expect(draftDoc?.['title']).toBe('Overridden Title')
+      // Should have the new field:
+      expect(draftDoc?.['newField']).toBe('New Value')
+    })
+
+    it('should create a draft with empty initial values object', () => {
+      const base: DocumentSet = {}
+      const working: DocumentSet = {}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {},
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      expect(draftDoc?._id).toBe(draftId)
+      expect(draftDoc?._type).toBe('article')
+      expect(draftDoc?._rev).toBe(transactionId)
+    })
   })
 
   describe('document.delete', () => {

package/src/document/processActions.ts

@@ -152,8 +152,18 @@ export function processActions({
         }
 
         // Spread the (possibly undefined) published version directly.
-        const newDocBase = {...base[publishedId], _type: action.documentType, _id: draftId}
-        const newDocWorking = {...working[publishedId], _type: action.documentType, _id: draftId}
+        const newDocBase = {
+          ...base[publishedId],
+          _type: action.documentType,
+          _id: draftId,
+          ...action.initialValue,
+        }
+        const newDocWorking = {
+          ...working[publishedId],
+          _type: action.documentType,
+          _id: draftId,
+          ...action.initialValue,
+        }
         const mutations: Mutation[] = [{create: newDocWorking}]
 
         base = processMutations({

package/src/query/queryStore.ts

@@ -23,9 +23,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,
@@ -62,6 +62,7 @@ export interface QueryOptions<
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
+  source?: DocumentSource
 }
 
 /**
@@ -160,6 +161,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               projectId,
               dataset,
               tag,
+              source,
               perspective: perspectiveFromOptions,
               ...restOptions
             } = parseQueryKey(group$.key)
@@ -172,6 +174,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               apiVersion: QUERY_STORE_API_VERSION,
               projectId,
               dataset,
+              source,
             }).observable
 
             return combineLatest([lastLiveEventId$, client$, perspective$]).pipe(
@@ -290,7 +293,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) => {
@@ -349,7 +352,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)

package/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')