@poool/buddy
v3.0.1
Published
๐ Dead simple cross-domain iframe messaging
Downloads
917
Keywords
Readme
๐ 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 namecallback
{Function
}event
{Object
}
options
{Object
}source
{Window
} Source windoworigin
{String
} Origin expected from source window.*
(default) or any other origin....globalOptions
send(target, name, data, options)
target
{Window
} Target windowname
{String
} Event namedata
{Object
} Data to be serialized & sent to childoptions
{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) orfalse
...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.