feat(projects): add organizationId and includeMembers parameters to useProjects hook (#607)

- Add optional organizationId parameter for filtering projects by organization
- Add optional includeMembers parameter
- Implement parameter-based caching with unique cache keys

Author: ryanbonial

packages/core/src/projects/projects.test.ts

@@ -36,6 +36,41 @@ describe('projects', () => {
 
     const result = await resolveProjects(instance)
     expect(result).toEqual(projects)
-    expect(list).toHaveBeenCalledWith({includeMembers: false})
+    expect(list).toHaveBeenCalledWith({includeMembers: false, organizationId: undefined})
+  })
+})
+
+describe('projects cache key generation', () => {
+  it('generates correct cache keys for different parameter combinations', async () => {
+    // Test the getKey function directly by creating a mock store
+    const mockGetKey = (
+      _instance: SanityInstance,
+      options?: {organizationId?: string; includeMembers?: boolean},
+    ) => {
+      const orgKey = options?.organizationId ? `:org:${options.organizationId}` : ''
+      const membersKey = options?.includeMembers === false ? ':no-members' : ''
+      return `projects${orgKey}${membersKey}`
+    }
+
+    const mockInstance = {} as SanityInstance
+
+    // Test default behavior (no options)
+    const defaultKey = mockGetKey(mockInstance)
+    expect(defaultKey).toBe('projects')
+
+    // Test with organizationId only
+    const orgKey = mockGetKey(mockInstance, {organizationId: 'org123'})
+    expect(orgKey).toBe('projects:org:org123')
+
+    // Test with includeMembers: false only
+    const noMembersKey = mockGetKey(mockInstance, {includeMembers: false})
+    expect(noMembersKey).toBe('projects:no-members')
+
+    // Test with both parameters
+    const bothKey = mockGetKey(mockInstance, {
+      organizationId: 'org123',
+      includeMembers: false,
+    })
+    expect(bothKey).toBe('projects:org:org123:no-members')
   })
 })

packages/core/src/projects/projects.ts

@@ -7,13 +7,25 @@ const API_VERSION = 'v2025-02-19'
 
 const projects = createFetcherStore({
   name: 'Projects',
-  getKey: () => 'projects',
-  fetcher: (instance) => () =>
+  getKey: (_instance, options?: {organizationId?: string; includeMembers?: boolean}) => {
+    const orgKey = options?.organizationId ? `:org:${options.organizationId}` : ''
+    const membersKey = options?.includeMembers === false ? ':no-members' : ''
+    return `projects${orgKey}${membersKey}`
+  },
+  fetcher: (instance) => (options?: {organizationId?: string; includeMembers?: boolean}) =>
     getClientState(instance, {
       apiVersion: API_VERSION,
       scope: 'global',
+      requestTagPrefix: 'sanity.sdk.projects',
     }).observable.pipe(
-      switchMap((client) => client.observable.projects.list({includeMembers: false})),
+      switchMap((client) => {
+        const organizationId = options?.organizationId
+        return client.observable.projects.list({
+          // client method has a type that expects false | undefined
+          includeMembers: !options?.includeMembers ? false : undefined,
+          organizationId,
+        })
+      }),
     ),
 })
 

packages/react/src/hooks/projects/useProjects.test.ts

@@ -59,12 +59,12 @@ describe('useProjects', () => {
     // Mock instance for the test call
     const mockInstance = {} as SanityInstance // Use specific type
 
-    // Call the shouldSuspend function
-    const result = shouldSuspend(mockInstance)
+    // Call the shouldSuspend function with both required parameters
+    const result = shouldSuspend(mockInstance, undefined) // Pass undefined for options
 
     // Assert that getProjectsState was called with the correct arguments
     const mockGetProjectsState = getProjectsState as ReturnType<typeof vi.fn>
-    expect(mockGetProjectsState).toHaveBeenCalledWith(mockInstance)
+    expect(mockGetProjectsState).toHaveBeenCalledWith(mockInstance, undefined)
 
     // Assert that getCurrent was called on the result of getProjectsState
     expect(mockGetProjectsState.mock.results.length).toBeGreaterThan(0)
@@ -74,4 +74,39 @@ describe('useProjects', () => {
     // Assert the result of shouldSuspend based on the mocked getCurrent value
     expect(result).toBe(true) // Since getCurrent is mocked to return undefined
   })
+
+  it('should call createStateSourceHook with correct getState function signature', async () => {
+    await import('./useProjects')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook).toHaveBeenCalled()
+
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const getState = createStateSourceHookArgs.getState
+
+    // Test that getState can handle the new options parameter
+    const mockInstance = {} as SanityInstance
+    const mockOptions = {organizationId: 'org123', includeMembers: false}
+
+    // This should not throw
+    expect(() => getState(mockInstance, mockOptions)).not.toThrow()
+  })
+
+  it('should handle different parameter combinations in shouldSuspend', async () => {
+    await import('./useProjects')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+
+    // Test with different options
+    expect(() => shouldSuspend(mockInstance, undefined)).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {organizationId: 'org123'})).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {includeMembers: false})).not.toThrow()
+    expect(() =>
+      shouldSuspend(mockInstance, {organizationId: 'org123', includeMembers: false}),
+    ).not.toThrow()
+  })
 })

packages/react/src/hooks/projects/useProjects.ts

@@ -30,16 +30,20 @@ type UseProjects = {
    * )
    * ```
    */
-  (): ProjectWithoutMembers[]
+  (options?: {organizationId?: string; includeMembers?: true}): SanityProject[]
+  (options: {organizationId?: string; includeMembers?: false}): ProjectWithoutMembers[]
 }
 
 /**
  * @public
  * @function
  */
 export const useProjects: UseProjects = createStateSourceHook({
-  // remove `undefined` since we're suspending when that is the case
-  getState: getProjectsState as (instance: SanityInstance) => StateSource<ProjectWithoutMembers[]>,
-  shouldSuspend: (instance) => getProjectsState(instance).getCurrent() === undefined,
+  getState: getProjectsState as (
+    instance: SanityInstance,
+    options?: {organizationId?: string; includeMembers?: boolean},
+  ) => StateSource<SanityProject[] | ProjectWithoutMembers[]>,
+  shouldSuspend: (instance, options) =>
+    getProjectsState(instance, options).getCurrent() === undefined,
   suspender: resolveProjects,
-})
+}) as UseProjects