@sanity/sdk 2.4.0 → 2.6.0

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,25 @@
-import {type DocumentSource, type SanityConfig, SOURCE_ID} from '../config/sanityConfig'
+import {
+  type DocumentSource,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+} 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,9 +54,10 @@ export type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (
  * )
  * ```
  */
-export function createActionBinder<TKeyParams extends unknown[]>(
-  keyFn: (config: SanityConfig, ...params: TKeyParams) => 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>>()
 
@@ -57,12 +69,12 @@ export function createActionBinder<TKeyParams extends unknown[]>(
    * @returns A function that executes the action with a Sanity instance
    */
   return function bindAction<TState, TParams extends TKeyParams, TReturn>(
-    storeDefinition: StoreDefinition<TState>,
-    action: StoreAction<TState, TParams, 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, ...params)
-      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)
@@ -89,12 +101,12 @@ export function createActionBinder<TKeyParams extends unknown[]>(
       // 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)
     }
   }
 }
@@ -130,31 +142,45 @@ export function createActionBinder<TKeyParams extends unknown[]>(
  * fetchDocument(sanityInstance, 'doc123')
  * ```
  */
-export const bindActionByDataset = createActionBinder<unknown[]>(({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 `${projectId}.${dataset}`
+  return {name: `${projectId}.${dataset}`, 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}`
+export const bindActionBySource = createActionBinder<
+  {name: string},
+  [{source?: DocumentSource}, ...unknown[]]
+>((instance, {source}) => {
+  if (source) {
+    let id: string | undefined
+    if (isDatasetSource(source)) {
+      id = `${source.projectId}.${source.dataset}`
+    } else if (isMediaLibrarySource(source)) {
+      id = `media-library:${source.mediaLibraryId}`
+    } else if (isCanvasSource(source)) {
+      id = `canvas:${source.canvasId}`
     }
 
-    if (!projectId || !dataset) {
-      throw new Error('This API requires a project ID and dataset configured.')
-    }
-    return `${projectId}.${dataset}`
-  },
-)
+    if (!id) throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
+    return {name: id}
+  }
+  const {projectId, dataset} = instance.config
+
+  if (!projectId || !dataset) {
+    throw new Error('This API requires a project ID and dataset configured.')
+  }
+  return {name: `${projectId}.${dataset}`}
+})
 
 /**
  * Binds an action to a global store that's shared across all Sanity instances
@@ -194,4 +220,4 @@ export const bindActionBySource = createActionBinder<[{source?: DocumentSource},
  * getCurrentUser(sanityInstance)
  * ```
  */
-export const bindActionGlobally = createActionBinder<unknown[]>(() => 'global')
+export const bindActionGlobally = createActionBinder((..._rest) => ({name: 'global'}))

package/src/store/createSanityInstance.test.ts

@@ -1,5 +1,6 @@
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {configureLogging, type LogHandler, resetLogging} from '../utils/logger'
 import {createSanityInstance} from './createSanityInstance'
 
 describe('createSanityInstance', () => {
@@ -81,4 +82,87 @@ describe('createSanityInstance', () => {
     const child = parent.createChild({auth: {token: 'my-token'}})
     expect(child.config.auth).toEqual({apiHost: 'api.sanity.work', token: 'my-token'})
   })
+
+  describe('logging', () => {
+    const mockHandler: LogHandler = {
+      error: vi.fn(),
+      warn: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+      trace: vi.fn(),
+    }
+
+    beforeEach(() => {
+      vi.clearAllMocks()
+      configureLogging({
+        level: 'debug',
+        namespaces: ['sdk'],
+        handler: mockHandler,
+      })
+    })
+
+    afterEach(() => {
+      resetLogging()
+    })
+
+    it('should log instance creation at info level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('[INFO] [sdk]'),
+        expect.objectContaining({
+          hasProjectId: true,
+          hasDataset: true,
+        }),
+      )
+    })
+
+    it('should log configuration details at debug level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.debug).toHaveBeenCalledWith(
+        expect.stringContaining('[DEBUG] [sdk]'),
+        expect.objectContaining({
+          projectId: 'test-proj',
+          dataset: 'test-ds',
+        }),
+      )
+    })
+
+    it('should log instance disposal', () => {
+      const instance = createSanityInstance({projectId: 'test-proj'})
+      vi.clearAllMocks() // Clear creation logs
+
+      instance.dispose()
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('Instance disposed'),
+        expect.anything(),
+      )
+    })
+
+    it('should log child instance creation at debug level', () => {
+      const parent = createSanityInstance({projectId: 'parent-proj'})
+      vi.clearAllMocks() // Clear parent creation logs
+
+      parent.createChild({dataset: 'child-ds'})
+
+      expect(mockHandler.debug).toHaveBeenCalledWith(
+        expect.stringContaining('Creating child instance'),
+        expect.objectContaining({
+          overridingDataset: true,
+        }),
+      )
+    })
+
+    it('should include instance context in logs', () => {
+      createSanityInstance({projectId: 'my-project', dataset: 'my-dataset'})
+
+      // Check that logs include the instance context (project and dataset)
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringMatching(/\[project:my-project\].*\[dataset:my-dataset\]/),
+        expect.anything(),
+      )
+    })
+  })
 })

