@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.1

package/src/hooks/projects/useProject.test.tsx

@@ -0,0 +1,120 @@
+import {createSanityInstance, type Project, project, type StateSource} from '@sanity/sdk'
+import {type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {type ReactNode} from 'react'
+import {type Observable} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useProject} from './useProject'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, project: {getState: vi.fn(), resolveState: vi.fn()}}
+})
+
+const stateSource = (current: Project | undefined): StateSource<FetcherSnapshot<Project>> => {
+  // Cache the snapshot: useSyncExternalStore requires a referentially stable current value.
+  const snapshot = current
+    ? {status: 'success', data: current, error: undefined, isFetching: false, dataUpdatedAt: 1}
+    : {
+        status: 'pending',
+        data: undefined,
+        error: undefined,
+        isFetching: true,
+        dataUpdatedAt: undefined,
+      }
+  return {
+    getCurrent: vi.fn(() => snapshot),
+    subscribe: vi.fn(() => () => {}),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  } as unknown as StateSource<FetcherSnapshot<Project>>
+}
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useProject', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(project.getState).mockReturnValue(stateSource({id: 'p'} as unknown as Project))
+  })
+
+  it('resolves the projectId from the instance config resource', () => {
+    // test-utils wraps with ResourceProvider projectId="test" dataset="test".
+    renderHook(() => useProject())
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'test'}),
+    )
+  })
+
+  it('lets an explicit projectId override the ambient resource', () => {
+    renderHook(() => useProject({projectId: 'explicit-project'}))
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'explicit-project'}),
+    )
+  })
+
+  it('resolves the projectId from an explicit resource when the config has none', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider
+          resource={{projectId: 'resource-project', dataset: 'production'}}
+          fallback={null}
+        >
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'resource-project'}),
+    )
+  })
+
+  it('resolves a dataset-less projectId config for project-scoped use', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider projectId="config-project" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    // A dataset-less config can't form a DatasetResource; the projectId is carried
+    // via ProjectContext and injected so project-scoped reads still resolve it.
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'config-project'}),
+    )
+  })
+
+  it('resolves a bare projectId from a ResourceProvider when the parent instance has no config', () => {
+    // An instance with no project/dataset config and no ambient
+    // resource, then a projectId-only ResourceProvider.
+    const emptyInstance = createSanityInstance({})
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <SanityInstanceContext.Provider value={emptyInstance}>
+          <ResourceProvider projectId="bare-project" fallback={null}>
+            {children}
+          </ResourceProvider>
+        </SanityInstanceContext.Provider>
+      ),
+    })
+    expect(project.getState).toHaveBeenCalledWith(
+      emptyInstance,
+      expect.objectContaining({projectId: 'bare-project'}),
+    )
+  })
+
+  it('suspends via the project fetcher until project data is available', () => {
+    vi.mocked(project.getState).mockReturnValue(stateSource(undefined))
+    vi.mocked(project.resolveState).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useProject())
+    expect(project.resolveState).toHaveBeenCalled()
+  })
+})

package/src/hooks/projects/useProject.ts

@@ -1,50 +1,49 @@
-import {
-  getProjectState,
-  type ProjectHandle,
-  resolveProject,
-  type SanityInstance,
-  type SanityProject,
-  type StateSource,
-} from '@sanity/sdk'
+import {type Project, project, type ProjectOptions} from '@sanity/sdk'
 
-import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useResolvedProjectId} from '../helpers/useResolvedProjectId'
 
