# @uttori/event-dispatcher

> An event bus system for registering, unregistering and triggering events.

Latest version **3.0.2** (published 2024-01-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @uttori/event-dispatcher
pnpm add @uttori/event-dispatcher
yarn add @uttori/event-dispatcher
bun add @uttori/event-dispatcher
```

## Health

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

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2024-01-14 |
| First published | 2020-06-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 0 |
| Unpacked size | 36.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Matthew Callis |
| Maintainers | matthewcallis |
| Keywords | uttori, events, event bus |

## Links

- npm: https://www.npmjs.com/package/@uttori/event-dispatcher
- Repository: https://github.com/uttori/uttori-event-dispatcher
- Issues: https://github.com/uttori/uttori-event-dispatcher/issues
- npm.io page: https://npm.io/package/@uttori/event-dispatcher

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

- 3.0.2 (latest) — 2024-01-14
- 3.0.1 — 2024-01-14
- 3.0.0 — 2024-01-13
- 2.0.2 — 2022-12-17
- 2.0.1 — 2021-12-23
- 2.0.0 — 2021-01-22
- 1.0.4 — 2020-12-31
- 1.0.3 — 2020-11-16
- 1.0.2 — 2020-10-14
- 1.0.1 — 2020-10-14
- 1.0.0 — 2020-06-21

## README

[![view on npm](https://img.shields.io/npm/v/@uttori/event-dispatcher.svg)](https://www.npmjs.org/package/@uttori/event-dispatcher)
[![npm module downloads](https://img.shields.io/npm/dt/@uttori/event-dispatcher.svg)](https://www.npmjs.org/package/@uttori/event-dispatcher)
[![Build Status](https://travis-ci.com/uttori/uttori-event-dispatcher.svg?branch=master)](https://travis-ci.com/uttori/uttori-event-dispatcher)

[![Coverage Status](https://coveralls.io/repos/github/uttori/uttori-event-dispatcher/badge.svg?branch=master)](https://coveralls.io/github/uttori/uttori-event-dispatcher?branch=master)
[![Tree-Shaking Support](https://badgen.net/bundlephobia/tree-shaking/@uttori/event-dispatcher)](https://bundlephobia.com/result?p=@uttori/event-dispatcher)
[![Dependency Count](https://badgen.net/bundlephobia/dependency-count/@uttori/event-dispatcher)](https://bundlephobia.com/result?p=@uttori/event-dispatcher)
[![Minified + GZip](https://badgen.net/bundlephobia/minzip/@uttori/event-dispatcher)](https://bundlephobia.com/result?p=@uttori/event-dispatcher)
[![Minified](https://badgen.net/bundlephobia/min/@uttori/event-dispatcher)](https://bundlephobia.com/result?p=@uttori/event-dispatcher)

# Uttori Event Dispatcher

An event bus system for registering, unregistering and triggering events.

## Install

```bash
npm install --save @uttori/event-dispatcher
```

* * *

# Example

```js
const hooks = new EventDispatcher();
hooks.on('update', callback);
hooks.dispatch('update', { data }, this);
hooks.off('update', callback);
```

# API Reference

<a name="EventDispatcher"></a>

## EventDispatcher
An event bus system for registering, unregistering and triggering events.

**Kind**: global class  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| events | <code>Record.&lt;string, UttoriEvent&gt;</code> | The collection of events to listen for. |


* [EventDispatcher](#EventDispatcher)
    * [new EventDispatcher()](#new_EventDispatcher_new)
    * _instance_
        * [.events](#EventDispatcher+events) : <code>Record.&lt;string, UttoriEvent&gt;</code>
        * [.validate(label, data, [context])](#EventDispatcher+validate) ⇒ <code>Promise.&lt;boolean&gt;</code>
        * [.filter(label, data, [context])](#EventDispatcher+filter) ⇒ <code>Promise.&lt;T&gt;</code>
        * [.dispatch(label, data, [context])](#EventDispatcher+dispatch)
        * [.fetch(label, data, [context])](#EventDispatcher+fetch) ⇒ <code>Promise.&lt;Array.&lt;T&gt;&gt;</code>
        * [.on(label, callback)](#EventDispatcher+on)
        * [.once(label, callback)](#EventDispatcher+once)
        * [.off(label, callback)](#EventDispatcher+off)
    * _static_
        * [.check(label)](#EventDispatcher.check)

<a name="new_EventDispatcher_new"></a>

### new EventDispatcher()
Creates a new EventDispatcher instance.

**Example** *(new EventDispatcher())*  
```js
const bus = new EventDispatcher();
bus.on('update', callback);
bus.dispatch('update', { data }, { context });
bus.off('update', callback);
```
<a name="EventDispatcher+events"></a>

### eventDispatcher.events : <code>Record.&lt;string, UttoriEvent&gt;</code>
The collection of events to listen for.

**Kind**: instance property of [<code>EventDispatcher</code>](#EventDispatcher)  
<a name="EventDispatcher+validate"></a>

### eventDispatcher.validate(label, data, [context]) ⇒ <code>Promise.&lt;boolean&gt;</code>
Fires off an event with passed in data and context for a given label.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  
**Returns**: <code>Promise.&lt;boolean&gt;</code> - The conclusion of the spam checks, true being it is spam, false meaning it is clean.  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| data | <code>any</code> | Data to be used, updated, or modified by event callbacks. |
| [context] | <code>object</code> | Context to help with updating or modification of the data. |

**Example**  
```js
is_spam = await bus.validate('check-for-spam', { data }, this);
```
<a name="EventDispatcher+filter"></a>

### eventDispatcher.filter(label, data, [context]) ⇒ <code>Promise.&lt;T&gt;</code>
Fires off an event with passed in data and context for a given label.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  
**Returns**: <code>Promise.&lt;T&gt;</code> - The original input data, either modified or untouched.  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| data | <code>any</code> | Data to be used, updated, or modified by event callbacks. |
| [context] | <code>object</code> | Context to help with updating or modification of the data. |

**Example**  
```js
output = await bus.filter('loaded', { data }, this);
```
<a name="EventDispatcher+dispatch"></a>

### eventDispatcher.dispatch(label, data, [context])
Fires off an event with passed in data and context for a given label.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| data | <code>any</code> | Data to be used, updated, or modified by event callbacks. |
| [context] | <code>object</code> | Context to help with updating or modification of the data. |

**Example**  
```js
bus.dispatch('loaded', { data }, this);
```
<a name="EventDispatcher+fetch"></a>

### eventDispatcher.fetch(label, data, [context]) ⇒ <code>Promise.&lt;Array.&lt;T&gt;&gt;</code>
Fires off an event with passed in data and context for a given label and returns an array of the results.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  
**Returns**: <code>Promise.&lt;Array.&lt;T&gt;&gt;</code> - An array of the results.  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| data | <code>any</code> | Data to be used by event callbacks. |
| [context] | <code>object</code> | Context to help with updating or modification of the data. |

**Example**  
```js
popular = await bus.fetch('popular-documents', { limit: 10 }, this);
```
<a name="EventDispatcher+on"></a>

### eventDispatcher.on(label, callback)
Add a function to an event that will be called when the label is dispatched.
If no label is found, one is created.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| callback | <code>UttoriEventCallback.&lt;any, any&gt;</code> | Function to be called when the event is fired. |

**Example**  
```js
bus.on('loaded', callback);
```
<a name="EventDispatcher+once"></a>

### eventDispatcher.once(label, callback)
Add a function to an event that will be called only once when the label is dispatched.
Uses the `EventDispatcher.on` method with a function wrapped to call off on use.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| callback | <code>UttoriEventCallback.&lt;any, any&gt;</code> | Function to be called when the event is fired. |

**Example**  
```js
bus.once('one-time-process', callback);
```
<a name="EventDispatcher+off"></a>

### eventDispatcher.off(label, callback)
Remove a function from an event.

**Kind**: instance method of [<code>EventDispatcher</code>](#EventDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |
| callback | <code>UttoriEventCallback.&lt;any, any&gt;</code> | Function to be removed. |

**Example**  
```js
bus.off('loaded', callback);
```
<a name="EventDispatcher.check"></a>

### EventDispatcher.check(label)
Verifies an event label.

**Kind**: static method of [<code>EventDispatcher</code>](#EventDispatcher)  

| Param | Type | Description |
| --- | --- | --- |
| label | <code>string</code> | The human readable identifier of the event. |

**Example**  
```js
EventDispatcher.check('event'); // No Error
EventDispatcher.check(1); // Throws Error
```

* * *

## Tests

To run the test suite, first install the dependencies, then run `npm test`:

```bash
npm install
npm test
DEBUG=Uttori* npm test
```

## Contributors

* [Matthew Callis](https://github.com/MatthewCallis)
* [You](https://github.com/YOU)

## License

* [MIT](LICENSE)

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