@sanity/sdk-react 2.9.0 → 2.11.0

package/src/hooks/organizations/useOrganizations.test-d.ts

@@ -0,0 +1,55 @@
+import {type OrganizationMember, type Organizations} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganizations} from './useOrganizations'
+
+test('useOrganizations — no args: members and features both omitted', () => {
+  expectTypeOf(useOrganizations()).toEqualTypeOf<Organizations<false, false>>()
+})
+
+test('useOrganizations — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganizations({includeMembers: true})).toEqualTypeOf<Organizations<true, false>>()
+  type Result = ReturnType<typeof useOrganizations<true, false>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganizations — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(useOrganizations({includeFeatures: true})).toEqualTypeOf<
+    Organizations<false, true>
+  >()
+})
+
+test('useOrganizations — both flags true → both arrays present', () => {
+  expectTypeOf(useOrganizations({includeMembers: true, includeFeatures: true})).toEqualTypeOf<
+    Organizations<true, true>
+  >()
+})
+
+test('useOrganizations — both flags false → bare base shape', () => {
+  expectTypeOf(useOrganizations({includeMembers: false, includeFeatures: false})).toEqualTypeOf<
+    Organizations<false, false>
+  >()
+  type Result = ReturnType<typeof useOrganizations<false, false>>
+  expectTypeOf<Result[number]['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganizations — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganizations({includeMembers: 'yes'})
+})
+
+test('useOrganizations — includeImplicitMemberships does not change the data shape', () => {
+  expectTypeOf(useOrganizations({includeImplicitMemberships: true})).toEqualTypeOf<
+    Organizations<false, false>
+  >()
+})
+
+test('useOrganizations — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganizations({includeMembers})).toEqualTypeOf<Organizations<boolean, false>>()
+  type Result = ReturnType<typeof useOrganizations<boolean, false>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<OrganizationMember[] | undefined>()
+  expectTypeOf<Pick<Result[number], 'members'>>().toEqualTypeOf<{
+    members?: OrganizationMember[]
+  }>()
+})

package/src/hooks/organizations/useOrganizations.test.ts

@@ -0,0 +1,85 @@
+import {getOrganizationsState, type SanityInstance} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+vi.mock('@sanity/sdk', () => ({
+  getOrganizationsState: vi.fn(() => ({
+    getCurrent: vi.fn(() => undefined),
+  })),
+  resolveOrganizations: vi.fn(),
+}))
+vi.mock('../helpers/createStateSourceHook', () => ({
+  createStateSourceHook: vi.fn(),
+}))
+
+describe('useOrganizations', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.mock('@sanity/sdk', () => ({
+      getOrganizationsState: vi.fn(() => ({
+        getCurrent: vi.fn(() => undefined),
+      })),
+      resolveOrganizations: vi.fn(),
+    }))
+    vi.mock('../helpers/createStateSourceHook', () => ({
+      createStateSourceHook: vi.fn(),
+    }))
+  })
+
+  it('should call createStateSourceHook with correct arguments on import', async () => {
+    await import('./useOrganizations')
+
+    expect(createStateSourceHook).toHaveBeenCalled()
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: expect.any(Function),
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function),
+      }),
+    )
+  })
+
+  it('shouldSuspend should call getOrganizationsState and getCurrent', async () => {
+    await import('./useOrganizations')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook.mock.calls.length).toBeGreaterThan(0)
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+
+    const result = shouldSuspend(mockInstance, undefined)
+
+    const mockGetOrganizationsState = getOrganizationsState as ReturnType<typeof vi.fn>
+    expect(mockGetOrganizationsState).toHaveBeenCalledWith(mockInstance, undefined)
+
+    expect(mockGetOrganizationsState.mock.results.length).toBeGreaterThan(0)
+    const getOrganizationsStateMockResult = mockGetOrganizationsState.mock.results[0].value
+    expect(getOrganizationsStateMockResult.getCurrent).toHaveBeenCalled()
+
+    expect(result).toBe(true)
+  })
+
+  it('should handle different parameter combinations in shouldSuspend', async () => {
+    await import('./useOrganizations')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+
+    expect(() => shouldSuspend(mockInstance, undefined)).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {includeMembers: true})).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {includeFeatures: true})).not.toThrow()
+    expect(() =>
+      shouldSuspend(mockInstance, {
+        includeMembers: true,
+        includeFeatures: true,
+        includeImplicitMemberships: true,
+      }),
+    ).not.toThrow()
+  })
+})

