feat(server, react)!: remake server action (#308)

Entirely rewrite server action for oRPC and comewith some utilities and
hooks for react

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

- **New Features**
- Introduced a dedicated React integration package that delivers
utilities for executing server actions and handling form submissions.
- Enabled experimental support in Next.js for enhanced authentication
handling.

- **Documentation**
- Updated guides and package overviews to highlight the new React
integration capabilities.

- **Chores**
	- Refreshed dependencies and configurations for Next.js and React.

- **Tests**
- Expanded test coverage to validate the new integration utilities and
enhanced workflows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

README.md

@@ -53,6 +53,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
 - [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).

apps/content/docs/procedure.md

@@ -28,7 +28,7 @@ const example = os
     return { id: 1 }
   })
   .callable() // Make the procedure callable like a regular function
-  .actionable() // Like .callable, but compatible with server actions
+  .actionable() // Server Action compatibility
 ```
 
 > The `.handler` method is the only required step. All other chains are optional.

apps/content/docs/server-action.md

@@ -5,39 +5,36 @@ description: Integrate oRPC procedures with React Server Actions
 
 # Server Action
 
-[Server Action](https://react.dev/reference/rsc/server-functions) let client components call asynchronous server functions. With oRPC, you can make your procedures compatible by appending the `.actionable` modifier.
+React [Server Actions](https://react.dev/reference/rsc/server-functions) let client components invoke asynchronous server functions. With oRPC, you simply append the `.actionable` modifier to enable Server Action compatibility.
 
 ## Server Side
 
-Define your procedure using `.actionable` to enable Server Action compatibility. For example:
+Define your procedure with `.actionable` for Server Action support.
 
 ```ts twoslash
 import { onError, os } from '@orpc/server'
 import { z } from 'zod'
+// ---cut---
 'use server'
 
 export const ping = os
   .input(z.object({ name: z.string() }))
-  .handler(async ({ input }) => {
-    return `Hello, ${input.name}`
-  })
+  .handler(async ({ input }) => `Hello, ${input.name}`)
   .actionable({
-    context: async () => ({}), // Provide initial context if needed
+    context: async () => ({}), // Optional: provide initial context if needed
     interceptors: [
-      onError((error) => {
-        console.error(error)
-      }),
-    ]
+      onError(error => console.error(error)),
+    ],
   })
 ```
 
 :::tip
-When using Server Actions, we recommend [Runtime Context](/docs/context#execution-context) over [Initial Context](/docs/context#initial-context).
+We recommend using [Runtime Context](/docs/context#execution-context) instead of [Initial Context](/docs/context#initial-context) when working with Server Actions.
 :::
 
 ## Client Side
 
-On the client, simply import and call your procedure as shown below:
+On the client, import and call your procedure as follows:
 
 ```tsx
 'use client'
