tiny-eventer
Tiny and simple event module with no third party dependencies.
Usage
Installation
Using npm:
npm install tiny-eventer [--save]
Using yarn:
yarn add tiny-eventer
In Node.js:
'use strict'
// Load a global instance
var eventer = require('tiny-eventer');
// Or load the Eventer class to use a new instance of it.
var Eventer = require('tiny-eventer').Eventer;
In the browser:
// eventer is a global object, attached on window.eventer
eventer === window.eventer;
// true
// Get the eventer class to for creating new instances
var Eventer = eventer.Eventer;
API
eventer.on(eventName, listener, [_this])
Subscribes to events on eventName
.
eventName (String)
Name of the event to listen for
listener (Function)
The function to be called. Any params passed into trigger(eventName, [...params])
will be passed in.
[_this (Any)]
A reference to this
(or an ID of sorts) which can be used for unsubscribing to events when listener
is an anonymous function. This can be used to group event listeners, as string or number could be passed in.
Example
/** ... */
// Passing in a named function and skipping *_this*
eventer.on('user_added', onAddedUser);
function onAddedUser(user) {
console.log('user_added event!');
}
// Passing in an anonymous function with a string ID as *_this*.
eventer.on('other_user_added', function (user) { console.log('other_user_added event!') }, 'some.id');
/** ... */
eventer.once(eventName, listener, [_this])
Subscribes to a single event on eventName
. Only difference between eventer.once
and eventer.on
is that eventer.once
will only fire once, as is suggested by the name of the function.
Events subscribed to using once are cancellable using eventer.off(...)
.
eventName (String)
Name of the event to listen for
listener (Function)
The function to be called. Any params passed into trigger(eventName, [...params])
will be passed in.
[_this (Any)]
A reference to this
(or an ID of sorts) which can be used for unsubscribing to events when listener
is an anonymous function. This can be used to group event listeners, as string or number could be passed in.
Example
/** ... */
// Passing in a named function and skipping *_this*
eventer.once('user_added', onAddedUser);
function onAddedUser(user) {
console.log('user_added event!');
}
eventer.trigger('user_added', { userId: 1, name: 'Arthur Dent' });
// Logs 'user_added event!'
eventer.trigger('user_added', { userId: 2, name: 'Ford Prefect' });
// Logs nothing
/** ... */
eventer.off(eventName, listener, [_this])
Unsubscribes to events on eventName
.
eventName (String)
Name of the event to stop listening for
[listener (Function)]
The function which would've been called. Either this _this
can be used to match an event listener.
[_this (Any)]
A possible other identification for when listener
is an anonymous function, or if a group of events should be unsubscribed with a single call.
Example
/** ... */
// Unsubscribe by passing in a named function and skipping *_this*
eventer.off('user_added', onAddedUser);
function onAddedUser(user) { /** ... */ }
// Unsubscribe by passing in a string ID as *_this* and leaving *listener* empty
eventer.off('other_user_added', undefined, 'some.id');
/** ... */
eventer.clear(eventName)
Unsubscribes all listeners on eventName
eventName (String)
Name of the event to remove all listeners from
Example
/** ... */
// Unsubscribe all listeners
eventer.clear('user_added');
/** ... */
eventer.clearAll()
Removes all listeners from all events
Example
/** ... */
// Remove all listeners
eventer.clearAll();
/** ... */
eventer.trigger(eventName, [...params])
Triggers an event with the passed in parameters, if any.
eventName (String)
Name of the event to trigger
[...params (Any)]
Parameters to be passed into callbacks
/** ... */
var newUser = {
id: 42,
name: 'Arthur Dent',
occupation: 'Hapless Englishman'
};
var otherUser = {
id: 49,
name: 'Ford Prefect',
occupation: 'Writer'
};
// Triggers an event with no parameters passed into it.
eventer.trigger('look_no_params_ma');
// Trigger event with a single parameter passed in (other than eventName, obviously).
eventer.trigger('user_added', newUser);
// Trigger event with multiple parameters passed in. Any number of parameters can be passed in.
eventer.trigger('users_added', newUser, otherUser);
/** ... */
eventer.$events
Container object for events, with keys as the name of the event and the values are arrays of event items (consisting of listener and _this)
new eventer.Eventer()
Creates a new Eventer instance useful for creating sandboxed events.
/** ... */
var _eventer = new eventer.Eventer();
_eventer === eventer;
// false
_eventer instanceof eventer.Eventer;
// true
eventer instanceof eventer.Eventer;
// true
/** ... */