openbet-eventbus v2.6.0-beta.0

openbet-eventbus

This repository provides an NPM module that can be used in your own application to both subscribe and publish events that you wish to be 'global'. These events can be heard by any other components that are in the same browser window and as such provides a sort of IPC solution.

Installation

This repository is published as an NPM module. Provided you are able to interact with the OpenBet NPM registry you can use it in your projects by running;

npm install --save openbet-eventbus

Standalone Usage

If you need to use this component in an environment where a build tool is not in use please get in contact with the package maintainers to understand options.

Examples

You use the library in your application as follows;

In one component;

import EventBus from 'openbet-eventbus'

EventBus.subscribe('an/event', payload => {
  console.log('received a message - %o', payload)
})

and in another component;

import EventBus from 'openbet-eventbus'

EventBus.publish('an/event', 'hello from somewhere else!')

the result being that the first component will log the message published by the second.

API Reference

EventBus

The EventBus offers a consistent way to subscribe to and/or publish events between disparate modules in an asynchronous manner.

Kind: global class

• EventBus
  • .publishAsync(same)
  • .publishSync(type, payload, eventInfo)
  • .publish(type, payload, eventInfo)
  • .subscribe(type, handler)
  • .subscribeLegacy(type, handler)
  • .unsubscribe(type, handler)
  • .unsubscribeLegacy(type, handler)

eventBus.publishAsync(same)

Publish an event of a particular type with the given payload. Guarantees to be executed later in the event loop

Kind: instance method of EventBus

eventBus.publishSync(type, payload, eventInfo)

Publish an event of a particular type with the given payload. Synchronous version, meaning it behaves like a function call, invoking subscribed listeners immediately.

Kind: instance method of EventBus

eventBus.publish(type, payload, eventInfo)

Publish an event of a particular type with the given payload both over the event bus and also as a CustomEvent on the window (so it can be heard by window.addEventListener subscribers).

This can be useful if you want to send messages that are available for both internal code using the subscribe* family of methods in this library or third parties that are using standard DOM APIs.

A client using this method to dispatch a unique message will result in the following behaviour;

• a message sent over the internal eventbus and delivered exactly once to any subscribers using the subscribe() or subscribeLegacy() methods of this library
• a message delivered exactly once to any DOM subscribers using addEventListener on the window object

Kind: instance method of EventBus

eventBus.subscribe(type, handler)

Subscribe to a particular event that may occur asynchronously. Invoke the handler with the event payload when a message is received.

Kind: instance method of EventBus

eventBus.subscribeLegacy(type, handler)

NOTE: Unless you need to handle messages delivered via both event bus AND window.dispatchEvent you shouldn't need to use this method!

This method provides a means of subscribing to messages that can be emitted either from the publish* family of methods in this library, or directly using window.dispatchEvent. This is useful for when you want to support an event based interface that is used not only by our own code, but also by third parties that can simply dispatch a CustomEvent on the window and not have to import the openbet-eventbus library.

A caveat for use is that there can only be one handler registered for a given type at any point in time (to avoid memory leaks due to how we offer unsubscribe). If you attempt to subscribe more than once using this method you will receive an error.

A client using this method will receive a unique message exactly once under the following conditions;

• when a call to publish(), publishAsync(), publishSync() is made
• when a call to window.dispatchEvent is made

Kind: instance method of EventBus

eventBus.unsubscribe(type, handler)

Unsubscribe from receiving messages.

Kind: instance method of EventBus

eventBus.unsubscribeLegacy(type, handler)

Unsubscribe from receiving messages.

Kind: instance method of EventBus

Documented by jsdoc-to-markdown.