Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/p3ol/buddy
🐕 Dead simple cross-domain iframe/window messaging
https://github.com/p3ol/buddy
iframe popup popup-messaging popup-windows post-message post-messaging promise
Last synced: 2 months ago
JSON representation
🐕 Dead simple cross-domain iframe/window messaging
- Host: GitHub
- URL: https://github.com/p3ol/buddy
- Owner: p3ol
- License: mit
- Created: 2019-10-28T20:03:52.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T07:18:26.000Z (9 months ago)
- Last Synced: 2024-04-14T03:15:37.914Z (9 months ago)
- Topics: iframe, popup, popup-messaging, popup-windows, post-message, post-messaging, promise
- Language: TypeScript
- Homepage:
- Size: 7.97 MB
- Stars: 7
- Watchers: 3
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Authors: AUTHORS
Awesome Lists containing this project
README
# 🐕 Buddy
> Dead simple cross-domain iframe messaging
## Installation
```bash
yarn add @poool/buddy
```
## Usage
```javascript
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:
```javascript
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`
- Default: `[]`
Custom serializers to use to serialize/unserialize data.
See [serializers](#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`.
```javascript
// 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
[](https://github.com/p3ol/buddy/graphs/contributors)
Please check the [CONTRIBUTING.md](https://github.com/p3ol/buddy/blob/master/CONTRIBUTING.md) doc for contribution guidelines.
## Development
Install dependencies:
```bash
yarn install
```
Run examples at http://localhost:64000/ with webpack dev server:
```bash
yarn serve
```
And test your code:
```bash
yarn test
```
## License
This software is licensed under [MIT](https://github.com/p3ol/buddy/blob/master/LICENSE).