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

package/src/hooks/document/useDocument.ts

@@ -1,8 +1,9 @@
-import {type DocumentOptions, getDocumentState, type JsonMatch, resolveDocument} from '@sanity/sdk'
-import {type SanityDocument} from 'groq'
-import {identity} from 'rxjs'
+import {type DocumentOptions, getDocumentState, resolveDocument} from '@sanity/sdk'
+import {type SanityDocument} from '@sanity/types'
 
+import {type DocumentHandle} from '../../config/handles'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 // used in an `{@link useDocumentProjection}` and `{@link useQuery}`
 // eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
 import type {useDocumentProjection} from '../projection/useDocumentProjection'
@@ -19,9 +20,6 @@ const useDocumentValue = createStateSourceHook({
   // Extract handle part for resolveDocument
   suspender: (instance, options: DocumentOptions<string | undefined>) =>
     resolveDocument(instance, options),
-  getConfig: identity as (
-    options: DocumentOptions<string | undefined>,
-  ) => DocumentOptions<string | undefined>,
 })
 
 const wrapHookWithData = <TParams extends unknown[], TReturn>(
@@ -33,184 +31,132 @@ const wrapHookWithData = <TParams extends unknown[], TReturn>(
   return useHook
 }
 
-interface UseDocument {
-  /** @internal */
-  <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
-    options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-  ): {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
-
-  /** @internal */
-  <
-    TPath extends string,
-    TDocumentType extends string,
-    TDataset extends string = string,
-    TProjectId extends string = string,
-  >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): {
-    data: JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
-  }
-
-  /** @internal */
-  <TData>(options: DocumentOptions<undefined>): {data: TData | null}
-  /** @internal */
-  <TData>(options: DocumentOptions<string>): {data: TData | undefined}
+type UseDocumentOptions<
+  TPath extends string | undefined = undefined,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = DocumentHandle<TDocumentType, TDataset, TProjectId> & {path?: TPath}
 
+interface UseDocument {
   /**
-   * ## useDocument via Type Inference (Recommended)
-   *
    * @public
    *
-   * The preferred way to use this hook when working with Sanity Typegen.
+   * ## useDocument with Explicit Types (no path)
    *
-   * Features:
-   * - Automatically infers document types from your schema
-   * - Provides type-safe access to documents and nested fields
-   * - Supports project/dataset-specific type inference
-   * - Works seamlessly with Typegen-generated types
-   *
-   * This hook will suspend while the document data is being fetched and loaded.
-   *
-   * When fetching a full document:
-   * - Returns the complete document object if it exists
-   * - Returns `null` if the document doesn't exist
+   * Provide an explicit type parameter `TData` to type the returned document data.
+   * You can define your own interfaces or use types generated by your Sanity Studio.
    *
-   * When fetching with a path:
-   * - Returns the value at the specified path if both the document and path exist
-   * - Returns `undefined` if either the document doesn't exist or the path doesn't exist in the document
+   * This hook will suspend while the document data is being fetched.
    *
-   * @category Documents
+   * @typeParam TData - The explicit type for the document
    * @param options - Configuration including `documentId`, `documentType`, and optionally:
-   *   - `path`: To select a nested value (returns typed value at path)
    *   - `projectId`/`dataset`: For multi-project/dataset setups
-   * @returns The document state (or nested value if path provided).
+   * @returns The document state
    *
-   * @example Basic document fetch
+   * @example Basic document fetch with explicit type
    * ```tsx
-   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   * import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
    *
-   * interface ProductViewProps {
-   *   doc: DocumentHandle<'product'> // Typegen infers product type
+   * interface Book extends SanityDocument {
+   *   _type: 'book'
+   *   title: string
+   *   author: string
    * }
    *
-   * function ProductView({doc}: ProductViewProps) {
-   *   const {data: product} = useDocument({...doc}) // Fully typed product
-   *   return <h1>{product.title ?? 'Untitled'}</h1>
+   * interface BookViewProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function BookView({doc}: BookViewProps) {
+   *   const {data: book} = useDocument<Book>({...doc})
+   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
    * }
    * ```
    *
-   * @example Fetching a specific field
+   * @inlineType DocumentOptions
+   */
+  <TData>(options: UseDocumentOptions<undefined>): {data: TData | null}
+
+  /**
+   * @public
+   *
+   * ## useDocument with Explicit Types (with path)
+   *
+   * Provide an explicit type parameter `TData` to type the returned field data
+   * when using a `path` to select a nested value.
+   *
+   * @typeParam TData - The explicit type for the field
+   * @param options - Configuration including `documentId`, `documentType`, `path`, and optionally:
+   *   - `projectId`/`dataset`: For multi-project/dataset setups
+   * @returns The field value at the specified path
+   *
+   * @example Fetching a specific field with explicit type
    * ```tsx
    * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
    *
-   * interface ProductTitleProps {
-   *   doc: DocumentHandle<'product'>
-   * }
-   *
-   * function ProductTitle({doc}: ProductTitleProps) {
-   *   const {data: title} = useDocument({
-   *     ...doc,
-   *     path: 'title' // Returns just the title field
-   *   })
+   * function BookTitle({doc}: {doc: DocumentHandle}) {
+   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
    *   return <h1>{title ?? 'Untitled'}</h1>
    * }
    * ```
    *
    * @inlineType DocumentOptions
    */
-  <
-    TPath extends string | undefined = undefined,
-    TDocumentType extends string = string,
-    TDataset extends string = string,
-    TProjectId extends string = string,
-  >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): TPath extends string
-    ? {
-        data:
-          | JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
-          | undefined
-      }
-    : {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
+  <TData>(options: UseDocumentOptions<string>): {data: TData | undefined}
 
   /**
    * @public
    *
-   * ## useDocument via Explicit Types
+   * ## useDocument (default)
    *
-   * Use this version when:
-   * - You're not using Sanity Typegen
-   * - You need to manually specify document types
-   * - You're working with dynamic document types
+   * When no explicit type parameter is provided, the hook returns `SanityDocument`.
    *
-   * Key differences from Typegen version:
-   * - Requires manual type specification via `TData`
-   * - Returns `TData | null` for full documents
-   * - Returns `TData | undefined` for nested values
+   * This hook will suspend while the document data is being fetched and loaded.
    *
-   * This hook will suspend while the document data is being fetched.
+   * When fetching a full document:
+   * - Returns the complete document object if it exists
+   * - Returns `null` if the document doesn't exist
+   *
+   * When fetching with a path:
+   * - Returns the value at the specified path if both the document and path exist
+   * - Returns `undefined` if either the document doesn't exist or the path doesn't exist in the document
    *
-   * @typeParam TData - The explicit type for the document or field
-   * @typeParam TPath - Optional path to a nested value
-   * @param options - Configuration including `documentId` and optionally:
+   * @category Documents
+   * @param options - Configuration including `documentId`, `documentType`, and optionally:
    *   - `path`: To select a nested value
    *   - `projectId`/`dataset`: For multi-project/dataset setups
-   * @returns The document state (or nested value if path provided)
-   *
-   * @example Basic document fetch with explicit type
-   * ```tsx
-   * import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
-   *
-   * interface Book extends SanityDocument {
-   *   _type: 'book'
-   *   title: string
-   *   author: string
-   * }
-   *
-   * interface BookViewProps {
-   *   doc: DocumentHandle
-   * }
-   *
-   * function BookView({doc}: BookViewProps) {
-   *   const {data: book} = useDocument<Book>({...doc})
-   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
-   * }
-   * ```
+   * @returns The document state (or nested value if path provided).
    *
-   * @example Fetching a specific field with explicit type
+   * @example Basic document fetch
    * ```tsx
    * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
    *
-   * interface BookTitleProps {
-   *   doc: DocumentHandle
-   * }
-   *
-   * function BookTitle({doc}: BookTitleProps) {
-   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
-   *   return <h1>{title ?? 'Untitled'}</h1>
+   * function ProductView({doc}: {doc: DocumentHandle}) {
+   *   const {data: product} = useDocument({...doc})
+   *   return <h1>{product?.title ?? 'Untitled'}</h1>
    * }
    * ```
    *
    * @inlineType DocumentOptions
    */
-  <TData, TPath extends string>(
-    options: DocumentOptions<TPath>,
-  ): TPath extends string ? {data: TData | undefined} : {data: TData | null}
+  (options: UseDocumentOptions<undefined>): {data: SanityDocument | null}
 
   /**
    * @internal
    */
-  (options: DocumentOptions): {data: unknown}
+  (options: UseDocumentOptions): {data: unknown}
 }
 
 /**
  * @public
  * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
  *
- * This hook comes in two main flavors to suit your needs:
+ * You can provide an explicit type parameter for full type safety:
+ * - `useDocument<MyType>({...})` returns `{data: MyType | null}`
+ * - `useDocument<string>({..., path: 'title'})` returns `{data: string | undefined}`
  *
- * 1. **[Type Inference](#usedocument-via-type-inference-recommended)** (Recommended) - Automatically gets types from your Sanity schema
- * 2. **[Explicit Types](#usedocument-via-explicit-types)** - Manually specify types when needed
+ * Without a type parameter, data is typed as `SanityDocument`.
  *
  * @remarks
  * `useDocument` is ideal for realtime editing interfaces where you need immediate feedback on changes.
@@ -226,4 +172,7 @@ interface UseDocument {
  *
  * @function
  */
-export const useDocument = wrapHookWithData(useDocumentValue) as UseDocument
+export const useDocument = wrapHookWithData((options: UseDocumentOptions) => {
+  const normalizedOptions = useNormalizedResourceOptions(options)
+  return useDocumentValue(normalizedOptions)
+}) as UseDocument

package/src/hooks/document/useDocumentEvent.test.tsx

@@ -1,9 +1,8 @@
 // tests/useDocumentEvent.test.ts
 import {type DocumentEvent, type DocumentHandle, subscribeDocumentEvents} from '@sanity/sdk'
-import {renderHook} from '@testing-library/react'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {ResourceProvider} from '../../context/ResourceProvider'
+import {renderHook} from '../../../test/test-utils'
 import {useDocumentEvent} from './useDocumentEvent'
 
 vi.mock('@sanity/sdk', async (importOriginal) => {
@@ -14,6 +13,7 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 const docHandle: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'book',
+  resource: {projectId: 'p', dataset: 'd'},
 }
 
 describe('useDocumentEvent hook', () => {
@@ -26,22 +26,16 @@ describe('useDocumentEvent hook', () => {
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}), {
-      wrapper: ({children}) => (
-        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
-          {children}
-        </ResourceProvider>
-      ),
-    })
+    renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}))
 
     expect(vi.mocked(subscribeDocumentEvents)).toHaveBeenCalledTimes(1)
     expect(vi.mocked(subscribeDocumentEvents).mock.calls[0][0]).toEqual(expect.any(Object))
 
