birpc

Message-based two-way remote procedure call. Useful for WebSockets and Workers communication.

Features

• Intuitive - call remote functions just like locals, with Promise to get the response
• TypeScript - safe function calls for arguments and returns
• Protocol agonostic - WebSocket, MessageChannel, any protocols with messages communication would work!
• Zero deps, ~0.5KB

Examples

Using WebSocket

When using WebSocket, you need to pass your custom serializer and deserializer.

Client

1import type { ServerFunctions } from './types'
2
3const ws = new WebSocket('ws://url')
4
5const clientFunctions: ClientFunctions = {
6  hey(name: string) {
7    return `Hey ${name} from client`
8  }
9}
10
11const rpc = createBirpc<ServerFunctions>(
12  clientFunctions,
13  {
14    post: data => ws.send(data),
15    on: data => ws.on('message', data),
16    // these are required when using WebSocket
17    serialize: v => JSON.stringify(v),
18    deserialize: v => JSON.parse(v),
19  },
20)
21
22await rpc.hi('Client') // Hi Client from server

Server

1import type { ClientFunctions } from './types'
2import { WebSocketServer } from 'ws'
3
4const serverFunctions: ServerFunctions = {
5  hi(name: string) {
6    return `Hi ${name} from server`
7  }
8}
9
10const wss = new WebSocketServer()
11
12wss.on('connection', (ws) => {
13  const rpc = createBirpc<ClientFunctions>(
14    serverFunctions,
15    {
16      post: data => ws.send(data),
17      on: fn => ws.on('message', fn),
18      serialize: v => JSON.stringify(v),
19      deserialize: v => JSON.parse(v),
20    },
21  )
22
23  await rpc.hey('Server') // Hey Server from client
24})

Circular References

As JSON.stringify does not supporting circular references, we recommend using structured-clone-es as the serializer when you expect to have circular references.

1import { parse, stringify } from 'structured-clone-es'
2
3const rpc = createBirpc<ServerFunctions>(
4  functions,
5  {
6    post: data => ws.send(data),
7    on: fn => ws.on('message', fn),
8    // use structured-clone-es as serializer
9    serialize: v => stringify(v),
10    deserialize: v => parse(v),
11  },
12)

Using MessageChannel

MessageChannel will automatically serialize the message and support circular references out-of-box.

1export const channel = new MessageChannel()

Bob

1import type { AliceFunctions } from './types'
2import { channel } from './channel'
3
4const Bob: BobFunctions = {
5  hey(name: string) {
6    return `Hey ${name}, I am Bob`
7  }
8}
9
10const rpc = createBirpc<AliceFunctions>(
11  Bob,
12  {
13    post: data => channel.port1.postMessage(data),
14    on: fn => channel.port1.on('message', fn),
15  },
16)
17
18await rpc.hi('Bob') // Hi Bob, I am Alice

Alice

1import type { BobFunctions } from './types'
2import { channel } from './channel'
3
4const Alice: AliceFunctions = {
5  hi(name: string) {
6    return `Hi ${name}, I am Alice`
7  }
8}
9
10const rpc = createBirpc<BobFunctions>(
11  Alice,
12  {
13    post: data => channel.port2.postMessage(data),
14    on: fn => channel.port2.on('message', fn),
15  },
16)
17
18await rpc.hey('Alice') // Hey Alice, I am Bob

One-to-multiple Communication

Refer to ./test/group.test.ts as an example.

Sponsors

License

MIT License © 2021 Anthony Fu