@sanity/sdk 0.0.0-alpha.21 → 0.0.0-alpha.23

package/src/store/createActionBinder.test.ts

@@ -0,0 +1,153 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {bindActionByDataset, bindActionGlobally, createActionBinder} from './createActionBinder'
+import {createSanityInstance} from './createSanityInstance'
+import {createStoreInstance} from './createStoreInstance'
+
+// Mock store instance creation for testing
+vi.mock('./createStoreInstance', () => ({
+  createStoreInstance: vi.fn(() => ({state: {counter: 0}, dispose: vi.fn()})),
+}))
+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 storeDefinition = {
+      name: 'TestStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    // Action that increments counter by given value
+    const action = vi.fn((context, increment: number) => {
+      context.state.counter += increment
+      return context.state.counter
+    })
+    const boundAction = binder(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    // First call creates store instance
+    const result1 = boundAction(instance, 5)
+    expect(result1).toBe(5)
+    // Second call reuses cached store
+    const result2 = boundAction(instance, 5)
+    expect(result2).toBe(10)
+
+    expect(action).toHaveBeenCalledTimes(2)
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(1)
+  })
+
+  it('should create separate store instances for different composite keys', () => {
+    const binder = createActionBinder(({projectId, dataset}) => `${projectId}.${dataset}`)
+    const storeDefinition = {
+      name: 'TestStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((context, val: number) => {
+      context.state.counter += val
+      return context.state.counter
+    })
+    const boundAction = binder(storeDefinition, action)
+    const instanceA = createSanityInstance({projectId: 'p1', dataset: 'd1'})
+    const instanceB = createSanityInstance({projectId: 'p2', dataset: 'd2'})
+
+    const resultA = boundAction(instanceA, 3)
+    const resultB = boundAction(instanceB, 4)
+
+    expect(resultA).toBe(3)
+    expect(resultB).toBe(4)
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(2)
+  })
+
+  it('should dispose the store instance when the last instance is disposed', () => {
+    const binder = createActionBinder(() => '')
+    const storeDefinition = {
+      name: 'TestStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((context) => context.state.counter)
+    const boundAction = binder(storeDefinition, action)
+    const instance1 = createSanityInstance({projectId: 'p1', dataset: 'd1'})
+    const instance2 = createSanityInstance({projectId: 'p1', dataset: 'd1'})
+
+    // Call action on both instances
+    boundAction(instance1)
+    boundAction(instance2)
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(1)
+
+    const [{value: storeInstance}] = vi.mocked(createStoreInstance).mock.results
+    expect(storeInstance).toBeDefined()
+
+    // First disposal shouldn't trigger store disposal
+    instance1.dispose()
+    expect(storeInstance.dispose).not.toHaveBeenCalled()
+
+    // Last disposal should trigger store disposal
+    instance2.dispose()
+    expect(storeInstance.dispose).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('bindActionByDataset', () => {
+  it('should work correctly when projectId and dataset are provided', () => {
+    const storeDefinition = {
+      name: 'DSStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context, value: string) => value)
+    const boundAction = bindActionByDataset(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+    const result = boundAction(instance, 'hello')
+    expect(result).toBe('hello')
+  })
+
+  it('should throw an error if projectId or dataset is missing', () => {
+    const storeDefinition = {
+      name: 'DSStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'fail')
+    const boundAction = bindActionByDataset(storeDefinition, action)
+    // Instance with missing dataset
+    const instance = createSanityInstance({projectId: 'proj1', dataset: ''})
+    expect(() => boundAction(instance)).toThrow(
+      'This API requires a project ID and dataset configured.',
+    )
+  })
+})
+
+describe('bindActionGlobally', () => {
+  it('should work correctly ignoring config in key generation', () => {
+    const storeDefinition = {
+      name: 'GlobalStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context, x: number) => x)
+    const boundAction = bindActionGlobally(storeDefinition, action)
+
+    // Create instances with different configs
+    const instance1 = createSanityInstance({projectId: 'any', dataset: 'any'})
+    const instance2 = createSanityInstance({projectId: 'different', dataset: 'config'})
+
+    // Both instances should use the same store
+    const result1 = boundAction(instance1, 42)
+    const result2 = boundAction(instance2, 99)
+
+    expect(result1).toBe(42)
+    expect(result2).toBe(99)
+
+    // Verify single store instance used
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(1)
+
+    // Verify action called with correct arguments
+    expect(action).toHaveBeenNthCalledWith(1, expect.anything(), 42)
+    expect(action).toHaveBeenNthCalledWith(2, expect.anything(), 99)
+
+    // Test disposal tracking
+    const [{value: storeInstance}] = vi.mocked(createStoreInstance).mock.results
+    instance1.dispose()
+    expect(storeInstance.dispose).not.toHaveBeenCalled()
+
+    instance2.dispose()
+    expect(storeInstance.dispose).toHaveBeenCalledTimes(1)
+  })
+})

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