| 1 | # EventEmitter3
|
|---|
| 2 |
|
|---|
| 3 | [](https://www.npmjs.com/package/eventemitter3)[](https://github.com/primus/eventemitter3/actions?query=workflow%3ACI+branch%3Amaster)[](https://coveralls.io/r/primus/eventemitter3?branch=master)
|
|---|
| 4 |
|
|---|
| 5 | EventEmitter3 is a high performance EventEmitter. It has been micro-optimized
|
|---|
| 6 | for various of code paths making this, one of, if not the fastest EventEmitter
|
|---|
| 7 | available for Node.js and browsers. The module is API compatible with the
|
|---|
| 8 | EventEmitter that ships by default with Node.js but there are some slight
|
|---|
| 9 | differences:
|
|---|
| 10 |
|
|---|
| 11 | - Domain support has been removed.
|
|---|
| 12 | - We do not `throw` an error when you emit an `error` event and nobody is
|
|---|
| 13 | listening.
|
|---|
| 14 | - The `newListener` and `removeListener` events have been removed as they
|
|---|
| 15 | are useful only in some uncommon use-cases.
|
|---|
| 16 | - The `setMaxListeners`, `getMaxListeners`, `prependListener` and
|
|---|
| 17 | `prependOnceListener` methods are not available.
|
|---|
| 18 | - Support for custom context for events so there is no need to use `fn.bind`.
|
|---|
| 19 | - The `removeListener` method removes all matching listeners, not only the
|
|---|
| 20 | first.
|
|---|
| 21 |
|
|---|
| 22 | It's a drop in replacement for existing EventEmitters, but just faster. Free
|
|---|
| 23 | performance, who wouldn't want that? The EventEmitter is written in EcmaScript 3
|
|---|
| 24 | so it will work in the oldest browsers and node versions that you need to
|
|---|
| 25 | support.
|
|---|
| 26 |
|
|---|
| 27 | ## Installation
|
|---|
| 28 |
|
|---|
| 29 | ```bash
|
|---|
| 30 | $ npm install --save eventemitter3
|
|---|
| 31 | ```
|
|---|
| 32 |
|
|---|
| 33 | ## CDN
|
|---|
| 34 |
|
|---|
| 35 | Recommended CDN:
|
|---|
| 36 |
|
|---|
| 37 | ```text
|
|---|
| 38 | https://unpkg.com/eventemitter3@latest/dist/eventemitter3.umd.min.js
|
|---|
| 39 | ```
|
|---|
| 40 |
|
|---|
| 41 | ## Usage
|
|---|
| 42 |
|
|---|
| 43 | After installation the only thing you need to do is require the module:
|
|---|
| 44 |
|
|---|
| 45 | ```js
|
|---|
| 46 | var EventEmitter = require('eventemitter3');
|
|---|
| 47 | ```
|
|---|
| 48 |
|
|---|
| 49 | And you're ready to create your own EventEmitter instances. For the API
|
|---|
| 50 | documentation, please follow the official Node.js documentation:
|
|---|
| 51 |
|
|---|
| 52 | http://nodejs.org/api/events.html
|
|---|
| 53 |
|
|---|
| 54 | ### Contextual emits
|
|---|
| 55 |
|
|---|
| 56 | We've upgraded the API of the `EventEmitter.on`, `EventEmitter.once` and
|
|---|
| 57 | `EventEmitter.removeListener` to accept an extra argument which is the `context`
|
|---|
| 58 | or `this` value that should be set for the emitted events. This means you no
|
|---|
| 59 | longer have the overhead of an event that required `fn.bind` in order to get a
|
|---|
| 60 | custom `this` value.
|
|---|
| 61 |
|
|---|
| 62 | ```js
|
|---|
| 63 | var EE = new EventEmitter()
|
|---|
| 64 | , context = { foo: 'bar' };
|
|---|
| 65 |
|
|---|
| 66 | function emitted() {
|
|---|
| 67 | console.log(this === context); // true
|
|---|
| 68 | }
|
|---|
| 69 |
|
|---|
| 70 | EE.once('event-name', emitted, context);
|
|---|
| 71 | EE.on('another-event', emitted, context);
|
|---|
| 72 | EE.removeListener('another-event', emitted, context);
|
|---|
| 73 | ```
|
|---|
| 74 |
|
|---|
| 75 | ### Tests and benchmarks
|
|---|
| 76 |
|
|---|
| 77 | To run tests run `npm test`. To run the benchmarks run `npm run benchmark`.
|
|---|
| 78 |
|
|---|
| 79 | Tests and benchmarks are not included in the npm package. If you want to play
|
|---|
| 80 | with them you have to clone the GitHub repository. Note that you will have to
|
|---|
| 81 | run an additional `npm i` in the benchmarks folder before `npm run benchmark`.
|
|---|
| 82 |
|
|---|
| 83 | ## License
|
|---|
| 84 |
|
|---|
| 85 | [MIT](LICENSE)
|
|---|
