Skip to content

PierfrancescoSoffritti/light-event-bus.js

Repository files navigation

light-event-bus.js

Build Status codecov License: MIT

light-event-bus.js is a lightweight event bus for Node.js and the browser.

Table of Contents

  1. Usage
    1. Browser
      1. Download
      2. Example
    2. Node.js
      1. Download
      2. Example
  2. API documentation

Usage

This library can be used both with Node.js and the browser.

Browser usage

Download - browser

You can download the library here. For the browser there are 2 options:

  1. Download light-event-bus.min.js here and import it in your app using the <script> tag.
  2. If you are using ES modules, download the library (here or through NPM) and import it using ES6 imports.

This file is also delivered through a CDN at this address.

Example - browser

  1. Importing with <script> tag
<script src='../build/light-event-bus.min.js'></script>

<script>
  const eventBus = new EVENT_BUS.EventBus()
            
  const subscription = eventBus.subscribe('event', arg => console.log(arg))
  eventBus.publish('event', 'message')

  subscription.unsubscribe()
</script>
  1. Importing ES module
<script type='module'>
  import { EventBus } from 'light-event-bus'

  const eventBus = new EventBus()

  const subscription = eventBus.subscribe('event', arg => console.log(arg))
  eventBus.publish('event', 'message')

  subscription.unsubscribe()
</script>

Node.js usage

Download - node

Run

npm install light-event-bus 

or

yarn add light-event-bus 

Example - node

const { EventBus } = require('light-event-bus')

const eventBus = new EventBus()

const subscription = eventBus.subscribe('event', arg => console.log(arg))
eventBus.publish('event', 'message')

subscription.unsubscribe()

API documentation

Table of Contents

  1. EventBus
    1. Subscribe
    2. Unsubscribe
    3. Publish
  2. EventBusSingleton

EventBus

The EventBus constructor can be accessed through the main object exposed by this library.

If you are using Node.js:

const { EventBus } = require('light-event-bus')

If you are using ES6 imports:

import { EventBus } from 'light-event-bus'

If you are using <script>:

const eventBus = new EVENT_BUS.EventBus()

Subscribe

Instances of EventBus expose a subscribe method.

Call subscribe when you want to start listening for an event.

subscribe takes two arguments: eventType and callback.

Example:

eventBus.subscribe('event', arg => console.log(arg))
  • eventType can be an object of any type. Strings are recomended.
  • callback must be a function. This function can have 0 or 1 argument.

Unsubscribe

subscribe returns an object that exposes an unsubscribe method.

Call unsubscribe to cancel the current subscription.

Example:

const subscription = eventBus.subscribe('event', arg => console.log(arg))

// To cancel the subscription
subscription.unsubscribe()

Publish

Instances of EventBus expose a publish method.

Call publish when you want to publish an event on the event bus.

publish takes two arguments: eventType and argument.

Example:

eventBus.publish('event', 'message')
  • eventType can be an object of any type. Strings are recomended.
  • argument is optional. It will be passed to all the listeners for the event. It can be of any type.

In the case of this examples, only subscribers of the event 'event' will be called, with the string 'mesage' as argument.

EventBusSingleton

Often a single instance of EventBus is needed across an entire application, a singleton. The main object of this library already exposes a singleton, so that you don't have to create your own.

You can access the EventBusSingleton in the following ways:

If you are using Node.js:

const { EventBusSingleton } = require('light-event-bus')

If you are using ES6 imports:

import { EventBusSingleton } from 'light-event-bus'

If you are using <script>:

const eventBus = new EVENT_BUS.EventBusSingleton()

This singleton is just an instance of EventBus, so it can be used as any other user-defined EventBus.