@sanity/sdk 0.0.0-chore-react-18-compat.1 → 0.0.0-chore-react-18-compat.3

package/src/store/createActionBinder.ts

@@ -0,0 +1,176 @@
+import {type SanityConfig} 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'
+
+/**
+ * Defines a store action that operates on a specific state type
+ */
+export type StoreAction<TState, TParams extends unknown[], TReturn> = (
+  context: StoreContext<TState>,
+  ...params: TParams
+) => TReturn
+
+/**
+ * Represents a store action that has been bound to a specific store instance
+ */
+export type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (
+  instance: SanityInstance,
+  ...params: TParams
+) => TReturn
+
+/**
+ * Creates an action binder function that uses the provided key function
+ * to determine how store instances are shared between Sanity instances
+ *
+ * @param keyFn - Function that generates a key from a Sanity config
+ * @returns A function that binds store actions to Sanity instances
+ *
+ * @remarks
+ * Action binders determine how store instances are shared across multiple
+ * Sanity instances. The key function determines which instances share state.
+ *
+ * @example
+ * ```ts
+ * // Create a custom binder that uses a tenant ID for isolation
+ * const bindActionByTenant = createActionBinder(config => config.tenantId || 'default')
+ *
+ * // Use the custom binder with a store definition
+ * const getTenantUsers = bindActionByTenant(
+ *   userStore,
+ *   ({state}) => state.get().users
+ * )
+ * ```
+ */
+export function createActionBinder(keyFn: (config: SanityConfig) => string) {
+  const instanceRegistry = new Map<string, Set<string>>()
+  const storeRegistry = new Map<string, StoreInstance<unknown>>()
+
+  /**
+   * Binds a store action to a store definition
+   *
+   * @param storeDefinition - The store definition
+   * @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>,
+  ): BoundStoreAction<TState, TParams, TReturn> {
+    return function boundAction(instance: SanityInstance, ...params: TParams) {
+      const keySuffix = keyFn(instance.config)
+      const compositeKey = storeDefinition.name + (keySuffix ? `:${keySuffix}` : '')
+
+      // Get or create instance set for this composite key
+      let instances = instanceRegistry.get(compositeKey)
+      if (!instances) {
+        instances = new Set<string>()
+        instanceRegistry.set(compositeKey, instances)
+      }
+
+      // Register instance for disposal tracking
+      if (!instances.has(instance.instanceId)) {
+        instances.add(instance.instanceId)
+        instance.onDispose(() => {
+          instances.delete(instance.instanceId)
+
+          // Clean up when last instance is disposed
+          if (instances.size === 0) {
+            storeRegistry.get(compositeKey)?.dispose()
+            storeRegistry.delete(compositeKey)
+            instanceRegistry.delete(compositeKey)
+          }
+        })
+      }
+
+      // Get or create store instance
+      let storeInstance = storeRegistry.get(compositeKey)
+      if (!storeInstance) {
+        storeInstance = createStoreInstance(instance, storeDefinition)
+        storeRegistry.set(compositeKey, storeInstance)
+      }
+
+      // Execute action with store context
+      return action({instance, state: storeInstance.state as StoreState<TState>}, ...params)
+    }
+  }
+}
+
+/**
+ * Binds an action to a store that's scoped to a specific project and dataset
+ *
+ * @remarks
+ * This creates actions that operate on state isolated to a specific projectId and dataset.
+ * Different project/dataset combinations will have separate states.
+ *
+ * @throws Error if projectId or dataset is missing from the Sanity instance config
+ *
+ * @example
+ * ```ts
+ * // Define a store
+ * const documentStore = defineStore<DocumentState>({
+ *   name: 'Document',
+ *   getInitialState: () => ({ documents: {} }),
+ *   // ...
+ * })
+ *
+ * // Create dataset-specific actions
+ * export const fetchDocument = bindActionByDataset(
+ *   documentStore,
+ *   ({instance, state}, documentId) => {
+ *     // This state is isolated to the specific project/dataset
+ *     // ...fetch logic...
+ *   }
+ * )
+ *
+ * // Usage
+ * fetchDocument(sanityInstance, 'doc123')
+ * ```
+ */
+export const bindActionByDataset = createActionBinder(({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 global store that's shared across all Sanity instances
+ *
+ * @remarks
+ * This creates actions that operate on state shared globally across all Sanity instances.
+ * Use this for features like authentication where the state should be the same
+ * regardless of which project or dataset is being used.
+ *
+ * @example
+ * ```ts
+ * // Define a store
+ * const authStore = defineStore<AuthState>({
+ *   name: 'Auth',
+ *   getInitialState: () => ({
+ *     user: null,
+ *     isAuthenticated: false
+ *   }),
+ *   // ...
+ * })
+ *
+ * // Create global actions
+ * export const getCurrentUser = bindActionGlobally(
+ *   authStore,
+ *   ({state}) => state.get().user
+ * )
+ *
+ * export const login = bindActionGlobally(
+ *   authStore,
+ *   ({state, instance}, credentials) => {
+ *     // Login logic that affects global state
+ *     // ...
+ *   }
+ * )
+ *
+ * // Usage with any instance
+ * getCurrentUser(sanityInstance)
+ * ```
+ */
+export const bindActionGlobally = createActionBinder(() => 'global')

package/src/store/createSanityInstance.test.ts

@@ -0,0 +1,84 @@
+import {describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance} from './createSanityInstance'
+
+describe('createSanityInstance', () => {
+  it('should create an instance with a unique instanceId and given config', () => {
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    expect(typeof instance.instanceId).toBe('string')
+    expect(instance.config).toEqual({projectId: 'proj1', dataset: 'ds1'})
+    expect(instance.isDisposed()).toBe(false)
+  })
+
+  it('should dispose an instance and call onDispose callbacks', () => {
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    const callback = vi.fn()
+    instance.onDispose(callback)
+    instance.dispose()
+    expect(instance.isDisposed()).toBe(true)
+    expect(callback).toHaveBeenCalled()
+  })
+
+  it('should not call onDispose callbacks more than once when disposed multiple times', () => {
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    const callback = vi.fn()
+    instance.onDispose(callback)
+    instance.dispose()
+    instance.dispose()
+    expect(callback).toHaveBeenCalledTimes(1)
+  })
+
+  it('should create a child instance with merged config and correct parent', () => {
+    const parent = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    const child = parent.createChild({dataset: 'ds2'})
+    expect(child.config).toEqual({projectId: 'proj1', dataset: 'ds2'})
+    expect(child.getParent()).toBe(parent)
+  })
+
+  it('should match an instance in the hierarchy using match', () => {
+    // three-level hierarchy
+    const grandparent = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    const parent = grandparent.createChild({projectId: 'proj2'})
+    const child = parent.createChild({dataset: 'ds2'})
+
+    expect(child.config).toEqual({projectId: 'proj2', dataset: 'ds2'})
+    expect(parent.config).toEqual({projectId: 'proj2', dataset: 'ds1'})
+
+    expect(child.match({dataset: 'ds2'})).toBe(child)
+    expect(child.match({projectId: 'proj2'})).toBe(child)
+    expect(child.match({projectId: 'proj1'})).toBe(grandparent)
+    expect(parent.match({projectId: 'proj1'})).toBe(grandparent)
+    expect(grandparent.match({projectId: 'proj1'})).toBe(grandparent)
+  })
+
+  it('should match `undefined` when the desired resource ID should not be set on an instance', () => {
+    const noProjectOrDataset = createSanityInstance()
+    const noDataset = noProjectOrDataset.createChild({projectId: 'proj1'})
+    const leaf = noDataset.createChild({dataset: 'ds1'})
+
+    // no keys means anything (in this case, self) will match
+    expect(leaf.match({})).toBe(leaf)
+
+    // `[resourceId]: undefined` means match an instance with no dataset set
+    expect(leaf.match({dataset: undefined})).toBe(noDataset)
+    expect(noDataset.match({dataset: undefined})).toBe(noDataset)
+    expect(leaf.match({projectId: undefined})).toBe(noProjectOrDataset)
+    expect(noDataset.match({projectId: undefined})).toBe(noProjectOrDataset)
+    expect(noProjectOrDataset.match({projectId: undefined})).toBe(noProjectOrDataset)
+  })
+
+  it('should return undefined when no match is found', () => {
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    expect(instance.match({dataset: 'non-existent'})).toBeUndefined()
+  })
+
+  it('should inherit and merge auth config', () => {
+    const parent = createSanityInstance({
+      projectId: 'proj1',
+      dataset: 'ds1',
+      auth: {apiHost: 'api.sanity.work'},
+    })
+    const child = parent.createChild({auth: {token: 'my-token'}})
+    expect(child.config.auth).toEqual({apiHost: 'api.sanity.work', token: 'my-token'})
+  })
+})

package/src/store/createSanityInstance.ts

@@ -0,0 +1,124 @@
+import {pick} from 'lodash-es'
+
+import {type SanityConfig} from '../config/sanityConfig'
+import {insecureRandomId} from '../utils/ids'
+
+/**
+ * Represents a Sanity.io resource instance with its own configuration and lifecycle
+ * @remarks Instances form a hierarchy through parent/child relationships
+ *
+ * @public
+ */
+export interface SanityInstance {
+  /**
+   * Unique identifier for this instance
+   * @remarks Generated using crypto.randomUUID()
+   */
+  readonly instanceId: string
+
+  /**
+   * Resolved configuration for this instance
+   * @remarks Merges values from parent instances where appropriate
+   */
+  readonly config: SanityConfig
+
+  /**
+   * Checks if the instance has been disposed
+   * @returns true if dispose() has been called
+   */
+  isDisposed(): boolean
+
+  /**
+   * Disposes the instance and cleans up associated resources
+   * @remarks Triggers all registered onDispose callbacks
+   */
+  dispose(): void
+
+  /**
+   * Registers a callback to be invoked when the instance is disposed
+   * @param cb - Callback to execute on disposal
+   * @returns Function to unsubscribe the callback
+   */
+  onDispose(cb: () => void): () => void
+
+  /**
+   * Gets the parent instance in the hierarchy
+   * @returns Parent instance or undefined if this is the root
+   */
+  getParent(): SanityInstance | undefined
+
+  /**
+   * Creates a child instance with merged configuration
+   * @param config - Configuration to merge with parent values
+   * @remarks Child instances inherit parent configuration but can override values
+   */
+  createChild(config: SanityConfig): SanityInstance
+
+  /**
+   * Traverses the instance hierarchy to find the first instance whose configuration
+   * matches the given target config using a shallow comparison.
+   * @param targetConfig - A partial configuration object containing key-value pairs to match.
+   * @returns The first matching instance or undefined if no match is found.
+   */
+  match(targetConfig: Partial<SanityConfig>): SanityInstance | undefined
+}
+
+/**
+ * Creates a new Sanity resource instance
+ * @param config - Configuration for the instance (optional)
+ * @returns A configured SanityInstance
+ * @remarks When creating child instances, configurations are merged with parent values
+ *
+ * @public
+ */
+export function createSanityInstance(config: SanityConfig = {}): SanityInstance {
+  const instanceId = crypto.randomUUID()
+  const disposeListeners = new Map<string, () => void>()
+  const disposed = {current: false}
+
+  const instance: SanityInstance = {
+    instanceId,
+    config,
+    isDisposed: () => disposed.current,
+    dispose: () => {
+      if (disposed.current) return
+      disposed.current = true
+      disposeListeners.forEach((listener) => listener())
+      disposeListeners.clear()
+    },
+    onDispose: (cb) => {
+      const listenerId = insecureRandomId()
+      disposeListeners.set(listenerId, cb)
+      return () => {
+        disposeListeners.delete(listenerId)
+      }
+    },
+    getParent: () => undefined,
+    createChild: (next) =>
+      Object.assign(
+        createSanityInstance({
+          ...config,
+          ...next,
+          ...(config.auth === next.auth
+            ? config.auth
+            : config.auth && next.auth && {auth: {...config.auth, ...next.auth}}),
+        }),
+        {getParent: () => instance},
+      ),
+    match: (targetConfig) => {
+      if (
+        Object.entries(pick(targetConfig, 'auth', 'projectId', 'dataset')).every(
+          ([key, value]) => config[key as keyof SanityConfig] === value,
+        )
+      ) {
+        return instance
+      }
+
+      const parent = instance.getParent()
+      if (parent) return parent.match(targetConfig)
+      return undefined
+    },
+  }
+
+  return instance
+}

package/src/store/createStateSourceAction.test.ts

@@ -0,0 +1,196 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance, type SanityInstance} from './createSanityInstance'
+import {createStateSourceAction, type SelectorContext} from './createStateSourceAction'
+import {createStoreState, type StoreState} from './createStoreState'
+
+interface CountStoreState {
+  count: number
+  items: string[]
+}
+
+describe('createStateSourceAction', () => {
+  let state: StoreState<CountStoreState>
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+    state = createStoreState({count: 0, items: [] as string[]}, {name: 'test-store'})
+  })
+
+  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})
+
+    expect(source.getCurrent()).toBe(0)
+    state.set('test', {count: 5})
+    expect(source.getCurrent()).toBe(5)
+  })
+
+  it('should call onStoreChanged when state changes', () => {
+    const onStoreChanged = vi.fn()
+    const source = createStateSourceAction({
+      selector: ({state: s}: SelectorContext<CountStoreState>) => s.count,
+      isEqual: (a, b) => a === b,
+    })({state, instance})
+
+    const unsubscribe = source.subscribe(onStoreChanged)
+
+    state.set('inc', (s) => ({count: s.count + 1}))
+    expect(onStoreChanged).toHaveBeenCalledTimes(1)
+
+    state.set('noop', (s) => s)
+    expect(onStoreChanged).toHaveBeenCalledTimes(1) // No change
+
+    unsubscribe()
+    state.set('inc2', (s) => ({count: s.count + 1}))
+    expect(onStoreChanged).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call onSubscribe handler when subscription starts', () => {
+    const onSubscribe = vi.fn(() => () => {})
+    const source = createStateSourceAction({
+      selector: ({state: s}: SelectorContext<CountStoreState>) => s.items,
+      onSubscribe,
+    })({state, instance})
+
+    const unsubscribe = source.subscribe()
+    expect(onSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({state, instance}),
+      // No params in this case
+    )
+
+    unsubscribe()
+  })
+
+  it('should support parameterized selectors', () => {
+    const action = createStateSourceAction({
+      selector: ({state: s}: SelectorContext<CountStoreState>, index: number) => s.items[index],
+    })
+    const source = action({state, instance}, 0)
+
+    state.set('add', {items: ['first']})
+    expect(source.getCurrent()).toBe('first')
+  })
+
+  it('should handle selector errors in observable', () => {
+    const error = new Error('Selector failed')
+    const source = createStateSourceAction({
+      selector: () => {
+        throw error
+      },
+    })({state, instance})
+
+    const errorHandler = vi.fn()
+    source.observable.subscribe({error: errorHandler})
+
+    state.set('trigger', {count: 1})
+    expect(errorHandler).toHaveBeenCalledWith(error)
+  })
+
+  it('should use custom equality check', () => {
+    const isEqual = vi.fn((a: number[], b: number[]) => a.length === b.length)
+    const source = createStateSourceAction({
+      selector: ({state: s}: SelectorContext<CountStoreState>) => s.items.map((i) => i.length),
+      isEqual,
+    })({state, instance})
+
+    const onChange = vi.fn()
+    source.subscribe(onChange)
+
+    // Same length, different contents
+    state.set('add1', {items: ['a']})
+    state.set('add2', {items: ['b']})
+
+    expect(isEqual).toHaveBeenCalledTimes(2)
+    expect(onChange).toHaveBeenCalledTimes(1) // Only first change
+  })
+
+  it('should cleanup onSubscribe when unsubscribed', () => {
+    const cleanup = vi.fn()
+    const source = createStateSourceAction({
+      selector: ({state: s}: SelectorContext<CountStoreState>) => s.count,
+      onSubscribe: () => cleanup,
+    })({state, instance})
+
+    const unsubscribe = source.subscribe()
+    unsubscribe()
+    expect(cleanup).toHaveBeenCalledTimes(1)
+  })
+
+  it('should share observable between subscribers', () => {
+    const source = createStateSourceAction(
+      ({state: s}: SelectorContext<CountStoreState>) => s.count,
+    )({
+      state,
+      instance,
+    })
+
+    const subscriber1 = vi.fn()
+    const subscriber2 = vi.fn()
+
+    const subscription1 = source.observable.subscribe(subscriber1)
+    const subscription2 = source.observable.subscribe(subscriber2)
+
+    state.set('inc', {count: 1})
+
+    expect(subscriber1).toHaveBeenCalledWith(1)
+    expect(subscriber2).toHaveBeenCalledWith(1)
+
+    subscription1.unsubscribe()
+    subscription2.unsubscribe()
+  })
+
+  it('should cache selector context per state object', () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction(selector)({state, instance})
+
+    // Initial call creates context
+    expect(source.getCurrent()).toBe(0)
+    expect(selector).toHaveBeenCalledTimes(1)
+    const firstContext = selector.mock.calls[0][0]
+
+    // Subsequent call with same state reuses context
+    expect(source.getCurrent()).toBe(0)
+    expect(selector).toHaveBeenCalledTimes(2)
+    expect(selector.mock.calls[1][0]).toBe(firstContext)
+
+    // After state change, new context is created
+    state.set('update1', {count: 1})
+    expect(source.getCurrent()).toBe(1)
+    expect(selector).toHaveBeenCalledTimes(3)
+    const secondContext = selector.mock.calls[2][0]
+    expect(secondContext).not.toBe(firstContext)
+
+    // Another call with same state reuses new context
+    expect(source.getCurrent()).toBe(1)
+    expect(selector).toHaveBeenCalledTimes(4)
+    expect(selector.mock.calls[3][0]).toBe(secondContext)
+
+    // State change again, new context
+    state.set('update2', {count: 2})
+    expect(source.getCurrent()).toBe(2)
+    expect(selector).toHaveBeenCalledTimes(5)
+    const thirdContext = selector.mock.calls[4][0]
+    expect(thirdContext).not.toBe(secondContext)
+  })
+
+  // New test: distinct contexts for same state with different instance
+  it('should create distinct contexts for same state with different instance', () => {
+    const secondInstance = createSanityInstance({projectId: 'test2', dataset: 'test2'})
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+
+    const source1 = createStateSourceAction(selector)({state, instance})
+    source1.getCurrent()
+
+    const source2 = createStateSourceAction(selector)({state, instance: secondInstance})
+    source2.getCurrent()
+
+    const context1 = selector.mock.calls[0][0]
+    const context2 = selector.mock.calls[1][0]
+    expect(context1).not.toBe(context2)
+    expect(context1.instance).toBe(instance)
+    expect(context2.instance).toBe(secondInstance)
+  })
+})