events.js
Stupidly simple events.
I found myself writing this code over and over again, so figured I'd zip it up in a library and save myself the trouble of doing it again. Just about 430 bytes gzipped (don't worry, there aren't any dependencies either), events.js
implements a -- stupidly simple, and appropriately tiny -- event interface.
How simple? This simple.
var events = Events();
events.on( 'cupcake', function () {
alert( 'yum!' );
} );
events.fire( 'cupcake' );
// yum!
Just four simple methods:
on()
one()
off()
fire()
They do... what you would expect them to do.
API documentation
Events.prototype.on( eventName, handler )
Parameters:
- eventName {string}
- handler {function}
Attaches a handler a given event. When the event is fired, (surprise suprise) the handler will be called.
events.on( 'cookie', function ( cookie ) {
eat( cookie );
} );
events.on( 'full', function () {
stopEating();
} );
Events.prototype.one( eventName, handler )
Parameters:
- eventName {string}
- handler {function}
Like .on()
, but with a twist – the handler is only called once. If eventName
is fired subseqent times, the handler won't be called again.
events.one( 'bloated', function () {
die();
} );
Events.prototype.off( eventName[, handler] )
Parameters:
- eventName {string}
- handler {function} (optional)
This function is used to remove event handler(s). If you would like to remove all event handlers attached to a particular event, use:
events.off( 'cookie' );
If you only want to remove one specific handler:
var handler = function () { alert( 'yay!' ) };
events.on( 'cookie', handler );
[...]
events.off( 'cookie', handler );
Events.prototype.fire( eventName[, arguments] )
Parameters:
- eventName {string}
- arguments {...mixed} (optional)
Trying to fire an event? You're in luck! In its simplest form:
events.fire( 'cheese' );
This calls all handlers previously attached to the cheese
event using .on()
(and .one()
) with no arguments. If you want to pass arguments...
events.on( 'cookie', function ( cookie ) {
eat( cookie );
} );
[...]
var cookie = new Cookie();
events.fire( 'cookie', cookie );
You can pass an unlimited number of arguments – that's right, knock yourself out!
Bonus feature
You can restrict the names of events available by passing in an array when initializing:
var limitedEvents = Events( [ 'joy', 'celebration' ] );
limitedEvents.on( 'death', function () {
alert( ':(' );
} );
// Error: The event "death" is not defined
If you later attempt to fire or add a handler to an event that wasn't in the initial array, an error will be thrown.
Get it
Available via npm:
npm install stupidly-simple-events
or just download events.min.js
.