feat(openapi): createJsonifiedRouterClient (#449)

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

## Summary by CodeRabbit

- **New Features**
- Introduced a new function for creating JSON-serialized router clients
compatible with OpenAPI-based RPC systems.
  - Expanded the public API to include new router client utilities.

- **Documentation**
- Added a detailed guide explaining how to use the new JSON-serialized
router client with code examples and usage notes.

- **Tests**
- Added comprehensive tests to verify correct serialization,
deserialization, and error handling for the new JSON-serialized router
client.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/best-practices/optimize-ssr.md

@@ -85,6 +85,58 @@ globalThis.$client = createRouterClient(router, {
 
 :::
 
+::: details `OpenAPILink` support?
+When you use [OpenAPILink](/docs/openapi/client/openapi-link), its `JsonifiedClient` turns native values (like Date or URL) into plain JSON, so your client types no longer match the output of `createRouterClient`. To fix this, oRPC offers `createJsonifiedRouterClient`, which builds a router client that matches the output of OpenAPILink.
+
+::: code-group
+
+```ts [lib/orpc.ts]
+import type { RouterClient } from '@orpc/server'
+import type { JsonifiedClient } from '@orpc/openapi-client'
+import { OpenAPILink } from '@orpc/openapi-client/fetch'
+import { createORPCClient } from '@orpc/client'
+
+declare global {
+  var $client: JsonifiedClient<RouterClient<typeof router>> | undefined
+}
+
+const link = new OpenAPILink({
+  url: () => {
+    if (typeof window === 'undefined') {
+      throw new Error('OpenAPILink is not allowed on the server side.')
+    }
+
+    return new URL('/api', window.location.href)
+  },
+})
+
+/**
+ * Fallback to client-side client if server-side client is not available.
+ */
+export const client: JsonifiedClient<RouterClient<typeof router>> = globalThis.$client ?? createORPCClient(link)
+```
+
+```ts [lib/orpc.server.ts]
+'server only'
+
+import { createJsonifiedRouterClient } from '@orpc/openapi-client'
+
+globalThis.$client = createJsonifiedRouterClient(router, {
+  /**
+   * Provide initial context if needed.
+   *
+   * Because this client instance is shared across all requests,
+   * only include context that's safe to reuse globally.
+   * For per-request context, use middleware context or pass a function as the initial context.
+   */
+  context: async () => ({
+    headers: await headers(),
+  }),
+})
+```
+
+:::
+
 Finally, import `lib/orpc.server.ts` before anything else and on the **server only**. For example, in Next.js add it to `app/layout.tsx`:
 
 ```ts

packages/openapi/src/index.ts

@@ -4,6 +4,7 @@ export * from './openapi'
 export * from './openapi-custom'
 export * from './openapi-generator'
 export * from './openapi-utils'
+export * from './router-client'
 export * from './schema'
 export * from './schema-converter'
 export * from './schema-utils'

packages/openapi/src/router-client.test.ts

@@ -0,0 +1,59 @@
+import { ORPCError, os } from '@orpc/server'
+import { createJsonifiedRouterClient } from './router-client'
+
+describe('createJsonifiedRouterClient', () => {
+  const date = new Date()
+  const file = new File(['foo'], 'some-name.pdf', { type: 'application/pdf' })
+
+  const router = os.router({
+    date: os.handler(({ input }) => ({ date, nested: { date }, input })),
+    file: os.handler(({ input }) => ({ file, nested: { file }, input })),
+    error: os.handler(() => {
+      throw new Error('error')
+    }),
+    orpc_error: os.handler(() => {
+      throw new ORPCError('BAD_REQUEST', {
+        message: 'orpc error',
+        data: { date, nested: { file } },
+      })
+    }),
+  })
+
+  it('on success', async () => {
+    const client = createJsonifiedRouterClient(router)
+
+    await expect(client.date('now')).resolves.toEqual({ date: date.toISOString(), nested: { date: date.toISOString() }, input: 'now' })
+
+    const { file, nested, input } = await client.file('file')
+
+    expect(file).toBeInstanceOf(File)
+    expect(file.name).toBe('some-name.pdf')
+    expect(file.type).toBe('application/pdf')
+    expect(await file.text()).toBe('foo')
+
+    expect(nested).toEqual({ file })
+    expect(input).toBe('file')
+  })
+
+  it('on error', async () => {
+    const client = createJsonifiedRouterClient(router)
+
+    await expect(client.error()).rejects.toSatisfy((e) => {
+      expect(e).toBeInstanceOf(Error)
+      expect(e.message).toBe('error')
+      expect(e.cause).toBeUndefined()
+
+      return true
+    })
+
+    await expect(client.orpc_error()).rejects.toSatisfy((e) => {
+      expect(e).toBeInstanceOf(ORPCError)
+      expect(e.code).toBe('BAD_REQUEST')
+      expect(e.status).toBe(400)
+      expect(e.message).toBe('orpc error')
+      expect(e.data).toEqual({ date: date.toISOString(), nested: { file } })
+
+      return true
+    })
+  })
+})

packages/openapi/src/router-client.ts

@@ -0,0 +1,49 @@
+import type { JsonifiedClient } from '@orpc/openapi-client'
+import type { AnyRouter, ClientContext, CreateProcedureClientOptions, ErrorMap, InferRouterInitialContext, Lazyable, Meta, RouterClient, Schema } from '@orpc/server'
+import type { MaybeOptionalOptions } from '@orpc/shared'
+import { createORPCErrorFromJson } from '@orpc/client'
+import { StandardBracketNotationSerializer, StandardOpenAPIJsonSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard'
+import { createRouterClient, ORPCError } from '@orpc/server'
+import { resolveMaybeOptionalOptions } from '@orpc/shared'
+
+export function createJsonifiedRouterClient<T extends AnyRouter, TClientContext extends ClientContext>(
+  router: Lazyable<T | undefined>,
+  ...rest: MaybeOptionalOptions<
+    CreateProcedureClientOptions<
+      InferRouterInitialContext<T>,
+      Schema<unknown, unknown>,
+      ErrorMap,
+      Meta,
+      TClientContext
+    >
+  >
+): JsonifiedClient<RouterClient<T, TClientContext>> {
+  const options = resolveMaybeOptionalOptions(rest)
+
+  const serializer = new StandardOpenAPISerializer(new StandardOpenAPIJsonSerializer(), new StandardBracketNotationSerializer())
+
+  options.interceptors ??= []
+  options.interceptors.unshift(async (options) => {
+    try {
+      return serializer.deserialize(
+        serializer.serialize(
+          await options.next(),
+        ),
+      )
+    }
+    catch (e) {
+      if (e instanceof ORPCError) {
+        throw createORPCErrorFromJson(serializer.deserialize(
+          serializer.serialize(
+            e.toJSON(),
+            { outputFormat: 'plain' },
+          ),
+        ) as any)
+      }
+
+      throw e
+    }
+  })
+
+  return createRouterClient(router, options) as any
+}