roro.js v1.0.12

roro.js

Description

roro.js is an RPC toolkit that works with web workers, web sockets, iframes and web rtc.

roro.js let you provide and use functions across message based channels, e.g., you can implement a function in a web worker and call it from the main script.

under the hood, function calls are translated to messages which are passed via the messaging API of the underlying channel (postMessage and onmessage for web workers, send and onmessage for web sockets, etc.).

roro.js let you optimize the way messages are transferred in two manners: batching and serializing.

Batching

Priorities

Each exposed function has two priorities: Call Priority and Return Priority. The value of these priorities is one of:

• None (-2)
• Immediate (-1)
• High (0)
• Animation (1000 / 60)
• Low (100)

Except for None and Immediate, the priority is specified in milliseconds. None is only available for return priority.

The default priority is Immediate

Immediate means that each function call will be translated to a unique message passing. This behavior might be inefficient since message passing via postMessage is much more time consuming than function calls.

For this reason, you can specify for each function a priority. When the the priority is 0 or more, the message representing the function call will be appended to a queue which will be serialized and passed in a single call to postMessage after the timeout. For example, a loop with 10 calls with an Immediate priority will result in 10 postMessages. The same loop with a High priority will result in 1 postMessage. Increasing the value of the priority will let more calls join the queue before the timeout is reached.

Although different calls might have different priorities, the order of calls is always guarantied to be kept. For that reason, if a higher priority call (one with a lower timeout value) is made after a lower priority call, when the queue is drained and the messages are serialized and posted, the lower priority call will be executed before it's timeout. For example, an Immediate call will always drain the queue and makes any pending call to be executed.

The None priority is useful for cases when a function doesn't return a value. Sometimes in these cases, caller is not interested in waiting for the promise to be resolved. Setting the return priority to None will resolve the promise on the calling side immediately and will not post a message for the return value.

Serializing

roro.js supports 3 types of serializers:

• Native
• JSON
• Binary

The Native serializer uses the browser structured clone algorithm. It can be user with web workers and iframes.

The JSON serializer uses JSON.stringify and JSON.parse and is therefore suitable for all types of channels.

The Binary serializer lets you write custom serialization and serialize the function parameters and return value to an ArrayBuffer and then post a message with that array as a transferable object

API

MessageRPC

WebWorkerChannel

NativeSerializer

Installation

yarn add roro.js

Usage

import { MessageRPC } from 'roro.js'