structured-channel

A wrapper around MessageChannel API for bi-directional communication between two browsing contexts.

Usage

The bundles in the dist/ directory are in UMD format which allows them to be included as CommonJS and AMD modules or directly in a <script> tag.

Simple example

Here's an example of Window - Worker communication using a StructuredChannel.

// In worker.js
self.importScripts("structured-channel.js");
StructuredChannel.waitForConnection(this).then(function(channel) {
  channel.on("sum", function(data) {
    return data.a + data.b;
  });
});

// In main.js with structured-channel.js included via script tag.
var worker = new Worker("worker.js");
StructuredChannel.connectTo(worker).then(function(channel) {
  channel.send("sum", { a: 1, b: 2 }).then(function(reply) {
    // reply == 3
  });
});

API

Initialization

A new StructuredChannel is initialized by calling the static methods connectTo() and waitForConnection() on the different sides of the channel.

StructuredChannel.connectTo(target, [targetOrigin], [global]) ⇒ Promise

Opens a StructuredChannel to the given target. The target must load this script and call StructuredChannel.waitForConnection().

Returns: Promise - A Promise that is fulfilled with a StructuredChannel instance once the connection has been established. The promise is rejected on error.

Param	Type	Default	Description
target	Window | Worker		The target window or a worker to connect to.
[targetOrigin]	String	*	If the target is a Window, this is the targetOrigin for Window.postMessage(). Failing to provide this parameter might have security implications as the channel could be opened to a malicious target. If the target is a Worker, this parameter is ignored.
[global]	Object		An optional global object that can be used to get a reference to the MessageChannel constructor.

StructuredChannel.waitForConnection([target], [origin]) ⇒ Promise

Waits for a connection request from StructuredChannel.connectTo() to arrive as a message event to the given target.

Returns: Promise - that is resolved with a StructuredChannel instance once the connection request is received.

Param	Type	Description
[target]	Window | Worker	The target that should receive the connection attempt (default self).
[origin]	String	The origin from which the connection attempt should come from. If undefined or '*', connection attempts and messages from all origins are allowed. Failing to provide a specific origin might have security implications as malicious parties could establish a connection to this target.

Instance methods

You can attach handlers to messages by calling StructuredChannel.on() and send messages with StructuredChannel.send().

StructuredChannel.send(type, payload) ⇒ Promise

Sends a message to the other side of the channel.

Returns: Promise - A Promise that is resolved once the receiver has handled the message. The resolution value will be the object the handler method returned. If the other party fails to handle the message, the promise is rejected.

Param	Type	Description
type	String	The type of the message.
payload	Object	The payload for the message. The value must support structured cloning.

StructuredChannel.on(type, handler)

Adds a handler for given message type.

Param	Type	Description
type	String	The type of the message to handle.
handler	function	The handler function. The return value will be transferred back to the sender and the Promise returned by send() is settled according to it. If the function throws, returns a Promise that is eventually rejected or returns a value that cannot be transmitted to the sender, the send() Promise rejects. If the function returns a value, the send() Promise is fulfilled with that value. If the function returns a Promise that is eventually fulfilled, the send() Promise is fulfilled with the fulfillment value.

StructuredChannel.off(type)

Removes the handler for the message of given type.

Param	Type	Description
type	String	The type of the message for which the handler is to be removed.