Skip to content

API.md

Latest commit

 

History

History
340 lines (239 loc) · 10.6 KB

API.md

File metadata and controls

340 lines (239 loc) · 10.6 KB

deventor API reference

deventor is a minimal event emitter system built entirely in pure Javascript with 0 dependencies, focused on the browser.

Class: Deventor(deventorSettings)

The Deventor constructor can accept an object parameter with two attributes:

  • name {?String} The name of the Deventor instance
  • maxListeners {?Number} The value of the maximum listeners of the Deventor instance
var myDeventor = new Deventor({
  name: 'myDeventor',
  maxListeners: 20
});

Event: Deventor:newListener

  • eventName {String} The name of the event being listened for
  • listener {Function} The event handler function

The Deventor instance will emit its own 'Deventor:newListener' event before a listener is added to its internal array of listeners.

var myDeventor = new Deventor();

// Only do this once so we don't loop forever
myDeventor.once(Deventor.DEVENTOR_EVENTS.NEW_LISTENER, function (eventName, listener) {
  if (eventName === 'myEvent') {
    myDeventor.on('myEvent', function () {
      console.log('B');
    });
  }
});

myDeventor.on('myEvent', function () {
  console.log('A');
});

myDeventor.emit('myEvent');
// Prints:
// B
// A

Event: Deventor:removeListener

  • eventName {String} The name of the event
  • listener {Function} The event handler function to be removed

The Deventor instance will emit its own 'Deventor:removeListener' event after the listener is removed from its internal array of listeners.

var myDeventor = new Deventor();

var myEventHandler = function () {
  console.log('A');
};

myDeventor.on('myEvent', myEventHandler);

myDeventor.emit('myEvent');
// Prints:
// A

myDeventor.on(Deventor.DEVENTOR_EVENTS.REMOVE_LISTENER, function (eventName, listener) {
  console.log('Event Name -> ' + eventName);
  console.log('Listener to be removed -> ', listener);
});

myDeventor.off('myEvent', myEventHandler)
// Prints:
// Event name -> myEvent
// Listener to be removed -> Function

Event: Deventor:setMaxListeners

  • oldMaxListeners {Number} The old value of maximum listeners of Deventor instance
  • newMaxListeners {Number} The new value of maximum listeners of Deventor instance

The Deventor instance will emit its own 'Deventor:setMaxListeners' event after the maxListeners attribute has changed.

var myDeventor = new Deventor();

myDeventor.on(Deventor.DEVENTOR_EVENTS.SET_MAX_LISTENERS, function (result) {
  console.log('Old max listeners value -> ' + result.oldMaxListeners);
  console.log('New max listeners value -> ' + result.newMaxListeners);
});

myDeventor.setMaxListeners(20);
// Prints:
// Old max listeners value -> 10
// New max listeners value -> 20

Static Attribute: Deventor.defaultMaxListeners

By default, a maximum of 10 listeners can be registered for any single event. This limit can be changed for individual Deventor instances using the deventor.setMaxListeners(maxListeners) method. To change the default for all Deventor instances, the Deventor.defaultMaxListeners property can be used.

Note that this is not a hard limit. The Deventor instance will allow more listeners to be added but will output a trace warning to console indicating that "Max. listeners exceeded to [eventName] event. Max. listeners = [maxListeners]. Take care of memory leaks.". For any single Deventor, the deventor.getMaxListeners() and deventor.setMaxListeners(maxListeners) methods can be used to temporarily avoid this warning:

var myDeventor = new Deventor();

myDeventor.setMaxListeners(myDeventor.getMaxListeners() + 1);

myDeventor.once('event', function () {
  // ...

  myDeventor.setMaxListeners(Math.max(myDeventor.getMaxListeners() - 1, 0));
});

Static Attribute: Deventor.DEVENTOR_EVENTS

Method: deventor.getDeventorName()

Returns the name of the Deventor instance.

