1 | # EventEmitter3
|
2 |
|
3 | [![Version npm](https://img.shields.io/npm/v/eventemitter3.svg?style=flat-square)](https://www.npmjs.com/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 |
|
7 | EventEmitter3 is a high performance EventEmitter. It has been micro-optimized
|
8 | for various of code paths making this, one of, if not the fastest EventEmitter
|
9 | available for Node.js and browsers. The module is API compatible with the
|
10 | EventEmitter that ships by default with Node.js but there are some slight
|
11 | differences:
|
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 its 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` method. Use `EE.listeners(event).length` instead.
|
21 | - Support for custom context for events so there is no need to use `fn.bind`.
|
22 | - The `listeners` method can do existence checking instead of returning only
|
23 | arrays.
|
24 | - The `removeListener` method removes all matching listeners, not only the
|
25 | first.
|
26 |
|
27 | It's a drop in replacement for existing EventEmitters, but just faster. Free
|
28 | performance, who wouldn't want that? The EventEmitter is written in EcmaScript 3
|
29 | so it will work in the oldest browsers and node versions that you need to
|
30 | support.
|
31 |
|
32 | ## Installation
|
33 |
|
34 | ```bash
|
35 | $ npm install --save eventemitter3 # npm
|
36 | $ component install primus/eventemitter3 # Component
|
37 | $ bower install eventemitter3 # Bower
|
38 | ```
|
39 |
|
40 | ## Usage
|
41 |
|
42 | After installation the only thing you need to do is require the module:
|
43 |
|
44 | ```js
|
45 | var EventEmitter = require('eventemitter3');
|
46 | ```
|
47 |
|
48 | And you're ready to create your own EventEmitter instances. For the API
|
49 | documentation, please follow the official Node.js documentation:
|
50 |
|
51 | http://nodejs.org/api/events.html
|
52 |
|
53 | ### Contextual emits
|
54 |
|
55 | We've upgraded the API of the `EventEmitter.on`, `EventEmitter.once` and
|
56 | `EventEmitter.removeListener` to accept an extra argument which is the `context`
|
57 | or `this` value that should be set for the emitted events. This means you no
|
58 | longer have the overhead of an event that required `fn.bind` in order to get a
|
59 | custom `this` value.
|
60 |
|
61 | ```js
|
62 | var EE = new EventEmitter()
|
63 | , context = { foo: 'bar' };
|
64 |
|
65 | function emitted() {
|
66 | console.log(this === context); // true
|
67 | }
|
68 |
|
69 | EE.once('event-name', emitted, context);
|
70 | EE.on('another-event', emitted, context);
|
71 | EE.removeListener('another-event', emitted, context);
|
72 | ```
|
73 |
|
74 | ### Existence
|
75 |
|
76 | To check if there is already a listener for a given event you can supply the
|
77 | `listeners` method with an extra boolean argument. This will transform the
|
78 | output from an array, to a boolean value which indicates if there are listeners
|
79 | in place for the given event:
|
80 |
|
81 | ```js
|
82 | var EE = new EventEmitter();
|
83 | EE.once('event-name', function () {});
|
84 | EE.on('another-event', function () {});
|
85 |
|
86 | EE.listeners('event-name', true); // returns true
|
87 | EE.listeners('unknown-name', true); // returns false
|
88 | ```
|
89 |
|
90 | ### Tests and benchmarks
|
91 |
|
92 | This module is well tested. You can run:
|
93 |
|
94 | - `npm test` to run the tests under Node.js.
|
95 | - `npm run coverage` to get the code coverage.
|
96 | - `npm run test-browser` to run the tests in real browsers via Sauce Labs.
|
97 |
|
98 | We also have a set of benchmarks to compare EventEmitter3 with some available
|
99 | alternatives. To run the benchmarks run `npm run benchmark`.
|
100 |
|
101 | Tests and benchmarks are not included in the npm package. If you want to play
|
102 | with them you have to clone the GitHub repository.
|
103 |
|
104 | ## License
|
105 |
|
106 | [MIT](LICENSE)
|