birpc

Using MessageChannel is simpler because it automatically handles message serialization and supports circular references out-of-the-box. You connect the two sides of the RPC by passing different ports (port1 and port2) from the same MessageChannel instance to the respective client and server configurations.

// Setup channel
export const channel = new MessageChannel()

// Bob (Side A)
const Bob: BobFunctions = {
  hey(name: string) {
    return `Hey ${name}, I am Bob`
  }
}

const rpcBob = createBirpc<AliceFunctions>(
  Bob,
  {
    post: data => channel.port1.postMessage(data),
    on: fn => channel.port1.on('message', fn),
  },
)

// Alice (Side B)
const Alice: AliceFunctions = {
  hi(name: string) {
    return `Hi ${name}, I am Alice`
  }
}

const rpcAlice = createBirpc<BobFunctions>(
  Alice,
  {
    post: data => channel.port2.postMessage(data),
    on: fn => channel.port2.on('message', fn),
  },
)

The broadcast property of a BirpcGroup allows you to invoke functions across all connected clients. Depending on whether proxify is enabled, you can call functions directly by name or use built-in utility methods.

Built-in Broadcast Methods

These methods are always available on the broadcast object:

• $call(method, ...args): Calls the method on all clients and returns an array of results (one per client).
• $callOptional(method, ...args): Same as $call, but returns undefined for a client if the method is not defined on their side.
• $callEvent(method, ...args): Sends the method call as an event (no response expected) to all clients.
• $callRaw(options): Performs a raw call using a CallRawOptions object.

Proxified Broadcast

If proxify: true (the default), you can call remote functions directly on the broadcast object. Each proxified function also gains an .asEvent(...args) method to trigger the call as an event across all clients.

// If proxify is true (default)
// Calling a remote function directly on broadcast
const results = await group.broadcast.hello('World')

// Calling a remote function as an event across all clients
await group.broadcast.hello.asEvent('World')

// Using built-in utility methods
const rawResults = await group.broadcast.$call('hello', 'World')

Birpc distinguishes between standard RPC calls (request-response) and events (fire-and-forget).

1. Standard Calls: By default, calling a proxified method sends a TYPE_REQUEST. The client waits for a TYPE_RESPONSE with a matching ID (i). If no response arrives within the timeout period, an error is thrown.
2. Events: If a method name is listed in eventNames, or if you use $callEvent / .asEvent, the request is sent without an ID or a requirement for a response. This is useful for one-to-many communication or notifications.
3. Optional Calls: Using $callOptional or setting the optional flag in a request tells the server that if the function is missing, it should return undefined instead of an error.

Customizing Request Flow with onRequest

The onRequest hook allows you to intercept a request before it is sent. You can use the provided next function to continue the standard flow or use resolve to provide a response immediately without hitting the transport layer.

const rpc = createBirpc(functions, {
  onRequest: async (req, next, resolve) => {
    if (req.m === 'secretMethod') {
      // Intercept and resolve manually
      resolve({ data: 'intercepted' })
    } else {
      // Continue standard flow
      await next()
    }
  }
})

BirpcOptions combines ChannelOptions (transport layer) and EventOptions (RPC behavior). Use these to customize the RPC lifecycle.

ChannelOptions

• post: Function to post raw messages. Returns a Thenable.
• on: Listener to receive raw messages. Takes a callback (data, ...extras) => void.
• off: (Optional) Function to clear the listener when $close is called.
• serialize: (Optional) Custom function to serialize data before sending.
• deserialize: (Optional) Custom function to deserialize incoming data.
• bind: 'rpc' | 'functions'. Determines the this context when calling local functions. Defaults to 'rpc'.
• meta: Custom metadata attached to the RPC instance's $meta property.

EventOptions

• eventNames: Array of method names that should be treated as events (no response expected).
• timeout: Maximum time to wait for a response in ms. Defaults to 60_000.
• proxify: Whether to proxy remote functions. If false, you must use rpc.$call('method', ...args). Defaults to true.
• resolver: Custom resolver for advanced function resolution.
• onRequest: Hook triggered before an event is sent. Allows intercepting or manually resolving requests.
• onFunctionError: Handler for errors in local functions. Returning true prevents the error from being thrown.
• onGeneralError: Handler for serialization or messaging errors. Returning true prevents the error from being thrown.
• onTimeoutError: Handler for timeout errors. Returning true prevents the error from being thrown.

The BirpcReturn object provides several built-in utilities for managing the RPC connection and making manual calls. These are available even if proxify is set to false.

Built-in Methods

• $call(method, ...args): Calls a remote function and waits for the result.
• $callOptional(method, ...args): Same as $call, but returns undefined if the function is not found on the remote side.
• $callEvent(method, ...args): Sends an event without expecting a response.
• $callRaw(options): Calls a method using a raw options object: { method: string, args: unknown[], event?: boolean, optional?: boolean }.
• $close(error?): Closes the RPC connection. If an error is provided, it is used to reject pending calls.
• $rejectPendingCalls(handler?): Rejects all currently pending calls. An optional handler can be used to customize the rejection.

Built-in Properties

• $functions: The original local functions object.
• $closed: A read-only boolean indicating if the RPC is closed.
• $meta: The custom metadata provided in options.

Event-specific behavior

If a method is included in eventNames, it will have an .asEvent property that allows you to send it as an event even if the proxy normally treats it as a call.

// Using built-in methods
await rpc.$call('methodName', arg1, arg2)
await rpc.$callEvent('eventMethod')

// Checking status
if (rpc.$closed) {
  console.log('Connection is dead')
}

// Closing connection
rpc.$close()

Use createBirpcGroup to manage multiple RPC clients simultaneously. This is useful for one-to-many communication patterns where you want to define a set of local functions and broadcast calls to multiple remote channels.

createBirpcGroup accepts:

1. functions: The local functions to be exposed.
2. channels: An array of ChannelOptions or a function that returns an array of ChannelOptions.
3. options: An optional EventOptions object. Setting proxify: false in options will disable the automatic proxying of remote functions.

The returned BirpcGroup object provides access to the individual clients, the original functions, a broadcast object for multi-client calls, and an updateChannels method to dynamically refresh the client list.

import { createBirpcGroup } from 'birpc'

const functions = {
  hello: (name: string) => `Hello ${name}`
}

const group = createBirpcGroup(
  functions,
  [{ url: 'ws://localhost:1234' }]
)

// Access individual clients
const clients = group.clients

// Access local functions
const local = group.functions