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

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

package/src/users/reducers.test.ts

@@ -0,0 +1,318 @@
+import {describe, expect, it} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {
+  addSubscription,
+  cancelRequest,
+  getUsersKey,
+  initializeRequest,
+  parseUsersKey,
+  removeSubscription,
+  setUsersData,
+  setUsersError,
+  updateLastLoadMoreRequest,
+} from './reducers'
+import {type GetUsersOptions, type SanityUserResponse, type UsersStoreState} from './types'
+import {DEFAULT_USERS_BATCH_SIZE} from './usersConstants'
+
+describe('Users Reducers', () => {
+  // Mock SanityInstance for testing
+  const mockInstance: SanityInstance = {
+    instanceId: 'test-instance-id',
+    config: {
+      projectId: 'test-project-id',
+    },
+    isDisposed: () => false,
+    dispose: () => {},
+    onDispose: () => () => {},
+    getParent: () => undefined,
+    createChild: (_config) => mockInstance,
+    match: () => undefined,
+  }
+
+  const sampleOptions: GetUsersOptions = {
+    resourceType: 'project',
+    projectId: 'proj123',
+    batchSize: 50,
+  }
+
+  const sampleOptionsWithDefaultBatchSize: GetUsersOptions = {
+    resourceType: 'project',
+    projectId: 'proj123',
+  }
+
+  describe('getUsersKey', () => {
+    it('should generate a key based on resourceType, resourceId and batchSize', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      expect(JSON.parse(key)).toEqual({
+        resourceType: 'project',
+        projectId: 'proj123',
+        batchSize: 50,
+      })
+    })
+
+    it('should use DEFAULT_USERS_BATCH_SIZE when batchSize is not provided', () => {
+      const key = getUsersKey(mockInstance, sampleOptionsWithDefaultBatchSize)
+      expect(JSON.parse(key)).toEqual({
+        resourceType: 'project',
+        projectId: 'proj123',
+        batchSize: DEFAULT_USERS_BATCH_SIZE,
+      })
+    })
+  })
+
+  describe('parseUsersKey', () => {
+    it('should parse a key back into its components', () => {
+      const key = JSON.stringify({
+        resourceType: 'organization',
+        resourceId: 'org456',
+        batchSize: 25,
+      })
+      const parsed = parseUsersKey(key)
+      expect(parsed).toEqual({
+        resourceType: 'organization',
+        resourceId: 'org456',
+        batchSize: 25,
+      })
+    })
+  })
+
+  describe('addSubscription', () => {
+    it('should add a subscription when key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const reducer = addSubscription('sub1', key)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({subscriptions: ['sub1']})
+    })
+
+    it('should append subscription when key exists', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['subA']}}}
+      const reducer = addSubscription('subB', key)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({subscriptions: ['subA', 'subB']})
+    })
+  })
+
+  describe('removeSubscription', () => {
+    it('should return state unchanged if key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const reducer = removeSubscription('subX', key)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should remove subscription and keep the group if other subscriptions remain', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['sub1', 'sub2']}}}
+      const reducer = removeSubscription('sub1', key)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({subscriptions: ['sub2']})
+    })
+
+    it('should remove the group if no subscriptions remain after removal', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['onlySub']}}}
+      const reducer = removeSubscription('onlySub', key)
+      const newState = reducer(state)
+      expect(newState.users).not.toHaveProperty(key)
+    })
+  })
+
+  describe('setUsersData', () => {
+    it('should return state unchanged if key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const userResponse: SanityUserResponse = {
+        data: [
+          {
+            sanityUserId: 'user1',
+            profile: {
+              id: 'profile1',
+              displayName: 'User One',
+              email: 'user1@example.com',
+              provider: 'google',
+              createdAt: '2023-01-01',
+            },
+            memberships: [],
+          },
+        ],
+        totalCount: 1,
+        nextCursor: null,
+      }
+      const reducer = setUsersData(key, userResponse)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should set users data if key exists', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['sub1']}}}
+      const userResponse: SanityUserResponse = {
+        data: [
+          {
+            sanityUserId: 'user1',
+            profile: {
+              id: 'profile1',
+              displayName: 'User One',
+              email: 'user1@example.com',
+              provider: 'google',
+              createdAt: '2023-01-01',
+            },
+            memberships: [],
+          },
+        ],
+        totalCount: 1,
+        nextCursor: null,
+      }
+      const reducer = setUsersData(key, userResponse)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({
+        subscriptions: ['sub1'],
+        users: userResponse.data,
+        totalCount: 1,
+        nextCursor: null,
+      })
+    })
+
+    it('should append new users to existing users', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const existingUser = {
+        sanityUserId: 'user1',
+        profile: {
+          id: 'profile1',
+          displayName: 'User One',
+          email: 'user1@example.com',
+          provider: 'google',
+          createdAt: '2023-01-01',
+        },
+        memberships: [],
+      }
+      const newUser = {
+        sanityUserId: 'user2',
+        profile: {
+          id: 'profile2',
+          displayName: 'User Two',
+          email: 'user2@example.com',
+          provider: 'google',
+          createdAt: '2023-01-02',
+        },
+        memberships: [],
+      }
+      const state: UsersStoreState = {
+        users: {
+          [key]: {
+            subscriptions: ['sub1'],
+            users: [existingUser],
+          },
+        },
+      }
+      const userResponse: SanityUserResponse = {
+        data: [newUser],
+        totalCount: 2,
+        nextCursor: null,
+      }
+      const reducer = setUsersData(key, userResponse)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({
+        subscriptions: ['sub1'],
+        users: [existingUser, newUser],
+        totalCount: 2,
+        nextCursor: null,
+      })
+    })
+  })
+
+  describe('updateLastLoadMoreRequest', () => {
+    it('should return state unchanged if key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const timestamp = '2023-05-15T12:00:00Z'
+      const reducer = updateLastLoadMoreRequest(timestamp, key)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should update lastLoadMoreRequest if key exists', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['sub1']}}}
+      const timestamp = '2023-05-15T12:00:00Z'
+      const reducer = updateLastLoadMoreRequest(timestamp, key)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({
+        subscriptions: ['sub1'],
+        lastLoadMoreRequest: timestamp,
+      })
+    })
+  })
+
+  describe('setUsersError', () => {
+    it('should return state unchanged if key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const error = new Error('Failed to fetch users')
+      const reducer = setUsersError(key, error)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should set error if key exists', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['sub1']}}}
+      const error = new Error('Failed to fetch users')
+      const reducer = setUsersError(key, error)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({
+        subscriptions: ['sub1'],
+        error,
+      })
+    })
+  })
+
+  describe('cancelRequest', () => {
+    it('should return state unchanged if key does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const reducer = cancelRequest(key)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should return state unchanged if group has subscriptions', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: ['sub1']}}}
+      const reducer = cancelRequest(key)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should remove the group if no subscriptions exist', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const state: UsersStoreState = {users: {[key]: {subscriptions: []}}}
+      const reducer = cancelRequest(key)
+      const newState = reducer(state)
+      expect(newState.users).not.toHaveProperty(key)
+    })
+  })
+
+  describe('initializeRequest', () => {
+    it('should return state unchanged if group already exists', () => {
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const existing = {subscriptions: ['sub1']}
+      const state: UsersStoreState = {users: {[key]: existing}}
+      const reducer = initializeRequest(key)
+      const newState = reducer(state)
+      expect(newState).toBe(state)
+    })
+
+    it('should add the group with empty subscriptions if it does not exist', () => {
+      const state: UsersStoreState = {users: {}}
+      const key = getUsersKey(mockInstance, sampleOptions)
+      const reducer = initializeRequest(key)
+      const newState = reducer(state)
+      expect(newState.users[key]).toEqual({subscriptions: []})
+    })
+  })
+})

