@sanity/sdk-react 0.0.0-alpha.3 → 0.0.0-alpha.30

package/src/hooks/query/useQuery.ts

@@ -0,0 +1,193 @@
+import {
+  getQueryKey,
+  getQueryState,
+  parseQueryKey,
+  type QueryOptions,
+  resolveQuery,
+} from '@sanity/sdk'
+import {type SanityQueryResult} from 'groq'
+import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+// Overload 1: Inferred Type (using Typegen)
+/**
+ * @beta
+ * Executes a GROQ query, inferring the result type from the query string and options.
+ * Leverages Sanity Typegen if configured for enhanced type safety.
+ *
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (typed based on the query) and `isPending` (for transitions).
+ *
+ * @example Basic usage (Inferred Type)
+ * ```tsx
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
+ *
+ * const myQuery = defineQuery(`*[_type == "movie"]{_id, title}`)
+ *
+ * function MovieList() {
+ *   // Typegen infers the return type for data
+ *   const {data} = useQuery({ query: myQuery })
+ *
+ *   return (
+ *     <div>
+ *       <h2>Movies</h2>
+ *       <ul>
+ *         {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * // Suspense boundary should wrap <MovieList /> for initial load
+ * ```
+ *
+ * @example Using parameters (Inferred Type)
+ * ```tsx
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
+ *
+ * const myQuery = defineQuery(`*[_type == "movie" && _id == $id][0]`)
+ *
+ * function MovieDetails({movieId}: {movieId: string}) {
+ *   // Typegen infers the return type based on query and params
+ *   const {data, isPending} = useQuery({
+ *     query: myQuery,
+ *     params: { id: movieId }
+ *   })
+ *
+ *   return (
+ *     // utilize `isPending` to signal to users that new data is coming in
+ *     // (e.g. the `movieId` changed and we're loading in the new one)
+ *     <div style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data ? <h1>{data.title}</h1> : <p>Movie not found</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useQuery<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: QueryOptions<TQuery, TDataset, TProjectId>,
+): {
+  /** The query result, typed based on the GROQ query string */
+  data: SanityQueryResult<TQuery, TDataset, TProjectId>
+  /** True if a query transition is in progress */
+  isPending: boolean
+}
+
+// Overload 2: Explicit Type Provided
+/**
+ * @beta
+ * Executes a GROQ query with an explicitly provided result type `TData`.
+ *
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (cast to `TData`) and `isPending` (indicates whether a query resolution is pending; note that Suspense handles initial loading states). *
+ * @example Manually typed query result
+ * ```tsx
+ * import {useQuery} from '@sanity/sdk-react'
+ *
+ * interface CustomMovieTitle {
+ *   movieTitle?: string
+ * }
+ *
+ * function FirstMovieTitle() {
+ *   // Provide the explicit type TData
+ *   const {data, isPending} = useQuery<CustomMovieTitle>({
+ *     query: '*[_type == "movie"][0]{ "movieTitle": title }'
+ *   })
+ *
+ *   return (
+ *     <h1 style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data?.movieTitle ?? 'No title found'}
+ *     </h1>
+ *   )
+ * }
+ * ```
+ */
+export function useQuery<TData>(options: QueryOptions): {
+  /** The query result, cast to the provided type TData */
+  data: TData
+  /** True if another query is resolving in the background (suspense handles the initial loading state) */
+  isPending: boolean
+}
+
+/**
+ * @beta
+ * Fetches data and subscribes to real-time updates using a GROQ query.
+ *
+ * @remarks
+ * This hook provides a convenient way to fetch data from your Sanity dataset and
+ * automatically receive updates in real-time when the queried data changes.
+ *
+ * Features:
+ * - Executes any valid GROQ query.
+ * - Subscribes to changes, providing real-time updates.
+ * - Integrates with React Suspense for handling initial loading states.
+ * - Uses React Transitions for managing loading states during query/parameter changes (indicated by `isPending`).
+ * - Supports type inference based on the GROQ query when using Sanity Typegen.
+ * - Allows specifying an explicit return type `TData` for the query result.
+ *
+ * @category GROQ
+ */
+export function useQuery(options: QueryOptions): {data: unknown; isPending: boolean} {
+  // Implementation returns unknown, overloads define specifics
+  const instance = useSanityInstance(options)
+
+  // Use React's useTransition to avoid UI jank when queries change
+  const [isPending, startTransition] = useTransition()
+
+  // Get the unique key for this query and its options
+  const queryKey = getQueryKey(options)
+  // Use a deferred state to avoid immediate re-renders when the query changes
+  const [deferredQueryKey, setDeferredQueryKey] = useState(queryKey)
+  // Parse the deferred query key back into a query and options
+  const deferred = useMemo(() => parseQueryKey(deferredQueryKey), [deferredQueryKey])
+
+  // Create an AbortController to cancel in-flight requests when needed
+  const ref = useRef<AbortController>(new AbortController())
+
+  // When the query or options change, start a transition to update the query
+  useEffect(() => {
+    if (queryKey === deferredQueryKey) return
+
+    startTransition(() => {
+      // Abort any in-flight requests for the previous query
+      if (ref && !ref.current.signal.aborted) {
+        ref.current.abort()
+        ref.current = new AbortController()
+      }
+
+      setDeferredQueryKey(queryKey)
+    })
+  }, [deferredQueryKey, queryKey])
+
+  // Get the state source for this query from the query store
+  const {getCurrent, subscribe} = useMemo(
+    () => getQueryState(instance, deferred),
+    [instance, deferred],
+  )
+
+  // If data isn't available yet, suspend rendering
+  if (getCurrent() === undefined) {
+    // Normally, reading from a mutable ref during render can be risky in concurrent mode.
+    // However, it is safe here because:
+    // 1. React guarantees that while the component is suspended (via throwing a promise),
+    //    no effects or state updates occur during that render pass.
+    // 2. We immediately capture the current abort signal in a local variable (currentSignal).
+    // 3. Even if a background render updates ref.current (for example, due to a query change),
+    //    the captured signal remains unchanged for this suspended render.
+    // Thus, the promise thrown here uses a stable abort signal, ensuring correct behavior.
+    const currentSignal = ref.current.signal
+    // eslint-disable-next-line react-compiler/react-compiler
+    throw resolveQuery(instance, {...deferred, signal: currentSignal})
+  }
+
+  // Subscribe to updates and get the current data
+  // useSyncExternalStore ensures the component re-renders when the data changes
+  const data = useSyncExternalStore(subscribe, getCurrent) as SanityQueryResult
+  return useMemo(() => ({data, isPending}), [data, isPending])
+}