@@ -49,20 +46,181 @@ export function MyComponent() {
 
   const handleSubmit = async (e: FormEvent) => {
     e.preventDefault()
-    const result = await ping({ name })
-    console.log(result)
+    const [error, data] = await ping({ name })
+    console.log(error, data)
   }
 
   return (
     <form onSubmit={handleSubmit}>
-      <input
-        value={name}
-        onChange={e => setName(e.target.value)}
-      />
+      <input value={name} onChange={e => setName(e.target.value)} />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+This approach seamlessly integrates server-side procedures with client components via Server Actions.
+
+## Type‑Safe Error Handling
+
+The `.actionable` modifier supports type-safe error handling with a JSON-like error object.
+
+```ts twoslash
+import { os } from '@orpc/server'
+import { z } from 'zod'
+
+export const someAction = os
+  .input(z.object({ name: z.string() }))
+  .errors({
+    SOME_ERROR: {
+      message: 'Some error message',
+      data: z.object({ some: z.string() }),
+    },
+  })
+  .handler(async ({ input }) => `Hello, ${input.name}`)
+  .actionable()
+// ---cut---
+'use client'
+
+const [error, data] = await someAction({ name: 'John' })
+
+if (error) {
+  if (error.defined) {
+    console.log(error.data)
+    //                 ^ Typed error data
+  }
+  // Handle unknown errors
+}
+else {
+  // Handle success
+  console.log(data)
+}
+```
+
+## `@orpc/react` Package
+
+The `@orpc/react` package offers utilities to integrate oRPC with React and React Server Actions.
+
+### Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/react@latest
+```
+
+```sh [yarn]
+yarn add @orpc/react@latest
+```
+
+```sh [pnpm]
+pnpm add @orpc/react@latest
+```
+
+```sh [bun]
+bun add @orpc/react@latest
+```
+
+```sh [deno]
+deno install npm:@orpc/react@latest
+```
+
+:::
+
+### `useServerAction` Hook
+
+The `useServerAction` hook simplifies invoking server actions in React.
+
+```tsx twoslash
+import * as React from 'react'
+import { os } from '@orpc/server'
+import { z } from 'zod'
+
+export const someAction = os
+  .input(z.object({ name: z.string() }))
+  .errors({
+    SOME_ERROR: {
+      message: 'Some error message',
+      data: z.object({ some: z.string() }),
+    },
+  })
+  .handler(async ({ input }) => `Hello, ${input.name}`)
+  .actionable()
+// ---cut---
+'use client'
+
+import { useServerAction } from '@orpc/react/hooks'
+import { isDefinedError, onError } from '@orpc/client'
+
+export function MyComponent() {
+  const { execute, data, error, status } = useServerAction(someAction, {
+    interceptors: [
+      onError((error) => {
+        if (isDefinedError(error)) {
+          console.error(error.data)
+          //                   ^ Typed error data
+        }
+      }),
+    ],
+  })
+
+  const action = async (form: FormData) => {
+    const name = form.get('name') as string
+    execute({ name })
+  }
+
+  return (
+    <form action={action}>
+      <input type="text" name="name" required />
       <button type="submit">Submit</button>
+      {status === 'pending' && <p>Loading...</p>}
     </form>
   )
 }
 ```
 
-This approach seamlessly integrates server-side procedures with your client components using Server Actions.
+### `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.
+
+```tsx
+import { createFormAction } from '@orpc/react'
+
+const dosomething = os
+  .input(
+    z.object({
+      user: z.object({
+        name: z.string(),
+        age: z.coerce.number(),
+      }),
+    })
+  )
+  .handler(({ input }) => {
+    console.log('Form action called!')
+    console.log(input)
+  })
+
+export const redirectSomeWhereForm = createFormAction(dosomething, {
+  interceptors: [
+    onSuccess(async () => {
+      redirect('/some-where')
+    }),
+  ],
+})
+
+export function MyComponent() {
+  return (
+    <form action={redirectSomeWhereForm}>
+      <input type="text" name="user[name]" required />
+      <input type="number" name="user[age]" required />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+By moving the `redirect('/some-where')` logic into `createFormAction` rather than the procedure, you enhance the procedure's reusability beyond Server Actions.
+
+::: info
+When using `createFormAction`, any `ORPCError` with a status of `401`, `403`, or `404` is automatically converted into the corresponding Next.js error responses: [unauthorized](https://nextjs.org/docs/app/api-reference/functions/unauthorized), [forbidden](https://nextjs.org/docs/app/api-reference/functions/forbidden), and [not found](https://nextjs.org/docs/app/api-reference/functions/not-found).
+:::

apps/content/package.json

@@ -13,6 +13,7 @@
     "@orpc/contract": "workspace:*",
     "@orpc/openapi": "workspace:*",
     "@orpc/openapi-client": "workspace:*",
+    "@orpc/react": "workspace:*",
     "@orpc/react-query": "workspace:*",
     "@orpc/server": "workspace:*",
     "@orpc/valibot": "workspace:*",
@@ -24,7 +25,7 @@
     "@tanstack/solid-query": "^5.66.4",
     "@tanstack/svelte-query": "^5.66.4",
     "@tanstack/vue-query": "^5.66.4",
-    "next": "^15.1.7",
+    "next": "^15.2.4",
     "openai": "^4.85.4",
     "pinia": "^2.3.0",
     "svelte": "^5.0.0"

packages/arktype/README.md

@@ -53,6 +53,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
 - [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).

packages/client/README.md

@@ -53,6 +53,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
 - [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).

packages/client/src/types.test-d.ts

@@ -1,54 +1,44 @@
+import type { ORPCError } from './error'
 import type { Client, ClientContext } from './types'
 
 describe('client', () => {
-  const fn: Client<ClientContext, string, number, Error> = async (...[input, options]) => {
-    expectTypeOf(input).toEqualTypeOf<string>()
-    expectTypeOf(options).toMatchTypeOf<({ context?: unknown, signal?: AbortSignal }) | undefined>()
-    return 123
-  }
-
-  const fnWithOptionalInput: Client<ClientContext, string | undefined, number, Error> = async (...args) => {
+  const client: Client<{ cache?: boolean }, string | undefined, number, Error | ORPCError<'OVERRIDE', unknown>> = async (...args) => {
     const [input, options] = args
 
     expectTypeOf(input).toEqualTypeOf<string | undefined>()
-    expectTypeOf(options).toMatchTypeOf<{ context?: unknown, signal?: AbortSignal } | undefined>()
+    expectTypeOf(options).toMatchTypeOf<{ context?: { cache?: boolean }, signal?: AbortSignal } | undefined>()
     return 123
   }
 
   it('just a function', () => {
-    expectTypeOf(fn).toMatchTypeOf<(input: string, options: { context?: ClientContext, signal?: AbortSignal }) => Promise<number>>()
-    expectTypeOf(fnWithOptionalInput).toMatchTypeOf<(input: string | undefined, options: { context?: ClientContext, signal?: AbortSignal }) => Promise<number>>()
+    expectTypeOf(client).toMatchTypeOf<(input: string | undefined, options: { context?: ClientContext, signal?: AbortSignal }) => Promise<number>>()
   })
 
   it('infer correct input', () => {
-    fn('123')
-    fnWithOptionalInput('123')
+    client('123')
+    client(undefined)
+    client()
 
     // @ts-expect-error - invalid input
-    fn(123)
+    client(123)
     // @ts-expect-error - invalid input
-    fnWithOptionalInput(123)
+    client({})
+  })
 
+  it('require non-undefindable input', () => {
+    const client = {} as Client<ClientContext, { val: string }, { val: number }, Error>
+
+    client({ val: '123' })
+    // @ts-expect-error - missing input
+    client()
     // @ts-expect-error - invalid input
-    fn({})
-    // @ts-expect-error - invalid input
-    fnWithOptionalInput({})
+    client({ val: 123 })
   })
 
   it('accept signal', () => {
-    fn('123', { signal: new AbortSignal() })
-    fnWithOptionalInput('123', { signal: new AbortSignal() })
-
+    client('123', { signal: new AbortSignal() })
     // @ts-expect-error - invalid signal
-    fn('123', { signal: 1234 })
-    // @ts-expect-error - invalid signal
-    fnWithOptionalInput('123', { signal: 1234 })
-  })
-
-  it('can accept call without args', () => {
-    expectTypeOf(fnWithOptionalInput()).toMatchTypeOf<Promise<number>>()
-    // @ts-expect-error - input is required
-    expectTypeOf(fn()).toEqualTypeOf<Promise<number>>()
+    client('123', { signal: 1234 })
   })
 
   describe('context', () => {
@@ -81,4 +71,14 @@ describe('client', () => {
       client({ val: '123' }, { context: { userId: 123 } })
     })
   })
+
+  it('infer correct output', async () => {
+    expectTypeOf(await client('123')).toEqualTypeOf<number>()
+  })
+
+  it('can reverse infer', () => {
+    expectTypeOf<
+      typeof client extends Client<infer C, infer I, infer O, infer E> ? [C, I, O, E] : never
+    >().toEqualTypeOf<[{ cache?: boolean }, string | undefined, number, Error | ORPCError<'OVERRIDE', unknown>]>()
+  })
 })

packages/contract/README.md

@@ -53,6 +53,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
 - [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).

packages/openapi-client/README.md

@@ -53,6 +53,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
 - [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).