Dead simple cross-domain iframe messaging

yarn add @poool/buddy

import { on, send } from '@poool/buddy';

// Register handler inside child window
on('getInfos', async event => {
  console.log('You have a message from some window :', event.data);

  // You can even pass methods to child window and retrieve its return value
  // using promises or async/await:'
  console.log(await event.data.someMethod());

  // You can even send data back to parent, EVEN METHODS \o/
  // Parent will only have to await `send()` method promise to get the result
  return { someOtherMethod: () => 30 };
}, { source: someParentWindow });

// And send some message from parent window
send(someChildWindow, 'getInfos', { infos: 'some string', someMethod: () => 25 }, { origin: '*' });

Buddy serializes all the primitive types (using JSON.parse) and even methods, using custom back & forth Promise logic.

Buddy can also be used with WebSockets, by using the WebSocket object as both target and source:

On the server:

import { createServer } from 'node:http';

import { on } from '@poool/buddy';
import { WebSocketServer } from 'ws';

const server = createServer();
const wss = new WebSocketServer({ server });

wss.on('connection', ws => {
  on('getInfos', async event => {
    console.log('You have a message from some browser:', event.data);

    return { someOtherMethod: () => 30 };
  }, { source: ws, target: ws });
});

server.listen(8080);

On the client:

import { send } from '@poool/buddy';

const ws = new WebSocket('ws://localhost:8080');
ws.addEventListener('open', () => {
  send(ws, 'getInfos', { infos: 'some string', someMethod: () => 25 }, {
    source: ws, target: ws,
  });
});

Global options can be updated using setGlobalOptions method:

import { setGlobalOptions } from '@poool/buddy';

setGlobalOptions({ logLevel: 0 });

• Type: Number
• Default: 5000

Message expiration time, after which an error will be thrown.

• Type: Number
• Default: 1

Either 0 (disabled), 1 (error), 2 (warn), 3 (info), 4 (debug), 5 (log)

• Type: Boolean
• Default: false

If true, messages will be queued until the target window is ready to receive them. Needs to also be set inside the target window to trigger a ready event.

• Type: Array<BuddySerializer>
• Default: []

Custom serializers to use to serialize/unserialize data. See serializers section for more details.

• name {String} Event name
• callback {Function}
  • event {Object}
• options {Object}
  • source {Window | WebSocket} Source window or websocket connection
  • origin {String} Origin expected from source. * (default) or any other origin.
  • ...globalOptions

• target {Window | WebSocket} Target window or websocket connection
• name {String} Event name
• data {Object} Data to be serialized & sent to child
• options {Object}
  • origin {String} Origin expected from source. * (default) or any other origin.
  • pingBack {Boolean} Mostly used internally. Whether sender should await a response from receiver or not. true (default) or false
  • ...globalOptions

Buddy uses JSON.stringify to send pre-serialized data to .postMessage (and JSON.parse to deserialize), allowing to automatically serialize primitive data like numbers or strings, and uses internal serializers to pre-serialize more complex data like Date, Error or even Function and Promise objects.

Although it cannot cover all the possible use cases, you can add your own serializers to handle custom data types. A serializer is a simple object with four methods: serializable, serialize, unserializable and unserialize.

// Creating a custom serializer for Map objects
const mapSerializer = {
  serializable: data => data instanceof Map,
  serialize: data => ({ type: 'map', entries: Array.from(data.entries()) }),
  unserializable: data => data.type === 'map' && data.entries,
  unserialize: data => new Map(data.entries),
};

⚠️ A custom serializer's serializable/unserializable methods returning true for any data will override all the other serializers, even internal ones, so be careful to only match the data you specifically want to serialize.

Please check the CONTRIBUTING.md doc for contribution guidelines.

Install dependencies:

yarn install

Run examples at http://localhost:64000/ with webpack dev server:

yarn serve

And test your code:

yarn test

This software is licensed under MIT.