// JSON-RPC defines a notification mechanism that can
// be used directly for primitive pub-sub systems
a.addEventListener('event', evt => {
console.log(evt.data[0]) // => 42
})
a.methods.event = evt => {
console.log(evt) // => 42
}
b.notify('event', 42)
Test
$ npm run test$ npm run test-browser # visit http://localhost:7357/test
API
const rpc = new RpcEngine(opts)
opts An optional Object. All key-value pairs are copied to the instance.
throw new RpcEngine.Error('error message')
Throw an instance of this error during method handler execution when the intended audience is the remote caller. Alternatively myExistingError.insecureRpc = true can be set before rethrowing an existing error. Note that only { message, code, data } properties of errors are actually passed to the transport.
Methods
await rpc.call(method[, param1][, param2][, ...])
Invokes a method on the remote side.
method A String.
params Anything the transport (or rpc.serialize()) can handle. Optional.
Invokes a method on the remote side without sending a message id.
method A String.
params Anything the transport (or rpc.serialize()) can handle. Optional.
await rpc.send(message)
Messages destined for the remote site are passed to this method after processing. Consumers of this module are responsible for providing an implementation.
message Whatever format the transport likes. See rpc.serialize() to control this.
await rpc.receive(message)
Messages originating from the remote side must be passed to this method for processing. Consumers of this module are responsible for invoking this method somehow.
This method is an optional hook consumers of this module may implement to convert outgoing messages into something compatible with the transport being used.
message An Object.
await rpc.deserialize(message)
This method is an optional hook consumers of this module may implement to convert raw a incoming message into an Object.
message Whatever format the transport uses.
rpc.close()
This method can be invoked (for example, when the transport is closed) to immediately cancel any outstanding requests.
Properties
rpc.methods
An Object representing the interface available to the remote peer. Keys are method names, values are functions.
rpc.defaultMethod
A Function. If implemented, this method will be invoked for any incoming message or notification that does not match an explicit handler in rpc.methods.
rpc.objectMode
A Boolean. RpcEngine defaults to passing parameters as an Array of positional arguments. Setting this property to true will pass them as key-value pairs instead. This is frequently needed for interop with other JSON-RPC implementations.
rpc.insecureErrors
A Boolean. When true, all errors thrown during method handler execution are returned to remote callers. To opt-in to sending a specific error to remote callers, set err.insecureRpc = true before throwing or throw an instance of RpcEngine.Error.
Events
Event('error')
Dispatched when something goes wrong while processing an incoming message.
Event(<arbitrary>)
Dispatched when a notification is received, after any matching methods have been called.
Releases
12.1.0
Change to autoincrementing integers for message IDs
Allow passing methods to constructor
Provide a mechanism for subclasses overriding _send to access caller params
Dispatch native events for notifications
12.0.0
Change default back to not sending method handler errors and add rpc.insecureErrors and RpcEngine.Error as opt-in mechanisms
11.0.0
Allow errors generated during method handler execution to be sent to peers. This is risky in a promise environment because the programmer must opt-out of sending potentially sensitive error data to peers, but the benefits probably outweigh the risks
10.0.0
Simplify, modernize
9.0.0
Add promise support
8.0.0
Convert to ES module
Switch from EventEmitter to EventTarget
7.0.0
Make default method invocation context the instance rather than the interface
6.0.0
Require manipulation of interfaces to be done via method calls so that interface-{add,remove} can be emitted reliably.
Always emit 'error' when send operations fail and no callback was passed.
5.0.0
Move pub-sub code out to separate module rpc-events
Rename constructor to RpcEngine
Rename methods property to interface
close() method should cancel pending requests immediately
Complete API documentation
4.0.0
Allow path delimited method and event names
Add feeds property and implement {un}subscribe() on the receive side
Change onmessage to receive (breaking change)
3.1.0
Switch license to MIT
3.0.0
Inherit from EventEmitter
Use emit('error', error) rather than the onerror property (this is a breaking change)