@sanity/sdk-react 2.10.0 → 2.11.0

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 {
-  useNormalizedResourceOptions,
-  type WithResourceNameSupport,
-} from '../helpers/useNormalizedResourceOptions'
+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 WithResourceNameSupport<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,7 +95,7 @@ export function useDocumentPreview({
   ref,
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
-  const instance = useSanityInstance(docHandle)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useDocumentPreview')
   const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 

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 {
-  useNormalizedResourceOptions,
-  type WithResourceNameSupport,
-} from '../helpers/useNormalizedResourceOptions'
+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 WithResourceNameSupport<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

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

package/src/hooks/projects/useProjects.ts

@@ -1,5 +1,4 @@
-import {type SanityProject} from '@sanity/client'
-import {getProjectsState, resolveProjects, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {getProjectsState, type Project, type ProjectsOptions, resolveProjects} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -7,24 +6,17 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * @public
  * @category Types
  * @interface
+ * @deprecated use the Project type directly.
  */
-export type ProjectWithoutMembers = Omit<SanityProject, 'members'>
-
-/**
- * @public
- * @category Types
- */
-type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
-  organizationId?: string
-  includeMembers?: TIncludeMembers
-}) => TIncludeMembers extends true ? SanityProject[] : ProjectWithoutMembers[]
+export type ProjectWithoutMembers = Project
 
 /**
  * Returns metadata for each project you have access to.
  *
  * @category Projects
  * @param options - Configuration options
- * @returns An array of project metadata. If includeMembers is true, returns full SanityProject objects. Otherwise, returns ProjectWithoutMembers objects.
+ * @returns An array of project metadata. `members` is included only when
+ *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
  * @example
  * ```tsx
  * const projects = useProjects()
@@ -39,18 +31,20 @@ type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
  * ```
  * @example
  * ```tsx
- * const projectsWithMembers = useProjects({ includeMembers: true })
- * const projectsWithoutMembers = useProjects({ includeMembers: false })
+ * const projects = useProjects()
+ * const projectsWithFeatures = useProjects()
+ * const projectsWithMembers = useProjects({includeMembers: true})
+ * const projectsWithoutMembers = useProjects({includeMembers: false})
+ * const projectsWithoutFeatures = useProjects({includeFeatures: false})
  * ```
  * @public
  * @function
  */
-export const useProjects: UseProjects = createStateSourceHook({
-  getState: getProjectsState as (
-    instance: SanityInstance,
-    options?: {organizationId?: string; includeMembers?: boolean},
-  ) => StateSource<SanityProject[] | ProjectWithoutMembers[]>,
-  shouldSuspend: (instance, options) =>
-    getProjectsState(instance, options).getCurrent() === undefined,
+export const useProjects = createStateSourceHook({
+  getState: getProjectsState,
+  shouldSuspend: (instance, ...params) =>
+    getProjectsState(instance, ...params).getCurrent() === undefined,
   suspender: resolveProjects,
-}) as UseProjects
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = true>(
+  options?: ProjectsOptions<IncludeMembers, IncludeFeatures>,
+) => Project<IncludeMembers, IncludeFeatures>[]

package/src/hooks/query/useQuery.ts

@@ -152,7 +152,7 @@ export function useQuery(options: WithResourceNameSupport<QueryOptions>): {
   isPending: boolean
 } {
   // Implementation returns unknown, overloads define specifics
-  const instance = useSanityInstance(options)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useQuery')
 
   // Normalize options: resolve resourceName to resource and strip resourceName

package/src/hooks/releases/useActiveReleases.ts

@@ -29,11 +29,11 @@ import {
  * const activeReleases = useActiveReleases()
  * ```
  */
-type UseActiveReleases = {
-  (options?: WithResourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+type UseActiveReleasesValue = {
+  (options?: {resource?: DocumentResource}): ReleaseDocument[]
 }
 
-const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
+const useActiveReleasesValue: UseActiveReleasesValue = createStateSourceHook({
   getState: getActiveReleasesState as (
     instance: SanityInstance,
     options?: {resource?: DocumentResource},
@@ -50,9 +50,9 @@ const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
  * @public
  * @function
  */
-export const useActiveReleases: UseActiveReleases = (
-  options: WithResourceNameSupport<{resource?: DocumentResource}> | undefined,
-) => {
+export function useActiveReleases(
+  options?: WithResourceNameSupport<SanityConfig> | undefined,
+): ReleaseDocument[] {
   const normalizedOptions = useNormalizedResourceOptions(options ?? {})
   return useActiveReleasesValue(normalizedOptions)
 }

package/src/hooks/releases/usePerspective.ts

@@ -1,5 +1,4 @@
 import {
-  type DatasetHandle,
   type DocumentResource,
   getPerspectiveState,
   type SanityInstance,
@@ -7,11 +6,9 @@ import {
 } from '@sanity/sdk'
 import {filter, firstValueFrom} from 'rxjs'
 
+import {type ResourceHandle} from '../../config/handles'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
-import {
-  useNormalizedResourceOptions,
-  type WithResourceNameSupport,
-} from '../helpers/useNormalizedResourceOptions'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -35,11 +32,11 @@ import {
  *
  * @returns The perspective for the given perspective handle.
  */
-type UsePerspective = {
-  (perspectiveHandle: DatasetHandle): string | string[]
+type UsePerspectiveValue = {
+  (perspectiveHandle: {resource?: DocumentResource}): string | string[]
 }
 
-const usePerspectiveValue: UsePerspective = createStateSourceHook({
+const usePerspectiveValue: UsePerspectiveValue = createStateSourceHook({
   getState: getPerspectiveState as (
     instance: SanityInstance,
     perspectiveHandle?: {resource?: DocumentResource},
@@ -54,9 +51,7 @@ const usePerspectiveValue: UsePerspective = createStateSourceHook({
  * @public
  * @function
  */
-export const usePerspective: UsePerspective = (
-  options: WithResourceNameSupport<DatasetHandle> | undefined,
-) => {
-  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
+export function usePerspective(perspectiveHandle?: ResourceHandle): string | string[] {
+  const normalizedOptions = useNormalizedResourceOptions(perspectiveHandle ?? {})
   return usePerspectiveValue(normalizedOptions)
 }

package/src/hooks/users/useUser.ts

@@ -59,7 +59,7 @@ export interface UserResult {
  * ```
  */
 export function useUser(options: GetUserOptions): UserResult {
-  const instance = useSanityInstance(options)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useUser')
   // Use React's useTransition to avoid UI jank when user options change
   const [isPending, startTransition] = useTransition()

package/src/hooks/users/useUsers.ts

@@ -69,7 +69,7 @@ export interface UsersResult {
  * ```
  */
 export function useUsers(options?: GetUsersOptions): UsersResult {
-  const instance = useSanityInstance(options)
+  const instance = useSanityInstance()
   trackHookUsage(instance, 'useUsers')
   // Use React's useTransition to avoid UI jank when user options change
   const [isPending, startTransition] = useTransition()