@sanity/sdk-react 0.0.0-rc.6 → 0.0.1

package/src/hooks/document/useDocument.ts

@@ -1,128 +1,212 @@
-import {
-  type DocumentHandle,
-  getDocumentState,
-  type JsonMatch,
-  type JsonMatchPath,
-  resolveDocument,
-} from '@sanity/sdk'
-import {type SanityDocument} from '@sanity/types'
+import {type DocumentOptions, getDocumentState, type JsonMatch, resolveDocument} from '@sanity/sdk'
+import {type SanityDocumentResult} from 'groq'
 import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+// used in an `{@link useProjection}` and `{@link useQuery}`
+// eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
+import type {useProjection} from '../projection/useProjection'
+// eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
+import type {useQuery} from '../query/useQuery'
 
-/**
- * @beta
- *
- * ## useDocument(doc, path)
- * Read and subscribe to nested values in a document
- * @category Documents
- * @param doc - The document to read state from, specified as a DocumentHandle
- * @param path - The path to the nested value to read from
- * @returns The value at the specified path
- * @example
- * ```tsx
- * import {useDocument} from '@sanity/sdk-react'
- *
- * const documentHandle = {
- *   documentId: 'order-123',
- *   documentType: 'order',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * function OrderLink() {
- *   const title = useDocument(documentHandle, 'title')
- *   const id = useDocument(documentHandle, '_id')
- *
- *   return (
- *     <a href={`/order/${id}`}>Order {title} today!</a>
- *   )
- * }
- * ```
- *
- */
-export function useDocument<
-  TDocument extends SanityDocument,
-  TPath extends JsonMatchPath<TDocument>,
->(doc: DocumentHandle<TDocument>, path: TPath): JsonMatch<TDocument, TPath> | undefined
+interface UseDocument {
+  /** @internal */
+  <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
+    options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+  ): SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
 
-/**
- * @beta
- * ## useDocument(doc)
- * Read and subscribe to an entire document
- * @param doc - The document to read state from, specified as a DocumentHandle
- * @returns The document state as an object
- * @example
- * ```tsx
- * import {type SanityDocument, useDocument} from '@sanity/sdk-react'
- *
- * interface Book extends SanityDocument {
- *   title: string
- *   author: string
- *   summary: string
- * }
- *
- * const documentHandle = {
- *   documentId: 'book-123',
- *   documentType: 'book',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * function DocumentView() {
- *   const book = useDocument<Book>(documentHandle)
- *
- *   if (!book) {
- *     return <div>Loading...</div>
- *   }
- *
- *   return (
- *     <article>
- *       <h1>{book.title}</h1>
- *       <address>By {book.author}</address>
- *
- *       <h2>Summary</h2>
- *       {book.summary}
- *
- *       <h2>Order</h2>
- *       <a href={`/order/${book._id}`}>Order {book.title} today!</a>
- *     </article>
- *   )
- * }
- * ```
- *
- */
-export function useDocument<TDocument extends SanityDocument>(
-  doc: DocumentHandle<TDocument>,
-): TDocument | null
+  /** @internal */
+  <
+    TPath extends string,
+    TDocumentType extends string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+  ): JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+
+  /** @internal */
+  <TData>(options: DocumentOptions<undefined>): TData | null
+  /** @internal */
+  <TData>(options: DocumentOptions<string>): TData | undefined
+
+  /**
+   * ## useDocument via Type Inference (Recommended)
+   *
+   * @beta
+   *
+   * The preferred way to use this hook when working with Sanity Typegen.
+   *
+   * 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
+   *
+   * 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
+   *
+   * @category Documents
+   * @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).
+   *
+   * @example Basic document fetch
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface ProductViewProps {
+   *   doc: DocumentHandle<'product'> // Typegen infers product type
+   * }
+   *
+   * function ProductView({doc}: ProductViewProps) {
+   *   const product = useDocument({...doc}) // Fully typed product
+   *   return <h1>{product.title ?? 'Untitled'}</h1>
+   * }
+   * ```
+   *
+   * @example Fetching a specific field
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface ProductTitleProps {
+   *   doc: DocumentHandle<'product'>
+   * }
+   *
+   * function ProductTitle({doc}: ProductTitleProps) {
+   *   const title = useDocument({
+   *     ...doc,
+   *     path: 'title' // Returns just the title field
+   *   })
+   *   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
+    ? JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+    : SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+
+  /**
+   * @beta
+   *
+   * ## useDocument via Explicit Types
+   *
+   * Use this version when:
+   * - You're not using Sanity Typegen
+   * - You need to manually specify document types
+   * - You're working with dynamic document types
+   *
+   * 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.
+   *
+   * @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:
+   *   - `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 book = useDocument<Book>({...doc})
+   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
+   * }
+   * ```
+   *
+   * @example Fetching a specific field with explicit type
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface BookTitleProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function BookTitle({doc}: BookTitleProps) {
+   *   const title = useDocument<string>({...doc, path: 'title'})
+   *   return <h1>{title ?? 'Untitled'}</h1>
+   * }
+   * ```
+   *
+   * @inlineType DocumentOptions
+   */
+  <TData, TPath extends string>(
+    options: DocumentOptions<TPath>,
+  ): TPath extends string ? TData | undefined : TData | null
+
+  /**
+   * @internal
+   */
+  (options: DocumentOptions): unknown
+}
 
 /**
  * @beta
  * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
- * When called with a `path` argument, the hook will return the nested value's state.
- * When called without a `path` argument, the entire document's state will be returned.
+ *
+ * This hook comes in two main flavors to suit your needs:
+ *
+ * 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
  *
  * @remarks
- * `useDocument` is designed to be used within a realtime context in which local updates to documents
- * need to be displayed before they are persisted to the remote copy. This can be useful within a collaborative
- * or realtime editing interface where local changes need to be reflected immediately.
+ * `useDocument` is ideal for realtime editing interfaces where you need immediate feedback on changes.
+ * However, it can be resource-intensive since it maintains a realtime connection.
  *
- * The hook automatically uses the correct Sanity instance based on the project and dataset
- * specified in the DocumentHandle. This makes it easy to work with documents from different
- * projects or datasets in the same component.
+ * For simpler cases where:
+ * - You only need to display content
+ * - Realtime updates aren't critical
+ * - You want better performance
  *
- * However, this hook can be too resource intensive for applications where static document values simply
- * need to be displayed (or when changes to documents don't need to be reflected immediately);
- * consider using `usePreview` or `useQuery` for these use cases instead. These hooks leverage the Sanity
- * Live Content API to provide a more efficient way to read and subscribe to document state.
+ * …consider using {@link useProjection} or {@link useQuery} instead. These hooks are more efficient
+ * for read-heavy applications.
+ *
+ * @function
  */
