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

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

package/src/store/createStoreState.ts

@@ -0,0 +1,92 @@
+import {Observable} from 'rxjs'
+import {devtools, type DevtoolsOptions} from 'zustand/middleware'
+import {createStore} from 'zustand/vanilla'
+
+/**
+ * Represents a reactive store state container with multiple access patterns
+ */
+export interface StoreState<TState> {
+  /**
+   * Gets the current state value
+   *
+   * @remarks
+   * This is a direct synchronous accessor that doesn't trigger subscriptions
+   */
+  get: () => TState
+
+  /**
+   * Updates the store state
+   * @param name - Action name for devtools tracking
+   * @param updatedState - New state value or updater function
+   *
+   * @remarks
+   * When providing a partial object, previous top-level keys not included in
+   * the update will be preserved.
+   */
+  set: (name: string, updatedState: Partial<TState> | ((s: TState) => Partial<TState>)) => void
+
+  /**
+   * Observable stream of state changes
+   * @remarks
+   * - Emits immediately with current state on subscription
+   * - Shares underlying subscription between observers
+   * - Only emits when state reference changes
+   * - Completes when store is disposed
+   */
+  observable: Observable<TState>
+}
+
+/**
+ * Creates a reactive store state container with multiple access patterns
+ * @param initialState - Initial state value for the store
+ * @param devToolsOptions - Configuration for Zustand devtools integration
+ * @returns StoreState instance with get/set/observable interface
+ *
+ * @example
+ * ```typescript
+ * // Create a simple counter store
+ * const counterStore = createStoreState({ count: 0 });
+ *
+ * // Update state
+ * counterStore.set('increment', { count: 1 });
+ *
+ * // Observe changes
+ * counterStore.observable.subscribe(console.log);
+ * ```
+ *
+ * @remarks
+ * Uses Zustand for state management under the hood with RxJS for observable interface.
+ * Designed to work with both imperative and reactive programming patterns.
+ */
+export function createStoreState<TState>(
+  initialState: TState,
+  devToolsOptions?: DevtoolsOptions,
+): StoreState<TState> {
+  // Create underlying Zustand store with devtools integration
+  const store = createStore<TState>()(devtools(() => initialState, devToolsOptions))
+
+  return {
+    get: store.getState,
+    set: (actionKey, updatedState) => {
+      const currentState = store.getState()
+      const nextState =
+        typeof updatedState === 'function' ? updatedState(currentState) : updatedState
+
+      // Optimization: Skip update if state reference remains the same
+      if (currentState !== nextState) {
+        store.setState(nextState, false, actionKey)
+      }
+    },
+    observable: new Observable((observer) => {
+      // Emit current state immediately on subscription
+      const emit = () => observer.next(store.getState())
+      emit()
+
+      // Subscribe to Zustand store changes
+      const unsubscribe = store.subscribe(emit)
+
+      // Cleanup when observable unsubscribed
+      return () => unsubscribe()
+    }),
+  }
+}

package/src/store/defineStore.test.ts

@@ -0,0 +1,18 @@
+import {describe, expect, it} from 'vitest'
+
+import {type SanityInstance} from './createSanityInstance'
+import {defineStore, type StoreDefinition} from './defineStore'
+
+describe('defineStore', () => {
+  it('should return the store definition unchanged', () => {
+    const storeDef: StoreDefinition<number> = {
+      name: 'TestStore',
+      getInitialState: () => 42,
+    }
+
+    const result = defineStore(storeDef)
+    expect(result).toBe(storeDef)
+    expect(result.name).toBe('TestStore')
+    expect(result.getInitialState({} as SanityInstance)).toBe(42)
+  })
+})

package/src/store/defineStore.ts

@@ -0,0 +1,81 @@
+import {type SanityInstance} from './createSanityInstance'
+import {type StoreState} from './createStoreState'
+
+/**
+ * Context object provided to store initialization functions
+ */
+export interface StoreContext<TState> {
+  /**
+   * Sanity instance associated with this store
+   *
+   * @remarks
+   * Provides access to the Sanity configuration and instance lifecycle methods
+   */
+  instance: SanityInstance
+
+  /**
+   * Reactive store state management utilities
+   *
+   * @remarks
+   * Contains methods for getting/setting state and observing changes
+   */
+  state: StoreState<TState>
+}
+
+/**
+ * Defines the structure and behavior of a store
+ *
+ * @remarks
+ * 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> {
+  /**
+   * Unique name for the store
+   *
+   * @remarks
+   * Used for debugging, devtools integration, and store identification
+   */
+  name: string
+
+  /**
+   * Creates the initial state for the store
+   * @param instance - Sanity instance the store is being created for
+   * @returns Initial state value
+   *
+   * @remarks
+   * Called when a new store instance is created. Can use Sanity instance
+   * configuration to determine initial state.
+   */
+  getInitialState: (instance: SanityInstance) => TState
+
+  /**
+   * Optional initialization function
+   * @param context - Store context with state and instance access
+   * @returns Optional cleanup function for store disposal
+   *
+   * @remarks
+   * Use this for:
+   * - Setting up event listeners
+   * - Initial data fetching
+   * - Connecting external services
+   *
+   * Return a cleanup function to:
+   * - Remove event listeners
+   * - Cancel pending operations
+   * - Dispose external connections
+   */
+  initialize?: (context: StoreContext<TState>) => (() => void) | undefined
+}
+
+/**
+ * Typescript helper function for creating store definitions
+ *
+ * @param storeDefinition - Configuration object defining the store
+ * @returns The finalized store definition
+ */
+export function defineStore<TState>(
+  storeDefinition: StoreDefinition<TState>,
+): StoreDefinition<TState> {
+  return storeDefinition
+}