package/src/store/createSanityInstance.ts

@@ -2,6 +2,7 @@ import {pick} from 'lodash-es'
 
 import {type SanityConfig} from '../config/sanityConfig'
 import {insecureRandomId} from '../utils/ids'
+import {createLogger, type InstanceContext} from '../utils/logger'
 
 /**
  * Represents a Sanity.io resource instance with its own configuration and lifecycle
@@ -76,15 +77,51 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
   const disposeListeners = new Map<string, () => void>()
   const disposed = {current: false}
 
+  // Create instance context for logging
+  const instanceContext: InstanceContext = {
+    instanceId,
+    projectId: config.projectId,
+    dataset: config.dataset,
+  }
+
+  // Create logger with instance context
+  const logger = createLogger('sdk', {instanceContext})
+
+  // Log instance creation
+  logger.info('Sanity instance created', {
+    hasProjectId: !!config.projectId,
+    hasDataset: !!config.dataset,
+    hasAuth: !!config.auth,
+    hasPerspective: !!config.perspective,
+  })
+
+  // Log configuration details at debug level
+  logger.debug('Instance configuration', {
+    projectId: config.projectId,
+    dataset: config.dataset,
+    perspective: config.perspective,
+    studioMode: config.studioMode?.enabled,
+    hasAuthProviders: !!config.auth?.providers,
+    hasAuthToken: !!config.auth?.token,
+  })
+
   const instance: SanityInstance = {
     instanceId,
     config,
     isDisposed: () => disposed.current,
     dispose: () => {
-      if (disposed.current) return
+      if (disposed.current) {
+        logger.trace('Dispose called on already disposed instance', {internal: true})
+        return
+      }
+      logger.trace('Disposing instance', {
+        internal: true,
+        listenerCount: disposeListeners.size,
+      })
       disposed.current = true
       disposeListeners.forEach((listener) => listener())
       disposeListeners.clear()
+      logger.info('Instance disposed')
     },
     onDispose: (cb) => {
       const listenerId = insecureRandomId()
@@ -94,8 +131,14 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
       }
     },
     getParent: () => undefined,
-    createChild: (next) =>
-      Object.assign(
+    createChild: (next) => {
+      logger.debug('Creating child instance', {
+        parentInstanceId: instanceId.slice(0, 8),
+        overridingProjectId: !!next.projectId,
+        overridingDataset: !!next.dataset,
+        overridingAuth: !!next.auth,
+      })
+      const child = Object.assign(
         createSanityInstance({
           ...config,
           ...next,
@@ -104,7 +147,13 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
             : config.auth && next.auth && {auth: {...config.auth, ...next.auth}}),
         }),
         {getParent: () => instance},
-      ),
+      )
+      logger.trace('Child instance created', {
+        internal: true,
+        childInstanceId: child.instanceId.slice(0, 8),
+      })
+      return child
+    },
     match: (targetConfig) => {
       if (
         Object.entries(pick(targetConfig, 'auth', 'projectId', 'dataset')).every(

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)
   })
 })