@sanity/sdk-react 2.6.0 → 2.8.0

package/src/hooks/helpers/useNormalizedSourceOptions.ts

@@ -0,0 +1,85 @@
+import {type DocumentSource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {SourcesContext} from '../../context/SourcesContext'
+
+/**
+ * Adds React hook support (sourceName resolution) to core types.
+ * This wrapper allows hooks to accept `sourceName` as a convenience,
+ * which is then resolved to a `DocumentSource` at the React layer.
+ * For now, we are trying to avoid source name resolution in core --
+ * functions having sources explicitly passed will reduce complexity.
+ *
+ * @typeParam T - The core type to extend (must have optional `source` field)
+ * @beta
+ */
+export type WithSourceNameSupport<T extends {source?: DocumentSource}> = T & {
+  /**
+   * Optional name of a source to resolve from context.
+   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
+   * @beta
+   */
+  sourceName?: string
+}
+
+/**
+ * Normalizes hook options by resolving `sourceName` to a `DocumentSource`.
+ * This hook ensures that options passed to core layer functions only contain
+ * `source` (never `sourceName`), preventing duplicate cache keys and maintaining
+ * clean separation between React and core layers.
+ *
+ * @typeParam T - The options type (must include optional source field)
+ * @param options - Hook options that may include `sourceName` and/or `source`
+ * @returns Normalized options with `sourceName` removed and `source` resolved
+ *
+ * @remarks
+ * Resolution priority:
+ * 1. If `sourceName` is provided, resolves it via `SourcesContext` and uses that
+ * 2. Otherwise, uses the inline `source` if provided
+ * 3. If neither is provided, returns options without a source field
+ *
+ * @example
+ * ```tsx
+ * function useQuery(options: WithSourceNameSupport<QueryOptions>) {
+ *   const instance = useSanityInstance(options)
+ *   const normalized = useNormalizedOptions(options)
+ *   // normalized now has source but never sourceName
+ *   const queryKey = getQueryKey(normalized)
+ * }
+ * ```
+ *
+ * @beta
+ */
+export function useNormalizedSourceOptions<
+  T extends {source?: DocumentSource; sourceName?: string},
+>(options: T): Omit<T, 'sourceName'> {
+  const {sourceName, ...rest} = options
+  if (sourceName && Object.hasOwn(options, 'source')) {
+    throw new Error(
+      `Source name ${JSON.stringify(sourceName)} and source ${JSON.stringify(options.source)} cannot be used together.`,
+    )
+  }
+
+  // Resolve sourceName to source via context
+  const sources = useContext(SourcesContext)
+  let resolvedSource: DocumentSource | undefined
+
+  if (options.source) {
+    resolvedSource = options.source
+  }
+
+  if (sourceName && !Object.hasOwn(sources, sourceName)) {
+    throw new Error(
+      `There's no source named ${JSON.stringify(sourceName)} in context. Please use <SourceProvider>.`,
+    )
+  }
+
+  if (sourceName && sources[sourceName]) {
+    resolvedSource = sources[sourceName]
+  }
+
+  return {
+    ...rest,
+    source: resolvedSource,
+  }
+}

package/src/hooks/projection/useDocumentProjection.ts

@@ -4,6 +4,10 @@ import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
 
 /**
  * @public
@@ -14,7 +18,7 @@ export interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
+> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -183,15 +187,22 @@ 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)
+
   // Memoize stateSource based on normalized projection and docHandle properties
   // This prevents creating a new StateSource on every render when projection content is the same
   const stateSource = useMemo(
-    () => getProjectionState<TData>(instance, {...docHandle, projection: normalizedProjection}),
-    [instance, normalizedProjection, docHandle],
+    () =>
+      getProjectionState<TData>(instance, {
+        ...normalizedDocHandle,
+        projection: normalizedProjection,
+      }),
+    [instance, normalizedDocHandle, normalizedProjection],
   )
 
   if (stateSource.getCurrent()?.data === null) {
-    throw resolveProjection(instance, {...docHandle, projection: normalizedProjection})
+    throw resolveProjection(instance, {...normalizedDocHandle, projection: normalizedProjection})
   }
 
   // Create subscribe function for useSyncExternalStore

package/src/hooks/query/useQuery.ts

@@ -9,16 +9,19 @@ import {type SanityQueryResult} from 'groq'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
-import {useSource} from '../context/useSource'
-
-interface UseQueryOptions<
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
+/**
+ * Hook options for useQuery, supporting both direct source and sourceName.
+ * @beta
+ */
+type UseQueryOptions<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-  TSourceName extends string = string,
-> extends QueryOptions<TQuery, TDataset, TProjectId> {
-  sourceName?: TSourceName
-}
+> = WithSourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
 
 // Overload 1: Inferred Type (using Typegen)
 /**
@@ -80,9 +83,8 @@ export function useQuery<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-  TSourceName extends string = string,
 >(
-  options: UseQueryOptions<TQuery, TDataset, TProjectId, TSourceName>,
+  options: UseQueryOptions<TQuery, TDataset, TProjectId>,
 ): {
   /** The query result, typed based on the GROQ query string */
   data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
@@ -119,7 +121,7 @@ export function useQuery<
  * }
  * ```
  */
-export function useQuery<TData>(options: QueryOptions): {
+export function useQuery<TData>(options: WithSourceNameSupport<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) */
@@ -144,17 +146,21 @@ export function useQuery<TData>(options: QueryOptions): {
  *
  * @category GROQ
  */
-export function useQuery(options: QueryOptions): {data: unknown; isPending: boolean} {
+export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
+  data: unknown
+  isPending: boolean
+} {
   // Implementation returns unknown, overloads define specifics
   const instance = useSanityInstance(options)
 
-  const source = useSource(options)
+  // Normalize options: resolve sourceName to source and strip sourceName
+  const normalized = useNormalizedSourceOptions(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)
+  // Get the unique key for this query and its options (using normalized options)
+  const queryKey = getQueryKey(normalized)
   // Use a deferred state to avoid immediate re-renders when the query changes
   const [deferredQueryKey, setDeferredQueryKey] = useState(queryKey)
 
@@ -180,8 +186,8 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
   // Memoize the options object by depending on the stable string key instead of the parsed object
   const {getCurrent, subscribe} = useMemo(() => {
     const deferred = parseQueryKey(deferredQueryKey)
-    return getQueryState(instance, {...deferred, source})
-  }, [instance, deferredQueryKey, source])
+    return getQueryState(instance, deferred)
+  }, [instance, deferredQueryKey])
 
   // If data isn't available yet, suspend rendering
   if (getCurrent() === undefined) {
@@ -196,7 +202,7 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
     const currentSignal = ref.current.signal
     const deferred = parseQueryKey(deferredQueryKey)
 
-    throw resolveQuery(instance, {...deferred, source, signal: currentSignal})
+    throw resolveQuery(instance, {...deferred, signal: currentSignal})
   }
 
   // Subscribe to updates and get the current data

package/src/hooks/context/useSource.tsx

@@ -1,34 +0,0 @@
-import {type DatasetHandle, type DocumentHandle, type DocumentSource} from '@sanity/sdk'
-import {useContext} from 'react'
-
-import {SourcesContext} from '../../context/SourcesContext'
-
-/** Retrieves the named source from context.
- * @beta
- * @param name - The name of the source to retrieve.
- * @returns The source.
- * @example
- * ```tsx
- * const source = useSource('my-source')
- * ```
- */
-export function useSource(options: DocumentHandle | DatasetHandle): DocumentSource | undefined {
-  const sources = useContext(SourcesContext)
-
-  // this might return the "default" source in the future once we implement it?
-  if (!options.sourceName && !options.source) {
-    return undefined
-  }
-
-  if (options.source) {
-    return options.source
-  }
-
-  if (options.sourceName && !Object.hasOwn(sources, options.sourceName)) {
-    throw new Error(
-      `There's no source named ${JSON.stringify(options.sourceName)} in context. Please use <SourceProvider>.`,
-    )
-  }
-
-  return options.sourceName ? sources[options.sourceName] : undefined
-}