feat(react): useOptimisticServerAction Hook (#724)

The `useOptimisticServerAction` hook enables optimistic UI updates while
a server action executes. This provides immediate visual feedback to
users before the server responds.

Closes: https://github.com/unnoq/orpc/issues/701

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Introduced a React hook for optimistic UI updates during server
actions, enabling immediate feedback before server responses.
* Added a set of deferred interceptor functions for asynchronous state
updates.
* **Documentation**
* Added comprehensive documentation and usage examples for the new
optimistic server action hook.
* **Tests**
* Implemented new test suites for the optimistic server action hook and
deferred interceptors to ensure correct behavior.
* **Refactor**
* Updated internal exports and type definitions to support new features
and improve maintainability.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/server-action.md

@@ -182,6 +182,51 @@ export function MyComponent() {
 }
 ```
 
+### `useOptimisticServerAction` Hook
+
+The `useOptimisticServerAction` hook enables optimistic UI updates while a server action executes. This provides immediate visual feedback to users before the server responds.
+
+```tsx
+import { useOptimisticServerAction } from '@orpc/react/hooks'
+import { onSuccessDeferred } from '@orpc/react'
+
+export function MyComponent() {
+  const [todos, setTodos] = useState<Todo[]>([])
+  const { execute, optimisticState } = useOptimisticServerAction(someAction, {
+    optimisticPassthrough: todos,
+    optimisticReducer: (currentState, newTodo) => [...currentState, newTodo],
+    interceptors: [
+      onSuccessDeferred(({ data }) => {
+        setTodos(prevTodos => [...prevTodos, data])
+      }),
+    ],
+  })
+
+  const handleSubmit = (form: FormData) => {
+    const todo = form.get('todo') as string
+    execute({ todo })
+  }
+
+  return (
+    <div>
+      <ul>
+        {optimisticState.map(todo => (
+          <li key={todo.todo}>{todo.todo}</li>
+        ))}
+      </ul>
+      <form action={handleSubmit}>
+        <input type="text" name="todo" required />
+        <button type="submit">Add Todo</button>
+      </form>
+    </div>
+  )
+}
+```
+
+:::info
+The `onSuccessDeferred` interceptor defers execution, useful for updating states.
+:::
+
 ### `createFormAction` Utility
 
 The `createFormAction` utility accepts a [procedure](/docs/procedure) and returns a function to handle form submissions. It uses [Bracket Notation](/docs/openapi/bracket-notation) to deserialize form data.

packages/react/src/deferred-interceptors.test.ts

@@ -0,0 +1,61 @@
+import { intercept } from '@orpc/shared'
+import { onErrorDeferred, onFinishDeferred, onStartDeferred, onSuccessDeferred } from './deferred-interceptors'
+
+describe('onStartDeferred/onSuccessDeferred/onErrorDeferred/onFinishDeferred', async () => {
+  it('on success', async () => {
+    const callback = vi.fn()
+    const output = await intercept([
+      onFinishDeferred(callback),
+      onStartDeferred(callback),
+      onSuccessDeferred(callback),
+      onErrorDeferred(callback),
+    ], {
+      context: true,
+    }, async () => {
+      return 'test'
+    })
+
+    expect(output).toBe('test')
+    expect(callback).toHaveBeenCalledTimes(0)
+
+    await new Promise(resolve => setTimeout(resolve, 6))
+    expect(callback).toHaveBeenCalledTimes(3)
+    expect(callback).toHaveBeenNthCalledWith(1, expect.objectContaining({
+      context: true,
+    }))
+    expect(callback).toHaveBeenNthCalledWith(2, 'test', expect.objectContaining({
+      context: true,
+    }))
+    expect(callback).toHaveBeenNthCalledWith(3, [null, 'test', true], expect.objectContaining({
+      context: true,
+    }))
+  })
+
+  it('on error', async () => {
+    const callback = vi.fn()
+    await expect(intercept([
+      onFinishDeferred(callback),
+      onStartDeferred(callback),
+      onSuccessDeferred(callback),
+      onErrorDeferred(callback),
+    ], {
+      context: true,
+    }, async () => {
+      throw new Error('test')
+    })).rejects.toThrow('test')
+
+    expect(callback).toHaveBeenCalledTimes(0)
+
+    await new Promise(resolve => setTimeout(resolve, 6))
+    expect(callback).toHaveBeenCalledTimes(3)
+    expect(callback).toHaveBeenNthCalledWith(1, expect.objectContaining({
+      context: true,
+    }))
+    expect(callback).toHaveBeenNthCalledWith(2, new Error('test'), expect.objectContaining({
+      context: true,
+    }))
+    expect(callback).toHaveBeenNthCalledWith(3, [new Error('test'), undefined, false], expect.objectContaining({
+      context: true,
+    }))
+  })
+})

packages/react/src/deferred-interceptors.ts

@@ -0,0 +1,45 @@
+import { onError, onFinish, onStart, onSuccess } from '@orpc/shared'
+
+/**
+ * Like `onStart`, but defers execution, useful for updating states.
+ */
+export const onStartDeferred: typeof onStart = (callback, ...rest) => {
+  return onStart((...args) => {
+    setTimeout(() => {
+      callback(...args)
+    }, 6)
+  }, ...rest)
+}
+
+/**
+ * Like `onSuccess`, but defers execution, useful for updating states.
+ */
+export const onSuccessDeferred: typeof onSuccess = (callback, ...rest) => {
+  return onSuccess((...args) => {
+    setTimeout(() => {
+      callback(...args)
+    }, 6)
+  }, ...rest)
+}
+
+/**
+ * Like `onError`, but defers execution, useful for updating states.
+ */
+export const onErrorDeferred: typeof onError = (callback, ...rest) => {
+  return onError((...args) => {
+    setTimeout(() => {
+      callback(...args)
+    }, 6)
+  }, ...rest)
+}
+
+/**
+ * Like `onFinish`, but defers execution, useful for updating states.
+ */
+export const onFinishDeferred: typeof onFinish = (callback, ...rest) => {
+  return onFinish((...args) => {
+    setTimeout(() => {
+      callback(...args)
+    }, 6)
+  }, ...rest)
+}

packages/react/src/hooks/index.ts

@@ -1 +1,2 @@
-export * from './action-hooks'
+export * from './optimistic-server-action'
+export * from './server-action'

packages/react/src/hooks/optimistic-server-action.test-d.ts

@@ -0,0 +1,25 @@
+import { os } from '@orpc/server'
+import { inputSchema } from '../../../contract/tests/shared'
+import { useOptimisticServerAction } from './optimistic-server-action'
+
+describe('useOptimisticServerAction', () => {
+  const action = os
+    .input(inputSchema.optional())
+    .handler(async ({ input }) => {
+      return { output: Number(input) }
+    })
+    .actionable()
+
+  it('can infer optimistic state', () => {
+    const state = useOptimisticServerAction(action, {
+      optimisticPassthrough: [{ output: 0 }],
+      optimisticReducer(state, input) {
+        expectTypeOf(state).toEqualTypeOf<{ output: number }[]>()
+        expectTypeOf(input).toEqualTypeOf<{ input: number } | undefined>()
+        return [...state, { output: Number(input?.input) }]
+      },
+    })
+
+    expectTypeOf(state.optimisticState).toEqualTypeOf<{ output: number }[]>()
+  })
+})

packages/react/src/hooks/optimistic-server-action.test.tsx

@@ -0,0 +1,54 @@
+import { os } from '@orpc/server'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { useState } from 'react'
+import { inputSchema } from '../../../contract/tests/shared'
+import { useOptimisticServerAction } from './optimistic-server-action'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('useOptimisticServerAction', () => {
+  const handler = vi.fn(async ({ input }) => {
+    return { output: Number(input?.input ?? 0) }
+  })
+
+  const action = os
+    .input(inputSchema)
+    .handler(handler)
+    .actionable()
+
+  it.each(['success', 'error'])('on %s', async (scenario) => {
+    if (scenario === 'error') {
+      handler.mockRejectedValueOnce(new Error('Test error'))
+    }
+
+    const { result } = renderHook(() => {
+      const [outputs, setOutputs] = useState(() => [{ output: 0 }])
+      const state = useOptimisticServerAction(action, {
+        optimisticPassthrough: outputs,
+        optimisticReducer(state, input) {
+          return [...state, { output: Number(input?.input ?? 0) }]
+        },
+      })
+
+      return { state, setOutputs }
+    })
+
+    act(() => {
+      result.current.state.execute({ input: 123 })
+    })
+
+    expect(result.current.state.optimisticState).toEqual([{ output: 0 }, { output: 123 }])
+
+    await waitFor(() => expect(result.current.state.status).toBe(scenario))
+
+    expect(result.current.state.optimisticState).toEqual([{ output: 0 }])
+
+    act(() => {
+      result.current.setOutputs(prev => [...prev, { output: 123 }])
+    })
+
+    expect(result.current.state.optimisticState).toEqual([{ output: 0 }, { output: 123 }])
+  })
+})

packages/react/src/hooks/optimistic-server-action.ts

@@ -0,0 +1,35 @@
+import type { ORPCErrorJSON } from '@orpc/client'
+import type { ActionableClient, UnactionableError } from '@orpc/server'
+import type { UseServerActionOptions, UseServerActionResult } from './server-action'
+import { onStart, toArray } from '@orpc/shared'
+import { useCallback, useMemo, useOptimistic } from 'react'
+import { useServerAction } from './server-action'
+
+export interface UseOptimisticServerActionOptions<TInput, TOutput, TError, TOptimisticState> extends
+  UseServerActionOptions<TInput, TOutput, TError> {
+  optimisticPassthrough: TOptimisticState
+  optimisticReducer: (state: TOptimisticState, input: TInput) => TOptimisticState
+}
+
+export type UseOptimisticServerActionResult<TInput, TOutput, TError, TOptimisticState> = UseServerActionResult<TInput, TOutput, TError> & {
+  optimisticState: TOptimisticState
+}
+
+export function useOptimisticServerAction<TInput, TOutput, TError extends ORPCErrorJSON<any, any>, TOptimisticState>(
+  action: ActionableClient<TInput, TOutput, TError>,
+  options: UseOptimisticServerActionOptions<TInput, TOutput, UnactionableError<TError>, TOptimisticState>,
+): UseOptimisticServerActionResult<TInput, TOutput, UnactionableError<TError>, TOptimisticState> {
+  const [optimisticState, addOptimistic] = useOptimistic(options.optimisticPassthrough, options.optimisticReducer)
+
+  const state = useServerAction(action, {
+    ...options,
+    interceptors: [
+      useCallback(onStart(({ input }) => {
+        addOptimistic(input)
+      }), [addOptimistic]),
+      ...toArray(options.interceptors),
+    ],
+  })
+
+  return useMemo(() => ({ ...state, optimisticState }), [state, optimisticState]) as any
+}

…s/react/src/hooks/action-hooks.test-d.ts …/react/src/hooks/server-action.test-d.tspackages/react/src/hooks/action-hooks.test-d.ts renamed to packages/react/src/hooks/server-action.test-d.ts packages/react/src/hooks/action-hooks.test-d.ts renamed to packages/react/src/hooks/server-action.test-d.ts

@@ -2,7 +2,7 @@ import type { ORPCError } from '@orpc/server'
 import { os, safe } from '@orpc/server'
 import { z } from 'zod'
 import { baseErrorMap, inputSchema, outputSchema } from '../../../contract/tests/shared'
-import { useServerAction } from './action-hooks'
+import { useServerAction } from './server-action'
 
 describe('useServerAction', () => {
   const action = os

…es/react/src/hooks/action-hooks.test.tsx …s/react/src/hooks/server-action.test.tsxpackages/react/src/hooks/action-hooks.test.tsx renamed to packages/react/src/hooks/server-action.test.tsx packages/react/src/hooks/action-hooks.test.tsx renamed to packages/react/src/hooks/server-action.test.tsx

@@ -1,7 +1,7 @@
 import { ORPCError, os } from '@orpc/server'
 import { act, renderHook, waitFor } from '@testing-library/react'
 import { baseErrorMap, inputSchema, outputSchema } from '../../../contract/tests/shared'
-import { useServerAction } from './action-hooks'
+import { useServerAction } from './server-action'
 
 beforeEach(() => {
   vi.clearAllMocks()

packages/react/src/hooks/action-hooks.ts packages/react/src/hooks/server-action.tspackages/react/src/hooks/action-hooks.ts renamed to packages/react/src/hooks/server-action.ts

@@ -70,6 +70,12 @@ export interface UseServerActionErrorResult<TInput, TOutput, TError> extends Use
   executedAt: Date
 }
 
+export type UseServerActionResult<TInput, TOutput, TError>
+  = | UseServerActionIdleResult<TInput, TOutput, TError>
+    | UseServerActionSuccessResult<TInput, TOutput, TError>
+    | UseServerActionErrorResult<TInput, TOutput, TError>
+    | UseServerActionPendingResult<TInput, TOutput, TError>
+
 const INITIAL_STATE = {
   data: undefined,
   error: null,
@@ -97,11 +103,8 @@ const PENDING_STATE = {
  */
 export function useServerAction<TInput, TOutput, TError extends ORPCErrorJSON<any, any>>(
   action: ActionableClient<TInput, TOutput, TError>,
-  options: NoInfer<UseServerActionOptions<TInput, TOutput, UnactionableError<TError>>> = {},
-): UseServerActionIdleResult<TInput, TOutput, UnactionableError<TError>>
-  | UseServerActionSuccessResult<TInput, TOutput, UnactionableError<TError>>
-  | UseServerActionErrorResult<TInput, TOutput, UnactionableError<TError>>
-  | UseServerActionPendingResult<TInput, TOutput, UnactionableError<TError>> {
+  options: UseServerActionOptions<TInput, TOutput, UnactionableError<TError>> = {},
+): UseServerActionResult<TInput, TOutput, UnactionableError<TError>> {
   const [state, setState] = useState<Omit<
     | UseServerActionIdleResult<TInput, TOutput, UnactionableError<TError>>
     | UseServerActionSuccessResult<TInput, TOutput, UnactionableError<TError>>