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

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

@@ -1,10 +1,5 @@
-import {
-  createSanityInstance,
-  getProjectState,
-  type Project,
-  resolveProject,
-  type StateSource,
-} from '@sanity/sdk'
+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'
@@ -16,30 +11,41 @@ import {useProject} from './useProject'
 
 vi.mock('@sanity/sdk', async (importOriginal) => {
   const original = await importOriginal<typeof import('@sanity/sdk')>()
-  return {...original, getProjectState: vi.fn(), resolveProject: vi.fn()}
+  return {...original, project: {getState: vi.fn(), resolveState: vi.fn()}}
 })
 
-const stateSource = (current: Project | undefined): StateSource<Project | undefined> =>
-  ({
-    getCurrent: vi.fn(() => current),
-    subscribe: 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<Project | undefined>
+  } as unknown as StateSource<FetcherSnapshot<Project>>
+}
 
 const sanityInstance = expect.objectContaining({config: expect.any(Object)})
 
 describe('useProject', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    vi.mocked(getProjectState).mockReturnValue(stateSource({id: 'p'} as unknown as Project))
+    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(getProjectState).toHaveBeenCalledWith(
+    expect(project.getState).toHaveBeenCalledWith(
       sanityInstance,
       expect.objectContaining({projectId: 'test'}),
     )
@@ -47,7 +53,7 @@ describe('useProject', () => {
 
   it('lets an explicit projectId override the ambient resource', () => {
     renderHook(() => useProject({projectId: 'explicit-project'}))
-    expect(getProjectState).toHaveBeenCalledWith(
+    expect(project.getState).toHaveBeenCalledWith(
       sanityInstance,
       expect.objectContaining({projectId: 'explicit-project'}),
     )
@@ -64,7 +70,7 @@ describe('useProject', () => {
         </ResourceProvider>
       ),
     })
-    expect(getProjectState).toHaveBeenCalledWith(
+    expect(project.getState).toHaveBeenCalledWith(
       sanityInstance,
       expect.objectContaining({projectId: 'resource-project'}),
     )
@@ -80,7 +86,7 @@ describe('useProject', () => {
     })
     // 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(getProjectState).toHaveBeenCalledWith(
+    expect(project.getState).toHaveBeenCalledWith(
       sanityInstance,
       expect.objectContaining({projectId: 'config-project'}),
     )
@@ -99,16 +105,16 @@ describe('useProject', () => {
         </SanityInstanceContext.Provider>
       ),
     })
-    expect(getProjectState).toHaveBeenCalledWith(
+    expect(project.getState).toHaveBeenCalledWith(
       emptyInstance,
       expect.objectContaining({projectId: 'bare-project'}),
     )
   })
 
-  it('suspends via resolveProject until project data is available', () => {
-    vi.mocked(getProjectState).mockReturnValue(stateSource(undefined))
-    vi.mocked(resolveProject).mockReturnValue(new Promise(() => {}))
+  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(resolveProject).toHaveBeenCalled()
+    expect(project.resolveState).toHaveBeenCalled()
   })
 })

package/src/hooks/projects/useProject.ts

@@ -1,26 +1,22 @@
-import {getProjectState, type Project, type ProjectOptions, resolveProject} 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'
 
-const useProjectBase = createStateSourceHook({
-  getState: getProjectState,
-  shouldSuspend: (instance, ...params) =>
-    getProjectState(instance, ...params).getCurrent() === undefined,
-  suspender: resolveProject,
-})
+const useProjectBase = createFetcherHook(project)
 
 /**
  * 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`.
+ * @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 project = useProject({projectId})
+ *   const {data: project} = useProject({projectId})
  *
  *   return (
  *     <figure style={{backgroundColor: project.metadata.color || 'lavender'}}>
@@ -31,10 +27,10 @@ const useProjectBase = createStateSourceHook({
  * ```
  * @example
  * ```tsx
- * const projectWithMembersAndFeatures = useProject({projectId})
- * const projectWithMembers = useProject({projectId, includeMembers: true})
- * const projectWithoutMembers = useProject({projectId, includeMembers: false})
- * const projectWithoutFeatures = useProject({projectId, includeFeatures: false})
+ * 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:
@@ -50,4 +46,4 @@ export const useProject = ((options?: ProjectOptions<boolean, boolean>) => {
   return useProjectBase(projectId ? {...options, projectId} : options)
 }) as <IncludeMembers extends boolean = true, IncludeFeatures extends boolean = true>(
   options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
-) => Project<IncludeMembers, IncludeFeatures>
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>>

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

@@ -4,31 +4,38 @@ import {expectTypeOf, test} from 'vitest'
 import {useProjects} from './useProjects'
 
 test('useProjects — no args: features included, members omitted', () => {
-  expectTypeOf(useProjects()).toEqualTypeOf<Project<false, true>[]>()
+  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})).toEqualTypeOf<Project<true, true>[]>()
+  expectTypeOf(useProjects({includeMembers: true}).data).toEqualTypeOf<Project<true, true>[]>()
   type Result = ReturnType<typeof useProjects<true, true>>
-  expectTypeOf<Result[number]['members']>().toEqualTypeOf<ProjectMember[]>()
+  expectTypeOf<Result['data'][number]['members']>().toEqualTypeOf<ProjectMember[]>()
 })
 
 test('useProjects — includeFeatures: false drops features from the type', () => {
-  expectTypeOf(useProjects({includeFeatures: false})).toEqualTypeOf<Project<false, false>[]>()
+  expectTypeOf(useProjects({includeFeatures: false}).data).toEqualTypeOf<Project<false, false>[]>()
 })
 
 test('useProjects — both flags true → both arrays present', () => {
-  expectTypeOf(useProjects({includeMembers: true, includeFeatures: true})).toEqualTypeOf<
+  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})).toEqualTypeOf<
+  expectTypeOf(useProjects({includeMembers: false, includeFeatures: false}).data).toEqualTypeOf<
     Project<false, false>[]
   >()
   type Result = ReturnType<typeof useProjects<false, false>>
-  expectTypeOf<Result[number]['id']>().toEqualTypeOf<string>()
+  expectTypeOf<Result['data'][number]['id']>().toEqualTypeOf<string>()
 })
 
 test('useProjects — rejects non-boolean flag values', () => {
@@ -37,13 +44,17 @@ test('useProjects — rejects non-boolean flag values', () => {
 })
 
 test('useProjects — organizationId alone does not change the data shape', () => {
-  expectTypeOf(useProjects({organizationId: 'org_123'})).toEqualTypeOf<Project<false, true>[]>()
+  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})).toEqualTypeOf<Project<boolean, true>[]>()
+  expectTypeOf(useProjects({includeMembers}).data).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[]}>()
+  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,6 +1,6 @@
-import {getProjectsState, type Project, type ProjectsOptions, resolveProjects} 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
@@ -15,11 +15,12 @@ export type ProjectWithoutMembers = Project
  *
  * @category Projects
  * @param options - Configuration options
- * @returns An array of project metadata. `members` is included only when
- *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
+ * @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>
@@ -31,20 +32,18 @@ export type ProjectWithoutMembers = Project
  * ```
  * @example
  * ```tsx
- * const projects = useProjects()
- * const projectsWithFeatures = useProjects()
- * const projectsWithMembers = useProjects({includeMembers: true})
- * const projectsWithoutMembers = useProjects({includeMembers: false})
- * const projectsWithoutFeatures = useProjects({includeFeatures: 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 = createStateSourceHook({
-  getState: getProjectsState,
-  shouldSuspend: (instance, ...params) =>
-    getProjectsState(instance, ...params).getCurrent() === undefined,
-  suspender: resolveProjects,
-}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = true>(
+export const useProjects = createFetcherHook(projects) as <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = true,
+>(
   options?: ProjectsOptions<IncludeMembers, IncludeFeatures>,
-) => Project<IncludeMembers, IncludeFeatures>[]
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>[]>