EventMixer

What is this?

Just another event-emitter implementation. Nothin' special.

Features

• Manage custom events in your application easily
• Listener registration and emitter functionality can be mixed-in to existing objects
• Listener functions can
  • opt-out of future notification
  • stop continued propagation of an event
  • request event cancellation (like 'preventDefault')

Mmm... Ok. How do I get it?

npm

npm install event-mixer --save

bower

bower install event-mixer --save

What's the Setup?

Simple.

For node

var eventMixer = require('event-mixer');

In a browser

<script src=".../dist/event-mixer.js"></script>
// or, minified
<script src=".../dist/event-mixer.min.js"></script>

How Does This Work?

You have an object. It needs some pub-sub functionality.

You want it to manage its own event subscriptions.

You want it (or some other object) to manage the event publishing.

var mySubber = {}, myPubber = {};
var mixer = eventMixer.mixer(mySubber, myPubber);

Now mySubber has .on()/.off() methods to register/unregister listener functions, and myPubber has a .fire() method to trigger event notifications.

Now, we need some events

var twist = mixer.create('twist'),
    mangle = mixer.create('mangle'),
    scratch = mixer.create('scratch');

At this point mySubber has .onTwist(), .offTwist(), .onMangle(), etc.

And myPubber now has .fireTwist(), .fireMangle(), etc.

Also, event handlers have been returned. More on those in a sec.

Register some listeners!

mySubber.onTwist([eo => console.log('dog'), eo => console.log('cat')]);
mySubber.onMangle(eo => console.log('mangled!'));
mySubber.on('scratch', eo => console.log('scratched!'));

So we've created events and registered some listeners.

Now we want to fire them. We can use the emitter object,

myPubber.fireTwist();     // => dog => cat
myPubber.fireMangle();    // => mangled!
myPubber.fireScratch();   // => scratched!

or the handlers we got earlier.

twist.fire();   
mangle.fire();
scratch.fire();

--

Now, let's talk about the event listener functions.

listener(eo:object):object

As you likely noticed earlier, listener functions are passed an event object (eo).

• eo.target
  The target object the mixer was created with.

• eo.name
  The name of the event that was triggered.

• eo.data
  Any additional data attached to the event. This will be data used to create the handler merged with any provided when the event was fired. Any changes made by a listener will also be available to subsequent listeners.

The listener object return value has some flags you can use.

If the listener wants to opt out of future event notifications:

return { remove: true };

If the listener wants to be the last one called for this event:

return { stop: true };

If the listener wants to stop whatever happens next (like .preventDefault()):

return { prevent: true };

Use whatever combination of these flags you like:

return { prevent: true, remove: true, stop: false };

Beyond this, listener return values are ignored.

Nice. Can I Get an API Quick-Ref?

Yep. Here you go!

module

• mixer(target:object, emitter:object):mixer
  Returns an event manager object that mixes listener registration methods into target object and event trigger methods into emitter object. Both arguments are optional.

• handler(target:object, name:string, data:object):handler
  Returns an event handler object that passes triggered events on to its listeners. Data provided here will be passed to each listener. (Note: Listeners are not managed as a Set so a handler can add the same listener function multiple times.)

mixer

• create(name:string, data:object):handler
  Creates a new event handler. This adds on/off methods to target object and a fire method to emitter object.

• destroy(name:string):handler
  Destroys an event handler. This removes on/off methods from target object and the fire method from emitter object.

• emitter():object
  Returns the emitter for this mixer.

• event(name:string):handler
  Returns the named handler object.

• fire(name:string, data:object):boolean
  Fires the named event. This method is also added directly to the emitter object.

• has(name:string):boolean
  Returns true if there is an event handler for the given name.

• names():array
  Returns the names of all event handlers.

• off(name:string|array, listener:function|array):this
  Removes listener(s) from named event(s). This method is also added directly to the target object.

• on(name:string|array, listener:function|array):this
  Adds listener(s) to named event(s). This method is also added directly to the target object.

• target():object
  Returns the target of this mixer.

handler

• add(listener:function|array):this
  Alias for .append().

• append(listener:function|array):this
  Appends listener function(s) to end of listener list.

• at(index:number):listener
  Returns the listener at the given index or null if not found.

• clear():this
  Removes all listeners.

• count():number
  Returns the number of listeners in this event handler.

• cut(index:number):listener
  Removes and returns the listener at the given index or null if not found.

• each(callback:function):this
  Filters the listener array. Each listener (and its index) is passed to 'callback' and replaced by its return value. If the callback does not return a function the listener will be omitted.

• fire(data:object):boolean
  Triggers the event (with optional data). The returned boolean value indicates if the event should continue normally (true) or not (false).

• has(listener:function):boolean
  Returns true if this handler has the given listener function.

• indexOf(listener:function, start:number):number
  Returns the index of given listener in the listener list or -1 if not found. Specify 'start' to begin the search at a specific index.

• prepend(listener:function|array):this
  Prepends listener function(s) to beginning of listener list.

• remove(listener:function|array):this
  Removes listener function(s).

target

• off(name:string|array, listener:function|array):this
  Removes listener(s) from named event handler(s). Added from mixer.

• on(name:string|array, listener:function|array):this
  Adds listener(s) to named event handler(s). Added from mixer.

• offXxx(listener:function|array):this
  Removes listener(s) from event handler 'Xxx'. Added via mixer.create().

• onXxx(listener:function|array):this
  Adds listener(s) to event handler 'Xxx'. Added via mixer.create().

emitter

• fire(name:string, data:object):boolean
  Fires the named event. Added from mixer.

• fireXxx(data:object):boolean
  Fires the event named 'Xxx'. Added via mixer.create().

Anything Else I Should Know?

Links

{ distrib } { updates } { feedback } { license } { versioning }

Please be sure to check 'updates' link when upgrading to a new version.

Tests

EventMixer uses Jasmine for testing and Istanbul for coverage analysis.

npm test

Finally

Don't Get Triggered! Happy Eventing!