@sanity/sdk 2.3.1 → 2.5.0

package/src/releases/getPerspectiveState.ts

@@ -17,13 +17,13 @@ const DEFAULT_PERSPECTIVE = 'drafts'
 // Cache for options
 const optionsCache = new Map<string, Map<string, PerspectiveHandle>>()
 
-const selectInstancePerspective = (context: SelectorContext<ReleasesStoreState>) =>
+const selectInstancePerspective = (context: SelectorContext<ReleasesStoreState>, _?: unknown) =>
   context.instance.config.perspective
 const selectActiveReleases = (context: SelectorContext<ReleasesStoreState>) =>
   context.state.activeReleases
 const selectOptions = (
   _context: SelectorContext<ReleasesStoreState>,
-  options?: PerspectiveHandle,
+  options: PerspectiveHandle & {projectId?: string; dataset?: string},
 ) => options
 
 const memoizedOptionsSelector = createSelector(

package/src/releases/releasesStore.ts

@@ -3,7 +3,7 @@ import {type SanityDocument} from '@sanity/types'
 import {catchError, EMPTY, retry, switchMap, timer} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {bindActionByDataset} from '../store/createActionBinder'
+import {bindActionByDataset, type BoundDatasetKey} from '../store/createActionBinder'
 import {createStateSourceAction} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {listenQuery} from '../utils/listenQuery'
@@ -32,7 +32,7 @@ export interface ReleasesStoreState {
   error?: unknown
 }
 
-export const releasesStore = defineStore<ReleasesStoreState>({
+export const releasesStore = defineStore<ReleasesStoreState, BoundDatasetKey>({
   name: 'Releases',
   getInitialState: (): ReleasesStoreState => ({
     activeReleases: undefined,
@@ -50,17 +50,23 @@ export const releasesStore = defineStore<ReleasesStoreState>({
 export const getActiveReleasesState = bindActionByDataset(
   releasesStore,
   createStateSourceAction({
-    selector: ({state}) => state.activeReleases,
+    selector: ({state}, _?) => state.activeReleases,
   }),
 )
 
 const RELEASES_QUERY = 'releases::all()'
 const QUERY_PARAMS = {}
 
-const subscribeToReleases = ({instance, state}: StoreContext<ReleasesStoreState>) => {
+const subscribeToReleases = ({
+  instance,
+  state,
+  key: {projectId, dataset},
+}: StoreContext<ReleasesStoreState, BoundDatasetKey>) => {
   return getClientState(instance, {
     apiVersion: '2025-04-10',
     perspective: 'raw',
+    projectId,
+    dataset,
   })
     .observable.pipe(
       switchMap((client: SanityClient) =>

package/src/store/createActionBinder.test.ts

@@ -12,7 +12,7 @@ beforeEach(() => vi.mocked(createStoreInstance).mockClear())
 
 describe('createActionBinder', () => {
   it('should bind an action and call it with correct context and parameters, using caching', () => {
-    const binder = createActionBinder(() => '')
+    const binder = createActionBinder((..._rest) => ({name: ''}))
     const storeDefinition = {
       name: 'TestStore',
       getInitialState: () => ({counter: 0}),
@@ -37,7 +37,9 @@ describe('createActionBinder', () => {
   })
 
   it('should create separate store instances for different composite keys', () => {
-    const binder = createActionBinder(({projectId, dataset}) => `${projectId}.${dataset}`)
+    const binder = createActionBinder(({config: {projectId, dataset}}, ..._rest) => ({
+      name: `${projectId}.${dataset}`,
+    }))
     const storeDefinition = {
       name: 'TestStore',
       getInitialState: () => ({counter: 0}),
@@ -59,7 +61,7 @@ describe('createActionBinder', () => {
   })
 
   it('should dispose the store instance when the last instance is disposed', () => {
-    const binder = createActionBinder(() => '')
+    const binder = createActionBinder((..._rest) => ({name: ''}))
     const storeDefinition = {
       name: 'TestStore',
       getInitialState: () => ({counter: 0}),
@@ -93,10 +95,10 @@ describe('bindActionByDataset', () => {
       name: 'DSStore',
       getInitialState: () => ({counter: 0}),
     }
-    const action = vi.fn((_context, value: string) => value)
+    const action = vi.fn((_context, {value}: {value: string}) => value)
     const boundAction = bindActionByDataset(storeDefinition, action)
     const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
-    const result = boundAction(instance, 'hello')
+    const result = boundAction(instance, {value: 'hello'})
     expect(result).toBe('hello')
   })
 
@@ -105,7 +107,7 @@ describe('bindActionByDataset', () => {
       name: 'DSStore',
       getInitialState: () => ({counter: 0}),
     }
-    const action = vi.fn((_context) => 'fail')
+    const action = vi.fn((_context, _?) => 'fail')
     const boundAction = bindActionByDataset(storeDefinition, action)
     // Instance with missing dataset
     const instance = createSanityInstance({projectId: 'proj1', dataset: ''})

package/src/store/createActionBinder.ts

@@ -1,14 +1,20 @@
-import {type SanityConfig} from '../config/sanityConfig'
+import {type DocumentSource, SOURCE_ID} from '../config/sanityConfig'
 import {type SanityInstance} from './createSanityInstance'
 import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
 import {type StoreContext, type StoreDefinition} from './defineStore'
 
+export type BoundDatasetKey = {
+  name: string
+  projectId: string
+  dataset: string
+}
+
 /**
  * Defines a store action that operates on a specific state type
  */
-export type StoreAction<TState, TParams extends unknown[], TReturn> = (
-  context: StoreContext<TState>,
+export type StoreAction<TState, TParams extends unknown[], TReturn, TKey = unknown> = (
+  context: StoreContext<TState, TKey>,
   ...params: TParams
 ) => TReturn
 
@@ -43,7 +49,10 @@ export type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (
  * )
  * ```
  */
-export function createActionBinder(keyFn: (config: SanityConfig) => string) {
+export function createActionBinder<
+  TKey extends {name: string},
+  TKeyParams extends unknown[] = unknown[],
+>(keyFn: (instance: SanityInstance, ...params: TKeyParams) => TKey) {
   const instanceRegistry = new Map<string, Set<string>>()
   const storeRegistry = new Map<string, StoreInstance<unknown>>()
 
@@ -54,13 +63,13 @@ 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>(
-    storeDefinition: StoreDefinition<TState>,
-    action: StoreAction<TState, TParams, TReturn>,
+  return function bindAction<TState, TParams extends TKeyParams, TReturn>(
+    storeDefinition: StoreDefinition<TState, TKey>,
+    action: StoreAction<TState, TParams, TReturn, TKey>,
   ): BoundStoreAction<TState, TParams, TReturn> {
     return function boundAction(instance: SanityInstance, ...params: TParams) {
-      const keySuffix = keyFn(instance.config)
-      const compositeKey = storeDefinition.name + (keySuffix ? `:${keySuffix}` : '')
+      const key = keyFn(instance, ...params)
+      const compositeKey = storeDefinition.name + (key.name ? `:${key.name}` : '')
 
       // Get or create instance set for this composite key
       let instances = instanceRegistry.get(compositeKey)
@@ -87,12 +96,12 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
       // Get or create store instance
       let storeInstance = storeRegistry.get(compositeKey)
       if (!storeInstance) {
-        storeInstance = createStoreInstance(instance, storeDefinition)
+        storeInstance = createStoreInstance(instance, key, storeDefinition)
         storeRegistry.set(compositeKey, storeInstance)
       }
 
       // Execute action with store context
-      return action({instance, state: storeInstance.state as StoreState<TState>}, ...params)
+      return action({instance, state: storeInstance.state as StoreState<TState>, key}, ...params)
     }
   }
 }
@@ -128,11 +137,38 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
  * fetchDocument(sanityInstance, 'doc123')
  * ```
  */
-export const bindActionByDataset = createActionBinder(({projectId, dataset}) => {
+export const bindActionByDataset = createActionBinder<
+  BoundDatasetKey,
+  [(object & {projectId?: string; dataset?: string})?, ...unknown[]]
+>((instance, options) => {
+  const projectId = options?.projectId ?? instance.config.projectId
+  const dataset = options?.dataset ?? instance.config.dataset
+  if (!projectId || !dataset) {
+    throw new Error('This API requires a project ID and dataset configured.')
+  }
+  return {name: `${projectId}.${dataset}`, projectId, dataset}
+})
+
+/**
+ * Binds an action to a store that's scoped to a specific document source.
+ **/
+export const bindActionBySource = createActionBinder<
+  {name: string},
+  [{source?: DocumentSource}, ...unknown[]]
+>((instance, {source}) => {
+  if (source) {
+    const id = source[SOURCE_ID]
+    if (!id) throw new Error('Invalid source (missing ID information)')
+    if (Array.isArray(id)) return {name: id.join(':')}
+    return {name: `${id.projectId}.${id.dataset}`}
+  }
+
+  const {projectId, dataset} = instance.config
+
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
   }
-  return `${projectId}.${dataset}`
+  return {name: `${projectId}.${dataset}`}
 })
 
 /**
@@ -173,4 +209,4 @@ export const bindActionByDataset = createActionBinder(({projectId, dataset}) =>
  * getCurrentUser(sanityInstance)
  * ```
  */
-export const bindActionGlobally = createActionBinder(() => 'global')
+export const bindActionGlobally = createActionBinder((..._rest) => ({name: 'global'}))

package/src/store/createStateSourceAction.test.ts

@@ -21,7 +21,7 @@ describe('createStateSourceAction', () => {
   it('should create a source that provides current state through getCurrent', () => {
     const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
     const action = createStateSourceAction(selector)
-    const source = action({state, instance})
+    const source = action({state, instance, key: null})
 
     expect(source.getCurrent()).toBe(0)
     state.set('test', {count: 5})
@@ -33,7 +33,7 @@ describe('createStateSourceAction', () => {
     const source = createStateSourceAction({
       selector: ({state: s}: SelectorContext<CountStoreState>) => s.count,
       isEqual: (a, b) => a === b,
-    })({state, instance})
+    })({state, instance, key: null})
 
     const unsubscribe = source.subscribe(onStoreChanged)
 
@@ -53,11 +53,11 @@ describe('createStateSourceAction', () => {
     const source = createStateSourceAction({
       selector: ({state: s}: SelectorContext<CountStoreState>) => s.items,
       onSubscribe,
-    })({state, instance})
+    })({state, instance, key: null})
 
     const unsubscribe = source.subscribe()
     expect(onSubscribe).toHaveBeenCalledWith(
-      expect.objectContaining({state, instance}),
+      expect.objectContaining({state, instance, key: null}),
       // No params in this case
     )
 
@@ -68,7 +68,7 @@ describe('createStateSourceAction', () => {
     const action = createStateSourceAction({
       selector: ({state: s}: SelectorContext<CountStoreState>, index: number) => s.items[index],
     })
-    const source = action({state, instance}, 0)
+    const source = action({state, instance, key: null}, 0)
 
     state.set('add', {items: ['first']})
     expect(source.getCurrent()).toBe('first')
@@ -80,7 +80,7 @@ describe('createStateSourceAction', () => {
       selector: () => {
         throw error
       },
-    })({state, instance})
+    })({state, instance, key: null})
 
     const errorHandler = vi.fn()
     source.observable.subscribe({error: errorHandler})
@@ -94,7 +94,7 @@ describe('createStateSourceAction', () => {
     const source = createStateSourceAction({
       selector: ({state: s}: SelectorContext<CountStoreState>) => s.items.map((i) => i.length),
       isEqual,
-    })({state, instance})
+    })({state, instance, key: null})
 
     const onChange = vi.fn()
     source.subscribe(onChange)
@@ -112,7 +112,7 @@ describe('createStateSourceAction', () => {
     const source = createStateSourceAction({
       selector: ({state: s}: SelectorContext<CountStoreState>) => s.count,
       onSubscribe: () => cleanup,
-    })({state, instance})
+    })({state, instance, key: null})
 
     const unsubscribe = source.subscribe()
     unsubscribe()
@@ -125,6 +125,7 @@ describe('createStateSourceAction', () => {
     )({
       state,
       instance,
+      key: null,
     })
 
     const subscriber1 = vi.fn()
@@ -144,7 +145,7 @@ describe('createStateSourceAction', () => {
 
   it('should cache selector context per state object', () => {
     const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
-    const source = createStateSourceAction(selector)({state, instance})
+    const source = createStateSourceAction(selector)({state, instance, key: null})
 
     // Initial call creates context
     expect(source.getCurrent()).toBe(0)
@@ -181,10 +182,10 @@ describe('createStateSourceAction', () => {
     const secondInstance = createSanityInstance({projectId: 'test2', dataset: 'test2'})
     const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
 
-    const source1 = createStateSourceAction(selector)({state, instance})
+    const source1 = createStateSourceAction(selector)({state, instance, key: null})
     source1.getCurrent()
 
-    const source2 = createStateSourceAction(selector)({state, instance: secondInstance})
+    const source2 = createStateSourceAction(selector)({state, instance: secondInstance, key: null})
     source2.getCurrent()
 
     const context1 = selector.mock.calls[0][0]

package/src/store/createStateSourceAction.ts

@@ -89,7 +89,7 @@ export type Selector<TState, TParams extends unknown[], TReturn> = (
 /**
  * Configuration options for creating a state source action
  */
-interface StateSourceOptions<TState, TParams extends unknown[], TReturn> {
+interface StateSourceOptions<TState, TParams extends unknown[], TReturn, TKey> {
   /**
    * Selector function that derives the desired value from store state
    *
@@ -106,7 +106,7 @@ interface StateSourceOptions<TState, TParams extends unknown[], TReturn> {
    * @param params - Action parameters provided during invocation
    * @returns Optional cleanup function called when subscription ends
    */
-  onSubscribe?: (context: StoreContext<TState>, ...params: TParams) => void | (() => void)
+  onSubscribe?: (context: StoreContext<TState, TKey>, ...params: TParams) => void | (() => void)
 
   /**
    * Equality function to prevent unnecessary updates
@@ -168,9 +168,9 @@ interface StateSourceOptions<TState, TParams extends unknown[], TReturn> {
  * })
  * ```
  */
-export function createStateSourceAction<TState, TParams extends unknown[], TReturn>(
-  options: Selector<TState, TParams, TReturn> | StateSourceOptions<TState, TParams, TReturn>,
-): StoreAction<TState, TParams, StateSource<TReturn>> {
+export function createStateSourceAction<TState, TParams extends unknown[], TReturn, TKey = unknown>(
+  options: Selector<TState, TParams, TReturn> | StateSourceOptions<TState, TParams, TReturn, TKey>,
+): StoreAction<TState, TParams, StateSource<TReturn>, TKey> {
   const selector = typeof options === 'function' ? options : options.selector
   const subscribeHandler = options && 'onSubscribe' in options ? options.onSubscribe : undefined
   const isEqual = options && 'isEqual' in options ? (options.isEqual ?? Object.is) : Object.is
@@ -184,7 +184,7 @@ export function createStateSourceAction<TState, TParams extends unknown[], TRetu
    * @param context - Store context providing access to state and instance
    * @param params - Parameters provided when invoking the bound action
    */
-  function stateSourceAction(context: StoreContext<TState>, ...params: TParams) {
+  function stateSourceAction(context: StoreContext<TState, TKey>, ...params: TParams) {
     const {state, instance} = context
 
     const getCurrent = () => {

package/src/store/createStoreInstance.test.ts

@@ -24,36 +24,45 @@ describe('createStoreInstance', () => {
   }
 
   it('should create store instance with initial state', () => {
-    const store = createStoreInstance(instance, storeDef)
+    const store = createStoreInstance(instance, {name: 'store'}, storeDef)
     expect(store.state).toBeDefined()
   })
 
   it('should call getInitialState with Sanity instance', () => {
     const getInitialState = vi.fn(() => ({count: 0}))
-    createStoreInstance(instance, {...storeDef, getInitialState})
-    expect(getInitialState).toHaveBeenCalledWith(instance)
+    createStoreInstance(instance, {name: 'store'}, {...storeDef, getInitialState})
+    expect(getInitialState).toHaveBeenCalledWith(instance, {name: 'store'})
   })
 
   it('should call initialize function with context', () => {
     const initialize = vi.fn()
 
-    const store = createStoreInstance(instance, {
-      ...storeDef,
-      initialize,
-    })
+    const store = createStoreInstance(
+      instance,
+      {name: 'store'},
+      {
+        ...storeDef,
+        initialize,
+      },
+    )
     expect(initialize).toHaveBeenCalledWith({
       state: store.state,
       instance,
+      key: {name: 'store'},
     })
   })
 
   it('should handle store disposal with cleanup function', () => {
     const disposeMock = vi.fn()
 
-    const store = createStoreInstance(instance, {
-      ...storeDef,
-      initialize: () => disposeMock,
-    })
+    const store = createStoreInstance(
+      instance,
+      {name: 'store'},
+      {
+        ...storeDef,
+        initialize: () => disposeMock,
+      },
+    )
     store.dispose()
 
     expect(disposeMock).toHaveBeenCalledTimes(1)
@@ -61,7 +70,7 @@ describe('createStoreInstance', () => {
   })
 
   it('should handle disposal without initialize function', () => {
-    const store = createStoreInstance(instance, storeDef)
+    const store = createStoreInstance(instance, {name: 'store'}, storeDef)
     store.dispose()
     expect(store.isDisposed()).toBe(true)
   })
@@ -69,10 +78,14 @@ describe('createStoreInstance', () => {
   it('should prevent multiple disposals', () => {
     const disposeMock = vi.fn()
 
-    const store = createStoreInstance(instance, {
-      ...storeDef,
-      initialize: () => disposeMock,
-    })
+    const store = createStoreInstance(
+      instance,
+      {name: 'store'},
+      {
+        ...storeDef,
+        initialize: () => disposeMock,
+      },
+    )
     store.dispose()
     store.dispose()
 

package/src/store/createStoreInstance.ts

@@ -57,15 +57,16 @@ export interface StoreInstance<TState> {
  * instance.dispose()
  * ```
  */
-export function createStoreInstance<TState>(
+export function createStoreInstance<TState, TKey extends {name: string}>(
   instance: SanityInstance,
-  {name, getInitialState, initialize}: StoreDefinition<TState>,
+  key: TKey,
+  {name, getInitialState, initialize}: StoreDefinition<TState, TKey>,
 ): StoreInstance<TState> {
-  const state = createStoreState(getInitialState(instance), {
+  const state = createStoreState(getInitialState(instance, key), {
     enabled: !!getEnv('DEV'),
-    name: `${name}-${instance.config.projectId}.${instance.config.dataset}`,
+    name: `${name}-${key.name}`,
   })
-  const dispose = initialize?.({state, instance})
+  const dispose = initialize?.({state, instance, key})
   const disposed = {current: false}
 
   return {

package/src/store/defineStore.test.ts

@@ -13,6 +13,6 @@ describe('defineStore', () => {
     const result = defineStore(storeDef)
     expect(result).toBe(storeDef)
     expect(result.name).toBe('TestStore')
-    expect(result.getInitialState({} as SanityInstance)).toBe(42)
+    expect(result.getInitialState({} as SanityInstance, null)).toBe(42)
   })
 })

package/src/store/defineStore.ts

@@ -4,7 +4,7 @@ import {type StoreState} from './createStoreState'
 /**
  * Context object provided to store initialization functions
  */
-export interface StoreContext<TState> {
+export interface StoreContext<TState, TKey = unknown> {
   /**
    * Sanity instance associated with this store
    *
@@ -20,6 +20,11 @@ export interface StoreContext<TState> {
    * Contains methods for getting/setting state and observing changes
    */
   state: StoreState<TState>
+
+  /**
+   * The key used to instantiate the store.
+   */
+  key: TKey
 }
 
 /**
@@ -29,7 +34,7 @@ export interface StoreContext<TState> {
  * Stores are isolated state containers that can be associated with Sanity instances.
  * Each store definition creates a separate state instance per composite key.
  */
-export interface StoreDefinition<TState> {
+export interface StoreDefinition<TState, TKey = unknown> {
   /**
    * Unique name for the store
    *
@@ -47,7 +52,7 @@ export interface StoreDefinition<TState> {
    * Called when a new store instance is created. Can use Sanity instance
    * configuration to determine initial state.
    */
-  getInitialState: (instance: SanityInstance) => TState
+  getInitialState: (instance: SanityInstance, key: TKey) => TState
 
   /**
    * Optional initialization function
@@ -65,7 +70,7 @@ export interface StoreDefinition<TState> {
    * - Cancel pending operations
    * - Dispose external connections
    */
-  initialize?: (context: StoreContext<TState>) => (() => void) | undefined
+  initialize?: (context: StoreContext<TState, TKey>) => (() => void) | undefined
 }
 
 /**
@@ -74,8 +79,8 @@ export interface StoreDefinition<TState> {
  * @param storeDefinition - Configuration object defining the store
  * @returns The finalized store definition
  */
-export function defineStore<TState>(
-  storeDefinition: StoreDefinition<TState>,
-): StoreDefinition<TState> {
+export function defineStore<TState, TKey = unknown>(
+  storeDefinition: StoreDefinition<TState, TKey>,
+): StoreDefinition<TState, TKey> {
   return storeDefinition
 }