fix(client): prevent unintended procedure calls when awaiting client (#887)

Previously, awaiting the client directly (e.g., `await client`) would
trigger a procedure call with the name "rpc", causing unexpected
behavior.

This fix ensures that awaiting the client itself does nothing, while
maintaining the ability to await actual procedure calls like `await
client.myProcedure()`.

The solution uses `preventNativeAwait` to disable the default
Promise-like behavior of the client proxy when used with the `await`
keyword.

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

* New Features
* Improved client behavior when accidentally awaited or when accessing
then-like properties, ensuring consistent chaining and calls.
* Introduced a shared safeguard that preserves normal object usage even
if awaited; now available to consumers.

* Bug Fixes
* Resolved unexpected behavior caused by native await semantics on
client objects without changing the public API.

* Tests
* Added comprehensive tests covering non-awaited, awaited, repeated,
nested, and Promise.resolve scenarios to validate consistent behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

packages/client/src/client.test.ts

@@ -45,4 +45,20 @@ describe('createORPCClient', () => {
     const client = createORPCClient(mockedLink) as any
     expect(client[Symbol('test')]).toBeUndefined()
   })
+
+  it('prevent native await', async () => {
+    const client = createORPCClient(mockedLink) as any
+
+    const client2 = await client
+    expect(await client2.then({ value: 'client2' })).toEqual('__mocked__')
+    expect(mockedLink.call).toHaveBeenNthCalledWith(1, ['then'], { value: 'client2' }, { context: {} })
+
+    const client3 = await client2.then
+    expect(await client3.something({ value: 'client3' })).toEqual('__mocked__')
+    expect(mockedLink.call).toHaveBeenNthCalledWith(2, ['then', 'something'], { value: 'client3' }, { context: {} })
+
+    const client4 = await client3.something
+    expect(await client4.then({ value: 'client4' })).toEqual('__mocked__')
+    expect(mockedLink.call).toHaveBeenNthCalledWith(3, ['then', 'something', 'then'], { value: 'client4' }, { context: {} })
+  })
 })

packages/client/src/client.ts

@@ -1,4 +1,5 @@
 import type { Client, ClientLink, FriendlyClientOptions, InferClientContext, NestedClient } from './types'
+import { preventNativeAwait } from '@orpc/shared'
 import { resolveFriendlyClientOptions } from './utils'
 
 export interface createORPCClientOptions {
@@ -38,5 +39,5 @@ export function createORPCClient<T extends NestedClient<any>>(
     },
   })
 
-  return recursive as any
+  return preventNativeAwait(recursive) as any
 }

packages/shared/src/index.ts

@@ -12,6 +12,7 @@ export * from './iterator'
 export * from './json'
 export * from './object'
 export * from './otel'
+export * from './proxy'
 export * from './queue'
 export * from './stream'
 export * from './types'

packages/shared/src/proxy.test.ts

