# @slimio/safe-emitter

> Safe and isolated Event Emitter with Asynchronous capabilities

Latest version **1.1.0** (published 2019-11-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @slimio/safe-emitter
pnpm add @slimio/safe-emitter
yarn add @slimio/safe-emitter
bun add @slimio/safe-emitter
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2019-11-10 |
| First published | 2018-10-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 0 |
| Unpacked size | 21.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | SlimIO |
| Maintainers | ahkrin, alexandre.malaj, captainfive, fraxken, mcroquet |
| Keywords | emitter, safe, event |

## Links

- npm: https://www.npmjs.com/package/@slimio/safe-emitter
- Repository: https://github.com/SlimIO/safeEmitter
- Homepage: https://github.com/SlimIO/safeEmitter#readme
- Issues: https://github.com/SlimIO/safeEmitter/issues
- npm.io page: https://npm.io/package/@slimio/safe-emitter

## 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) — 2019-11-10
- 1.0.6 — 2019-01-30
- 1.0.5 — 2018-12-28
- 1.0.4 — 2018-12-28
- 1.0.3 — 2018-11-20
- 1.0.2 — 2018-11-15
- 1.0.1 — 2018-10-09
- 1.0.0 — 2018-10-05

## README

# SafeEmitter

![![version]](https://img.shields.io/badge/dynamic/json.svg?url=https://raw.githubusercontent.com/SlimIO/safeEmitter/master/package.json&query=$.version&label=Version)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/SlimIO/safeEmitter/commit-activity)
[![mit](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/SlimIO/safeEmitter/blob/master/LICENSE)
![size](https://img.shields.io/bundlephobia/min/@slimio/safe-emitter.svg?style=flat)
![DEP](https://img.shields.io/david/SlimIO/safeEmitter.svg)
[![Known Vulnerabilities](https://snyk.io/test/github/SlimIO/safeEmitter/badge.svg?targetFile=package.json)](https://snyk.io/test/github/SlimIO/safeEmitter?targetFile=package.json)
[![Build Status](https://travis-ci.com/SlimIO/safeEmitter.svg?branch=master)](https://travis-ci.com/SlimIO/safeEmitter)
[![Greenkeeper badge](https://badges.greenkeeper.io/SlimIO/Safe-emitter.svg)](https://greenkeeper.io/)

Safe Node.js Event Emitter (aim to be compatible with [Node.js Emitter](https://nodejs.org/api/events.html) as possible). This package has been created to answer specific need of the SlimIO product and has no purpose of replacing Node.js Emitter.

Within the SlimIO Core we need to ensure that all addons are started as expected without any errors (any Error in an EventEmitter will cause a stop at the core level).

If you dont know why you need this, **please don't use it** !

> Note: The SlimIO core force Node.js DEP0018 (So unhandledPromise will stop the process).

<p align="center">
    <img src="https://i.imgur.com/ogpk93x.png" width="610">
</p>

## Requirements
- [Node.js](https://nodejs.org/en/) v12 or higher

## Getting Started

This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).

```bash
$ npm i @slimio/safe-emitter
# or
$ yarn add @slimio/safe-emitter
```

## Usage example

```js
const SafeEmitter = require("@slimio/safe-emitter");

const evt = new SafeEmitter().catch((err, eventName) => {
    console.log(`Catched error for event <${eventName}> ${err.message}`);
});

evt.on("foo", () => {
    new Error("ooppsss!");
});
evt.once("foo").then(() => {
    console.log("triggered one time!");
});

evt.emit("foo");
evt.emitAndWait("foo").then(() => {
    console.log("all foo events have been emitted!");
}).catch(console.error);
```

## API

All API are compatible with Node.js EventEmitter except `emitAsync`, `catch`, `once` and `prependOnceListener`.

The method **prependOnceListener** is not implemented (it will throw a not Implemented error if you try to call it).

```ts
declare class SafeEmitter {
    constructor();

    // Static Properties
    static defaultMaxListeners: number;

    // Methods
    getMaxListeners(): number;
    setMaxListeners(max: number): void;
    catch(errorListener: SafeEmitter.ErrorListener): this;
    eventNames(): SafeEmitter.EventName[];
    listenerCount(eventName: SafeEmitter.EventName): number;
    listeners(eventName: SafeEmitter.EventName): SafeEmitter.Listener[];
    rawListeners(eventName: SafeEmitter.EventName): SafeEmitter.Listener[];
    on(eventName: SafeEmitter.EventName, listener: SafeEmitter.Listener): void;
    off(eventName: SafeEmitter.EventName, listener: SafeEmitter.Listener): boolean;
    once(eventName: SafeEmitter.EventName, timeOut?: number): Promise<void>;
    addEventListener(eventName: SafeEmitter.EventName, listener: SafeEmitter.Listener): void;
    removeEventListener(eventName: SafeEmitter.EventName, listener: SafeEmitter.Listener): void;
    prependListener(eventName: SafeEmitter.EventName, listener: SafeEmitter.Listener): void;
    prependOnceListener(): void;
    removeAllListeners(eventName?: SafeEmitter.EventName): void;
    emit(eventName: SafeEmitter.EventName, ...data: any[]): void;
    emitAndWait(eventName: SafeEmitter.EventName, ...data: any[]): Promise<void>;
}

declare namespace SafeEmitter {
    export type ErrorListener = (error: Error, eventName: EventName, listener: Listener) => void;
    export type EventName = String | Symbol;
    export type Listener = (...any: any[]) => any;
}
```

### once(eventName: String|Symbol, timeOut?: number): Promise< void >;
The method `once` has been refactored to return a Promise when the event is catched. Optionally you can set a timeOut in milliseconds. The back listener will be cleaned-up automatically !

```js
async function main() {
    const evt = new SafeEmitter();
    setTimeout(() => {
        evt.emit("foo");
    }, 500);
    await evt.once("foo");
    console.log("foo has been triggered!");
}
main().catch(console.error);
```

> It's a design choice made for SlimIO core and addons containers.

### catch(errorListener: SafeEmitter.ErrorListener): this;
Add an error listener to the EventEmitter. The listener is able to catch all kind of errors (even for Asynchronous Function).

The error listener is has described by the TypeScript definition:
```ts
type ErrorListener = (error: Error, eventName: EventName, listener: Listener) => void;
```

Example:

```js
const evt = new SafeEmitter().catch((err) => {
    console.log(err.message);
});
evt.on("foo", () => {
    throw new Error("ooppss sync!");
});
evt.on("bar", async() => {
    throw new Error("ooppss async!");
});

evt.emit("foo");
evt.emit("bar");
```

### emitAndWait(eventName: String|Symbol, ...data: any[]): Promise< void >;
Emit an event and wait for all listeners to be completed (It's work for AsyncFunction too). Be sure to use this method wisely !

```js
async function main() {
    const evt = new SafeEmitter();
    // ... add many listeners (synchronous or event asynchronous).

    await evt.emitAndWait("foo");
    console.log("all foo listeners have been triggered and completed!");
}
main().catch(console.error);
```

## Dependencies
This project have no dependencies.

## License
MIT

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