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

package/src/hooks/helpers/createMutationHook.test.tsx

@@ -0,0 +1,125 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {type MutationResult} from '@sanity/sdk/_internal'
+import {act, renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {createMutationHook} from './createMutationHook'
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+
+const settled = <T,>(data: T): MutationResult<T> => ({data, invalidated: Promise.resolve()})
+
+describe('createMutationHook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValue(instance)
+  })
+
+  it('starts idle', () => {
+    const useThing = createMutationHook(vi.fn())
+    const {result} = renderHook(() => useThing())
+
+    expect(result.current.isPending).toBe(false)
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.error).toBeUndefined()
+  })
+
+  it('calls the mutation with the instance and resolves with the server data', async () => {
+    const mutation = vi.fn((_instance, input: string) =>
+      Promise.resolve(settled(`created:${input}`)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    let resolved: string | undefined
+    await act(async () => {
+      resolved = await result.current.mutate('a')
+    })
+
+    expect(mutation).toHaveBeenCalledWith(instance, 'a')
+    expect(resolved).toBe('created:a')
+    expect(result.current.data).toBe('created:a')
+    expect(result.current.error).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('reports isPending while the mutation is in flight', async () => {
+    let release!: (value: MutationResult<string>) => void
+    const mutation = vi.fn(
+      () => new Promise<MutationResult<string>>((resolve) => (release = resolve)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    act(() => {
+      void result.current.mutate('a')
+    })
+    expect(result.current.isPending).toBe(true)
+
+    await act(async () => {
+      release(settled('done'))
+    })
+    expect(result.current.isPending).toBe(false)
+    expect(result.current.data).toBe('done')
+  })
+
+  it('rejects on failure and captures the error in state', async () => {
+    const boom = new Error('nope')
+    const mutation = vi.fn(() => Promise.reject(boom))
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    await act(async () => {
+      await expect(result.current.mutate('a')).rejects.toBe(boom)
+    })
+
+    expect(result.current.error).toBe(boom)
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('reset() returns to idle', async () => {
+    const mutation = vi.fn((_instance, input: string) => Promise.resolve(settled(input)))
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    await act(async () => {
+      await result.current.mutate('a')
+    })
+    expect(result.current.data).toBe('a')
+
+    act(() => result.current.reset())
+    expect(result.current.data).toBeUndefined()
+    expect(result.current.error).toBeUndefined()
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('only the latest call writes state, so a stale call cannot clobber it', async () => {
+    const releases: Array<(value: MutationResult<string>) => void> = []
+    const mutation = vi.fn(
+      () => new Promise<MutationResult<string>>((resolve) => releases.push(resolve)),
+    )
+    const useThing = createMutationHook(mutation)
+    const {result} = renderHook(() => useThing())
+
+    let first!: Promise<string>
+    let second!: Promise<string>
+    act(() => {
+      first = result.current.mutate('first')
+      second = result.current.mutate('second')
+    })
+
+    await act(async () => {
+      releases[1]!(settled('second-result')) // latest resolves first
+      releases[0]!(settled('first-result')) // stale resolves after
+      await Promise.all([first, second])
+    })
+
+    expect(result.current.data).toBe('second-result')
+  })
+})

package/src/hooks/helpers/createMutationHook.tsx

@@ -0,0 +1,93 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {type MutationResult} from '@sanity/sdk/_internal'
+import {useCallback, useRef, useState} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * The value returned by a mutation-backed hook. The write-side counterpart to
+ * {@link FetcherHookResult}: local `{mutate, isPending, error, data, reset}`
+ * state around a core mutation action.
+ *
+ * @public
+ */
+export interface MutationHookResult<TInput, TResult> {
+  /**
+   * Runs the mutation. Resolves with the server response; rejects on failure
+   * (the failure is also captured in {@link MutationHookResult.error}, so a
+   * fire-and-forget caller should read `error` and an `await`ing caller should
+   * `try`/`catch`).
+   */
+  mutate: (input: TInput) => Promise<TResult>
+  /** A mutation is currently in flight. */
+  isPending: boolean
+  /** The most recent failure; cleared by the next `mutate` or `reset`. */
+  error: unknown
+  /** The last successful server response, or `undefined` before the first success. */
+  data: TResult | undefined
+  /** Clears state back to idle and abandons any in-flight result. */
+  reset: () => void
+}
+
+type MutationState<TResult> =
+  | {status: 'idle'; data: undefined; error: undefined}
+  | {status: 'pending'; data: TResult | undefined; error: undefined}
+  | {status: 'success'; data: TResult; error: undefined}
+  | {status: 'error'; data: TResult | undefined; error: unknown}
+
+/**
+ * Builds a hook over a core mutation action (the result of `defineMutation`).
+ * The write-side counterpart to {@link createFetcherHook}: it binds the action
+ * to the current {@link SanityInstance} and tracks `{isPending, error, data}`
+ * locally. `mutate` resolves with the server response only — the mutation's
+ * `invalidated` promise is intentionally not exposed, since cache
+ * reconciliation is handled by the fetcher stores.
+ *
+ * @internal
+ */
+export function createMutationHook<TInput, TResult>(
+  mutation: (instance: SanityInstance, input: TInput) => Promise<MutationResult<TResult>>,
+): () => MutationHookResult<TInput, TResult> {
+  const idle: MutationState<TResult> = {status: 'idle', data: undefined, error: undefined}
+
+  return function useMutationHook(): MutationHookResult<TInput, TResult> {
+    const instance = useSanityInstance()
+    const [state, setState] = useState<MutationState<TResult>>(idle)
+    // Increments per call; only the latest call is allowed to write state, so an
+    // earlier in-flight mutation can't clobber a later one (or a `reset`).
+    const callId = useRef(0)
+
+    const mutate = useCallback(
+      (input: TInput): Promise<TResult> => {
+        const id = ++callId.current
+        setState((prev) => ({status: 'pending', data: prev.data, error: undefined}))
+        return mutation(instance, input).then(
+          ({data}) => {
+            if (id === callId.current) setState({status: 'success', data, error: undefined})
+            return data
+          },
+          (error: unknown) => {
+            if (id === callId.current) {
+              setState((prev) => ({status: 'error', data: prev.data, error}))
+            }
+            throw error
+          },
+        )
+      },
+      [instance],
+    )
+
+    const reset = useCallback(() => {
+      callId.current++ // abandon any in-flight response so it can't revive stale state
+      setState(idle)
+    }, [])
+
+    return {
+      mutate,
+      isPending: state.status === 'pending',
+      error: state.error,
+      data: state.data,
+      reset,
+    }
+  }
+}

package/src/hooks/helpers/createStateSourceHook.test.tsx

@@ -1,4 +1,4 @@
-import {createSanityInstance, type DatasetResource, type SanityInstance} from '@sanity/sdk'
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
 import {throwError} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
@@ -17,7 +17,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should create a hook that provides access to state source', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const mockState = {count: 0}
@@ -39,7 +39,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should recreate state source when params change', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const subscribe = vi.fn()
@@ -65,14 +65,14 @@ describe('createStateSourceHook', () => {
   })
 
   it('should recreate state source when instance changes', () => {
-    const mockInstance1 = createSanityInstance({defaultResource: {projectId: 'p1', dataset: 'd'}})
-    const mockInstance2 = createSanityInstance({defaultResource: {projectId: 'p2', dataset: 'd'}})
+    const mockInstance1 = createSanityInstance({projectId: 'p1', dataset: 'd'})
+    const mockInstance2 = createSanityInstance({projectId: 'p2', dataset: 'd'})
 
     vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance1)
 
     const stateSourceFactory = vi.fn((instance: SanityInstance) => ({
       subscribe: vi.fn(),
-      getCurrent: () => (instance.config.defaultResource as DatasetResource)?.projectId,
+      getCurrent: () => instance.config.projectId,
       observable: throwError(() => new Error('unexpected usage of observable')),
     }))
 
@@ -89,7 +89,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should handle subscription functionality', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const mockSubscribe = vi.fn()
@@ -110,7 +110,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should handle multiple parameters', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const stateSourceFactory = vi.fn(
@@ -129,7 +129,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should throw suspender promise when shouldSuspend is true', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const mockGetState = vi.fn().mockReturnValue({
@@ -163,7 +163,7 @@ describe('createStateSourceHook', () => {
   })
 
   it('should not suspend when shouldSuspend returns false', () => {
-    const mockInstance = createSanityInstance()
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
     vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
 
     const mockState = {value: 'test'}

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -1,4 +1,4 @@
-import {type SanityInstance, type StateSource} from '@sanity/sdk'
+import {type SanityConfig, type SanityInstance, type StateSource} from '@sanity/sdk'
 import {useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -12,6 +12,7 @@ interface CreateStateSourceHookOptions<TParams extends unknown[], TState> {
   getState: StateSourceFactory<TParams, TState>
   shouldSuspend?: (instance: SanityInstance, ...params: TParams) => boolean
   suspender?: (instance: SanityInstance, ...params: TParams) => Promise<unknown>
+  getConfig?: (...params: TParams) => SanityConfig | undefined
 }
 
 export function createStateSourceHook<TParams extends unknown[], TState>(

package/src/hooks/{document/useApplyDocumentActions.test.ts → helpers/useApplyActions.test.tsx}

@@ -1,10 +1,11 @@
-import {applyDocumentActions, type SanityInstance} from '@sanity/sdk'
-import React from 'react'
+import {applyDocumentActions, createSanityInstance} from '@sanity/sdk'
+import {renderHook as reactRenderHook} from '@testing-library/react'
 import {describe, it} from 'vitest'
 
 import {renderHook} from '../../../test/test-utils'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 import {useSanityInstance} from '../context/useSanityInstance'
-import {useApplyDocumentActions} from './useApplyDocumentActions'
+import {useApplyActions} from './useApplyActions'
 
 vi.mock('@sanity/sdk', async (importOriginal) => {
   const original = await importOriginal<typeof import('@sanity/sdk')>()
@@ -13,21 +14,20 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 
 vi.mock('../context/useSanityInstance')
 
-const instance = {instanceId: 'test'} as unknown as SanityInstance
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
 
-describe('useApplyDocumentActions', () => {
+describe('useApplyActions', () => {
   beforeEach(() => {
     vi.resetAllMocks()
     vi.mocked(useSanityInstance).mockReturnValueOnce(instance)
   })
 
-  it('uses the SanityInstance and injects resource from context', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
+  it('uses the effective context resource', async () => {
+    const {result} = renderHook(() => useApplyActions())
     result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
-      resource: {projectId: 'p123', dataset: 'd123'},
     })
 
     expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
@@ -36,21 +36,28 @@ describe('useApplyDocumentActions', () => {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'p123', dataset: 'd123'},
+          // resource named in test-utils
+          resource: {projectId: 'test', dataset: 'test'},
         },
       ],
-      resource: {projectId: 'p123', dataset: 'd123'},
+      resource: {projectId: 'test', dataset: 'test'},
     })
   })
 
-  it('passes resource from action to applyDocumentActions', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
-    result.current({
-      type: 'document.edit',
-      documentType: 'post',
-      documentId: 'abc',
-      resource: {projectId: 'p123', dataset: 'd123'},
+  it('uses the SanityInstance when resource is not provided', async () => {
+    const {result} = reactRenderHook(() => useApplyActions(), {
+      wrapper: ({children}) => (
+        <SanityInstanceContext.Provider value={instance}>{children}</SanityInstanceContext.Provider>
+      ),
     })
+    result.current(
+      {
+        type: 'document.edit',
+        documentType: 'post',
+        documentId: 'abc',
+      },
+      {},
+    )
 
     expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
       actions: [
@@ -58,20 +65,21 @@ describe('useApplyDocumentActions', () => {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'p123', dataset: 'd123'},
+          resource: {projectId: 'p', dataset: 'd'},
         },
       ],
-      resource: {projectId: 'p123', dataset: 'd123'},
+      resource: {projectId: 'p', dataset: 'd'},
     })
   })
 
-  it('uses context resource when action has no resource', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
+  it('resolves resource from projectId and dataset on the action', async () => {
+    const {result} = renderHook(() => useApplyActions())
     result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
-      resource: {projectId: 'test', dataset: 'test'},
+      projectId: 'p',
+      dataset: 'd123',
     })
 
     expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
@@ -80,55 +88,59 @@ describe('useApplyDocumentActions', () => {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'test', dataset: 'test'},
+          resource: {projectId: 'p', dataset: 'd123'},
         },
       ],
-      resource: {projectId: 'test', dataset: 'test'},
+      resource: {projectId: 'p', dataset: 'd123'},
     })
   })
 
-  it('throws when actions have mismatched resources', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
+  it('throws when actions have mismatched project IDs', async () => {
+    const {result} = renderHook(() => useApplyActions())
     expect(() => {
       result.current([
         {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'p', dataset: 'd1'},
+          projectId: 'p123',
+          dataset: 'd',
         },
         {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'def',
-          resource: {projectId: 'p', dataset: 'd2'},
+          projectId: 'p456',
+          dataset: 'd',
         },
       ])
     }).toThrow(/Mismatched resources found in actions/)
   })
 
-  it('throws when actions have mismatched project IDs', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
+  it('throws when actions have mismatched datasets', async () => {
+    const {result} = renderHook(() => useApplyActions())
     expect(() => {
       result.current([
         {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'p123', dataset: 'd1'},
+          projectId: 'p',
+          dataset: 'd1',
         },
         {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'def',
-          resource: {projectId: 'p456', dataset: 'd1'},
+          projectId: 'p',
+          dataset: 'd2',
         },
       ])
     }).toThrow(/Mismatched resources found in actions/)
   })
 
-  it('throws when actions have mismatched datasets', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
+  it('throws when actions have mismatched resources', async () => {
+    const {result} = renderHook(() => useApplyActions())
     expect(() => {
       result.current([
         {
@@ -147,34 +159,61 @@ describe('useApplyDocumentActions', () => {
     }).toThrow(/Mismatched resources found in actions/)
   })
 
-  it('throws when no resource is found from actions or context', async () => {
-    // Use a minimal wrapper without resource context so contextResource is undefined
-    const {result} = renderHook(() => useApplyDocumentActions(), {
-      wrapper: (props) => React.createElement(React.Fragment, null, props.children),
-    })
-
+  it('throws when mixing projectId/dataset and resource with a mismatch (projectId first)', async () => {
+    const {result} = renderHook(() => useApplyActions())
     expect(() => {
-      result.current({
-        type: 'document.edit',
-        documentType: 'post',
-        documentId: 'abc',
-        // no resource
-      } as never)
-    }).toThrow(/resource is required/)
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          projectId: 'p1',
+          dataset: 'd',
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          resource: {projectId: 'p2', dataset: 'd'},
+        },
+      ])
+    }).toThrow(/Mismatched resources found in actions/)
   })
 
-  it('throws when options resource mismatches action resource', async () => {
-    const {result} = renderHook(() => useApplyDocumentActions())
-
+  it('throws when mixing resource and projectId/dataset with a mismatch (resource first)', async () => {
+    const {result} = renderHook(() => useApplyActions())
     expect(() => {
-      result.current(
+      result.current([
         {
           type: 'document.edit',
           documentType: 'post',
           documentId: 'abc',
-          resource: {projectId: 'p1', dataset: 'd1'},
+          resource: {projectId: 'p1', dataset: 'd'},
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          projectId: 'p2',
+          dataset: 'd',
         },
-        {resource: {projectId: 'p2', dataset: 'd2'}},
+      ])
+    }).toThrow(/Mismatched resources found in actions/)
+  })
+
+  it('throws when a top-level options resource conflicts with an action resource', async () => {
+    const {result} = renderHook(() => useApplyActions())
+    expect(() => {
+      result.current(
+        [
+          {
+            type: 'document.edit',
+            documentType: 'post',
+            documentId: 'abc',
+            resource: {projectId: 'p', dataset: 'd1'},
+          },
+        ],
+        {resource: {projectId: 'p', dataset: 'd2'}},
       )
     }).toThrow(/Mismatched resources found in actions/)
   })

package/src/hooks/helpers/useApplyActions.ts

@@ -0,0 +1,68 @@
+import {type Action, type ActionsResult, applyDocumentActions} from '@sanity/sdk'
+import {isDeepEqual} from '@sanity/sdk/_internal'
+import {useContext} from 'react'
+
+import {type ResourceHandle} from '../../config/handles'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {normalizeResourceOptions, useEffectiveContextResource} from './useNormalizedResourceOptions'
+
+/**
+ * @internal
+ *
+ * Shared implementation behind `useApplyDocumentActions` and
+ * `useApplyReleaseActions`. Resolves the effective resource from the action
+ * handles, top-level `options`, or context (in that order), validates that
+ * everything agrees on a single resource, and forwards to
+ * `applyDocumentActions`.
+ *
+ * The two public hooks differ only in their input/output types — at runtime
+ * they're identical because core's `applyDocumentActions` accepts the full
+ * `Action` union.
+ */
+export function useApplyActions(): (
+  actionOrActions: Action | Action[],
+  options?: ResourceHandle,
+) => Promise<ActionsResult> {
+  const instance = useSanityInstance()
+  const resources = useContext(ResourcesContext)
+  const effectiveContextResource = useEffectiveContextResource()
+
+  return (actionOrActions, options) => {
+    const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+    const optionsResource = options
+      ? normalizeResourceOptions(options, resources, effectiveContextResource).resource
+      : undefined
+
+    const normalizedActions = actions.map((action) =>
+      normalizeResourceOptions(action, resources, effectiveContextResource),
+    )
+
+    let resource
+    for (const action of normalizedActions) {
+      const actionResource = action['resource']
+      if (!resource && actionResource) resource = actionResource
+      if (!isDeepEqual(actionResource, resource)) {
+        throw new Error(
+          `Mismatched resources found in actions. All actions must belong to the same resource. Found "${JSON.stringify(actionResource)}" but expected "${JSON.stringify(resource)}".`,
+        )
+      }
+    }
+
+    if (optionsResource && resource && !isDeepEqual(optionsResource, resource)) {
+      throw new Error(
+        `Mismatched resources found in actions. Found top-level resource "${JSON.stringify(optionsResource)}" but expected resource from action handles "${JSON.stringify(resource)}".`,
+      )
+    }
+
+    const effectiveResource = resource ?? optionsResource ?? effectiveContextResource
+    if (!effectiveResource) {
+      throw new Error('No resource found. Provide a resource via the action handle or context.')
+    }
+
+    return applyDocumentActions(instance, {
+      actions: normalizedActions as Action[],
+      resource: effectiveResource,
+    })
+  }
+}