package/src/hooks/releases/useActiveReleases.test.tsx

@@ -0,0 +1,84 @@
+import {getActiveReleasesState, type ReleaseDocument, type SanityInstance} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {BehaviorSubject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useActiveReleases} from './useActiveReleases'
+
+// Mock the useSanityInstance hook
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+// Mock the getActiveReleasesState function
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getActiveReleasesState: vi.fn(),
+  }
+})
+
+describe('useActiveReleases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should suspend when initial state is undefined', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockSubject = new BehaviorSubject<ReleaseDocument[] | undefined>(undefined)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => undefined),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getActiveReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => {
+      try {
+        return useActiveReleases()
+      } catch (e) {
+        return e
+      }
+    })
+
+    // Verify that the hook threw a promise (suspended)
+    expect(result.current).toBeInstanceOf(Promise)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+
+  it('should resolve with releases when data is available', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockReleases: ReleaseDocument[] = [
+      {_id: 'release1', _type: 'release'} as ReleaseDocument,
+      {_id: 'release2', _type: 'release'} as ReleaseDocument,
+    ]
+
+    const mockSubject = new BehaviorSubject<ReleaseDocument[]>(mockReleases)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => mockReleases),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getActiveReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => useActiveReleases())
+
+    // Verify that the hook returned the releases without suspending
+    expect(result.current).toEqual(mockReleases)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+})

package/src/hooks/releases/useActiveReleases.ts

