# events-decorator

> decorates EventEmitter with methods to handle multiple events

Latest version **0.2.0** (published 2018-12-04) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2018-12-04 |
| First published | 2018-12-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.4.0 |
| Dependencies | 0 |
| Unpacked size | 94.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Guilherme Hermeto |
| Maintainers | ghermeto |
| Keywords | event, events, on-any, on-all, on-first, on-last, onfirst, onany, onall, onlast, eventemitter, event-emitter, event-decorator |

## Links

- npm: https://www.npmjs.com/package/events-decorator
- Repository: https://github.com/ghermeto/event-decorator
- Homepage: https://github.com/ghermeto/event-decorator#readme
- Issues: https://github.com/ghermeto/event-decorator/issues
- npm.io page: https://npm.io/package/events-decorator

## 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

- 0.2.0 (latest) — 2018-12-04
- 0.1.0 — 2018-12-04

## README

# Event Decorator

[![node](https://img.shields.io/node/v/events-decorator.svg)]()
[![Build Status](https://travis-ci.org/ghermeto/event-decorator.svg?branch=master)](https://travis-ci.org/ghermeto/event-decorator)
[![npm](https://img.shields.io/npm/v/events-decorator.svg)](https://www.npmjs.com/package/events-decorator)
[![GitHub](https://img.shields.io/github/license/ghermeto/event-decorator.svg)](https://github.com/ghermeto/event-decorator/blob/master/LICENSE)
[![David](https://img.shields.io/david/ghermeto/event-decorator.svg)](https://david-dm.org/ghermeto/event-decorator)
[![David](https://img.shields.io/david/dev/ghermeto/event-decorator.svg)](https://david-dm.org/ghermeto/event-decorator?type=dev)

Decorates EventEmitter with handy methods when working with multiple events

## Install

```sh
$ npm install --save events-decorator
```

## API

```javascript
    const { onceAny, onceAll, decorate } = require('events-decorator');
```

### onceAny(emitter, eventNames, handler)

Will subscribe to all events is `evantNames` from `emitter` and will execute `handler` **once** for 
the **first** event that occurs. When handler is executed, it will immediately unsubscribe from all 
events.

Returns a function to unsubscribe from the events.

```javascript
const { onceAny } = require('events-decorator');

const unsubscribe = onceAny(emitter, ['one', 'two', 'three'], (trigger, ...arguments) => {
    console.info(`first event was ${trigger}`);
});
```
   
#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| emitter | `EventEmitter`  |  |
| eventNames | `Array`  | defaults to empty array `[]` |
| handler | `Function`  | user provider handler |

#### Returns

`unsubscriber: function()` calling this function before the handler is executed will unsubscribe 
from all the events. Calling it after the handler is executed has no effect. 

### onceAll(emitter, eventNames, handler)

Will subscribe to all events is `evantNames` from `emitter` and will execute `handler` **once** for 
the **last** event that occurs. When handler is executed, it will immediately unsubscribe from all 
events.

Returns a function to unsubscribe from the events.

```javascript
const { onceAll } = require('events-decorator');

const unsubscribe = onceAll(emitter, ['one', 'two', 'three'], (argumentsArray) => {
    console.info(`the last event was ${trigger}`);
});
```
   
#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| emitter | `EventEmitter`  |  |
| eventNames | `Array`  | defaults to empty array `[]` |
| handler | `Function`  | user provider handler |

#### Returns

`unsubscriber: function()` calling this function before the handler is executed will unsubscribe 
from all the events. Calling it after the handler is executed has no effect. 

### decorate(emitter)

Decorates the `EventEmitter` with the `onceAny` and `onceAll` methods. It won't modify the `emitter`.
The new methods will have similar API to the ones described above, but omitting the first parameter.

Returns a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
for the `emitter`.

```javascript
const { decorate } = require('events-decorator');

const decorated = decorate(emitter);

const unsub1 = decorated.onceAny(['one', 'two', 'three'], (trigger, ...arguments) => {
    console.info(`first event was ${trigger}`);
});

const unsub2 = decorated.onLast(['one', 'two', 'three'], (trigger, ...arguments) => {
    console.info(`the last event was ${trigger}`);
});
```
   
#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| emitter | `EventEmitter`  |  |

#### Returns

`decorated: Proxy<EventEmitter>` 

## Examples

To count the in-flight requests on a express server:

```js
const { onceAny } = require('events-decorator');

let inflightRequests = 0;
app.use((req, res, next) => {
    inflightRequests++;
    onceAny(res, ['error', 'finish', 'close'], () => {
        inflightRequests--;
    });
    next();
});
```

To log the response time for each request: 

```js
const { onceAny } = require("events-decorator");

app.use((req, res, next) => {
    // hrtime.bigint is available on Node v10.7+
    const start = process.hrtime.bigint();
    onceAny(res, ['finish', 'close'], () => {
        const end = process.hrtime.bigint();
        console.log(`response took ${end - star} nanosecods`);
    });
    next();
});
```
---

MIT © [Guilherme Hermeto](http://github.com/ghermeto)

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