feat: provide additional $call calling style, add $callOptional feature

Author: antfu

src/index.ts

@@ -117,15 +117,48 @@ export interface BirpcGroupFn<T> {
   asEvent: (...args: ArgumentsType<T>) => Promise<void>
 }
 
-export type BirpcReturn<RemoteFunctions, LocalFunctions = Record<string, never>> = {
-  [K in keyof RemoteFunctions]: BirpcFn<RemoteFunctions[K]>
-} & {
+export interface BirpcReturnBuiltin<
+  RemoteFunctions,
+  LocalFunctions = Record<string, never>,
+> {
+  /**
+   * Raw functions object
+   */
   $functions: LocalFunctions
+  /**
+   * Whether the RPC is closed
+   */
+  readonly $closed: boolean
+  /**
+   * Close the RPC connection
+   */
   $close: (error?: Error) => void
-  $closed: boolean
+  /**
+   * Reject pending calls
+   */
   $rejectPendingCalls: (handler?: PendingCallHandler) => Promise<void>[]
+  /**
+   * Call the remote function and wait for the result.
+   * An alternative to directly calling the function
+   */
+  $call: <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) => Promise<Awaited<ReturnType<RemoteFunctions[K]>>>
+  /**
+   * Same as `$call`, but returns `undefined` if the function is not defined on the remote side.
+   */
+  $callOptional: <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) => Promise<Awaited<ReturnType<RemoteFunctions[K]> | undefined>>
+  /**
+   * Send event without asking for response
+   */
+  $callEvent: <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) => Promise<void>
 }
 
