fix(client): stop client proxies from resolving primitive coercion over the network (#1815)

Backports `RECURSIVE_CLIENT_UNWRAP_KEYS` from v2 to the 1.x line. Client
proxies no longer treat `bind`, `valueOf`, `toString`, and `toJSON` as
procedure paths, so `String(client)`, template literals, and
`JSON.stringify(client)` resolve normally instead of throwing or issuing
spurious RPCs — including the React 19.2 dev-build freeze when a client
is passed through props.

Resolves #1809

## Fixes

- `createORPCClient` and `createSafeClient` no longer fire network
requests or throw on primitive coercion and serialization.
- `createRouterUtils` in all query integrations (tanstack-query,
react-query, vue-query, solid-query, svelte-query, vue-colada,
react-swr) gained the same unwrap keys plus v2's `isTypescriptObject`
guard: `JSON.stringify` of utils built over a server-side client no
longer crashes, and `utils.call` on server-side clients now returns the
underlying client as documented.
- Unlike v2, `then` is intentionally not in the unwrap set: v1 keeps
supporting procedures named `then` via `preventNativeAwait`, so no
existing behavior breaks in a patch release.

## Testing

- New coercion/serialization tests for the client, safe client, and
every integration's router utils; changed files are at 100%
statement/branch/function/line coverage.
- All 713 unit tests across the touched packages pass; e2e failures
observed locally are identical on a clean checkout (environment timing,
unrelated).

Author: dinwwwh

apps/content/docs/router.md

@@ -24,6 +24,10 @@ const router = {
 }
 ```
 
+::: warning
+For compatibility, do not use these router keys: `then`, `bind`, `valueOf`, `toString`, `toJSON`.
+:::
+
 ## Extending Router
 
 Routers can be modified to include additional features. For example, to require authentication on all procedures:

packages/client/src/client-safe.test.ts

@@ -54,4 +54,14 @@ describe('createSafeClient', () => {
     expect(safeClient[Symbol('test')]).toEqual(undefined)
     expect(safeClient.nested[Symbol('test')]).toEqual(undefined)
   })
+
+  it('not proxy on unwrap keys', () => {
+    expect(() => String(safeClient)).not.toThrow()
+    expect(() => `${safeClient}`).not.toThrow()
+    expect(JSON.stringify({ safeClient })).toEqual('{}')
+    expect(typeof safeClient.bind).toEqual('function')
+
+    expect(client.ping).not.toBeCalled()
+    expect(client.nested.pong).not.toBeCalled()
+  })
 })

packages/client/src/client-safe.ts

@@ -1,6 +1,7 @@
 import type { Client, ClientRest, NestedClient } from './types'
 import type { SafeResult } from './utils'
 import { isTypescriptObject } from '@orpc/shared'
+import { RECURSIVE_CLIENT_UNWRAP_KEYS } from './consts'
 import { safe } from './utils'
 
 export type SafeClient<T extends NestedClient<any>>
@@ -23,13 +24,13 @@ export type SafeClient<T extends NestedClient<any>>
  */
 export function createSafeClient<T extends NestedClient<any>>(client: T): SafeClient<T> {
   const proxy = new Proxy((...args: any[]) => safe((client as any)(...args)), {
-    get(_, prop, receiver) {
-      const value = Reflect.get(client, prop, receiver)
-
-      if (typeof prop !== 'string') {
-        return value
+    get(target, prop, receiver) {
+      if (typeof prop !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(prop)) {
+        return Reflect.get(target, prop)
       }
 
+      const value = Reflect.get(client, prop, receiver)
+
       if (!isTypescriptObject(value)) {
         return value
       }

packages/client/src/client.test.ts

@@ -46,6 +46,20 @@ describe('createORPCClient', () => {
     expect(client[Symbol('test')]).toBeUndefined()
   })
 
+  it('not recursive on unwrap keys', async () => {
+    const client = createORPCClient(mockedLink) as any
+
+    expect(() => String(client)).not.toThrow()
+    expect(() => `${client}`).not.toThrow()
+    expect(() => `${client.nested}`).not.toThrow()
+    expect(JSON.stringify(client)).toBeUndefined()
+    expect(JSON.stringify({ client })).toEqual('{}')
+    expect(typeof client.bind).toEqual('function')
+    expect(typeof client.nested.bind).toEqual('function')
+
+    expect(mockedLink.call).not.toBeCalled()
+  })
+
   it('prevent native await', async () => {
     const client = createORPCClient(mockedLink) as any
 

packages/client/src/client.ts

@@ -1,5 +1,6 @@
 import type { Client, ClientLink, FriendlyClientOptions, InferClientContext, NestedClient } from './types'
 import { preventNativeAwait } from '@orpc/shared'
+import { RECURSIVE_CLIENT_UNWRAP_KEYS } from './consts'
 import { resolveFriendlyClientOptions } from './utils'
 
 export interface createORPCClientOptions {
@@ -28,7 +29,7 @@ export function createORPCClient<T extends NestedClient<any>>(
 
   const recursive = new Proxy(procedureClient, {
     get(target, key) {
-      if (typeof key !== 'string') {
+      if (typeof key !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(key)) {
         return Reflect.get(target, key)
       }
 

packages/client/src/consts.ts

@@ -1,2 +1,34 @@
 export const ORPC_CLIENT_PACKAGE_NAME = '__ORPC_CLIENT_PACKAGE_NAME_PLACEHOLDER__'
 export const ORPC_CLIENT_PACKAGE_VERSION = '__ORPC_CLIENT_PACKAGE_VERSION_PLACEHOLDER__'
+
+/**
+ * Property names that should resolve to the underlying value instead of
+ * continuing recursive proxy traversal.
+ *
+ * These properties are commonly accessed automatically by JavaScript runtimes,
+ * language features, or third-party libraries. Returning another recursive
+ * proxy for them can cause unexpected behavior, compatibility issues, or
+ * infinite proxy chains.
+ *
+ * Unlike v2, `then` is not included here because v1 supports procedures
+ * named `then` and relies on `preventNativeAwait` to keep `await client` safe.
+ */
+export const RECURSIVE_CLIENT_UNWRAP_KEYS = new Set([
+  /**
+   * Commonly used by libraries to bind functions to a specific `this`
+   * context.
+   */
+  'bind',
+  /**
+   * Commonly accessed during primitive conversion, inspection, and logging.
+   */
+  'valueOf',
+  /**
+   * Commonly accessed during string conversion, inspection, and logging.
+   */
+  'toString',
+  /**
+   * Commonly accessed by serializers such as `JSON.stringify`.
+   */
+  'toJSON',
+])

packages/react-query/src/router-utils.test.ts

@@ -60,4 +60,23 @@ describe('createRouterUtils', () => {
 
     expect(utils[Symbol.for('a')]).toBe(undefined)
   })
+
+  it('safe on primitive coercion and serialization', () => {
+    const utils = createRouterUtils(client) as any
+
+    expect(() => String(utils)).not.toThrow()
+    expect(() => `${utils}`).not.toThrow()
+    expect(() => `${utils.key}`).not.toThrow()
+    expect(() => JSON.stringify({ utils })).not.toThrow()
+
+    expect(client).not.toBeCalled()
+    expect(client.key).not.toBeCalled()
+  })
+
+  it('not recursive on non-object clients', () => {
+    const utils = createRouterUtils(undefined as any) as any
+
+    expect(utils.nonExists).toBeUndefined()
+    expect(utils.key()).toEqual(generalUtilsSpy.mock.results[0]!.value.key())
+  })
 })

packages/react-query/src/router-utils.ts

@@ -1,6 +1,8 @@
 import type { Client, NestedClient } from '@orpc/client'
 import type { GeneralUtils } from './general-utils'
 import type { ProcedureUtils } from './procedure-utils'
+import { RECURSIVE_CLIENT_UNWRAP_KEYS } from '@orpc/client'
+import { isTypescriptObject } from '@orpc/shared'
 import { createGeneralUtils } from './general-utils'
 import { createProcedureUtils } from './procedure-utils'
 
@@ -36,8 +38,9 @@ export function createRouterUtils<T extends NestedClient<any>>(
   }, {
     get(target, prop) {
       const value = Reflect.get(target, prop)
+      const nextClient = isTypescriptObject(client) ? Reflect.get(client, prop) : undefined
 
-      if (typeof prop !== 'string') {
+      if (typeof prop !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(prop) || !isTypescriptObject(nextClient)) {
         return value
       }
 
@@ -48,7 +51,11 @@ export function createRouterUtils<T extends NestedClient<any>>(
       }
 
       return new Proxy(value, {
-        get(_, prop) {
+        get(target, prop) {
+          if (typeof prop !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(prop)) {
+            return Reflect.get(target, prop)
+          }
+
           return Reflect.get(nextUtils, prop)
         },
       })

packages/react-swr/src/router-utils.test.ts

@@ -63,4 +63,23 @@ describe('createRouterUtils', () => {
     const utils = createRouterUtils(client) as any
     expect(utils[Symbol.for('a')]).toBe(undefined)
   })
+
+  it('safe on primitive coercion and serialization', () => {
+    const utils = createRouterUtils(client) as any
+
+    expect(() => String(utils)).not.toThrow()
+    expect(() => `${utils}`).not.toThrow()
+    expect(() => `${utils.key}`).not.toThrow()
+    expect(() => JSON.stringify({ utils })).not.toThrow()
+
+    expect(client).not.toBeCalled()
+    expect(client.key).not.toBeCalled()
+  })
+
+  it('not recursive on non-object clients', () => {
+    const utils = createRouterUtils(undefined as any) as any
+
+    expect(utils.nonExists).toBeUndefined()
+    expect(utils.key()).toEqual(procedureUtilsSpy.mock.results[0]!.value.key())
+  })
 })

packages/react-swr/src/router-utils.ts

@@ -1,7 +1,8 @@
 import type { Client, NestedClient } from '@orpc/client'
 import type { GeneralUtils } from './general-utils'
 import type { ProcedureUtils } from './procedure-utils'
-import { toArray } from '@orpc/shared'
+import { RECURSIVE_CLIENT_UNWRAP_KEYS } from '@orpc/client'
+import { isTypescriptObject, toArray } from '@orpc/shared'
 import { createGeneralUtils } from './general-utils'
 import { createProcedureUtils } from './procedure-utils'
 
@@ -37,8 +38,9 @@ export function createRouterUtils<T extends NestedClient<any>>(
   }, {
     get(target, prop) {
       const value = Reflect.get(target, prop)
+      const nextClient = isTypescriptObject(client) ? Reflect.get(client, prop) : undefined
 
-      if (typeof prop !== 'string') {
+      if (typeof prop !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(prop) || !isTypescriptObject(nextClient)) {
         return value
       }
 
@@ -49,7 +51,11 @@ export function createRouterUtils<T extends NestedClient<any>>(
       }
 
       return new Proxy(value, {
-        get(_, prop) {
+        get(target, prop) {
+          if (typeof prop !== 'string' || RECURSIVE_CLIENT_UNWRAP_KEYS.has(prop)) {
+            return Reflect.get(target, prop)
+          }
+
           return Reflect.get(nextUtils, prop)
         },
       })