-    const stableHandler = vi.mocked(subscribeDocumentEvents).mock.calls[0][1]
-    expect(typeof stableHandler).toBe('function')
+    const options = vi.mocked(subscribeDocumentEvents).mock.calls[0][1]
+    expect(typeof options.eventHandler).toBe('function')
 
     const event = {type: 'edited', documentId: 'doc1', outgoing: {}} as DocumentEvent
-    stableHandler(event)
+    options.eventHandler(event)
     expect(handleEvent).toHaveBeenCalledWith(event)
   })
 
@@ -50,13 +44,7 @@ describe('useDocumentEvent hook', () => {
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    const {unmount} = renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}), {
-      wrapper: ({children}) => (
-        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
-          {children}
-        </ResourceProvider>
-      ),
-    })
+    const {unmount} = renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}))
     unmount()
     expect(unsubscribe).toHaveBeenCalledTimes(1)
   })

package/src/hooks/document/useDocumentEvent.ts

@@ -1,7 +1,9 @@
-import {type DatasetHandle, type DocumentEvent, subscribeDocumentEvents} from '@sanity/sdk'
+import {type DocumentEvent, subscribeDocumentEvents} from '@sanity/sdk'
 import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
+import {type ResourceHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -9,7 +11,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
 export interface UseDocumentEventOptions<
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DatasetHandle<TDataset, TProjectId> {
+> extends ResourceHandle<TProjectId, TDataset> {
   onEvent: (documentEvent: DocumentEvent) => void
 }
 
@@ -20,19 +22,19 @@ export interface UseDocumentEventOptions<
  * Subscribes an event handler to events in your application's document store.
  *
  * @category Documents
- * @param options - An object containing the event handler (`onEvent`) and optionally a `DatasetHandle` (projectId and dataset). If the handle is not provided, the nearest Sanity instance from context will be used.
+ * @param options - An object containing the event handler (`onEvent`) and optionally a `resource`. If no resource is provided, the nearest resource from context will be used.
  * @example Creating a custom hook for document event toasts
  * ```tsx
- * import {createDatasetHandle, type DatasetHandle, type DocumentEvent, useDocumentEvent} from '@sanity/sdk-react'
+ * import {type DocumentResource, type DocumentEvent, useDocumentEvent} from '@sanity/sdk-react'
  * import {useToast} from './my-ui-library'
  *
- * // Define options for the custom hook, extending DatasetHandle
- * interface DocumentToastsOptions extends DatasetHandle {
- *   // Could add more options, e.g., { includeEvents: DocumentEvent['type'][] }
+ * // Define options for the custom hook
+ * interface DocumentToastsOptions {
+ *   resource?: DocumentResource
  * }
  *
  * // Define the custom hook
- * function useDocumentToasts({...datasetHandle}: DocumentToastsOptions = {}) {
+ * function useDocumentToasts({resource}: DocumentToastsOptions = {}) {
  *   const showToast = useToast() // Get the toast function
  *
  *   // Define the event handler logic to show toasts on specific events
@@ -44,24 +46,20 @@ export interface UseDocumentEventOptions<
  *     } else if (event.type === 'deleted') {
  *       showToast(`Document ${event.documentId} deleted.`)
  *     } else {
- *       // Optionally log other events for debugging
  *       console.log('Document Event:', event.type, event.documentId)
  *     }
  *   }
  *
- *   // Call the original hook, spreading the handle properties
  *   useDocumentEvent({
- *     ...datasetHandle, // Spread the dataset handle (projectId, dataset)
+ *     resource,
  *     onEvent: handleEvent,
  *   })
  * }
  *
  * function MyComponentWithToasts() {
- *   // Use the custom hook, passing specific handle info
- *   const specificHandle = createDatasetHandle({ projectId: 'p1', dataset: 'ds1' })
- *   useDocumentToasts(specificHandle)
+ *   useDocumentToasts({resource: {projectId: 'p1', dataset: 'ds1'}})
  *
- *   // // Or use it relying on context for the handle
+ *   // Or rely on context for the resource:
  *   // useDocumentToasts()
  *
  *   return <div>...</div>
@@ -76,7 +74,8 @@ export function useDocumentEvent<
   options: UseDocumentEventOptions<TDataset, TProjectId>,
 ): void {
   // Destructure handler and datasetHandle from options
-  const {onEvent, ...datasetHandle} = options
+  const normalizedOptions = useNormalizedResourceOptions(options)
+  const {onEvent, ...datasetHandle} = normalizedOptions
   const ref = useRef(onEvent)
 
   useInsertionEffect(() => {
@@ -87,8 +86,11 @@ export function useDocumentEvent<
     return ref.current(documentEvent)
   }, [])
 
-  const instance = useSanityInstance(datasetHandle)
+  const instance = useSanityInstance()
   useEffect(() => {
-    return subscribeDocumentEvents(instance, stableHandler)
-  }, [instance, stableHandler])
+    return subscribeDocumentEvents(instance, {
+      eventHandler: stableHandler,
+      resource: datasetHandle.resource,
+    })
+  }, [instance, datasetHandle.resource, stableHandler])
 }