-export function useDocument(doc: DocumentHandle, path?: string): unknown {
-  return _useDocument(doc, path)
-}
-
-const _useDocument = createStateSourceHook<[doc: DocumentHandle, path?: string], unknown>({
-  getState: getDocumentState,
-  shouldSuspend: (instance, doc) => getDocumentState(instance, doc).getCurrent() === undefined,
-  suspender: resolveDocument,
-  getConfig: identity,
-})
+export const useDocument = createStateSourceHook({
+  // Pass options directly to getDocumentState
+  getState: (instance, options: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options),
+  // Pass options directly to getDocumentState for checking current value
+  shouldSuspend: (instance, {path: _path, ...options}: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options).getCurrent() === undefined,
+  // Extract handle part for resolveDocument
+  suspender: (instance, options: DocumentOptions<string | undefined>) =>
+    resolveDocument(instance, options),
+  getConfig: identity as (
+    options: DocumentOptions<string | undefined>,
+  ) => DocumentOptions<string | undefined>,
+}) as UseDocument

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

@@ -33,11 +33,11 @@ describe('useDocumentEvent hook', () => {
   })
 
   it('calls subscribeDocumentEvents with instance and a stable handler', () => {
-    const handler = vi.fn()
+    const handleEvent = vi.fn()
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    renderHook(() => useDocumentEvent(handler, docHandle))
+    renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}))
 
     expect(vi.mocked(subscribeDocumentEvents)).toHaveBeenCalledTimes(1)
     expect(vi.mocked(subscribeDocumentEvents).mock.calls[0][0]).toBe(instance)
@@ -47,15 +47,15 @@ describe('useDocumentEvent hook', () => {
 
     const event = {type: 'edited', documentId: 'doc1', outgoing: {}} as DocumentEvent
     stableHandler(event)
-    expect(handler).toHaveBeenCalledWith(event)
+    expect(handleEvent).toHaveBeenCalledWith(event)
   })
 
   it('calls the unsubscribe function on unmount', () => {
-    const handler = vi.fn()
+    const handleEvent = vi.fn()
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    const {unmount} = renderHook(() => useDocumentEvent(handler, docHandle))
+    const {unmount} = renderHook(() => useDocumentEvent({...docHandle, onEvent: handleEvent}))
     unmount()
     expect(unsubscribe).toHaveBeenCalledTimes(1)
   })

package/src/hooks/document/useDocumentEvent.ts

