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

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

package/src/store/createStateSourceAction.ts

@@ -0,0 +1,260 @@
+import {distinctUntilChanged, map, Observable, share, skip} from 'rxjs'
+
+import {type StoreAction} from './createActionBinder'
+import {type SanityInstance} from './createSanityInstance'
+import {type StoreContext} from './defineStore'
+
+/**
+ * Represents a reactive state source that provides synchronized access to store data
+ *
+ * @remarks
+ * Designed to work with React's useSyncExternalStore hook. Provides three ways to access data:
+ * 1. `getCurrent()` for synchronous current value access
+ * 2. `subscribe()` for imperative change notifications
+ * 3. `observable` for reactive stream access
+ *
+ * @public
+ */
+export interface StateSource<T> {
+  /**
+   * Subscribes to state changes with optional callback
+   * @param onStoreChanged - Called whenever relevant state changes occur
+   * @returns Unsubscribe function to clean up the subscription
+   */
+  subscribe: (onStoreChanged?: () => void) => () => void
+
+  /**
+   * Gets the current derived state value
+   *
+   * @remarks
+   * Safe to call without subscription. Will always return the latest value
+   * based on the current store state and selector parameters.
+   */
+  getCurrent: () => T
+
+  /**
+   * Observable stream of state values
+   *
+   * @remarks
+   * Shares a single underlying subscription between all observers. Emits:
+   * - Immediately with current value on subscription
+   * - On every relevant state change
+   * - Errors if selector throws
+   */
+  observable: Observable<T>
+}
+
+/**
+ * Context passed to selectors when deriving state
+ *
+ * @remarks
+ * Provides access to both the current state value and the Sanity instance,
+ * allowing selectors to use configuration values when computing derived state.
+ * The context is memoized for each state object and instance combination
+ * to optimize performance and prevent unnecessary recalculations.
+ *
+ * @example
+ * ```ts
+ * // Using both state and instance in a selector (psuedo example)
+ * const getUserByProjectId = createStateSourceAction(
+ *   ({ state, instance }: SelectorContext<UsersState>, options?: ProjectHandle) => {
+ *     const allUsers = state.users
+ *     const projectId = options?.projectId ?? instance.config.projectId
+ *     return allUsers.filter(user => user.projectId === projectId)
+ *   }
+ * )
+ * ```
+ */
+export interface SelectorContext<TState> {
+  /**
+   * The current state object from the store
+   */
+  state: TState
+
+  /**
+   * The Sanity instance associated with this state
+   */
+  instance: SanityInstance
+}
+
+/**
+ * Function type for selecting derived state from store state and parameters
+ * @public
+ */
+export type Selector<TState, TParams extends unknown[], TReturn> = (
+  context: SelectorContext<TState>,
+  ...params: TParams
+) => TReturn
+
+/**
+ * Configuration options for creating a state source action
+ */
+interface StateSourceOptions<TState, TParams extends unknown[], TReturn> {
+  /**
+   * Selector function that derives the desired value from store state
+   *
+   * @remarks
+   * Will be called on every store change. Should be pure function.
+   * Thrown errors will propagate to observable subscribers.
+   */
+  selector: Selector<TState, TParams, TReturn>
+
+  /**
+   * Optional setup/cleanup handler for subscriptions
+   *
+   * @param context - Store context containing state and instance
+   * @param params - Action parameters provided during invocation
+   * @returns Optional cleanup function called when subscription ends
+   */
+  onSubscribe?: (context: StoreContext<TState>, ...params: TParams) => void | (() => void)
+
+  /**
+   * Equality function to prevent unnecessary updates
+   */
+  isEqual?: (prev: TReturn, curr: TReturn) => boolean
+}
+
+/**
+ * Creates a state source action that generates StateSource instances
+ *
+ * @remarks
+ * The returned action can be bound to a store using createActionBinder.
+ * When invoked, returns a StateSource that stays synchronized with the store.
+ *
+ * Key performance features:
+ * - Memoizes selector contexts to prevent redundant object creation
+ * - Only runs selectors when the underlying state changes
+ *
+ * For complex data transformations, consider using memoized selectors
+ * (like those from Reselect) to prevent expensive recalculations.
+ *
+ * @example
+ * ```ts
+ * // Create a simple counter source
+ * const getCount = createStateSourceAction(({state}: SelectorContext<CounterState>) => state.count)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create a parameterized source with setup/cleanup
+ * const getItem = createStateSourceAction({
+ *   selector: ({state}, index: number) => state.items[index],
+ *   onSubscribe: (context, index) => {
+ *     trackItemSubscription(index)
+ *     return () => untrackItem(index)
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Binding a state source to a specific store
+ * const documentStore = defineStore<DocumentState>({
+ *   name: 'Documents',
+ *   getInitialState: () => ({ documents: {} }),
+ *   // ...
+ * })
+ *
+ * const getDocument = bindActionByDataset(
+ *   documentStore,
+ *   createStateSourceAction(({state}, documentId: string) => state.documents[documentId])
+ * )
+ *
+ * // Usage
+ * const documentSource = getDocument(sanityInstance, 'doc123')
+ * const doc = documentSource.getCurrent()
+ * const subscription = documentSource.observable.subscribe(updatedDoc => {
+ *   console.log('Document changed:', updatedDoc)
+ * })
+ * ```
+ */
+export function createStateSourceAction<TState, TParams extends unknown[], TReturn>(
+  options: Selector<TState, TParams, TReturn> | StateSourceOptions<TState, TParams, TReturn>,
+): StoreAction<TState, TParams, StateSource<TReturn>> {
+  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
+  const selectorContextCache = new WeakMap<
+    object,
+    WeakMap<SanityInstance, SelectorContext<TState>>
+  >()
+
+  /**
+   * The state source action implementation
+   * @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) {
+    const {state, instance} = context
+
+    const getCurrent = () => {
+      const currentState = state.get()
+      if (typeof currentState !== 'object' || currentState === null) {
+        throw new Error(
+          `Expected store state to be an object but got "${typeof currentState}" instead`,
+        )
+      }
+
+      let instanceCache = selectorContextCache.get(currentState)
+      if (!instanceCache) {
+        instanceCache = new WeakMap<SanityInstance, SelectorContext<TState>>()
+        selectorContextCache.set(currentState, instanceCache)
+      }
+      let selectorContext = instanceCache.get(instance)
+      if (!selectorContext) {
+        selectorContext = {state: currentState, instance}
+        instanceCache.set(instance, selectorContext)
+      }
+      return selector(selectorContext, ...params)
+    }
+
+    // Subscription manager handles both RxJS and direct subscriptions
+    const subscribe = (onStoreChanged?: () => void) => {
+      // Run setup handler if provided
+      const cleanup = subscribeHandler?.(context, ...params)
+
+      // Set up state change subscription
+      const subscription = state.observable
+        .pipe(
+          // Derive value from current state
+          map(getCurrent),
+          // Filter unchanged values using custom equality check
+          distinctUntilChanged(isEqual),
+          // Skip initial emission since we only want changes
+          skip(1),
+        )
+        .subscribe({
+          next: () => onStoreChanged?.(),
+          // Propagate selector errors to both subscription types
+          error: () => onStoreChanged?.(),
+        })
+
+      return () => {
+        subscription.unsubscribe()
+        cleanup?.()
+      }
+    }
+
+    // Create shared observable that handles multiple subscribers efficiently
+    const observable = new Observable<TReturn>((observer) => {
+      const emitCurrent = () => {
+        try {
+          observer.next(getCurrent())
+        } catch (error) {
+          observer.error(error)
+        }
+      }
+      // Emit immediately on subscription
+      emitCurrent()
+      return subscribe(emitCurrent)
+    }).pipe(share())
+
+    return {
+      getCurrent,
+      subscribe,
+      observable,
+    }
+  }
+
+  return stateSourceAction
+}

package/src/store/createStoreInstance.test.ts

@@ -0,0 +1,81 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance} from './createSanityInstance'
+import {createStoreInstance} from './createStoreInstance'
+import {type StoreDefinition} from './defineStore'
+
+describe('createStoreInstance', () => {
+  let instance: ReturnType<typeof createSanityInstance>
+
+  beforeEach(() => {
+    // Mock crypto for predictable instance IDs
+    vi.stubGlobal('crypto', {
+      randomUUID: () => 'test-uuid-1234',
+    })
+
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+  })
+
+  const storeDef: StoreDefinition<{count: number}> = {
+    name: 'TestStore',
+    getInitialState: (inst) => ({
+      count: inst.config.projectId === 'test' ? 0 : -1,
+    }),
+  }
+
+  it('should create store instance with initial state', () => {
+    const store = createStoreInstance(instance, 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)
+  })
+
+  it('should call initialize function with context', () => {
+    const initialize = vi.fn()
+
+    const store = createStoreInstance(instance, {
+      ...storeDef,
+      initialize,
+    })
+    expect(initialize).toHaveBeenCalledWith({
+      state: store.state,
+      instance,
+    })
+  })
+
+  it('should handle store disposal with cleanup function', () => {
+    const disposeMock = vi.fn()
+
+    const store = createStoreInstance(instance, {
+      ...storeDef,
+      initialize: () => disposeMock,
+    })
+    store.dispose()
+
+    expect(disposeMock).toHaveBeenCalledTimes(1)
+    expect(store.isDisposed()).toBe(true)
+  })
+
+  it('should handle disposal without initialize function', () => {
+    const store = createStoreInstance(instance, storeDef)
+    store.dispose()
+    expect(store.isDisposed()).toBe(true)
+  })
+
+  it('should prevent multiple disposals', () => {
+    const disposeMock = vi.fn()
+
+    const store = createStoreInstance(instance, {
+      ...storeDef,
+      initialize: () => disposeMock,
+    })
+    store.dispose()
+    store.dispose()
+
+    expect(disposeMock).toHaveBeenCalledTimes(1)
+  })
+})

package/src/store/createStoreInstance.ts

@@ -0,0 +1,80 @@
+import {getEnv} from '../utils/getEnv'
+import {type SanityInstance} from './createSanityInstance'
+import {createStoreState, type StoreState} from './createStoreState'
+import {type StoreDefinition} from './defineStore'
+
+/**
+ * Represents a running instance of a store with its own state and lifecycle
+ *
+ * @remarks
+ * Each StoreInstance is tied to a specific SanityInstance, manages its own state,
+ * and can be independently disposed when no longer needed.
+ */
+export interface StoreInstance<TState> {
+  /**
+   * Access to the reactive state container for this store instance
+   */
+  state: StoreState<TState>
+
+  /**
+   * Checks if this store instance has been disposed
+   * @returns Boolean indicating disposed state
+   */
+  isDisposed: () => void
+
+  /**
+   * Cleans up this store instance and runs any initialization cleanup functions
+   * @remarks Triggers the cleanup function returned from the initialize method
+   */
+  dispose: () => void
+}
+
+/**
+ * Creates a new instance of a store from a store definition
+ *
+ * @param instance - The Sanity instance this store will be associated with
+ * @param storeDefinition - The store definition containing initial state and initialization logic
+ * @returns A store instance with state management and lifecycle methods
+ *
+ * @remarks
+ * The store instance maintains its own state that is scoped to the given Sanity instance.
+ * If the store definition includes an initialize function, it will be called during
+ * instance creation, and its cleanup function will be called during disposal.
+ *
+ * @example
+ * ```ts
+ * const counterStore = defineStore({
+ *   name: 'Counter',
+ *   getInitialState: () => ({ count: 0 }),
+ *   initialize: ({state}) => {
+ *     console.log('Counter store initialized')
+ *     return () => console.log('Counter store disposed')
+ *   }
+ * })
+ *
+ * const instance = createStoreInstance(sanityInstance, counterStore)
+ * // Later when done with the store:
+ * instance.dispose()
+ * ```
+ */
+export function createStoreInstance<TState>(
+  instance: SanityInstance,
+  {name, getInitialState, initialize}: StoreDefinition<TState>,
+): StoreInstance<TState> {
+  const state = createStoreState(getInitialState(instance), {
+    enabled: !!getEnv('DEV'),
+    name: `${name}-${instance.config.projectId}.${instance.config.dataset}`,
+  })
+  const dispose = initialize?.({state, instance})
+  const disposed = {current: false}
+
+  return {
+    state,
+    dispose: () => {
+      if (disposed.current) return
+      disposed.current = true
+      dispose?.()
+    },
+    isDisposed: () => disposed.current,
+  }
+}

package/src/store/createStoreState.test.ts

@@ -0,0 +1,85 @@
+import {firstValueFrom} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {createStoreState} from './createStoreState'
+
+describe('createStoreState', () => {
+  it('should initialize with correct state', () => {
+    const store = createStoreState({count: 0, items: []})
+    expect(store.get()).toEqual({count: 0, items: []})
+  })
+
+  it('should update state with set()', () => {
+    const store = createStoreState({count: 0})
+    store.set('increment', {count: 1})
+    expect(store.get()).toEqual({count: 1})
+  })
+
+  it('should not update state if new value is identical', () => {
+    const store = createStoreState({count: 0})
+    const originalState = store.get()
+    store.set('noop', originalState)
+    expect(store.get()).toBe(originalState) // Reference equality check
+  })
+
+  it('should support functional updates', () => {
+    const store = createStoreState({count: 0})
+    store.set('increment', (prev) => ({count: prev.count + 1}))
+    expect(store.get()).toEqual({count: 1})
+  })
+
+  it('should emit initial state through observable', async () => {
+    const store = createStoreState({count: 42})
+    const value = await firstValueFrom(store.observable)
+    expect(value).toEqual({count: 42})
+  })
+
+  it('should emit state changes through observable', async () => {
+    const store = createStoreState({count: 0})
+    const emissions: number[] = []
+
+    const sub = store.observable.subscribe((state) => {
+      emissions.push(state.count)
+    })
+
+    store.set('inc1', {count: 1})
+    store.set('inc2', {count: 2})
+    sub.unsubscribe()
+
+    expect(emissions).toEqual([0, 1, 2])
+  })
+
+  it('should share observable between subscribers', () => {
+    const store = createStoreState({count: 0})
+    const sub1 = vi.fn()
+    const sub2 = vi.fn()
+
+    const subscription1 = store.observable.subscribe(sub1)
+    const subscription2 = store.observable.subscribe(sub2)
+
+    store.set('inc', {count: 1})
+
+    expect(sub1).toHaveBeenCalledWith({count: 1})
+    expect(sub2).toHaveBeenCalledWith({count: 1})
+
+    subscription1.unsubscribe()
+    subscription2.unsubscribe()
+  })
+
+  it('should handle multiple subscribers independently', () => {
+    const store = createStoreState({count: 0})
+    const sub1 = vi.fn()
+    const sub2 = vi.fn()
+
+    const subscription1 = store.observable.subscribe(sub1)
+    store.set('inc1', {count: 1})
+    const subscription2 = store.observable.subscribe(sub2)
+    store.set('inc2', {count: 2})
+
+    expect(sub1.mock.calls).toEqual([[{count: 0}], [{count: 1}], [{count: 2}]])
+    expect(sub2.mock.calls).toEqual([[{count: 1}], [{count: 2}]])
+
+    subscription1.unsubscribe()
+    subscription2.unsubscribe()
+  })
+})