var myDeventor = new Deventor({
  name: 'myDeventor'
});

console.log(myDeventor.getDeventorName());
// Prints:
// myDeventor

Method: deventor.setDeventorName(deventorName)

Sets the name of the Deventor instance.

  • deventorName {String} The new Deventor name
var myDeventor = new Deventor({
  name: 'myDeventor'
});

myDeventor.setDeventorName('myOtherDeventor');

console.log(myDeventor.getDeventorName());
// Prints:
// myOtherDeventor

Method: deventor.getMaxListeners()

Returns the current max listeners value for the Deventor which is either set by deventor.setMaxListeners(maxListeners) or defaults to Deventor.defaultMaxListeners

var myDeventor = new Deventor();
console.log(myDeventor.getMaxListeners());
// Prints:
// 10

Method: deventor.setMaxListeners(maxListeners)

Sets the max listeners value for the Deventor instance.

  • maxListeners {Number} The new max listeners value for the Deventor instance
var myDeventor = new Deventor();

myDeventor.setMaxListeners(30);

console.log(myDeventor.getMaxListeners());
// Prints:
// 30

Method: deventor.getEventNames()

Returns an array listing the events which the emitter has registered listeners. The values in the array will be strings.

var myDeventor = new Deventor();

myDeventor.on('event1', function () {
  // ...
});

myDeventor.on('event2', function () {
  // ...
});

console.log(myDeventor.getEventNames());
// Prints:
// ['event1', 'event2']

Method: deventor.getListenersByEventName(eventName)

Returns an array listing the listeners of an event that has been registered. The values in the array will be functions.

  • eventName {String} The name of the event
var myDeventor = new Deventor();

myDeventor.on('event1', function () {
  console.log('A');
});

myDeventor.on('event1', function () {
  console.log('B');
});

console.log(myDeventor.getListenersByEventName('event1'));
// Prints:
// [function () { console.log('A'); }, function () { console.log('B'); }]

Method: deventor.on(eventName, listener)

  • eventName {String} The name of the event
  • listener {Function} The callback function

Adds the listener function to the end of the listeners array of the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times. By default, event listeners are invoked in the order they are added.

var myDeventor = new Deventor();

myDeventor.on('myEvent', function () {
  console.log('My event');
});

Method: deventor.once(eventName, listener)

  • eventName {String} The name of the event
  • listener {Function} The callback function

Adds a one time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked. By default, event listeners are invoked in the order they are added.

var myDeventor = new Deventor();

myDeventor.once('myEvent', function () {
  console.log('My event');
});

Method: deventor.off(eventName, listener)

  • eventName {String} The name of the event
  • listener {Function} The callback function

Removes the specified listener from the listener array for the event named eventName.

var myDeventor = new Deventor();

var callback = function () {
  console.log('My event');
};

myDeventor.on('myEvent', callback);

myDeventor.off('myEvent', callback);

Method: deventor.emit(eventName[,...args])

  • eventName {String} The name of the event
  • ...args {?Any} The arguments to pass to the event

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

var myDeventor = new Deventor();

myDeventor.on('myEvent', function (args) {
  console.log('My event with args -> ', args);
});

myDeventor.emit('myEvent', {
  attribute: 'attribute',
  value: 10
});
// Prints:
// My event with args -> { attribute: 'attribute', value: 10 }

Method: deventor.removeAllListeners()

Removes all listeners.

var myDeventor = new Deventor();

myDeventor.on('myEvent', function (args) {
  console.log('My event with args -> ', args);
});

myDeventor.on('myOtherEvent', function () {
  console.log('My other event');
});

myDeventor.removeAllListeners();

Method: deventor.addListener(eventName, listener)

  • eventName {String} The name of the event
  • listener {Function} The callback function

Alias for deventor.on(eventName, listener)

Method: deventor.removeListener(eventName, listener)

  • eventName {String} The name of the event
  • listener {Function} The callback function

Alias for deventor.off(eventName, listener)