@@ -0,0 +1,39 @@
+import {
+  getActiveReleasesState,
+  type ReleaseDocument,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * @public
+ */
+type UseActiveReleases = {
+  (): ReleaseDocument[]
+}
+
+/**
+ * @public
+
+ * Returns the active releases for the current project,
+ * represented as a list of release documents.
+ *
+ * @returns The active releases for the current project.
+ *
+ * @example
+ * ```tsx
+ * import {useActiveReleases} from '@sanity/sdk-react'
+ *
+ * const activeReleases = useActiveReleases()
+ * ```
+ */
+export const useActiveReleases: UseActiveReleases = createStateSourceHook({
+  getState: getActiveReleasesState as (instance: SanityInstance) => StateSource<ReleaseDocument[]>,
+  shouldSuspend: (instance: SanityInstance) =>
+    getActiveReleasesState(instance).getCurrent() === undefined,
+  suspender: (instance: SanityInstance) =>
+    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+})

package/src/hooks/releases/usePerspective.test.tsx

@@ -0,0 +1,120 @@
+import {type ClientPerspective} from '@sanity/client'
+import {
+  getActiveReleasesState,
+  getPerspectiveState,
+  type PerspectiveHandle,
+  type ReleaseDocument,
+  type SanityInstance,
+} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {BehaviorSubject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {usePerspective} from './usePerspective'
+
+// Mock the useSanityInstance hook
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+// Mock the SDK functions
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getPerspectiveState: vi.fn(),
+    // getPerspectiveState uses getActiveReleasesState
+    // to determine if it should suspend
+    getActiveReleasesState: vi.fn(),
+  }
+})
+
+describe('usePerspective', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should suspend when initial state is undefined', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const perspectiveHandle: PerspectiveHandle = {
+      perspective: 'published',
+    }
+
+    const mockSubject = new BehaviorSubject<ClientPerspective | undefined>(undefined)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => undefined),
+      observable: mockSubject,
+    }
+
+    // Mock the active releases observable for the suspender
+    const mockReleaseDoc: ReleaseDocument = {
+      _id: 'release1',
+      _type: 'release',
+      _createdAt: '2021-01-01T00:00:00Z',
+      _updatedAt: '2021-01-01T00:00:00Z',
+      _rev: 'rev1',
+      name: 'Test Release',
+      metadata: {
+        title: 'Test Release',
+        releaseType: 'asap',
+      },
+    }
+    const mockReleasesSubject = new BehaviorSubject([mockReleaseDoc])
+    const mockReleasesStateSource = {
+      subscribe: vi.fn(),
+      getCurrent: vi.fn(),
+      observable: mockReleasesSubject,
+    }
+
+    vi.mocked(getPerspectiveState).mockReturnValue(mockStateSource)
+    vi.mocked(getActiveReleasesState).mockReturnValue(mockReleasesStateSource)
+
+    const {result} = renderHook(() => {
+      try {
+        return usePerspective(perspectiveHandle)
+      } catch (e) {
+        return e
+      }
+    })
+
+    // Verify that the hook threw a promise (suspended)
+    expect(result.current).toBeInstanceOf(Promise)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+
+  it('should resolve with perspective when data is available', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const perspectiveHandle: PerspectiveHandle = {
+      perspective: 'published',
+    }
+
+    const mockPerspective: ClientPerspective = 'published'
+    const mockSubject = new BehaviorSubject<ClientPerspective>(mockPerspective)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => mockPerspective),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getPerspectiveState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => usePerspective(perspectiveHandle))
+
+    // Verify that the hook returned the perspective without suspending
+    expect(result.current).toEqual(mockPerspective)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+    expect(getPerspectiveState).toHaveBeenCalledWith(mockInstance, perspectiveHandle)
+  })
+})

package/src/hooks/releases/usePerspective.ts

@@ -0,0 +1,49 @@
+import {
+  getActiveReleasesState,
+  getPerspectiveState,
+  type PerspectiveHandle,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * @public
+ */
+type UsePerspective = {
+  (perspectiveHandle: PerspectiveHandle): string | string[]
+}
+
+/**
+ * @public
+ *
+ * Returns a single or stack of perspectives for the given perspective handle,
+ * which can then be used to correctly query the documents
+ * via the `perspective` parameter in the client.
+ *
+ * @param perspectiveHandle - The perspective handle to get the perspective for.
+ *
+ * @example
+ * ```tsx
+ * import {usePerspective, useQuery} from '@sanity/sdk-react'
+
+ * const perspective = usePerspective({perspective: 'rxg1346', projectId: 'abc123', dataset: 'production'})
+ * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
+ *   perspective: perspective,
+ * })
+ * ```
+ *
+ * @returns The perspective for the given perspective handle.
+ */
+export const usePerspective: UsePerspective = createStateSourceHook({
+  getState: getPerspectiveState as (
+    instance: SanityInstance,
+    perspectiveHandle?: PerspectiveHandle,
+  ) => StateSource<string | string[]>,
+  shouldSuspend: (instance: SanityInstance, options?: PerspectiveHandle): boolean =>
+    getPerspectiveState(instance, options).getCurrent() === undefined,
+  suspender: (instance: SanityInstance, _options?: PerspectiveHandle) =>
+    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+})