1# EventEmitter3
 2
 3[![Version npm](https://img.shields.io/npm/v/eventemitter3.svg?style=flat-square)](http://browsenpm.org/package/eventemitter3)[![Build Status](https://img.shields.io/travis/primus/eventemitter3/master.svg?style=flat-square)](https://travis-ci.org/primus/eventemitter3)[![Dependencies](https://img.shields.io/david/primus/eventemitter3.svg?style=flat-square)](https://david-dm.org/primus/eventemitter3)[![Coverage Status](https://img.shields.io/coveralls/primus/eventemitter3/master.svg?style=flat-square)](https://coveralls.io/r/primus/eventemitter3?branch=master)[![IRC channel](https://img.shields.io/badge/IRC-irc.freenode.net%23primus-00a8ff.svg?style=flat-square)](https://webchat.freenode.net/?channels=primus)
 4
 5[![Sauce Test Status](https://saucelabs.com/browser-matrix/eventemitter3.svg)](https://saucelabs.com/u/eventemitter3)
 6
 7EventEmitter3 is a high performance EventEmitter. It has been micro-optimized
 8for various of code paths making this, one of, if not the fastest EventEmitter
 9available for Node.js and browsers. The module is API compatible with the
10EventEmitter that ships by default with Node.js but there are some slight
11differences:
12
13- Domain support has been removed.
14- We do not `throw` an error when you emit an `error` event and nobody is
15  listening.
16- The `newListener` event is removed as the use-cases for this functionality are
17  really just edge cases.
18- No `setMaxListeners` and it's pointless memory leak warnings. If you want to
19  add `end` listeners you should be able to do that without modules complaining.
20- No `listenerCount` function. Use `EE.listeners(event).length` instead.
21- Support for custom context for events so there is no need to use `fn.bind`.
22- `listeners` method can do existence checking instead of returning only arrays.
23
24It's a drop in replacement for existing EventEmitters, but just faster. Free
25performance, who wouldn't want that? The EventEmitter is written in EcmaScript 3
26so it will work in the oldest browsers and node versions that you need to
27support.
28
29## Installation
30
31```bash
32$ npm install --save eventemitter3        # npm
33$ component install primus/eventemitter3  # Component
34$ bower install eventemitter3             # Bower
35```
36
37## Usage
38
39After installation the only thing you need to do is require the module:
40
41```js
42var EventEmitter = require('eventemitter3');
43```
44
45And you're ready to create your own EventEmitter instances. For the API
46documentation, please follow the official Node.js documentation:
47
48http://nodejs.org/api/events.html
49
50### Contextual emits
51
52We've upgraded the API of the `EventEmitter.on`, `EventEmitter.once` and
53`EventEmitter.removeListener` to accept an extra argument which is the `context`
54or `this` value that should be set for the emitted events. This means you no
55longer have the overhead of an event that required `fn.bind` in order to get a
56custom `this` value.
57
58```js
59var EE = new EventEmitter()
60  , context = { foo: 'bar' };
61
62function emitted() {
63  console.log(this === context); // true
64}
65
66EE.once('event-name', emitted, context);
67EE.on('another-event', emitted, context);
68EE.removeListener('another-event', emitted, context);
69```
70
71### Existence
72
73To check if there is already a listener for a given event you can supply the
74`listeners` method with an extra boolean argument. This will transform the
75output from an array, to a boolean value which indicates if there are listeners
76in place for the given event:
77
78```js
79var EE = new EventEmitter();
80EE.once('event-name', function () {});
81EE.on('another-event', function () {});
82
83EE.listeners('event-name', true); // returns true
84EE.listeners('unknown-name', true); // returns false
85```
86
87## License
88
89[MIT](LICENSE)