@rzmu/rpc
v0.2.18
Published
Message based Two-way remote procedure call
Downloads
9
Readme
@rzmu/rpc
Fork of birpc. add object nesting support.
the @rzmu/rpc
use Object.setPrototypeOf
^1, this may be slower [^2], if you are not want with this, please use 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
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 server
Server
import { 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: fn => ws.on('message', fn),
serialize: v => JSON.stringify(v),
deserialize: v => JSON.parse(v),
},
)
await rpc.hey('Server') // Hey Server from client
})
Circular References
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: fn => ws.on('message', fn),
// use flatted as serializer
serialize: v => stringify(v),
deserialize: v => parse(v),
},
)
Using MessageChannel
MessageChannel will automatically serialize the message and support circular references out-of-box.
export const channel = new MessageChannel()
Bob
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: fn => channel.port1.on('message', fn),
},
)
await rpc.hi('Alice') // Hi Bob, I am Alice
Alice
import 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: fn => channel.port2.on('message', fn),
},
)
await 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