🐕 Buddy

Dead simple cross-domain iframe messaging

Installation

yarn add @poool/buddy

Usage

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.

Configuration

Global options can be updated using setGlobalOptions method:

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

setGlobalOptions({ logLevel: 0 });

Options

timeout

Type: Number
Default: 5000

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

logLevel

Type: Number
Default: 1

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

queue

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.

serializers

Type: Array<BuddySerializer>
Default: []

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

Documentation

on(name, callback, options)

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

send(target, name, data, options)

target {Window} Target window
name {String} Event name
data {Object} Data to be serialized & sent to child
options {Object}
- origin {String} Origin expected from source window. * (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

Custom serializers

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.

Contributing

Please check the CONTRIBUTING.md doc for contribution guidelines.

Development

Install dependencies:

yarn install

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

yarn serve

And test your code:

yarn test

License

This software is licensed under MIT.

p3ol/buddy