BrowserRPC
This library allows you exchange messages beetween BrowserRPC instances using window.postMessage API. You can call remote procedures as promises.
Installing
Using npm:
$ npm install @fleekhq/browser-rpc
Using yarn
$ yarn add @fleekhq/browser-rpc
Usage
RPC requires that you setup a client (who calls remote procedures and wait for responses) and a server (who process the calls and send back the responses).
Let's say that your client is going to be placed in your webpage and need to call a remote procedure method called sum
that receives 2 arguments (2 number values to sum).
import { BrowserRPC } from '@fleekhq/browser-rpc';
const client = new BrowserRPC(window, {
name: 'browser-client',
target: 'rpc-server',
timeout: 10000,
});
client.start();
client
.call('sum', [1, 2])
.then((result) => {
console.log(result);
})
.catch((error) => {
console.error(error);
});
client.stop();
We've already setup the client, now we have to setup the server. The server listen for methods calls, process the calls and send the responses back to the client. Take in mind that the server only process the calls coming from the target
specified in the initial config object.
import { BrowserRPC } from '@fleekhq/browser-rpc';
const server = new BrowserRPC(window, {
name: 'rpc-server',
target: 'browser-client',
});
server.exposeHandler('sum', (cb, val1, val2) => {
const result = val1 + val2;
cb(null, result);
});
server.start();
API
For types info please refer to the types.ts
file: src/types.ts
New BrowserRPC instance:
new BrowserRPC(window, config)
window
: the window object used by the instance to post messages and add the event listeners.config
: [object] config required by the instance
name
: [string] name of the instance. This name is injected in every message emitted by the instance to identify the caller.target
: [string] the name of the rpc instance that has to handle the call requeststimeout?
: [number] timeout for call methods. 0 means no timeout. by default this value is 5000 mshandlers?
{[name: string]: Handler} object with handlers functions. object key is taken as the name identifier for the every handler function defined in the object
BrowserRPC.start(): void
Add the event listeners required by the instance
BrowserRPC.stop(): void
Remove the event listeners and rejects all the pending calls.
BrowserRPC.exposeHandler(name: string, handler: Handler): void
Add a new handler to the instance
BrowserRPC.removeHandler(name: string): boolean
Remove a handler by its name
BrowserRPC.call(handler: string, args: any[], config?: CallConfigObject): Promise
Call a new remote procedure method. Returns a promise resolving to the response or rejecting with an error.
ErrorRes Type
Your handlers functions receive as first argument a callback function that has to be called with the response (second argument) or with an ErrorRes object as first argument if there is any error.
ErrorRes Type:
export type ErrorRes = {
code: number,
message: string,
data?: any,
};
This error type represents a JSON RPC error object. Please refer to the JSON RPC documentation to get information about error codes, message and data:
https://www.jsonrpc.org/specification#error_object