+export type BirpcReturn<
+  RemoteFunctions,
+  LocalFunctions = Record<string, never>,
+> = {
+  [K in keyof RemoteFunctions]: BirpcFn<RemoteFunctions[K]>
+} & BirpcReturnBuiltin<RemoteFunctions, LocalFunctions>
+
 type PendingCallHandler = (options: Pick<PromiseEntry, 'method' | 'reject'>) => void | Promise<void>
 
 export type BirpcGroupReturn<RemoteFunctions> = {
@@ -166,6 +199,10 @@ interface Request {
    * Arguments
    */
   a: any[]
+  /**
+   * Optional
+   */
+  o?: boolean
 }
 
 interface Response {
@@ -201,7 +238,7 @@ const { clearTimeout, setTimeout } = globalThis
 const random = Math.random.bind(Math)
 
 export function createBirpc<RemoteFunctions = Record<string, never>, LocalFunctions extends object = Record<string, never>>(
-  functions: LocalFunctions,
+  $functions: LocalFunctions,
   options: BirpcOptions<RemoteFunctions>,
 ): BirpcReturn<RemoteFunctions, LocalFunctions> {
   const {
@@ -216,107 +253,134 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
     timeout = DEFAULT_TIMEOUT,
   } = options
 
-  const rpcPromiseMap = new Map<string, PromiseEntry>()
+  let $closed = false
 
+  const _rpcPromiseMap = new Map<string, PromiseEntry>()
   let _promiseInit: Promise<any> | any
-  let closed = false
 
-  const rpc = new Proxy({}, {
-    get(_, method: string) {
-      if (method === '$functions')
-        return functions
-
-      if (method === '$close')
-        return close
+  async function _call(
+    method: string,
+    args: unknown[],
+    event?: boolean,
+    optional?: boolean,
+  ) {
+    if ($closed)
+      throw new Error(`[birpc] rpc is closed, cannot call "${method}"`)
+
+    const req: Request = { m: method, a: args, t: TYPE_REQUEST }
+    if (optional)
+      req.o = true
+
+    const send = async (_req: Request) => post(serialize(_req))
+    if (event) {
+      await send(req)
+      return
+    }
 
-      if (method === '$rejectPendingCalls') {
-        return rejectPendingCalls
+    if (_promiseInit) {
+      // Wait if `on` is promise
+      try {
+        await _promiseInit
       }
+      finally {
+        // don't keep resolved promise hanging
+        _promiseInit = undefined
+      }
+    }
 
-      if (method === '$closed')
-        return closed
+    // eslint-disable-next-line prefer-const
+    let { promise, resolve, reject } = createPromiseWithResolvers<any>()
 
-      // catch if "createBirpc" is returned from async function
-      if (method === 'then' && !eventNames.includes('then' as any) && !('then' in functions))
-        return undefined
+    const id = nanoid()
+    req.i = id
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
 
-      const sendEvent = async (...args: any[]) => {
-        await post(serialize(<Request>{ m: method, a: args, t: TYPE_REQUEST }))
-      }
-      if (eventNames.includes(method as any)) {
-        sendEvent.asEvent = sendEvent
-        return sendEvent
-      }
-      const sendCall = async (...args: any[]) => {
-        if (closed)
-          throw new Error(`[birpc] rpc is closed, cannot call "${method}"`)
-        if (_promiseInit) {
-          // Wait if `on` is promise
+    async function handler(newReq: Request = req) {
+      if (timeout >= 0) {
+        timeoutId = setTimeout(() => {
           try {
-            await _promiseInit
+            // Custom onTimeoutError handler can throw its own error too
+            const handleResult = options.onTimeoutError?.(method, args)
+            if (handleResult !== true)
+              throw new Error(`[birpc] timeout on calling "${method}"`)
           }
-          finally {
-            // don't keep resolved promise hanging
-            _promiseInit = undefined
+          catch (e) {
+            reject(e)
           }
-        }
+          _rpcPromiseMap.delete(id)
+        }, timeout)
 
-        // eslint-disable-next-line prefer-const
-        let { promise, resolve, reject } = createPromiseWithResolvers<any>()
-
-        const id = nanoid()
-        let timeoutId: ReturnType<typeof setTimeout> | undefined
-        const _req: Request = { m: method, a: args, i: id, t: TYPE_REQUEST }
-
-        async function handler(req: Request = _req) {
-          if (timeout >= 0) {
-            timeoutId = setTimeout(() => {
-              try {
-                // Custom onTimeoutError handler can throw its own error too
-                const handleResult = options.onTimeoutError?.(method, args)
-                if (handleResult !== true)
-                  throw new Error(`[birpc] timeout on calling "${method}"`)
-              }
-              catch (e) {
-                reject(e)
-              }
-              rpcPromiseMap.delete(id)
-            }, timeout)
-
-            // For node.js, `unref` is not available in browser-like environments
-            if (typeof timeoutId === 'object')
-              timeoutId = timeoutId.unref?.()
-          }
+        // For node.js, `unref` is not available in browser-like environments
+        if (typeof timeoutId === 'object')
+          timeoutId = timeoutId.unref?.()
+      }
 
-          rpcPromiseMap.set(id, { resolve, reject, timeoutId, method })
-          await post(serialize(req))
-          return promise
-        }
+      _rpcPromiseMap.set(id, { resolve, reject, timeoutId, method })
+      await send(newReq)
+      return promise
+    }
 
-        try {
-          if (options.onRequest)
-            await options.onRequest(_req, handler, resolve)
-          else
-            await handler()
-        }
-        catch (e) {
-          clearTimeout(timeoutId)
-          rpcPromiseMap.delete(id)
-          if (options.onGeneralError?.(e as Error) !== true)
-            throw e
-          return
-        }
+    try {
+      if (options.onRequest)
+        await options.onRequest(req, handler, resolve)
+      else
+        await handler()
+    }
+    catch (e) {
+      if (options.onGeneralError?.(e as Error) !== true)
+        throw e
+      return
+    }
+    finally {
+      clearTimeout(timeoutId)
+      _rpcPromiseMap.delete(id)
+    }
 
-        return promise
+    return promise
+  }
+
+  const $call = <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) =>
+    _call(method as string, args, false)
+  const $callOptional = <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) =>
+    _call(method as string, args, false, true)
+  const $callEvent = <K extends keyof RemoteFunctions>(method: K, ...args: ArgumentsType<RemoteFunctions[K]>) =>
+    _call(method as string, args, true)
+
+  const specialMethods = {
+    $call,
+    $callOptional,
+    $callEvent,
+    $rejectPendingCalls,
+    get $closed() {
+      return $closed
+    },
+    $close,
+    $functions,
+  }
+
+  const rpc = new Proxy({}, {
+    get(_, method: string) {
+      if (Object.prototype.hasOwnProperty.call(specialMethods, method))
+        return (specialMethods as any)[method]
+
+      // catch if "createBirpc" is returned from async function
+      if (method === 'then' && !eventNames.includes('then' as any) && !('then' in $functions))
+        return undefined
+
+      const sendEvent = (...args: any[]) => _call(method, args, true)
+      if (eventNames.includes(method as any)) {
+        sendEvent.asEvent = sendEvent
+        return sendEvent
       }
+      const sendCall = (...args: any[]) => _call(method, args, false)
       sendCall.asEvent = sendEvent
       return sendCall
     },
   }) as BirpcReturn<RemoteFunctions, LocalFunctions>
 
-  function close(customError?: Error) {
-    closed = true
-    rpcPromiseMap.forEach(({ reject, method }) => {
+  function $close(customError?: Error) {
+    $closed = true
+    _rpcPromiseMap.forEach(({ reject, method }) => {
       const error = new Error(`[birpc] rpc is closed, cannot call "${method}"`)
 
       if (customError) {
@@ -326,12 +390,12 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
 
       reject(error)
     })
-    rpcPromiseMap.clear()
+    _rpcPromiseMap.clear()
     off(onMessage)
   }
 
-  function rejectPendingCalls(handler?: PendingCallHandler) {
-    const entries = Array.from(rpcPromiseMap.values())
+  function $rejectPendingCalls(handler?: PendingCallHandler) {
+    const entries = Array.from(_rpcPromiseMap.values())
 
     const handlerResults = entries.map(({ method, reject }) => {
       if (!handler) {
@@ -341,7 +405,7 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
       return handler({ method, reject })
     })
 
-    rpcPromiseMap.clear()
+    _rpcPromiseMap.clear()
 
     return handlerResults
   }
@@ -359,18 +423,21 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
     }
 
     if (msg.t === TYPE_REQUEST) {
-      const { m: method, a: args } = msg
+      const { m: method, a: args, o: optional } = msg
       let result, error: any
-      const fn = await (resolver
-        ? resolver(method, (functions as any)[method])
-        : (functions as any)[method])
+      let fn = await (resolver
+        ? resolver(method, ($functions as any)[method])
+        : ($functions as any)[method])
+
+      if (optional)
+        fn ||= () => undefined
 
       if (!fn) {
         error = new Error(`[birpc] function "${method}" not found`)
       }
       else {
         try {
-          result = await fn.apply(bind === 'rpc' ? rpc : functions, args)
+          result = await fn.apply(bind === 'rpc' ? rpc : $functions, args)
         }
         catch (e) {
           error = e
@@ -410,7 +477,7 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
     }
     else {
       const { i: ack, r: result, e: error } = msg
-      const promise = rpcPromiseMap.get(ack)
+      const promise = _rpcPromiseMap.get(ack)
       if (promise) {
         clearTimeout(promise.timeoutId)
 
@@ -419,7 +486,7 @@ export function createBirpc<RemoteFunctions = Record<string, never>, LocalFuncti
         else
           promise.resolve(result)
       }
-      rpcPromiseMap.delete(ack)
+      _rpcPromiseMap.delete(ack)
     }
   }
 

test/index.test.ts

@@ -47,9 +47,39 @@ it('basic', async () => {
   expect(Bob.getCount()).toBe(1)
 })
 
-it('async', async () => {
+it('await on birpc should not throw error', async () => {
   const { bob, alice } = createChannel()
 
   await alice
   await bob
 })
+
+it('$call', async () => {
+  const { bob, alice } = createChannel()
+
+  // RPCs
+  expect(await bob.$call('hello', 'Bob'))
+    .toEqual('Hello Bob, my name is Alice')
+  expect(await alice.$call('hi', 'Alice'))
+    .toEqual('Hi Alice, I am Bob')
+
+  // one-way event
+  expect(await alice.$callEvent('bump')).toBeUndefined()
+
+  expect(Bob.getCount()).toBe(1)
+  await new Promise(resolve => setTimeout(resolve, 1))
+  expect(Bob.getCount()).toBe(2)
+})
+
+it('$callOptional', async () => {
+  const { bob } = createChannel()
+
+  // @ts-expect-error `hello2` is not defined
+  expect(async () => await bob.$call('hello2', 'Bob'))
+    .rejects
+    .toThrow('[birpc] function "hello2" not found')
+
+  // @ts-expect-error `hello2` is not defined
+  expect(await bob.$callOptional('hello2', 'Bob'))
+    .toEqual(undefined)
+})