Package Exports

emmy
emmy/delegate
emmy/emit
emmy/keypass
emmy/later
emmy/not
emmy/off
emmy/on
emmy/once
emmy/throttle

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (emmy) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Emmy

Emmy is enhanced event emitter and event methods for green components.

Emits events on any target: plain object, element, jQuery, Backbone model, color etc. Uses target events first, if available, like dispatchEvent or addEventListener on DOM elements or on, trigger on jQuery objects.
Fully compliant with component-emitter, but behaves in an unobtrusive way, not polluting target with _callbacks property by leveraging WeakMaps.
Provides standalone on, once, emit, off and additional delegate, not, throttle, later and keypass methods. Each is available as require('emmy/<method>');.
Accepts space-separated multiple events, e.g. on(el, 'click touchstart', cb).
Handles event-namespaces, e.g. on(el, 'click.x', cb); off(el, 'click.x');.
Works both in browsers and io.
Asbestos-free.

Use

$ npm install emmy

Standalone methods

var on = require('emmy/on');
var once = require('emmy/once');
var off = require('emmy/off');
var emit = require('emmy/emit');

on(target, 'evt', function(){});
emit(target, 'evt', data1, data2);
off(target, 'evt');

//typical use-case
once(webWorker, 'message', function(){...});

Use: bind events to any object in an unobtrusive way. Also use if only one method is required and/or to reduce size of build.

Create `Emitter` instance

var Emitter = require('emmy');

var emitter = new Emitter;
emitter.emit('something');

Use: сreate a new object with event methods.

Mixin object

var Emitter = require('emmy');

user = Emitter({name: 'John'});

user.emit('hello');

Use: extend existing object with event methods.

Mixin prototype

var Emitter = require('emmy');
Emitter(User.prototype);

Use: extend existing class prototype with event methods.

Inherit Emitter

var Emitter = require('emmy');

function Actor(){};

//Give out emmy to an actor :)
Actor.prototype = Object.create(Emitter);

var actor = new Actor();

actor
//Bind events
.on('event', handler)
.on('otherEvent', handler)
.on('event2', [handler1, handler2]) //bind list of handlers


//Unbind events
.off('event', handler)
.off('otherEvent') //unbind all 'otherEvent' callbacks
.off('event2', [handler1, handler2]); //unbind list of handlers
.off(target) //unbind all events


//Emit events
.emit('a')
.emit('b', data, bubbles);

Use: make instances of class instanceof Emitter.

API

Standalone functions

Process single target/event/callback.

Function	Arguments	Description
`on`	target, event, callback	Bind event handler to a target.
`once`	target, event, callback	Bind single-shot event handler to a target.
`off`	target, event?, callback?	Unbind event handler from a target. If calback isn’t passed - unbind all callbacks for an event. If no event passed - unbind all.
`emit`	target, event, callback, data1, data2, ...	Emit an event on a target, passing dataN. If target is an element then data1 is e.details, data2 is bubbles. So to fire bubbling event, call `emit`
`later`	target, event, callback, delay	Bind an event handler which triggers a delay later than actual event occures.
`throttle`	target, event, callback, interval	Bind an event handler which won’t be called more often than an interval.
`delegate`	target, event, callback, selector	Bind an event handler catching bubbling events from target’s descendants.
`not`	target, event, callback, selector	Bind an event handler catching events from target’s descendants ignoring ones that match selector.
`keypass`	target, event, callback, keylist	Bind an event handler which triggers only if `e.which` or `e.keyCode` is one from the defined keylist. Any keyname can be declared instead of a code.
`listeners`	target [, event]	Get list of listeners registered for an event.

Prototype methods

Method	Arguments	Description
`.on`	event, handler	Register handler for event.
`.once`	event, handler	Register single-shot event handler.
`.off`	event, handler	Remove an event handler. If no handler passed - remove all registered handlers. In no event passed - remove all registered listeners for all events.
`.emit`	event, data1, data2, ...	Emit an event with params passed. Each argument after event will be passed to the callback.
`.listeners`	event	Get list of listeners for an `event`.
`.hasListeners`	event	Check if emitter has `event` handlers.

Afterword

Emmy implements maximally minimal coverage for main use-cases. It’s not supposed to recognize broad range of input values. For that take a look at ENot (event notation system) — an easy wrapper for emmy with humanized event notation.

There’s also a similar project - emmitt, but it can’t emit bubbling events nor DOM-events, it does not provide an Emitter class and a bunch of useful methods.

emmy