# alcumus-local-events

> Hookable local event emitter

Latest version **1.1.33** (published 2020-07-16) · ISC license · 0 weekly downloads

## Install

```sh
npm install alcumus-local-events
pnpm add alcumus-local-events
yarn add alcumus-local-events
bun add alcumus-local-events
```

## 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.33 |
| Published | 2020-07-16 |
| First published | 2018-12-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Mike Talbot |
| Maintainers | adavies, andtrobs, blair.macneil, davecozens, itinfrastructure_alcumusgroup, jnaylor_alcumus, markgabb, michael.john.talbot |

## Links

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

## Dependencies (1)

- [alcumus-event-emitter](https://npm.io/package/alcumus-event-emitter.md) ^1.0.5

## Recent versions

- 1.1.33 (latest) — 2020-07-16
- 1.1.32 — 2020-07-16
- 1.1.31 — 2020-07-16
- 1.1.30 — 2020-07-16
- 1.2.29 — 2020-07-16
- 1.1.29 — 2020-07-16
- 1.1.28 — 2020-07-16
- 1.0.27 — 2020-01-31
- 1.0.26 — 2019-11-22
- 1.0.25 — 2019-08-08
- 1.0.24 — 2019-08-06
- 1.0.23 — 2019-08-06
- 1.0.22 — 2019-08-05
- 1.0.21 — 2019-08-05
- 1.0.20 — 2019-08-01
- … 18 more at https://npm.io/package/alcumus-local-events/versions

## README

# Local Events & Hookable Event Emitter

The local events module provides a project wide method of creating loosely coupled events that have the ability to provide hooks to override default behaviour or to apply additional processing before or after standard events.

The library provides a standard local-events emitter and an upgraded version of [eventemitter2](https://github.com/EventEmitter2/EventEmitter2) that can be used to create other hookable events.

## Hookable Events

All of the events fired have multiple steps that can be used to override or augment default behaviour.

Events are fired with additional elements prepended to allow for a variety of hooks.  The elements are divided by the standard delimiter, which is '.' as standard.  The order of events for 'EVENT' is `early.0.EVENT` - `early.9.EVENT`, `before.EVENT`, `pre.0.EVENT` - `pre.9.EVENT`, `EVENT`, `post.0.EVENT` - `post.9.EVENT`, `after.EVENT`, `late.0.EVENT` - `late.9.EVENT`

Each event processing function is passed a first parameter to indicate *context*, this has a `cancel` property and a `preventDefault()` method which causes the chain of events to be aborted.


```javascript
    let counter = 0
    events.on('test', function() {
        throw new Error("Should not be here")
    })
    events.on('pre.4.test', function() {
        counter++
    })
    events.on('before.test', function(context) {
        context.preventDefault()
        counter++
    })
    events.emit('test')
    expect(counter).to.equal(2)
```

You may also use the context object to pass other data between event invocations.

### Wildcard Events

The eventemitter2 implementation allows multipart events with wildcard support.  For example:

```javascript

    events.on('registerUser.*.start', function(context, param1, param2) {
        console.log("Generic user start")
    })
    
    events.on('before.registerUser.tfl.start', async function(context, param1, param2) {
        console.log("Hook tfl before Generic user start")
        if(param1 === 'admin') {
            if(!await callSomething(param2)) {
                context.preventDefault()
            }
        }
    })

    await events.emitAsync(`registerUser.${clientName}.start`, role, authToken)
```

### Asynchronous Events

eventemitter2 fully supports asynchronous events using `emitAsync`.

```javascript
    async function test() {
        let counter = 0
        events.on('early.1.test', function () {
            expect(counter++).to.equal(0)
        })
        events.on('before.test', function () {
            expect(counter++).to.equal(1)
        })
        events.on('pre.1.test', function () {
            expect(counter++).to.equal(2)
        })
        events.on('test', function () {
            expect(counter++).to.equal(3)
        })
        events.on('post.1.test', function () {
            expect(counter++).to.equal(4)
        })
        events.on('after.test', function () {
            expect(counter++).to.equal(5)
        })
        events.on('late.1.test', function () {
            expect(counter++).to.equal(6)
        })
        await events.emitAsync('test')
        expect(counter).to.equal(7)
    }
```
### Usage

```javascript
const HookedEvents = require('local-events/hooked-events')
const myEmitter = new HookedEvents({wildcard: true, delimiter: '::'})
```

## Local Events

The local-events object is a configured hooked eventemitter2 instance with wildcards supported and the delimiter set to be '.' (it also supports up to 200 listeners per event before warning).

local-events can therefore be used across an entire project to react to and raise events.

### Usage

`const events = require('local-events')`

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