# events-listener

> Listen to events from a Node.js EventEmitter.

Latest version **1.1.0** (published 2018-04-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install events-listener
pnpm add events-listener
yarn add events-listener
bun add events-listener
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2018-04-19 |
| First published | 2017-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Jason Walton |
| Maintainers | jwalton |
| Keywords | events, EventEmitter, listenTo, node, node.js, stopListening |

## Links

- npm: https://www.npmjs.com/package/events-listener
- Repository: https://github.com/jwalton/node-events-listener
- Homepage: https://github.com/jwalton/node-events-listener#readme
- Issues: https://github.com/jwalton/node-events-listener/issues
- npm.io page: https://npm.io/package/events-listener

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2018-04-19
- 1.0.2 — 2017-04-30
- 1.0.1 — 2017-04-30
- 1.0.0 — 2017-04-30

## README

Node.js provides the `events` modules, which provides `EventEmitter`.  This modules provides `EventListener`,
an object that can listen for events.

This was heavily inspired by [Backbone](http://backbonejs.org/)'s `listenTo()` and `stopListening()` functions.
The idea is to make it easy to de-regster an event listener when you're done with it.

Supports Node.js 0.12 and up.

Event Listener Memory Leaks
===========================

```js
import EventEmitter from 'events';

class Widget() {
    constructor(emitter) {
        emitter.on('error', err => this.close());
    }
    ...
}

let emitter = new EventEmitter();

let widget = new Widget(emitter);
// Do some stuff with `widget`.  When we're done with it, clear the reference to
// `widget` so the garbage collector can free it.
widget = null;
```

The code above creates a pretty common memory leak in node.js apps; the problem in the above is that when we call
`emitter.on('error', ...)`, we add the function we pass in to the EventEmitter's list of events to call, which
means EventEmitter has a reference to the handler function.  But, the handler function is an arrow function,
which binds `this`, which means the handler function has a reference to `widget`.  When we set `widget = null`,
the `Widget` object will never be garbage collected, because `emitter` still has a reference to it.

One way to solve this problem is to call `emitter.removeListener('error', handler)`, but note that the function
we passed to `emitter.on(...)` was not `this.close()`, so we can't call `emitter.removeListener('error', this.close)`.
We need to keep a reference to the anonymous arrow function we passed in to `emitter.on()`.

`EventListener`'s job is to keep track of these references for you:


```js
import EventEmitter from 'events';
import EventListener from 'events-listener';

class Widget() {
    constructor(emitter) {
        this.listener = new EventListener();
        this.listener.listenTo(emitter, 'error', err => this.close());
    }

    destroy() {
        this.listener.stopListening();
    }
    ...
}

let emitter = new EventEmitter();

let widget = new Widget(emitter);

// Do some stuff with `widget`.

widget.destroy();
widget = null;
```



API
===

### class EventListener

#### EventListener.listenTo(emitter, event, handler)

Similar to calling `emitter.on(event, handler)`.

#### EventListener.listenToOnce(emitter, event, handler)

Similar to calling `emitter.once(event, handler)`.

#### EventListener.stopListening([emitter,] [event,] [handler]);

Stop listening to some or all events that were registered with calls to `listenTo()` or `listenToOnce()`.

If all three arguments are passed, this is similar to calling `emitter.removeListener(handler)`.

If no arguments are passed, then this will remove all listeners that have been registered on this listener.
If an `emitter` is passed, this will remove all listeners that have been registered on the specific emitter.
If `emitter` and `event` are passed, then this will remove all listeners from the specific emitter that were
registered for the specific event.

---
_Source: https://npm.io/package/events-listener · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._