package/src/users/reducers.ts

@@ -0,0 +1,88 @@
+import {omit} from 'lodash-es'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type GetUsersOptions, type SanityUserResponse, type UsersStoreState} from './types'
+import {DEFAULT_USERS_BATCH_SIZE} from './usersConstants'
+
+/** @internal */
+export const getUsersKey = (
+  instance: SanityInstance,
+  {
+    resourceType,
+    organizationId,
+    batchSize = DEFAULT_USERS_BATCH_SIZE,
+    projectId = instance.config.projectId,
+  }: GetUsersOptions = {},
+): string =>
+  JSON.stringify({resourceType, organizationId, batchSize, projectId} satisfies ReturnType<
+    typeof parseUsersKey
+  >)
+
+/** @internal */
+export const parseUsersKey = (
+  key: string,
+): {
+  batchSize: number
+  resourceType?: 'organization' | 'project'
+  projectId?: string
+  organizationId?: string
+} => JSON.parse(key)
+
+export const addSubscription =
+  (subscriptionId: string, key: string) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    const subscriptions = [...(group?.subscriptions ?? []), subscriptionId]
+    return {...prev, users: {...prev.users, [key]: {...group, subscriptions}}}
+  }
+
+export const removeSubscription =
+  (subscriptionId: string, key: string) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    if (!group) return prev
+    const subscriptions = group.subscriptions.filter((id) => id !== subscriptionId)
+    if (!subscriptions.length) return {...prev, users: omit(prev.users, key)}
+    return {...prev, users: {...prev.users, [key]: {...group, subscriptions}}}
+  }
+
+export const setUsersData =
+  (key: string, {data, nextCursor, totalCount}: SanityUserResponse) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    if (!group) return prev
+    const users = [...(group.users ?? []), ...data]
+    return {...prev, users: {...prev.users, [key]: {...group, users, totalCount, nextCursor}}}
+  }
+
+export const updateLastLoadMoreRequest =
+  (timestamp: string, key: string) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    if (!group) return prev
+    return {...prev, users: {...prev.users, [key]: {...group, lastLoadMoreRequest: timestamp}}}
+  }
+
+export const setUsersError =
+  (key: string, error: unknown) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    if (!group) return prev
+    return {...prev, users: {...prev.users, [key]: {...group, error}}}
+  }
+
+export const cancelRequest =
+  (key: string) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    const group = prev.users[key]
+    if (!group) return prev
+    if (group.subscriptions.length) return prev
+    return {...prev, users: omit(prev.users, key)}
+  }
+
+export const initializeRequest =
+  (key: string) =>
+  (prev: UsersStoreState): UsersStoreState => {
+    if (prev.users[key]) return prev
+    return {...prev, users: {...prev.users, [key]: {subscriptions: []}}}
+  }

