@sanity/sdk-react 0.0.0-rc.5 → 0.0.0-rc.7

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

@@ -1,7 +1,7 @@
 // tests/useEditDocument.test.ts
 import {
+  createDocumentHandle,
   createSanityInstance,
-  type DocumentHandle,
   editDocument,
   getDocumentState,
   resolveDocument,
@@ -43,11 +43,29 @@ const doc = {
   _rev: 'tx0',
   _createdAt: '2025-02-06T00:11:00.000Z',
   _updatedAt: '2025-02-06T00:11:00.000Z',
-} satisfies SanityDocument
+} satisfies Book
 
-const docHandle: DocumentHandle<SanityDocument> = {
+const docHandle = createDocumentHandle({
   documentId: 'doc1',
   documentType: 'book',
+})
+
+// Define a single generic TestDocument type
+interface Book extends SanityDocument {
+  _type: 'book'
+  foo?: string
+  extra?: string
+  title?: string
+}
+
+// Scope the TestDocument type to the project/datasets used in tests
+type AllTestSchemaTypes = Book
+
+// Augment the 'groq' module
+declare module 'groq' {
+  interface SanitySchemas {
+    'default:default': AllTestSchemaTypes
+  }
 }
 
 describe('useEditDocument hook', () => {
@@ -67,7 +85,7 @@ describe('useEditDocument hook', () => {
     const apply = vi.fn().mockResolvedValue({transactionId: 'tx1'})
     vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
 
-    const {result} = renderHook(() => useEditDocument(docHandle, 'foo'))
+    const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current('newValue')
     expect(editDocument).toHaveBeenCalledWith(docHandle, {set: {foo: 'newValue'}})
     expect(apply).toHaveBeenCalledWith(editDocument(docHandle, {set: {foo: 'newValue'}}))
@@ -106,7 +124,7 @@ describe('useEditDocument hook', () => {
     const apply = vi.fn().mockResolvedValue({transactionId: 'tx3'})
     vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
 
-    const {result} = renderHook(() => useEditDocument(docHandle, 'foo'))
+    const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current((prev: unknown) => `${prev}Updated`) // 'bar' becomes 'barUpdated'
     expect(editDocument).toHaveBeenCalledWith(docHandle, {set: {foo: 'barUpdated'}})
     expect(apply).toHaveBeenCalledWith(editDocument(docHandle, {set: {foo: 'barUpdated'}}))
@@ -145,7 +163,7 @@ describe('useEditDocument hook', () => {
     vi.mocked(useApplyDocumentActions).mockReturnValue(fakeApply)
 
     const {result} = renderHook(() => useEditDocument(docHandle))
-    expect(() => result.current('notAnObject' as unknown as SanityDocument)).toThrowError(
+    expect(() => result.current('notAnObject' as unknown as Book)).toThrowError(
       'No path was provided to `useEditDocument` and the value provided was not a document object.',
     )
   })

package/src/hooks/document/useEditDocument.ts

@@ -1,13 +1,12 @@
 import {
   type ActionsResult,
-  type DocumentHandle,
+  type DocumentOptions,
   editDocument,
   getDocumentState,
   type JsonMatch,
-  type JsonMatchPath,
   resolveDocument,
 } from '@sanity/sdk'
-import {type SanityDocument} from '@sanity/types'
+import {type SanityDocumentResult} from 'groq'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -15,178 +14,281 @@ import {useApplyDocumentActions} from './useApplyDocumentActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
 
-type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
+type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
+// Overload 1: No path, relies on Typegen
 /**
+ * @beta
+ * Edit an entire document, relying on Typegen for the type.
  *
+ * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>,
+) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+
+// Overload 2: Path provided, relies on Typegen
+/**
  * @beta
+ * Edit a specific path within a document, relying on Typegen for the type.
  *
- * ## useEditDocument(doc, path)
- * Edit a nested value within a document
+ * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TPath extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath>>,
+) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+
+// Overload 3: Explicit type, no path
+/**
+ * @beta
+ * Edit an entire document with an explicit type `TData`.
+ *
+ * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<TData>(
+  options: DocumentOptions<undefined>,
+): (nextValue: Updater<TData>) => Promise<ActionsResult>
+
+// Overload 4: Explicit type, path provided
+/**
+ * @beta
+ * Edit a specific path within a document with an explicit type `TData`.
+ *
+ * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<TData>(
+  options: DocumentOptions<string>,
+): (nextValue: Updater<TData>) => Promise<ActionsResult>
+
+/**
+ * @beta
+ * Provides a stable function to apply edits to a document or a specific path within it.
  *
  * @category Documents
- * @param docHandle - The document to be edited, specified as a DocumentHandle
- * @param path - The path to the nested value to be edited
- * @returns A function to update the nested value. Accepts either a new value, or an updater function that exposes the previous value and returns a new value.
- * @example Update a document's name by providing the new value directly
+ * @remarks
+ * This hook simplifies editing documents by automatically:
+ * - Comparing the current and next states to determine the minimal set of `set` and `unset` operations required for the update via `editDocument`.
+ * - Handling both full document updates and specific path updates.
+ * - Supporting functional updates (e.g., `edit(prev => ({...prev, title: 'New'}))`).
+ * - Integrating with the active {@link SanityInstance} context.
+ * - Utilizing `useApplyDocumentActions` internally for optimistic updates and transaction handling.
+ *
+ * It offers several overloads for flexibility:
+ * 1. **Typegen (Full Document):** Edit the entire document, inferring types from your schema.
+ * 2. **Typegen (Specific Path):** Edit a specific field, inferring types.
+ * 3. **Explicit Type (Full Document):** Edit the entire document with a manually specified type.
+ * 4. **Explicit Type (Specific Path):** Edit a specific field with a manually specified type.
+ *
+ * This hook relies on the document state being loaded. If the document is not yet available
+ * (e.g., during initial load), the component using this hook will suspend.
+ *
+ * @example Basic Usage (Typegen, Full Document)
  * ```tsx
- * const handle = {
- *   documentId: 'movie-123',
- *   documentType: 'movie',
- *   projectId: 'abc123',
- *   dataset: 'production'
+ * import {useCallback} from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'title' field (string)
+ * interface ProductEditorProps {
+ *   productHandle: DocumentHandle<'product'> // Typegen infers 'product' type
  * }
  *
- * const name = useDocument(handle, 'name')
- * const editName = useEditDocument(handle, 'name')
+ * function ProductEditor({ productHandle }: ProductEditorProps) {
+ *   // Fetch the document to display its current state (optional)
+ *   const product = useDocument(productHandle);
+ *   // Get the edit function for the full document
+ *   const editProduct = useEditDocument(productHandle);
  *
- * function handleNameChange(event: React.ChangeEvent<HTMLInputElement>) {
- *   editName(event.target.value)
- * }
+ *   // Use useCallback for stable event handlers
+ *   const handleTitleChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+ *     const newTitle = event.target.value;
+ *     // Use the functional updater for safe partial updates
+ *     editProduct(prev => ({
+ *       ...prev,
+ *       title: newTitle,
+ *     })).
+ *   }, [editProduct]);
  *
- * return (
- *   <input type='text' value={name} onChange={handleNameChange} />
- * )
+ *   return (
+ *     <div>
+ *       <label>
+ *         Product Title:
+ *         <input
+ *           type="text"
+ *           value={product?.title ?? ''}
+ *           onChange={handleTitleChange}
+ *         />
+ *       </label>
+ *     </div>
+ *   );
+ * }
  * ```
  *
- * @example Update a count on a document by providing an updater function
+ * @example Editing a Specific Path (Typegen)
  * ```tsx
- * const handle = {
- *   documentId: 'counter-123',
- *   documentType: 'counter',
- *   projectId: 'abc123',
- *   dataset: 'production'
+ * import React, { useCallback } from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'price' field (number)
+ * interface ProductPriceEditorProps {
+ *   productHandle: DocumentHandle<'product'>;
  * }
  *
- * const count = useDocument(handle, 'count')
- * const editCount = useEditDocument(handle, 'count')
+ * function ProductPriceEditor({ productHandle }: ProductPriceEditorProps) {
+ *   // Construct DocumentOptions internally, combining the handle and a hardcoded path
+ *   const priceOptions {
+ *     ...productHandle,
+ *     path: 'price', // Hardcode the path to edit
+ *   };
  *
- * function incrementCount() {
- *   editCount(previousCount => previousCount + 1)
+ *   // Fetch the current price to display it
+ *   const currentPrice = useDocument(priceOptions);
+ *   // Get the edit function for the specific path 'price'
+ *   const editPrice = useEditDocument(priceOptions);
+ *
+ *   const handleSetFixedPrice = useCallback(() => {
+ *     // Update the price directly to a hardcoded value
+ *     editPrice(99.99)
+ *   }, [editPrice]);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current Price: {currentPrice}</p>
+ *       <button onClick={handleSetFixedPrice}>
+ *         Set Price to $99.99
+ *       </button>
+ *     </div>
+ *   );
  * }
  *
- * return (
- *   <>
- *     <button onClick={incrementCount}>
- *       Increment
- *     </button>
- *     Current count: {count}
- *   </>
- * )
  * ```
- */
-export function useEditDocument<
-  TDocument extends SanityDocument,
-  TPath extends JsonMatchPath<TDocument>,
->(
-  docHandle: DocumentHandle<TDocument>,
-  path: TPath,
-): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
-
-/**
  *
- * @beta
- *
- * ## useEditDocument(doc)
- * Edit an entire document
- * @param docHandle - The document to be edited, specified as a DocumentHandle.
- * The hook will automatically use the Sanity instance that matches the project and dataset specified in the handle.
- * @returns A function to update the document state. Accepts either a new document state, or an updater function that exposes the previous document state and returns the new document state.
- * @example
+ * @example Usage with Explicit Types (Full Document)
  * ```tsx
- * const myDocumentHandle = {
- *   documentId: 'product-123',
- *   documentType: 'product',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * const myDocument = useDocument(myDocumentHandle)
- * const { title, price } = myDocument ?? {}
+ * import React, { useCallback } from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
  *
- * const editMyDocument = useEditDocument(myDocumentHandle)
+ * interface Book extends SanityDocument { _type: 'book', title: string, author: string }
  *
- * function handleFieldChange(e: React.ChangeEvent<HTMLInputElement>) {
- *   const {name, value} = e.currentTarget
- *   // Use an updater function to update the document state based on the previous state
- *   editMyDocument(previousDocument => ({
- *     ...previousDocument,
- *     [name]: value
- *   }))
+ * interface BookEditorProps {
+ *   bookHandle: DocumentHandle // No documentType needed if providing TData
  * }
  *
- * function handleSaleChange(e: React.ChangeEvent<HTMLInputElement>) {
- *   const { checked } = e.currentTarget
- *   if (checked) {
- *     // Use an updater function to add a new salePrice field;
- *     // set it at a 20% discount off the normal price
- *     editMyDocument(previousDocument => ({
- *       ...previousDocument,
- *       salePrice: previousDocument.price * 0.8,
+ * function BookEditor({ bookHandle }: BookEditorProps) {
+ *   const book = useDocument<Book>(bookHandle);
+ *   // Provide the explicit type <Book>
+ *   const editBook = useEditDocument<Book>(bookHandle);
+ *
+ *   const handleAuthorChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+ *     const newAuthor = event.target.value;
+ *     editBook(prev => ({
+ *       ...prev,
+ *       author: newAuthor
  *     }))
- *   } else {
- *     // Get the document state without the salePrice field
- *     const { salePrice, ...rest } = myDocument
- *     // Update the document state to remove the salePrice field
- *     editMyDocument(rest)
- *   }
+ *   }, [editBook]);
+ *
+ *   return (
+ *      <div>
+ *       <label>
+ *         Book Author:
+ *         <input
+ *           type="text"
+ *           value={book?.author ?? ''}
+ *           onChange={handleAuthorChange}
+ *         />
+ *       </label>
+ *     </div>
+ *   );
  * }
  *
- * return (
- *   <>
- *     <form onSubmit={e => e.preventDefault()}>
- *       <input name='title' type='text' value={title} onChange={handleFieldChange} />
- *       <input name='price' type='number' value={price} onChange={handleFieldChange} />
- *       <input
- *         name='salePrice'
- *         type='checkbox'
- *         checked={myDocument && 'salePrice' in myDocument}
- *         onChange={handleSaleChange}
- *       />
- *     </form>
- *     <pre><code>
- *       {JSON.stringify(myDocument, null, 2)}
- *     </code></pre>
- *   </>
- * )
  * ```
- */
-export function useEditDocument<TDocument extends SanityDocument>(
-  docHandle: DocumentHandle<TDocument>,
-): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
-
-/**
  *
- * @beta
+ * @example Usage with Explicit Types (Specific Path)
+ * ```tsx
+ * import React, { useCallback } from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'
+ *
+ * // Assume 'book' has 'author.name' (string)
+ * interface AuthorNameEditorProps {
+ *   bookHandle: DocumentHandle; // No documentType needed if providing TData for path
+ * }
+ *
+ * function AuthorNameEditor({ bookHandle }: AuthorNameEditorProps) {*
+ *   // Fetch current value
+ *   const currentName = useDocument<string>({...bookHandle, path: 'author.name'});
+ *   // Provide the explicit type <string> for the path's value
+ *   const editAuthorName = useEditDocument<string>({...bookHandle, 'author.name'});
  *
- * Enables editing of a document’s state.
- * When called with a `path` argument, the hook will return a function for updating a nested value.
- * When called without a `path` argument, the hook will return a function for updating the entire document.
+ *   const handleUpdate = useCallback(() => {
+ *     // Update with a hardcoded string directly
+ *     editAuthorName('Jane Doe')
+ *   }, [editAuthorName]);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current Author Name: {currentName}</p>
+ *       <button onClick={handleUpdate} disabled={currentName === undefined}>
+ *         Set Author Name to Jane Doe
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ *
+ * ```
  */
-export function useEditDocument(
-  docHandle: DocumentHandle,
-  path?: string,
-): (updater: Updater<unknown>) => Promise<ActionsResult> {
-  const instance = useSanityInstance(docHandle)
+export function useEditDocument({
+  path,
+  ...doc
+}: DocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
+  const instance = useSanityInstance(doc)
   const apply = useApplyDocumentActions()
   const isDocumentReady = useCallback(
-    () => getDocumentState(instance, docHandle).getCurrent() !== undefined,
-    [instance, docHandle],
+    () => getDocumentState(instance, doc).getCurrent() !== undefined,
+    [instance, doc],
   )
-  if (!isDocumentReady()) throw resolveDocument(instance, docHandle)
+  if (!isDocumentReady()) throw resolveDocument(instance, doc)
 
   return (updater: Updater<unknown>) => {
-    if (path) {
+    const currentPath = path
+
+    if (currentPath) {
+      const stateWithOptions = getDocumentState(instance, {...doc, path})
+      const currentValue = stateWithOptions.getCurrent()
+
       const nextValue =
         typeof updater === 'function'
-          ? updater(getDocumentState(instance, docHandle, path).getCurrent())
+          ? (updater as (prev: typeof currentValue) => typeof currentValue)(currentValue)
           : updater
 
-      return apply(editDocument(docHandle, {set: {[path]: nextValue}}))
+      return apply(editDocument(doc, {set: {[currentPath]: nextValue}}))
     }
 
-    const current = getDocumentState(instance, docHandle).getCurrent() as object | null | undefined
-    const nextValue = typeof updater === 'function' ? updater(current) : updater
+    const fullDocState = getDocumentState(instance, {...doc, path})
+    const current = fullDocState.getCurrent() as object | null | undefined
+    const nextValue =
+      typeof updater === 'function'
+        ? (updater as (prev: typeof current) => typeof current)(current)
+        : updater
 
     if (typeof nextValue !== 'object' || !nextValue) {
       throw new Error(
@@ -197,11 +299,14 @@ export function useEditDocument(
     const allKeys = Object.keys({...current, ...nextValue})
     const editActions = allKeys
       .filter((key) => !ignoredKeys.includes(key))
-      .filter((key) => current?.[key as keyof typeof current] !== nextValue[key])
+      .filter(
+        (key) =>
+          current?.[key as keyof typeof current] !== (nextValue as Record<string, unknown>)[key],
+      )
       .map((key) =>
         key in nextValue
-          ? editDocument(docHandle, {set: {[key]: nextValue[key]}})
-          : editDocument(docHandle, {unset: [key]}),
+          ? editDocument(doc, {set: {[key]: (nextValue as Record<string, unknown>)[key]}})
+          : editDocument(doc, {unset: [key]}),
       )
 
     return apply(editActions)

package/src/hooks/documents/useDocuments.test.tsx

@@ -68,7 +68,7 @@ describe('useDocuments', () => {
       },
     ]
 
-    vi.mocked(useQuery).mockImplementation((query, options) => {
+    vi.mocked(useQuery).mockImplementation(({query, ...options}) => {
       const result = evaluateSync(parse(query), {dataset, params: options?.params}).get()
       return {
         data: result,