paperboy-events

A lightweight event emitter and mixin with advanced features that don't get in the way.

Paperboy

A simple event emitter and mixin.

 
var myObject = {'foo':'bar'};
 
var trigger = paperboy.mixin( myObject );
 
myObject.on('myevent', function( howMany ) {
    console.log( howMany ); // 5 
    console.log( this ); // myObject 
});
 
trigger('myevent', 5);
 
  • var trigger = paperboy.mixin( target ) - Adds on, one, and off to target. Returns the trigger function.
  • paperboy.emitter() - Returns a new object with on, one, off, and trigger functions.

NOTE: paperboy.mixin returns the trigger function. It does not add it to the target.

To catch errors early, before they hit production, you can whitelist event names. If anyone tries to add to or trigger events that are not white listed an error will be thrown.

// with a mixin 
var target = {};
var trigger = paperboy.mixin( target, ['eventOne', 'eventTwo']);
 
// with an emitter 
var emitter = paperboy.emitter(['eventOne', 'eventTwo']);
 
emitter.on('eventOne', function(){}); // works 
emitter.on('eventOen', function(){}); // throws an error 

You can have a paperboy emitter repeat the events triggered by other emitters. This is done with the repeat property of the trigger function.

// This will cause `emitter` to echo every event that `otherPaperboyEmitter` triggers. 
emitter.trigger.repeat( otherPaperboyEmitter );
 
// This will cause `emitter` to echo specific events that `otherEmitter` throws. 
// You can even repeat events from jQuery objects or anything else with an `on` function. 
emitter.trigger.repeat( otherEmitter, ['pickup', 'putdown'] );
emitter.trigger.repeat( $('.button'), ['click'] );
emitter.trigger.repeat( backboneModel, ['update'] );

If you specify a list of events to repeat you can use emitters from jQuery, Backbone, or other libraries. You can only repeat all events from other paperboy emitters.

Listeners applied to the * event will be triggered for each event. The first argument will be the event name.

Emitters trigger event listeners. The mixin function turns any object into an emitter.

  • emitter.on( eventName, callback ) - adds a listener to the eventName event. eventName must be a string.
  • emitter.off( eventName, callback ) - removes a listener from an event.
  • emitter.one( eventName, callback ) - adds a listener that will remove itself after being triggered once.
  • emitter.trigger( eventName /*, additional, arguments */ ) - triggeres all event handlers for eventName.
  • emitter.trigger.repeat( otherEmitter /*, [eventNames] */ ) - Causes this emitter to repeat events triggered on another emitter.

NOTE: trigger is not added by the mixin function. If you want trigger to be public you must attach it to the target yourself.

  • Event listeners are always kept private.
  • Passing in a whitelist of event names can prevent bugs.
  • The trigger function is private by default, making it easier to write safe code. If you want it to be public simply add it to the target.
  • Removing a listener in a callback will not cause it to skip the next listener.
  • It's small, under 1k minified and gzipped.

Inspired by LucidJS