package/src/hooks/organizations/useOrganizations.ts

@@ -0,0 +1,45 @@
+import {
+  getOrganizationsState,
+  type Organizations,
+  type OrganizationsOptions,
+  resolveOrganizations,
+} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns metadata for each organisation the current user has access to.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns An array of organisation metadata. `members` is included only when
+ *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * const organizations = useOrganizations()
+ *
+ * return (
+ *   <select>
+ *     {organizations.map((organization) => (
+ *       <option key={organization.id}>{organization.name}</option>
+ *     ))}
+ *   </select>
+ * )
+ * ```
+ * @example
+ * ```tsx
+ * const organizationsWithMembers = useOrganizations({includeMembers: true})
+ * const organizationsWithFeatures = useOrganizations({includeFeatures: true})
+ * const organizationsIncludingImplicit = useOrganizations({includeImplicitMemberships: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganizations = createStateSourceHook({
+  getState: getOrganizationsState,
+  shouldSuspend: (instance, ...params) =>
+    getOrganizationsState(instance, ...params).getCurrent() === undefined,
+  suspender: resolveOrganizations,
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = false>(
+  options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
+) => Organizations<IncludeMembers, IncludeFeatures>

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -1,9 +1,17 @@
-import {createGroqSearchFilter, type DocumentHandle, type QueryOptions} from '@sanity/sdk'
+import {
+  createGroqSearchFilter,
+  type DocumentHandle,
+  isDatasetResource,
+  type QueryOptions,
+} from '@sanity/sdk'
+import {pickProperties} from '@sanity/sdk/_internal'
 import {type SortOrderingItem} from '@sanity/types'
-import {pick} from 'lodash-es'
-import {useCallback, useEffect, useMemo, useState} from 'react'
+import {useCallback, useMemo, useState} from 'react'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
@@ -17,7 +25,9 @@ export interface PaginatedDocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'> {
+> extends WithResourceNameSupport<
+  Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'>
+> {
   documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
@@ -233,21 +243,22 @@ export function usePaginatedDocuments<
   params = {},
   orderings,
   search,
-  ...options
+  ...rawOptions
 }: PaginatedDocumentsOptions<TDocumentType, TDataset, TProjectId>): PaginatedDocumentsResponse<
   TDocumentType,
   TDataset,
   TProjectId
 > {
   useTrackHookUsage('usePaginatedDocuments')
-  const instance = useSanityInstance(options)
+  const options = useNormalizedResourceOptions(rawOptions)
   const [pageIndex, setPageIndex] = useState(0)
-  const key = JSON.stringify({filter, search, params, orderings, pageSize})
-  // Reset the pageIndex to 0 whenever any query parameters (filter, search,
-  // params, orderings) or pageSize changes
-  useEffect(() => {
+  const key = JSON.stringify({filter, search, params, orderings, pageSize, ...options})
+  // Reset pageIndex to 0 whenever any query parameter changes.
+  const [prevKey, setPrevKey] = useState(key)
+  if (prevKey !== key) {
+    setPrevKey(key)
     setPageIndex(0)
-  }, [key])
+  }
 
   const startIndex = pageIndex * pageSize
   const endIndex = (pageIndex + 1) * pageSize
@@ -303,8 +314,12 @@ export function usePaginatedDocuments<
       ...params,
       __types: documentTypes,
       __handle: {
-        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
-        ...pick(options, 'projectId', 'dataset', 'perspective'),
+        // keep projectId/dataset for backward compat until v4; resource is added
+        // intentionally so that hook consumers can resolve the correct resource
+        ...(options.resource && isDatasetResource(options.resource)
+          ? pickProperties(options.resource, ['projectId', 'dataset'])
+          : {}),
+        ...pickProperties(options, ['perspective', 'resource']),
       },
     },
   })

package/src/hooks/presence/usePresence.test.tsx

@@ -6,14 +6,17 @@ import {describe, expect, it, vi} from 'vitest'
 import {ResourceProvider} from '../../context/ResourceProvider'
 import {usePresence} from './usePresence'
 
-vi.mock('@sanity/sdk', () => ({
-  getPresence: vi.fn(),
-  createSanityInstance: vi.fn(() => ({
-    createChild: vi.fn(),
-    isDisposed: vi.fn(() => false),
-    dispose: vi.fn(),
-  })),
-}))
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...actual,
+    getPresence: vi.fn(),
+    createSanityInstance: vi.fn(() => ({
+      isDisposed: vi.fn(() => false),
+      dispose: vi.fn(),
+    })),
+  }
+})
 
 describe('usePresence', () => {
   it('should return presence locations and update when the store changes', () => {
@@ -59,7 +62,10 @@ describe('usePresence', () => {
 
     const {result, unmount} = renderHook(() => usePresence(), {
       wrapper: ({children}) => (
-        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+        <ResourceProvider
+          resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+          fallback={null}
+        >
           {children}
         </ResourceProvider>
       ),
@@ -80,4 +86,45 @@ describe('usePresence', () => {
     expect(result.current.locations).toEqual(updatedLocations)
     unmount()
   })
+
+  it('should throw an error when used with a media library resource', () => {
+    expect(() => {
+      renderHook(() => usePresence({resource: {mediaLibraryId: 'ml123'}}), {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      })
+    }).toThrow('usePresence() does not support media library resources')
+  })
+
+  it('should work with a dataset resource', () => {
+    const mockPresenceSource = {
+      getCurrent: vi.fn().mockReturnValue([]),
+      subscribe: vi.fn(() => () => {}),
+      observable: NEVER,
+    }
+    vi.mocked(getPresence).mockReturnValue(mockPresenceSource)
+
+    const {result, unmount} = renderHook(
+      () => usePresence({resource: {projectId: 'test-project', dataset: 'test-dataset'}}),
+      {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      },
+    )
+
+    expect(result.current.locations).toEqual([])
+    unmount()
+  })
 })

package/src/hooks/presence/usePresence.ts

@@ -1,19 +1,31 @@
-import {getPresence, type UserPresence} from '@sanity/sdk'
+import {getPresence, isMediaLibraryResource, type UserPresence} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
+import {type ResourceHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
- * A hook for subscribing to presence information for the current project.
+ * A hook for subscribing to presence information for the current project or Canvas.
  * @public
  */
-export function usePresence(): {
+export function usePresence(options: ResourceHandle = {}): {
   locations: UserPresence[]
 } {
+  const normalizedOptions = useNormalizedResourceOptions(options)
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource)) {
+    throw new Error(
+      'usePresence() does not support media library resources. Presence tracking requires a canvas or dataset resource.',
+    )
+  }
+
   const sanityInstance = useSanityInstance()
   trackHookUsage(sanityInstance, 'usePresence')
-  const source = useMemo(() => getPresence(sanityInstance), [sanityInstance])
+  const source = useMemo(
+    () => getPresence(sanityInstance, normalizedOptions),
+    [sanityInstance, normalizedOptions],
+  )
   const subscribe = useCallback((callback: () => void) => source.subscribe(callback), [source])
   const locations = useSyncExternalStore(
     subscribe,

package/src/hooks/preview/useDocumentPreview.tsx

@@ -1,5 +1,4 @@
 import {
-  type DocumentHandle,
   PREVIEW_PROJECTION,
   type PreviewQueryResult,
   type PreviewValue,
@@ -7,11 +6,9 @@ import {
 } from '@sanity/sdk'
 import {useMemo} from 'react'
 
+import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
-import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useDocumentProjection} from '../projection/useDocumentProjection'
 
@@ -19,7 +16,7 @@ import {useDocumentProjection} from '../projection/useDocumentProjection'
  * @public
  * @category Types
  */
-export interface useDocumentPreviewOptions extends WithSourceNameSupport<DocumentHandle> {
+export interface useDocumentPreviewOptions extends DocumentHandle {
   /**
    * Optional ref object to track visibility. When provided, preview resolution
    * only occurs when the referenced element is visible in the viewport.
@@ -98,9 +95,9 @@ export function useDocumentPreview({
   ref,
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
-  const instance = useSanityInstance(docHandle)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useDocumentPreview')
-  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
+  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Use the projection hook with the fixed preview projection
   const projectionResult = useDocumentProjection<PreviewQueryResult>({
@@ -112,8 +109,9 @@ export function useDocumentPreview({
   // Contract: useDocumentProjection suspends while data is null, so data is always available here.
   // Keep this non-null assumption aligned with useDocumentPreviewResults.data.
   const previewValue = useMemo(
-    () => transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.source),
-    [projectionResult.data, instance, normalizedDocHandle.source],
+    () =>
+      transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.resource),
+    [projectionResult.data, instance, normalizedDocHandle.resource],
   )
 
   return {

package/src/hooks/projection/useDocumentProjection.ts

@@ -1,13 +1,11 @@
-import {type DocumentHandle, getProjectionState, resolveProjection} from '@sanity/sdk'
+import {getProjectionState, resolveProjection} from '@sanity/sdk'
 import {type SanityProjectionResult} from 'groq'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
+import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
-import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
@@ -19,7 +17,7 @@ export interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
+> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -181,7 +179,7 @@ export function useDocumentProjection<TData extends object>({
   projection,
   ...docHandle
 }: useDocumentProjectionOptions): useDocumentProjectionResults<TData> {
-  const instance = useSanityInstance(docHandle)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useDocumentProjection')
 
   // Normalize projection string to handle template literals with whitespace
@@ -189,8 +187,8 @@ export function useDocumentProjection<TData extends object>({
   // even if the string reference changes (e.g., from inline template literals)
   const normalizedProjection = useMemo(() => projection.trim(), [projection])
 
-  // Normalize options: resolve sourceName to source and strip sourceName
-  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
+  // Normalize options: resolve resourceName to resource and strip resourceName
+  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Memoize stateSource based on normalized projection and docHandle properties
   // This prevents creating a new StateSource on every render when projection content is the same

package/src/hooks/projects/useProject.test-d.ts

@@ -0,0 +1,49 @@
+import {type Project, type ProjectMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useProject} from './useProject'
+
+test('useProject — no args: members and features both included by default', () => {
+  expectTypeOf(useProject()).toEqualTypeOf<Project<true, true>>()
+  type Result = ReturnType<typeof useProject<true, true>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('useProject — includeMembers: false drops members from the type', () => {
+  expectTypeOf(useProject({includeMembers: false})).toEqualTypeOf<Project<false, true>>()
+})
+
+test('useProject — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(useProject({includeFeatures: false})).toEqualTypeOf<Project<true, false>>()
+})
+
+test('useProject — both flags true → both arrays present', () => {
+  expectTypeOf(useProject({includeMembers: true, includeFeatures: true})).toEqualTypeOf<
+    Project<true, true>
+  >()
+})
+
+test('useProject — both flags false → bare base shape', () => {
+  expectTypeOf(useProject({includeMembers: false, includeFeatures: false})).toEqualTypeOf<
+    Project<false, false>
+  >()
+  type Result = ReturnType<typeof useProject<false, false>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('useProject — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useProject({includeMembers: 'yes'})
+})
+
+test('useProject — projectId alone does not change the data shape', () => {
+  expectTypeOf(useProject({projectId: 'p'})).toEqualTypeOf<Project<true, true>>()
+})
+
+test('useProject — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useProject({includeMembers})).toEqualTypeOf<Project<boolean, true>>()
+  type Result = ReturnType<typeof useProject<boolean, true>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Pick<Result, 'members'>>().toEqualTypeOf<{members?: ProjectMember[]}>()
+})

package/src/hooks/projects/useProject.ts

@@ -1,51 +1,43 @@
-import {
-  getProjectState,
-  type ProjectHandle,
-  resolveProject,
-  type SanityInstance,
-  type SanityProject,
-  type StateSource,
-} from '@sanity/sdk'
+import {getProjectState, type Project, type ProjectOptions, resolveProject} from '@sanity/sdk'
 import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
-type UseProject = {
-  /**
-   *
-   * Returns metadata for a given project
-   *
-   * @category Projects
-   * @param projectId - The ID of the project to retrieve metadata for
-   * @returns The metadata for the project
-   * @example
-   * ```tsx
-   *  function ProjectMetadata({ projectId }: { projectId: string }) {
-   *    const project = useProject(projectId)
-   *
-   *    return (
-   *      <figure style={{ backgroundColor: project.metadata.color || 'lavender'}}>
-   *        <h1>{project.displayName}</h1>
-   *      </figure>
-   *    )
-   *  }
-   * ```
-   */
-  (projectHandle?: ProjectHandle): SanityProject
-}
-
 /**
+ * Returns metadata for a given project.
+ *
+ * @category Projects
+ * @param options - Configuration options
+ * @returns The metadata for the project. `members` is included only when
+ *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
+ * @example
+ * ```tsx
+ * function ProjectMetadata({projectId}: {projectId: string}) {
+ *   const project = useProject({projectId})
+ *
+ *   return (
+ *     <figure style={{backgroundColor: project.metadata.color || 'lavender'}}>
+ *       <h1>{project.displayName}</h1>
+ *     </figure>
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const projectWithMembersAndFeatures = useProject({projectId})
+ * const projectWithMembers = useProject({projectId, includeMembers: true})
+ * const projectWithoutMembers = useProject({projectId, includeMembers: false})
+ * const projectWithoutFeatures = useProject({projectId, includeFeatures: false})
+ * ```
  * @public
  * @function
  */
-export const useProject: UseProject = createStateSourceHook({
-  // remove `undefined` since we're suspending when that is the case
-  getState: getProjectState as (
-    instance: SanityInstance,
-    projectHandle?: ProjectHandle,
-  ) => StateSource<SanityProject>,
-  shouldSuspend: (instance, projectHandle) =>
-    getProjectState(instance, projectHandle).getCurrent() === undefined,
+export const useProject = createStateSourceHook({
+  getState: getProjectState,
+  shouldSuspend: (instance, ...params) =>
+    getProjectState(instance, ...params).getCurrent() === undefined,
   suspender: resolveProject,
   getConfig: identity,
-})
+}) as <IncludeMembers extends boolean = true, IncludeFeatures extends boolean = true>(
+  options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
+) => Project<IncludeMembers, IncludeFeatures>

package/src/hooks/projects/useProjects.test-d.ts

@@ -0,0 +1,49 @@
+import {type Project, type ProjectMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useProjects} from './useProjects'
+
+test('useProjects — no args: features included, members omitted', () => {
+  expectTypeOf(useProjects()).toEqualTypeOf<Project<false, true>[]>()
+})
+
+test('useProjects — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useProjects({includeMembers: true})).toEqualTypeOf<Project<true, true>[]>()
+  type Result = ReturnType<typeof useProjects<true, true>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('useProjects — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(useProjects({includeFeatures: false})).toEqualTypeOf<Project<false, false>[]>()
+})
+
+test('useProjects — both flags true → both arrays present', () => {
+  expectTypeOf(useProjects({includeMembers: true, includeFeatures: true})).toEqualTypeOf<
+    Project<true, true>[]
+  >()
+})
+
+test('useProjects — both flags false → bare base shape', () => {
+  expectTypeOf(useProjects({includeMembers: false, includeFeatures: false})).toEqualTypeOf<
+    Project<false, false>[]
+  >()
+  type Result = ReturnType<typeof useProjects<false, false>>
+  expectTypeOf<Result[number]['id']>().toEqualTypeOf<string>()
+})
+
+test('useProjects — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useProjects({includeMembers: 'yes'})
+})
+
+test('useProjects — organizationId alone does not change the data shape', () => {
+  expectTypeOf(useProjects({organizationId: 'org_123'})).toEqualTypeOf<Project<false, true>[]>()
+})
+
+test('useProjects — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useProjects({includeMembers})).toEqualTypeOf<Project<boolean, true>[]>()
+  type Result = ReturnType<typeof useProjects<boolean, true>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Pick<Result[number], 'members'>>().toEqualTypeOf<{members?: ProjectMember[]}>()
+})