jacomyal / emmett

A custom event emitter for Node.js and the browser

Emmett

A custom event emitter for Node.js and the browser.

Its aim is to provide its user with a lot of event emitting sugar while remaining lightweight and fast.

Installation

You can install Emmett through npm:

npm install --save emmett

Usage

Creating an emitter

var Emitter = require('emmett');

var emitter = new Emitter();

Extending the emitter

Node.js

var util = require('util'),
    Emitter = require('emmett');

function MyObject() {
	Emitter.call(this);
}

util.inherits(MyObject, Emitter);

ES6 class

import Emitter from 'emmett';

class MyObject extends Emitter {
	/* ... */
}

Listening to events

// Basic
emitter.on('eventName', callback);

// Once
emitter.once('eventName', callback);

// Using ES6 symbol as event name
const sym = Symbol();
emitter.on(sym, callback);

// Matching event names with a regex
emitter.on(/^event/, callback);

// Options
emitter.on('eventName', callback, {scope: customScope, once: true});

// Polymorphisms
emitter.on(['event1', 'event2'], callback);

emitter.on({
	event1: callback1,
	event2: callback2
});

// Listening to every events
emitter.on(callback);

Event data

Events are objects having the following keys:

• data: the data attached to the event.
• type: the event type.
• target: the event emitter.

emitter.on('myEvent', function(e) {
	console.log(e.data);
});

emitter.emit('myEvent', 'Hello World!');

// Will print "Hello World!" in the console

Removing listeners

// Basic
emitter.off('eventName', callback);

// Removing every listeners attached to the given event
emitter.off('eventName');

// Removing the callback from any event
emitter.off(callback);

// Polymorphisms
emitter.off(['event1', 'event2'], callback);

emitter.off({
	event1: callback1,
	event2: callback2
});

// Removing every listeners
emitter.unbindAll();

Emitting

// Basic
emitter.emit('eventName');

// With data
emitter.emit('eventName', {hello: 'world'});

// Polymorphisms
emitter.emit(['event1', 'event2']);
emitter.emit(['event1', 'event2'], {hello: 'world'});

emitter.emit({
	event1: 'hey',
	event2: 'ho'
});

Retrieving listeners

// Return every matching handlers for a given event name
emitter.listeners('eventName');

Disabling an emitter

While disabled, emitting events won't produce nothing.

emitter.disable();
emitter.enable();

Killing an emitter

Killing an emitter will remove all its listeners and make it inoperant in the future.

emitter.kill();

Contribution

Do not hesitate to contribute to the library. Be sure to add and pass any relevant unit test before submitting any code.

# Installing the dev version
git clone http://github.com/jacomyal/emmett
cd emmett

# Installing dependencies
npm install

# Running unit tests
npm test

# Lint the code
npm run lint

emmett's Issues

Implement .off variant 3

Cut sort on event sourcing possibilities

Support Symbols as event names.

What it says in the description :)

Event names enumerator

Can we add some option to enumerate all possible event names?

This is valuable because:

1. users will have an official place to check for possible emit options
2. we get errors when event name is mistyped

Something like:

import Emmett from "emmett";

let emitter = new Emmett([
  "scale.mouseDown"
]);

emitter.on("scale.mouseDown", (data) => {
  console.log("scale.mouseDown!");
});

emitter.emit("scale.mouseDown"); // CONSOLE.LOG
emitter.emit("scale.mouseUp"); // ERROR!

I don't know how it's better to adopt this to custom emitters (inheritance) but there are some ways...

Seems to fail when trying to emit an invalid argument

Maybe some type checking and a better error can be created.

Kill: reminder to check whether silence is the good option

Add a once method to the emitter and the binders.

Documentation

Symbol-keys are ignored when using pair events

Hi there,

just noticed you've added Symbol support. There is one bug though when using pair events like this:

myEmitter.on({
  myEvent1: function(e) {  },
  myEvent2: function(e) {  }
});

Since Symbols can not be enumerated with for ... in or Object.keys(events).on they are just being ignored in such cases.

Sorry, I don't have time for a proper PR, but here is a possible solution

// instead of using `for ... in` you can process each key type individually

// Symbol-keys
Object.getOwnPropertySymbols(events).forEach(function(event){
     // this.on/off/etc....
});

// String-keys
Object.getOwnPropertyNames(events).forEach(function(event){
     // this.on/off/etc....
});

#off(handler) fails with symbols

const Emitter = require("emmett");
const emitter = new Emitter();
const event = Symbol("myEvent");

let count = 0;
const handler = function() { count++; }

emitter.on(event, handler);
emitter.off(handler);
emitter.emit(event);

console.log("Count:", count);

Expected result:

Should log Count: 0

Actual result:

Should log Count: 1

Once in combination with off fires constantly

Please see #19 for a test case and more details.

Sort handlers (only in worst cases)

Cleaning up offing process

Should the minified version served along the npm package?

Support for wildcards in event listening?

This could be insanely useful at times:

ee.on('ns:*', fn);

Method to retrieve listeners

http://nodejs.org/api/events.html#events_emitter_listeners_event

Would be nicer than counting _handlers and _handlersAll.

Decide whether absent data should be {} or undefined

Distinguish handlers and handler functions in the code

New emit polymorphism

e.emit({eventName1: data1, eventName2: data2});

Fire handlers in the emitter's scope.

Emitter.off('event') polymorphism.

#emit breaks with symbols and complex handlers

const Emitter = require("emmett");
const emitter = new Emitter();

emitter.on(/some pattern/, function() {});
emitter.emit(Symbol("myEvent"));

console.log("All good.");

Expected result:

Should log All good.

Actual result:

Throws TypeError: event.search is not a function