Coder Social home page Coder Social logo

p3ol / buddy Goto Github PK

View Code? Open in Web Editor NEW
8.0 3.0 0.0 9.2 MB

๐Ÿ• Dead simple cross-domain iframe/window messaging

License: MIT License

JavaScript 34.33% TypeScript 65.67%
popup-messaging popup-windows popup post-messaging iframe promise post-message

buddy's Introduction

CI

๐Ÿ• 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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.