Message-based two-way remote procedure call. Useful for WebSockets and Workers communication.
- 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
When using WebSocket, you need to pass your custom serializer and deserializer.
import type { ServerFunctions } from './types'
const ws = new WebSocket('ws://url')
const clientFunctions: ClientFunctions = {
hey(name: string) {
return `Hey ${name} from client`
}
}
const rpc = createBirpc<ServerFunctions>(
clientFunctions,
{
post: data => ws.send(data),
on: data => ws.on('message', data),
// these are required when using WebSocket
serialize: v => JSON.stringify(v),
deserialize: v => JSON.parse(v),
},
)
await rpc.hi('Client') // Hi Client from serverimport { WebSocketServer } from 'ws'
import type { ClientFunctions } from './types'
const serverFunctions: ServerFunctions = {
hi(name: string) {
return `Hi ${name} from server`
}
}
const wss = new WebSocketServer()
wss.on('connection', (ws) => {
const rpc = createBirpc<ClientFunctions>(
serverFunctions,
{
post: data => ws.send(data),
on: data => ws.on('message', data),
serialize: v => JSON.stringify(v),
deserialize: v => JSON.parse(v),
},
)
await rpc.hey('Server') // Hey Server from client
})As JSON.stringify does not supporting circular references, we recommend using flatted as the serializer when you expect to have circular references.
import { parse, stringify } from 'flatted'
const rpc = createBirpc<ServerFunctions>(
functions,
{
post: data => ws.send(data),
on: data => ws.on('message', data),
// use flatted as serializer
serialize: v => stringify(v),
deserialize: v => parse(v),
},
)MessageChannel will automatically serialize the message and support circular references out-of-box.
export const channel = new MessageChannel()import type { AliceFunctions } from './types'
import { channel } from './channel'
const Bob: BobFunctions = {
hey(name: string) {
return `Hey ${name}, I am Bob`
}
}
const rpc = createBirpc<AliceFunctions>(
Bob,
{
post: data => channel.port1.postMessage(data),
on: data => channel.port1.on('message', data),
},
)
await rpc.hi('Alice') // Hi Bob, I am Aliceimport type { BobFunctions } from './types'
import { channel } from './channel'
const Alice: AliceFunctions = {
hi(name: string) {
return `Hi ${name}, I am Alice`
}
}
const rpc = createBirpc<BobFunctions>(
Alice,
{
post: data => channel.port2.postMessage(data),
on: data => channel.port2.on('message', data),
},
)
await rpc.hey('Alice') // Hey Alice, I am BobRefer to ./test/group.test.ts as an example.
MIT License © 2021 Anthony Fu