@@ -3,47 +3,91 @@ import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
+/**
+ * @beta
+ */
+export interface UseDocumentEventOptions<
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId> {
+  onEvent: (documentEvent: DocumentEvent) => void
+}
+
 /**
  *
  * @beta
  *
- * Subscribes an event handler to events in your application's document store, such as document
- * creation, deletion, and updates.
+ * Subscribes an event handler to events in your application's document store.
  *
  * @category Documents
- * @param handler - The event handler to register.
- * @param doc - The document to subscribe to events for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
- * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
- * the document will use the nearest instance from context.
- * @example
- * ```
- * import {useDocumentEvent} from '@sanity/sdk-react'
- * import {type DocumentEvent} from '@sanity/sdk'
- *
- * useDocumentEvent((event) => {
- *   if (event.type === DocumentEvent.DocumentDeletedEvent) {
- *     alert(`Document with ID ${event.documentId} deleted!`)
- *   } else {
- *     console.log(event)
+ * @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.
+ * @example Creating a custom hook for document event toasts
+ * ```tsx
+ * import {createDatasetHandle, type DatasetHandle, 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 the custom hook
+ * function useDocumentToasts({...datasetHandle}: DocumentToastsOptions = {}) {
+ *   const showToast = useToast() // Get the toast function
+ *
+ *   // Define the event handler logic to show toasts on specific events
+ *   const handleEvent = (event: DocumentEvent) => {
+ *     if (event.type === 'published') {
+ *       showToast(`Document ${event.documentId} published.`)
+ *     } else if (event.type === 'unpublished') {
+ *       showToast(`Document ${event.documentId} unpublished.`)
+ *     } 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)
+ *     onEvent: handleEvent,
+ *   })
+ * }
+ *
+ * function MyComponentWithToasts() {
+ *   // Use the custom hook, passing specific handle info
+ *   const specificHandle = createDatasetHandle({ projectId: 'p1', dataset: 'ds1' })
+ *   useDocumentToasts(specificHandle)
+ *
+ *   // // Or use it relying on context for the handle
+ *   // useDocumentToasts()
+ *
+ *   return <div>...</div>
+ * }
  * ```
  */
