cross-context-events

A lightweight event library for cross context messaging and events synchronization

Usage no npm install needed!

<script type="module">
  import crossContextEvents from 'https://cdn.skypack.dev/cross-context-events';
</script>

README

Cross Context Events

Cross context events is a robust, lightweight package providing the option to send and receive events across JS execution context.

You asked, what does this mean, exactly? Well, it means that when you emit an event in your script, the same event will also be emitted in all other linked execution contexts (i.e. other tabs, windows, processes), even on different computers if you want to! All you need to do is writing a few lines of code to link them together.

demo

Try the demo here       Source code for the demo

Documentations

See here.

Features

  • Lightweight
  • No runtime dependency

Comprehensive documentations

  • Containerization
    • Support for named and anonymous containers to provide isolation if you need
  • Unified interface
    • Works the same way whether you are using browser, service worker, node, or even electron.
  • Cross Context
    • Capable of sending events across execution context (e.g. from one tab to another tab in browser or from one process to another process in Node) with minimal setup, so long as an IPC channel can be established between the sending context and receiving context.
    • Relay support: events can be optionally relayed across the network if you have one.
  • Typescript support
    • Written completely in typescript completely with strong type inferences.
  • Comprehensive testing
    • All core functions are unittested
  • Namespaced events and bubbling
    • If you emit an event for event.context.new, then listeners for event.context and event are also notified (but event.context2 is not). This behavior can be disabled if desired. See event bubbling.
  • Event relaying

    • Even if you have a network of nested iframes like the image below, and you emit an event in iframe 9 (or any frame or the parent window for that matter), it will be emitted in all frames and the parent window. This also applies to a chain or child processes or workers or any other combinations of communication channels. See event relaying.

Installation

Unpkg


<script src="https://unpkg.com/cross-context-events/dist/cross-context-events.min.js"></script>

jsDelivr


<script src="https://cdn.jsdelivr.net/npm/cross-context-events/dist/cross-context-events.min.js"></script>

yarn

yarn add cross-context-events

npm

npm install cross-context-events

Getting started

This example uses the WebWorker API , but it can be easily switched to Node processes, iFrames, or others by simply changing the transport used. For details, please refer to transports.

// index.js

import {
    useGlobalTransport,
    createDefaultTransport,
    createEvent
} from "cross-context-events";

const OnlineEvent = createEvent("worker.online")
OnlineEvent.addListener(() => console.log("Worker is now online ＼(＾▽＾)／"))

let worker = new Worker("worker.js")

useGlobalTransport(createDefaultTransport({
    type: "worker",
    target: worker
}))

// worker.js

import {
    useGlobalTransport,
    createDefaultTransport,
    createEvent
} from "cross-context-events";

useGlobalTransport(createDefaultTransport({
    type: "worker",
    target: self
}))

const OnlineEvent = createEvent("worker.online")
new OnlineEvent().emit()

As you can see, Worker is now online ＼(＾▽＾)／ has been logged to the console from the main thread. Yay!

Please refer to the documentation for more information.