Package Exports

emmy
emmy/delegate
emmy/emit
emmy/keypass
emmy/later
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 asbestos-free event emitter and utils for green components development.

It emits events on any target: plain object, html element, jQuery set, Backbone model, color etc.
It is fully compliant with component-emitter.
It works both in browsers and io.
It is tiny — 1.4kb gzipped.
Each method can be used standalone as require('emmy/<method>');. That way final build size can be reduced even more.
It provides additional event methods: delegate, throttle, later and keypass. They can be required selectively.

Test it, feel it.

Use

For browser use browserify or standalone emmy.js.

Install:

$ npm install emmy

Wrapping methods:

var Emitter = require('emmy');

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

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

Use: bind events to any object in an unobtrusive way.

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.

Standalone

var once = require('emmy/once');

once(worker, 'message', function(){});

Use: if only one specific event method is required or to reduce size of build.

API

Standalone functions

Function	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(element, 'click', null, true)`.
`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.
`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.

Emitter prototype methods

Method | 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

A comprehensive emitter notation reader - have a look at ENot — event notation system.

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