@@ -0,0 +1,102 @@
+import { preventNativeAwait } from './proxy'
+
+describe('preventNativeAwait', () => {
+  it('should work normally if not awaited', () => {
+    const obj = { value: 42 }
+    const proxy = preventNativeAwait(obj)
+    expect(proxy).toEqual(obj)
+
+    const obj2 = { then: 323, catch: 123 }
+    const proxy2 = preventNativeAwait(obj2)
+    expect(proxy2).toEqual(obj2)
+
+    const obj3 = { then: (...args: any[]) => ({ args }), catch: (...args: any[]) => ({ args }) }
+    const proxy3 = preventNativeAwait(obj3)
+    expect(proxy3.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(proxy3.catch(4, 5, 6)).toEqual({ args: [4, 5, 6] })
+  })
+
+  it('returns itself if awaited', async () => {
+    const obj = { value: 42 }
+    const proxy = preventNativeAwait(obj)
+    expect(await proxy).toEqual(obj)
+
+    const obj2 = { then: 323, catch: 123 }
+    const proxy2 = preventNativeAwait(obj2)
+    expect(await proxy2).toEqual(obj2)
+    expect(await proxy2).toEqual(obj2)
+
+    const obj3 = { then: (...args: any[]) => ({ args }), catch: (...args: any[]) => ({ args }) }
+    const proxy3 = preventNativeAwait(obj3)
+    const result3 = await (proxy3 as any)
+    expect(result3.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(result3.catch(3, 4, 5)).toEqual({ args: [3, 4, 5] })
+  })
+
+  it('returns itself if multiple awaited times', async () => {
+    const obj = { value: 42 }
+    const proxy = preventNativeAwait(obj)
+    const result = await (proxy as any)
+    expect(result).toEqual(obj)
+    await new Promise(resolve => setTimeout(resolve, 1))
+    expect(await proxy).toEqual(obj)
+
+    const obj2 = { then: 323, catch: 123 }
+    const proxy2 = preventNativeAwait(obj2)
+    const result2 = await (proxy2 as any)
+    expect(result2).toEqual(obj2)
+    await new Promise(resolve => setTimeout(resolve, 1))
+    expect(await proxy2).toEqual(obj2)
+
+    const obj3 = { then: (...args: any[]) => ({ args }), catch: (...args: any[]) => ({ args }) }
+    const proxy3 = preventNativeAwait(obj3)
+    const result3 = await (proxy3 as any)
+    expect(result3.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(result3.catch(4, 5, 6)).toEqual({ args: [4, 5, 6] })
+    await new Promise(resolve => setTimeout(resolve, 1))
+    const result3_2 = await (proxy3 as any)
+    expect(result3_2.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(result3_2.catch(4, 5, 6)).toEqual({ args: [4, 5, 6] })
+  })
+
+  it('returns itself if nested awaited times', async () => {
+    const obj = { value: 42 }
+    const proxy = preventNativeAwait(obj)
+    const result = await (proxy as any)
+    expect(result).toEqual(obj)
+    await new Promise(resolve => setTimeout(resolve, 1))
+    expect(await result).toEqual(obj)
+
+    const obj2 = { then: 323, catch: 123 }
+    const proxy2 = preventNativeAwait(obj2)
+    const result2 = await (proxy2 as any)
+    expect(result2).toEqual(obj2)
+    await new Promise(resolve => setTimeout(resolve, 1))
+    expect(await result2).toEqual(obj2)
+
+    const obj3 = { then: (...args: any[]) => ({ args }), catch: (...args: any[]) => ({ args }) }
+    const proxy3 = preventNativeAwait(obj3)
+    const result3 = await (proxy3 as any)
+    expect(result3.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(result3.catch(4, 5, 6)).toEqual({ args: [4, 5, 6] })
+    await new Promise(resolve => setTimeout(resolve, 1))
+    const result3_2 = await (result3 as any)
+    expect(result3_2.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+    expect(result3_2.catch(4, 5, 6)).toEqual({ args: [4, 5, 6] })
+  })
+
+  it('resolves via Promise.resolve without triggering thenable assimilation', async () => {
+    const obj = { value: 42 }
+    const proxy = preventNativeAwait(obj)
+    await expect(Promise.resolve(proxy)).resolves.toEqual(obj)
+
+    const obj2 = { then: 123 }
+    const proxy2 = preventNativeAwait(obj2)
+    await expect(Promise.resolve(proxy2)).resolves.toEqual(obj2)
+
+    const obj3 = { then: (...args: any[]) => ({ args }) }
+    const proxy3 = preventNativeAwait(obj3)
+    const resolved = await Promise.resolve(proxy3 as any)
+    expect(resolved.then(1, 2, 3)).toEqual({ args: [1, 2, 3] })
+  })
+})

packages/shared/src/proxy.ts

@@ -0,0 +1,49 @@
+import type { AnyFunction } from './function'
+
+/**
+ * Prevents objects from being awaitable by intercepting the `then` method
+ * when called by the native await mechanism. This is useful for preventing
+ * accidental awaiting of objects that aren't meant to be promises.
+ */
+export function preventNativeAwait<T extends object>(target: T): T {
+  return new Proxy(target, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver)
+
+      if (prop !== 'then' || typeof value !== 'function') {
+        return value
+      }
+
+      return new Proxy(value, {
+        apply(targetFn, thisArg, args) {
+          /**
+           * Do nothing if .then not triggered by `await`
+           */
+          if (args.length !== 2 || args.some(arg => !isNativeFunction(arg))) {
+            return Reflect.apply(targetFn, thisArg, args)
+          }
+
+          let shouldOmit = true
+          args[0].call(thisArg, preventNativeAwait(new Proxy(target, {
+            get: (target, prop, receiver) => {
+              /**
+               * Only omit `then` once, in `await` resolution, afterwards it should become normal
+               */
+              if (shouldOmit && prop === 'then') {
+                shouldOmit = false
+                return undefined
+              }
+
+              return Reflect.get(target, prop, receiver)
+            },
+          })))
+        },
+      })
+    },
+  })
+}
+
+const NATIVE_FUNCTION_REGEX = /^\s*function\s*\(\)\s*\{\s*\[native code\]\s*\}\s*$/
+function isNativeFunction(fn: unknown): fn is AnyFunction {
+  return typeof fn === 'function' && NATIVE_FUNCTION_REGEX.test(fn.toString())
+}