event-dispatcher

Many variations of event dispatchers exist for Node. Node even includes its own. However, none of them provide any sort of callback for when the listeners have all finished. This is what makes this package different.

Installation

$ npm install @eddieajau/event-dispatcher

Example

var EventDispatcher = require('@eddieajau/event-dispatcher');
var Event = EventDispatcher.Event;
var priority = EventDispatcher.priority;

var dispatcher = new EventDispatcher();

dispatcher.addListener('an-event', function listener1(event, next) {
  event.foo = 'bar';
  next();
}, priority.HIGHEST);

dispatcher.dispatch('an-event')
  .then(function (event) {
    console.log(event.foo);
  })
  .catch(function (err) {
    // If next is invoke like `next(err)`, if will reject.
    console.err(err);
  });

Preset priotities

• HIGHEST
• HIGHER
• HIGH
• NORMAL
• LOW
• LOWER
• LOWEST

Code quality and tests

$ npm run lint
$ npm run test

API

EventDispatcher

Kind: global class
See: https://github.com/symfony/EventDispatcher/blob/master/EventDispatcherInterface.php

• EventDispatcher
  • new EventDispatcher()
  • instance
    • .addListener(eventName, callback, [priority]) ⇒ EventDispatcher
    • .getListeners(eventName) ⇒ Array.<function()>
    • .dispatch(eventName, [event]) ⇒ Event
    • .emit(eventName)
  • static
    • .Event : Event

new EventDispatcher()

A class to manage dispatching events and resolving when they are all complete.

eventDispatcher.addListener(eventName, callback, [priority]) ⇒ EventDispatcher

Adds an event listener that listens on the specified events.

Kind: instance method of EventDispatcher
Returns: EventDispatcher - The dispatcher so calls can be chained.

| Param | Type | Description | | --- | --- | --- | | eventName | String | The name of the event to listen on. | | callback | function | The listener callback | | [priority] | integer | The higher this value, the earlier an event listener will be triggered in the chain (defaults to 0) |

eventDispatcher.getListeners(eventName) ⇒ Array.<function()>

Gets the listeners of a specific event.

Kind: instance method of EventDispatcher
Returns: Array.<function()> - - An array of function listeners (to call).

| Param | Type | Description | | --- | --- | --- | | eventName | String | The name of the event. |

eventDispatcher.dispatch(eventName, [event]) ⇒ Event

Dispatches an event to all registered listeners.

Kind: instance method of EventDispatcher
Returns: Event - The original event is returned back. It may, however, have been modified by the event listeners.

| Param | Type | Description | | --- | --- | --- | | eventName | String | The name of the event to dispatch. | | [event] | Event | The event to pass to the event handlers/listeners. If not supplied, an empty Event instance is created. |

eventDispatcher.emit(eventName)

Emits an event to all registered listeners without returning on completion.

This is different from dispatch in that it doesn't resolve, does not pass an event around and priority is unreliable.

Kind: instance method of EventDispatcher

| Param | Type | Description | | --- | --- | --- | | eventName | String | The name of the event to dispatch. |

EventDispatcher.Event : Event

Kind: static property of EventDispatcher

Event

Kind: global class
See: Based on https://github.com/symfony/EventDispatcher/blob/master/Event.php

• Event
  • new Event()
  • .isPropagationStopped() ⇒ boolean
  • .stopPropagation()

new Event()

Base event class.

This class contains no event data. It is used by events that do not pass state information to an event handler when an event is raised.

event.isPropagationStopped() ⇒ boolean

Returns whether event listeners should be triggered.

Kind: instance method of Event
Returns: boolean - Whether propagation was already stopped for this event.

event.stopPropagation()

Stops the propagation of the event to further event listeners.

If multiple event listeners are connected to the same event, no further event listener will be triggered once any trigger calls stopPropagation().

Kind: instance method of Event

License

MIT

References

• http://keepachangelog.com
• https://github.com/jsdoc2md/jsdoc-to-markdown
• http://sinonjs.org/docs/#spies
• Inspired by
  • Hoopla by Justin Howard.
  • Symfony (EventDispatcherInterface)

© 2015 Andrew Eddie. Documented by jsdoc-to-markdown.