-type UseProject = {
-  /**
-   *
-   * Returns metadata for a given project
-   *
-   * @category Projects
-   * @param projectHandle - An optional project handle identifying which 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
-}
+const useProjectBase = createFetcherHook(project)
 
 /**
+ * Returns metadata for a given project.
+ *
+ * @category Projects
+ * @param options - Configuration options
+ * @returns A {@link FetcherHookResult} whose `data` is 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 {data: project} = useProject({projectId})
+ *
+ *   return (
+ *     <figure style={{backgroundColor: project.metadata.color || 'lavender'}}>
+ *       <h1>{project.displayName}</h1>
+ *     </figure>
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const {data: projectWithMembersAndFeatures} = useProject({projectId})
+ * const {data: projectWithMembers} = useProject({projectId, includeMembers: true})
+ * const {data: projectWithoutMembers} = useProject({projectId, includeMembers: false})
+ * const {data: projectWithoutFeatures} = useProject({projectId, includeFeatures: false})
+ * ```
+ * @remarks
+ * The `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  * @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: SanityInstance, projectHandle?: ProjectHandle) =>
-    getProjectState(instance, projectHandle as ProjectHandle).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, projectHandle?: ProjectHandle) =>
-    resolveProject(instance, projectHandle as ProjectHandle),
-}) as UseProject
+export const useProject = ((options?: ProjectOptions<boolean, boolean>) => {
+  const projectId = useResolvedProjectId(options)
+  return useProjectBase(projectId ? {...options, projectId} : options)
+}) as <IncludeMembers extends boolean = true, IncludeFeatures extends boolean = true>(
+  options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>>

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

@@ -0,0 +1,60 @@
+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().data).toEqualTypeOf<Project<false, true>[]>()
+})
+
+test('useProjects — returns the FetcherHookResult envelope', () => {
+  const result = useProjects()
+  expectTypeOf(result.isFetching).toEqualTypeOf<boolean>()
+  expectTypeOf(result.error).toEqualTypeOf<unknown>()
+  expectTypeOf(result.refetch).toEqualTypeOf<() => Promise<Project<false, true>[]>>()
+})
+
+test('useProjects — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useProjects({includeMembers: true}).data).toEqualTypeOf<Project<true, true>[]>()
+  type Result = ReturnType<typeof useProjects<true, true>>
+  expectTypeOf<Result['data'][number]['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('useProjects — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(useProjects({includeFeatures: false}).data).toEqualTypeOf<Project<false, false>[]>()
+})
+
+test('useProjects — both flags true → both arrays present', () => {
+  expectTypeOf(useProjects({includeMembers: true, includeFeatures: true}).data).toEqualTypeOf<
+    Project<true, true>[]
+  >()
+})
+
+test('useProjects — both flags false → bare base shape', () => {
+  expectTypeOf(useProjects({includeMembers: false, includeFeatures: false}).data).toEqualTypeOf<
+    Project<false, false>[]
+  >()
+  type Result = ReturnType<typeof useProjects<false, false>>
+  expectTypeOf<Result['data'][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'}).data).toEqualTypeOf<
+    Project<false, true>[]
+  >()
+})
+
+test('useProjects — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useProjects({includeMembers}).data).toEqualTypeOf<Project<boolean, true>[]>()
+  type Result = ReturnType<typeof useProjects<boolean, true>>
+  expectTypeOf<Result['data'][number]['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Pick<Result['data'][number], 'members'>>().toEqualTypeOf<{
+    members?: ProjectMember[]
+  }>()
+})

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

@@ -1,112 +1,59 @@
-import {getProjectsState, type SanityInstance} from '@sanity/sdk'
+import {type Project, projects, type StateSource} from '@sanity/sdk'
+import {type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {type Observable} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {renderHook} from '../../../test/test-utils'
+import {useProjects} from './useProjects'
 
-// Mock dependencies
-vi.mock('@sanity/sdk', () => ({
-  getProjectsState: vi.fn(() => ({
-    getCurrent: vi.fn(() => undefined), // Mocking getCurrent to satisfy the call within shouldSuspend
-  })),
-  resolveProjects: vi.fn(),
-}))
-vi.mock('../helpers/createStateSourceHook', () => ({
-  createStateSourceHook: vi.fn(),
-}))
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, projects: {getState: vi.fn(), resolveState: vi.fn(), refetch: vi.fn()}}
+})
+
+const stateSource = (current: Project[] | undefined): StateSource<FetcherSnapshot<Project[]>> => {
+  const snapshot = current
+    ? {status: 'success', data: current, error: undefined, isFetching: false, dataUpdatedAt: 1}
+    : {
+        status: 'pending',
+        data: undefined,
+        error: undefined,
+        isFetching: true,
+        dataUpdatedAt: undefined,
+      }
+  return {
+    getCurrent: vi.fn(() => snapshot),
+    subscribe: vi.fn(() => () => {}),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  } as unknown as StateSource<FetcherSnapshot<Project[]>>
+}
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
 
 describe('useProjects', () => {
-  // Use beforeEach to reset modules and ensure mocks are fresh for each test
   beforeEach(() => {
-    vi.resetModules()
-    // Re-mock dependencies for each test after resetModules
-    vi.mock('@sanity/sdk', () => ({
-      getProjectsState: vi.fn(() => ({
-        getCurrent: vi.fn(() => undefined),
-      })),
-      resolveProjects: vi.fn(),
-    }))
-    vi.mock('../helpers/createStateSourceHook', () => ({
-      createStateSourceHook: vi.fn(),
-    }))
-  })
-
-  it('should call createStateSourceHook with correct arguments on import', async () => {
-    // Dynamically import the hook *after* mocks are set up and modules reset
-    await import('./useProjects')
-
-    // Check if createStateSourceHook was called during the module evaluation (import)
-    expect(createStateSourceHook).toHaveBeenCalled()
-    expect(createStateSourceHook).toHaveBeenCalledWith(
-      expect.objectContaining({
-        getState: expect.any(Function),
-        shouldSuspend: expect.any(Function),
-        suspender: expect.any(Function), // Actual function reference doesn't matter here as it's mocked
-        // Note: getConfig is not used in useProjects
-      }),
-    )
+    vi.clearAllMocks()
+    vi.mocked(projects.getState).mockReturnValue(stateSource([{id: 'a'}] as unknown as Project[]))
   })
 
-  it('shouldSuspend should call getProjectsState and getCurrent', async () => {
-    // Dynamically import the hook *after* mocks are set up and modules reset
-    await import('./useProjects')
-
-    // Get the arguments passed to createStateSourceHook
-    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
-
-    // Mock instance for the test call
-    const mockInstance = {} as SanityInstance // Use specific type
-
-    // 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, undefined)
-
-    // Assert that getCurrent was called on the result of getProjectsState
-    expect(mockGetProjectsState.mock.results.length).toBeGreaterThan(0)
-    const getProjectsStateMockResult = mockGetProjectsState.mock.results[0].value
-    expect(getProjectsStateMockResult.getCurrent).toHaveBeenCalled()
-
-    // Assert the result of shouldSuspend based on the mocked getCurrent value
-    expect(result).toBe(true) // Since getCurrent is mocked to return undefined
+  it('reads the projects fetcher with the passed options', () => {
+    renderHook(() => useProjects({organizationId: 'org123'}))
+    expect(projects.getState).toHaveBeenCalledWith(sanityInstance, {organizationId: 'org123'})
   })
 
-  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('returns the fetcher data in the result envelope', () => {
+    const {result} = renderHook(() => useProjects())
+    expect(result.current.data).toEqual([{id: 'a'}])
+    expect(result.current.isFetching).toBe(false)
+    expect(typeof result.current.refetch).toBe('function')
   })
 
-  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()
+  it('suspends via the projects fetcher until data is available', () => {
+    vi.mocked(projects.getState).mockReturnValue(stateSource(undefined))
+    vi.mocked(projects.resolveState).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useProjects())
+    expect(projects.resolveState).toHaveBeenCalled()
   })
 })

package/src/hooks/projects/useProjects.ts

@@ -1,33 +1,26 @@
-import {type SanityProject} from '@sanity/client'
-import {getProjectsState, resolveProjects, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {type Project, projects, type ProjectsOptions} from '@sanity/sdk'
 
-import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
 
 /**
  * @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 A {@link FetcherHookResult} whose `data` is an array of project
+ *   metadata. `members` is included only when `includeMembers: true`; `features`
+ *   is included unless `includeFeatures: false`.
  * @example
  * ```tsx
- * const projects = useProjects()
+ * const {data: projects} = useProjects()
  *
  * return (
  *   <select>
@@ -39,18 +32,18 @@ type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
  * ```
  * @example
  * ```tsx
- * const projectsWithMembers = useProjects({ includeMembers: true })
- * const projectsWithoutMembers = useProjects({ includeMembers: false })
+ * const {data: projects} = useProjects()
+ * const {data: projectsWithFeatures} = useProjects()
+ * const {data: projectsWithMembers} = useProjects({includeMembers: true})
+ * const {data: projectsWithoutMembers} = useProjects({includeMembers: false})
+ * const {data: 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,
-  suspender: resolveProjects,
-}) as UseProjects
+export const useProjects = createFetcherHook(projects) as <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = true,
+>(
+  options?: ProjectsOptions<IncludeMembers, IncludeFeatures>,
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>[]>

package/src/hooks/query/useQuery.test.tsx

@@ -33,7 +33,7 @@ describe('useQuery', () => {
     } as StateSource<unknown>)
 
     function TestComponent() {
-      const {data, isPending} = useQuery<string>({query: 'test query'})
+      const {data, isPending} = useQuery({query: 'test query'})
       return (
         <div data-testid="output">
           {data} - {isPending ? 'pending' : 'not pending'}
@@ -42,7 +42,7 @@ describe('useQuery', () => {
     }
 
     render(
-      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={<p>Loading...</p>}>
+      <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading...</p>}>
         <TestComponent />
       </ResourceProvider>,
     )
@@ -82,13 +82,14 @@ describe('useQuery', () => {
     )
 
     function TestComponent() {
-      const {data} = useQuery<string>({query: 'test query'})
+      const {data} = useQuery({query: 'test query'})
       return <div data-testid="output">{data}</div>
     }
 
     render(
       <ResourceProvider
-        resource={{projectId: 'p', dataset: 'd'}}
+        projectId="p"
+        dataset="d"
         fallback={<div data-testid="fallback">Loading...</div>}
       >
         <TestComponent />
@@ -163,7 +164,7 @@ describe('useQuery', () => {
     }
 
     render(
-      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={<p>Loading...</p>}>
+      <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading...</p>}>
         <WrapperComponent />
       </ResourceProvider>,
     )