MessagePortDispatcher

MessagePortDispatcher is an extended API for cross-origin communication. It wraps the MessagePort API available on window, Worker, and other targets to send and receive typed custom events across <iframe> boundaries, Web Workers, and any object that implements the MessagePort interface. Internally it uses two EventDispatcher instances — one for incoming events and one for outgoing.

Demo with two <iframe>'s talking to each other

Installation

npm install @actualwave/messageport-dispatcher

yarn add @actualwave/messageport-dispatcher

Usage

Instantiate with any object that implements the MessagePort interface (postMessage, addEventListener, removeEventListener):

const dispatcher = new MessagePortDispatcher(iframe.contentWindow);

Communicating across an iframe boundary

In the outer document, pass the iframe's contentWindow:

import { MessagePortDispatcher } from '@actualwave/messageport-dispatcher';

const frameDispatcher = new MessagePortDispatcher(iframeNode.contentWindow);
frameDispatcher.addEventListener('initialized', () => {
  console.log('Communication channel is open.');
});

Inside the iframe, use getForSelf():

import { getForSelf } from '@actualwave/messageport-dispatcher';

const dispatcher = getForSelf();
dispatcher.dispatchEvent('initialized');

getForSelf(), getForParent(), and getForTop() return cached singletons, so they always return the same instance.

Sending and receiving events

// Send to the other side
dispatcher.dispatchEvent('someEvent', { someData: 'anything here' });

// Receive on the other side
dispatcher.addEventListener('someEvent', (event) => {
  console.log('Data received', event.data);
});

dispatchEvent() serialises the event and calls postMessage() — it does not fire the event locally on receiver. To observe sent events locally, listen on sender:

dispatcher.sender.addEventListener('someEvent', () => {
  console.log('Outgoing event observed');
});
dispatcher.dispatchEvent('someEvent');

Custom adapter target

const target = {
  postMessage: (data, origin) => {
    console.log('Message sent', data);
    window.postMessage(data, origin);
  },
  addEventListener: (eventType, handler) => {
    window.addEventListener(eventType, handler);
  },
  removeEventListener: (eventType, handler) => {
    window.removeEventListener(eventType, handler);
  },
};
const dispatcher = new MessagePortDispatcher(target);

MessagePortTarget

MessagePortTarget is a convenience wrapper for cases where sending and receiving are handled by different objects — for example, an iframe's contentWindow for sending and your own window for receiving:

import { MessagePortDispatcher, MessagePortTarget } from '@actualwave/messageport-dispatcher';

const frameDispatcher = new MessagePortDispatcher(
  new MessagePortTarget(iframeNode.contentWindow, window),
);

It also accepts arrays for broadcasting to or receiving from multiple targets:

const frameDispatcher = new MessagePortDispatcher(
  new MessagePortTarget(
    [iframe1.contentWindow, iframe2.contentWindow, iframe3.contentWindow],
    window,
  ),
);

Data serialisation

Because events cross origin boundaries, only serialisable data can be transferred. Before sending, dispatchEvent checks the event's data value:

• If the value has a toJSON() method, its return value is sent as-is (structured clone). The developer is responsible for converting nested objects.
• Otherwise the value is JSON.stringify-d, then parsed back on the receiving side.

Dispatcher ID and echo suppression

Each MessagePortDispatcher instance generates a unique dispatcherId. When a sent event is echoed back (which happens with window.postMessage), the dispatcher detects its own ID and routes the echo to the sender EventDispatcher instead of receiver, preventing false local dispatch.

API

MessagePortDispatcher constructor

| Parameter | Type | Description | |---|---|---| | target | MessagePortLike \| null | Object with postMessage and addEventListener. Defaults to self. | | customPostMessageHandler | Function \| null | Replaces the default target.postMessage() call. | | receiverEventPreprocessor | EventProcessor \| null | Transforms incoming events before listeners are called. | | senderEventPreprocessor | EventProcessor \| null | Transforms outgoing events before postMessage is called. |

MessagePortDispatcher instance members

| Member | Type | Description | |---|---|---| | dispatcherId | string | Unique ID for this instance. | | targetOrigin | string | Passed to postMessage as the target origin. Defaults to '*'. | | target | MessagePortLike | The underlying message port object. | | sender | IEventDispatcher | Fires outgoing events (echoes of sent messages). | | receiver | IEventDispatcher | Fires incoming events received from the other side. | | addEventListener(type, listener, priority?) | void | Delegates to receiver.addEventListener. | | hasEventListener(type) | boolean | Delegates to receiver.hasEventListener. | | removeEventListener(type, listener) | void | Delegates to receiver.removeEventListener. | | removeAllEventListeners(type) | void | Delegates to receiver.removeAllEventListeners. | | dispatchEvent(eventType, data?, transferList?) | void | Serialises and sends the event via postMessage. |

Factory functions

| Function | Description | |---|---| | getForSelf() | Cached dispatcher for self (current window / worker). | | getForParent() | Cached dispatcher for parent window. | | getForTop() | Cached dispatcher for top window. | | createMessagePortDispatcher(target?, ...) | Creates a new MessagePortDispatcher instance. |

MessagePortTarget

| Member | Description | |---|---| | constructor(sender?, receiver?) | Accepts single objects or arrays of objects for each role. | | postMessage(...args) | Calls postMessage on all senders. | | addEventListener(type, handler) | Calls addEventListener on all receivers. | | removeEventListener(type, handler) | Calls removeEventListener on all receivers. |

TypeScript

The package ships with TypeScript declarations. Types from @actualwave/event-dispatcher are also available for event typing:

import {
  MessagePortDispatcher,
  MessagePortTarget,
  MessagePortEvent,
  createMessagePortDispatcher,
  getForSelf,
  getForParent,
  getForTop,
} from '@actualwave/messageport-dispatcher';

import type { EventListener, EventProcessor } from '@actualwave/event-dispatcher';

const preprocessor: EventProcessor = (event) => {
  return { ...event, data: { ...(event.data as object), timestamp: Date.now() } };
};

const dispatcher = new MessagePortDispatcher(iframe.contentWindow, null, preprocessor);

const handler: EventListener = (event) => {
  console.log(event.type, event.data);
};

dispatcher.addEventListener('myEvent', handler);
dispatcher.dispatchEvent('myEvent', { payload: 42 });