-export function useDocumentEvent(
-  handler: (documentEvent: DocumentEvent) => void,
-  dataset: DatasetHandle,
+export function useDocumentEvent<
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  // Single options object parameter
+  options: UseDocumentEventOptions<TDataset, TProjectId>,
 ): void {
-  const ref = useRef(handler)
+  // Destructure handler and datasetHandle from options
+  const {onEvent, ...datasetHandle} = options
+  const ref = useRef(onEvent)
 
   useInsertionEffect(() => {
-    ref.current = handler
+    ref.current = onEvent
   })
 
   const stableHandler = useCallback((documentEvent: DocumentEvent) => {
     return ref.current(documentEvent)
   }, [])
 
-  const instance = useSanityInstance(dataset)
+  const instance = useSanityInstance(datasetHandle)
   useEffect(() => {
     return subscribeDocumentEvents(instance, stableHandler)
   }, [instance, stableHandler])

package/src/hooks/document/useDocumentPermissions.ts

@@ -11,23 +11,41 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * Check if the current user has the specified permissions for the given document actions.
  *
  * @category Permissions
- * @param actionOrActions - One more more calls to a particular document action function for a given document
+ * @param actionOrActions - One or more document action functions (e.g., `publishDocument(handle)`).
  * @returns An object that specifies whether the action is allowed; if the action is not allowed, an explanatory message and list of reasons is also provided.
  *
+ * @remarks
+ * When passing multiple actions, all actions must belong to the same project and dataset.
+ * Note, however, that you can check permissions on multiple documents from the same project and dataset (as in the second example below).
+ *
  * @example Checking for permission to publish a document
- * ```ts
- * import {useDocumentPermissions, useApplyDocumentActions} from '@sanity/sdk-react'
- * import {publishDocument} from '@sanity/sdk'
+ * ```tsx
+ * import {
+ *   useDocumentPermissions,
+ *   useApplyDocumentActions,
+ *   publishDocument,
+ *   createDocumentHandle,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * // Define props using the DocumentHandle type
+ * interface PublishButtonProps {
+ *   doc: DocumentHandle
+ * }
  *
- * export function PublishButton({doc}: {doc: DocumentHandle}) {
- *   const publishPermissions = useDocumentPermissions(publishDocument(doc))
- *   const applyAction = useApplyDocumentActions()
+ * function PublishButton({doc}: PublishButtonProps) {
+ *   const publishAction = publishDocument(doc)
+ *
+ *   // Pass the same action call to check permissions
+ *   const publishPermissions = useDocumentPermissions(publishAction)
+ *   const apply = useApplyDocumentActions()
  *
  *   return (
  *     <>
  *       <button
  *         disabled={!publishPermissions.allowed}
- *         onClick={() => applyAction(publishDocument(doc))}
+ *         // Pass the same action call to apply the action
+ *         onClick={() => apply(publishAction)}
  *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
  *       >
  *         Publish
@@ -40,6 +58,27 @@ import {useSanityInstance} from '../context/useSanityInstance'
  *     </>
  *   )
  * }
+ *
+ * // Usage:
+ * // const doc = createDocumentHandle({ documentId: 'doc1', documentType: 'myType' })
+ * // <PublishButton doc={doc} />
+ * ```
+ *
+ * @example Checking for permissions to edit multiple documents
+ * ```tsx
+ * import {
+ *   useDocumentPermissions,
+ *   editDocument,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * export default function canEditMultiple(docHandles: DocumentHandle[]) {
+ *   // Create an array containing an editDocument action for each of the document handles
+ *   const editActions = docHandles.map(doc => editDocument(doc))
+ *
+ *   // Return the result of checking for edit permissions on all of the document handles
+ *   return useDocumentPermissions(editActions)
+ * }
  * ```
  */
 export function useDocumentPermissions(

package/src/hooks/document/useDocumentSyncStatus.test.ts

@@ -1,16 +1,23 @@
 import {getDocumentSyncStatus} from '@sanity/sdk'
-import {identity} from 'rxjs'
 import {describe, it} from 'vitest'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
-vi.mock('../helpers/createStateSourceHook', () => ({createStateSourceHook: vi.fn(identity)}))
+const mockHook = vi.fn()
+vi.mock('../helpers/createStateSourceHook', () => ({createStateSourceHook: vi.fn(() => mockHook)}))
 vi.mock('@sanity/sdk', () => ({getDocumentSyncStatus: vi.fn()}))
 
 describe('useDocumentSyncStatus', () => {
-  it('calls `createStateSourceHook` with `getTokenState`', async () => {
+  it('calls `createStateSourceHook` with `getDocumentSyncStatus`', async () => {
     const {useDocumentSyncStatus} = await import('./useDocumentSyncStatus')
-    expect(createStateSourceHook).toHaveBeenCalledWith(getDocumentSyncStatus)
-    expect(useDocumentSyncStatus).toBe(getDocumentSyncStatus)
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: getDocumentSyncStatus,
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function),
+        getConfig: expect.any(Function),
+      }),
+    )
+    expect(useDocumentSyncStatus).toBe(mockHook)
   })
 })

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -1,4 +1,11 @@
-import {type DocumentHandle, getDocumentSyncStatus} from '@sanity/sdk'
+import {
+  type DocumentHandle,
+  getDocumentSyncStatus,
+  resolveDocument,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -10,25 +17,45 @@ type UseDocumentSyncStatus = {
    * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
    * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
    * the document will use the nearest instance from context.
-   * @returns `true` if local changes are synced with remote, `false` if the changes are not synced, and `undefined` if the document is not found
-   * @example Disable a Save button when there are no changes to sync
-   * ```
-   * const myDocumentHandle = { documentId: 'documentId', documentType: 'documentType', projectId: 'projectId', dataset: 'dataset' }
-   * const documentSynced = useDocumentSyncStatus(myDocumentHandle)
+   * @returns `true` if local changes are synced with remote, `false` if changes are pending. Note: Suspense handles loading states.
+   * @example Show sync status indicator
+   * ```tsx
+   * import {useDocumentSyncStatus, createDocumentHandle, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * // Define props including the DocumentHandle type
+   * interface SyncIndicatorProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function SyncIndicator({doc}: SyncIndicatorProps) {
+   *   const isSynced = useDocumentSyncStatus(doc)
+   *
+   *   return (
+   *     <div className={`sync-status ${isSynced ? 'synced' : 'pending'}`}>
+   *       {isSynced ? '✓ Synced' : 'Saving changes...'}
+   *     </div>
+   *   )
+   * }
    *
-   * return (
-   *   <button disabled={documentSynced}>
-   *     Save Changes
-   *   </button>
-   * )
+   * // Usage:
+   * // const doc = createDocumentHandle({ documentId: 'doc1', documentType: 'myType' })
+   * // <SyncIndicator doc={doc} />
    * ```
    */
-  (doc: DocumentHandle): boolean | undefined
+  (doc: DocumentHandle): boolean
 }
 
 /**
  * @beta
  * @function
  */
-export const useDocumentSyncStatus: UseDocumentSyncStatus =
-  createStateSourceHook(getDocumentSyncStatus)
+export const useDocumentSyncStatus: UseDocumentSyncStatus = createStateSourceHook({
+  getState: getDocumentSyncStatus as (
+    instance: SanityInstance,
+    doc: DocumentHandle,
+  ) => StateSource<boolean>,
+  shouldSuspend: (instance, doc: DocumentHandle) =>
+    getDocumentSyncStatus(instance, doc).getCurrent() === undefined,
+  suspender: (instance, doc: DocumentHandle) => resolveDocument(instance, doc),
+  getConfig: identity,
+})