package/src/users/types.ts

@@ -1,7 +1,4 @@
-/**
- * @public
- */
-export type ResourceType = 'organization' | 'project'
+import {type ProjectHandle} from '../config/sanityConfig'
 
 /**
  * @public
@@ -41,3 +38,48 @@ export interface UserProfile {
   isCurrentUser?: boolean
   providerId?: string
 }
+
+/**
+ * @public
+ */
+export interface GetUsersOptions extends ProjectHandle {
+  resourceType?: 'organization' | 'project'
+  batchSize?: number
+  organizationId?: string
+}
+
+/**
+ * @public
+ */
+export interface UsersGroupState {
+  subscriptions: string[]
+  totalCount?: number
+  nextCursor?: string | null
+  lastLoadMoreRequest?: string
+  users?: SanityUser[]
+  error?: unknown
+}
+
+/**
+ * @public
+ */
+export interface SanityUserResponse {
+  data: SanityUser[]
+  totalCount: number
+  nextCursor: string | null
+}
+
+/**
+ * @public
+ */
+export interface UsersStoreState {
+  users: {[TUsersKey in string]?: UsersGroupState}
+  error?: unknown
+}
+
+/**
+ * @public
+ */
+export interface ResolveUsersOptions extends GetUsersOptions {
+  signal?: AbortSignal
+}

package/src/users/usersConstants.ts

@@ -0,0 +1,4 @@
+// NOTE: currently this API is only available on vX
+export const API_VERSION = 'vX'
+export const USERS_STATE_CLEAR_DELAY = 5000
+export const DEFAULT_USERS_BATCH_SIZE = 100