# theatre-events

> A full implementation of a standard event dispatcher for javascript

Latest version **1.1.9** (published 2017-06-21) · WTFPL license · 0 weekly downloads

## Install

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

## 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.9 |
| Published | 2017-06-21 |
| First published | 2017-05-27 |
| Weekly downloads | 0 |
| License | WTFPL |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | David Jegat |
| Maintainers | djeg |
| Keywords | Event, Dispatcher, ECM6, Promise, Future, Listener |

## Links

- npm: https://www.npmjs.com/package/theatre-events
- npm.io page: https://npm.io/package/theatre-events

## 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.9 (latest) — 2017-06-21
- 1.1.8 — 2017-06-21
- 1.1.7 — 2017-06-21
- 1.0.7 — 2017-06-02
- 1.0.6 — 2017-05-27
- 1.0.4 — 2017-05-27
- 1.0.2 — 2017-05-27
- 1.0.1 — 2017-05-27
- 1.0.0 — 2017-05-27

## README

Theatre Events
==============

[![Circle CI](https://circleci.com/gh/theatre-components/theatre-events/tree/master.svg?style=shield)](https://circleci.com/gh/theatre-components/theatre-events/tree/master)
[![npm version](https://badge.fury.io/js/theatre-events.svg)](https://badge.fury.io/js/theatre-events)
[![dependencies](https://david-dm.org/theatre-components/theatre-events.svg)](https://david-dm.org/theatre-components/theatre-events)
[![WTFPL Licence](http://www.wtfpl.net/wp-content/uploads/2012/12/wtfpl-badge-2.png)](http://www.wtfpl.net/about/)


This library is a part of the **Theatre** module. You can use it ase is or with a complete **Theatre** installation.

## About

**Theatre Events** is a short but complete implementation of a standard `ÈventDispatcher`, `EventEmitter` and `EventBroadcaster`. It can be use as a standalone module in any project to start helping you building robust events system.

## Installation

```
npm install theatre-events --save
```

## Quick Start

This module brings 3 usefull and flexible components: the `EventDispatcher`, the `EventBroadcaster` and the `EventEmitter`. Both cames with a **synchronous** and **asynchronous** implementation.

### EventDispatcher: Synchronous

```javascript
import {SynchronousEventDispatcher} from 'theatre-events';

let dispatcher = new SynchronousEventDispatcher();

// Register also supports symbols
dispatcher.addEventListener('My Event', (myPayload) => {
    console.log(myPayload);
});

// This command will log "{name: 'test'}"
dispatcher.dispatch('My Event', {name: 'test'});
```

### EventDispatcher: Asynchronous

```javascript
import {AsynchronousEventDispatcher} from 'theatre/events';

let dispatcher = new AsynchronousEventDispatcher();

dispatcher.addEventListener('send email', (emailPayload) => {
    sendMail(emailPayload);
});

// The dispatch method will not be blocking, so you can send your email
// and do other stuff during the mail is processed
dispatcher.dispatch('send email', {
    subject: 'Do you heard about theatre components ?',
}).then(d => console.log('The email has been sent')).catch(console.error);
```

### Event Emitter: Synchronous

It is quite the same API as an `EventDispatcher`.

```javascript
import {SynchronousEventEmitter} from 'theatre-events';

// You can pass an instance of a `SynchronousEventDispatcher`. If you do so,
// the event emitter will be a simple wrap of the dispatcher.
let emitter = new SynchronousEventEmitter();

emitter.on('test', (payload) => {
    payload.name = 'test';
});

let data = {};
emitter.emit('test', data);

console.log(data.name);
```

### Event Emitter: Asynchronous

```javascript
import {AsynchronousEventEmitter} from 'theatre-events';

let emitter = new AsynchronousEventEmitter();

emitter.on('test', (payload) => {
    payload.name = 'test';
});

let data = {};
emitter.emit('test', data).then(() => {
    console.log(data.name);
}).catch(console.error);
```

### Event Broadcaster: Synchronous

Event broadcaster is very similar to an event dispatcher but it don't use
named event.

```javascript
import {SynchronousEventBroadcaster} from 'theatre-events';

let broadcaster = new SynchronousEventBroadcaster();

broadcaster.subscribe((data) => {
    data.name ='test';
});

let data = {};
broadcaster.broadcast(data);

console.log(data.name);
```

### Event Broadcaster: Asynchronous

```javascript
import {AsynchronousEventBroadcaster} from 'theatre-events';

let broadcaster = new AsynchronousEventBroadcaster();

broadcaster.subscribe((data) => {
    data.name ='test';
});

let data = {};
broadcaster.broadcast(data).then(() => {
    console.log(data.name);
}).catch(console.error);
```

### Event listener priority

You can control the execution priority of your listeners:

```javascript
import {SynchronousEventDispatcher, LOW_PRIORITY, HIGH_PRIORITY} from 'theatre-events';

let dispatcher = new SynchronousEventDispatcher();

function sendLast() {
    console.log('Must be the last event');
}

function sendFirst() {
    console.log('Must be the first');
}

// You can also assign an integer. The highest the integer is
// the latest it will be triggered. By default you can use:
// LOW_PRIORITY = 255
// NORMAL_PRIORITY = 0
// HIGH_PRIORITY = -255
sendLast.priority = LOW_PRIORITY;
sendFirst.priority = HIGH_PRIORITY;

dispatcher.addEventListener('send message', sendLast);
dispatcher.addEventListener('send message', sendFirst);

dispatcher.dispatch('test');
```

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