# @nichoth/events

> Event emitter and helpers

Latest version **3.2.0** (published 2024-02-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nichoth/events
pnpm add @nichoth/events
yarn add @nichoth/events
bun add @nichoth/events
```

## 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.2.0 |
| Published | 2024-02-06 |
| First published | 2017-12-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 242.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | nichoth |
| Maintainers | nichoth |

## Links

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

## Recent versions

- 3.2.0 (latest) — 2024-02-06
- 3.1.9 — 2023-11-14
- 3.1.8 — 2023-09-26
- 3.1.7 — 2023-09-20
- 3.1.6 — 2023-09-14
- 3.1.5 — 2023-09-14
- 3.1.4 — 2023-09-14
- 3.1.3 — 2023-09-14
- 3.1.2 — 2023-09-14
- 3.1.1 — 2023-09-14
- 3.1.0 — 2023-09-13
- 3.0.9 — 2023-09-13
- 3.0.8 — 2023-09-13
- 3.0.7 — 2023-09-13
- 3.0.6 — 2023-09-13
- … 37 more at https://npm.io/package/@nichoth/events/versions

## README

# events
![tests](https://github.com/nichoth/events/actions/workflows/nodejs.yml/badge.svg)
[![Socket Badge](https://socket.dev/api/badge/npm/package/@nichoth/events)](https://socket.dev/npm/package/@nichoth/events)
[![module](https://img.shields.io/badge/module-ESM%2FCJS-blue)](README.md)
[![types](https://img.shields.io/npm/types/@nichoth/events)](README.md)
[![license](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)

An extra minimal event emitter

__featuring__
* 0 production dependencies
* CJS and ESM versions
* 637 bytes minified and gzipped

## install
```bash
npm i -S @nichoth/events
```

## example
You can pass in an array of valid event names. If you subscribe to or emit an
event not in the list, this will throw a runtime error. Also, you can create
a typed event bus because `Bus` takes a type argument.

### create an event bus, with types
```ts
import { Bus } from '@nichoth/events'

const eventTree = Bus.createEvents({
    a: ['b', 'c', 'd'],
    b: {
        _: ['e', 'f'],
        c: ['1', '2', '3']
    }
})
const events = Bus.flatten(eventTree)

const bus = new Bus<Array<typeof events[number]>>(events)

bus.on(eventTree.a)
```


### create an event bus
```js
import { Bus } from '@nichoth/events'
const bus = new Bus()

// you can pass in a list of event names that are allowed.
// If you subscribe or emit something not in the list, it will throw an error.
const bus2 = new Bus(['valid', 'events'])
```

### create namespaced events
Take an object of arrays of strings, and return a new object where the leaf nodes are strings containing the full object path.

```js
import { Bus } from '@nichoth/events'

Bus.createEvents({
    a: {
        _: [1, 2, 3]
        b: {
            c: [1,2,3]
        }
    }
})

// => {
//   a: {
//     1: 'a.1',
//     2: 'a.2',
//     3: 'a.3
//     b: {
//       c: {
//         1: 'a.b.c.1',
//         2: 'a.b.c.2',
//         3: 'a.b.c.3'
//       }
//     }
//   },
// }
//
```

### Bus.flatten
Get an array of the leaf node values of an object of any shape, for example the return value of `Bus.createEvents`.

It's recommended to use the `.flatten` static function to get the event name values after calling `.createEvents`. Or, if you pass in anything that is not an array, the constructor will call `.flatten` on it.
```js
import { Bus } from '@nichoth/events'

const events = Bus.createEvents({
    a: {
        _: [1, 2, 3]
        b: {
            c: [1,2,3]
        }
    }
})

// pass in a list of valid event names
const bus = new Bus(Bus.flatten(events))
// is the same as
const bust2 = new Bus(events)
```

### subscribe
```js
import { Bus } from '@nichoth/events'
const bus = new Bus()

const off = bus.on(events.a['1'], (data) => {
    t.equal(data, 'test data', 'first listener gets the event')
    off()  // unsubscribe
})
```

### emit events
```js
import { Bus } from '@nichoth/events'
const bus = new Bus()

bus.emit(events.a['1'], 'test data')
```

You can partially apply the the `.emit` function
```js
const emitFoo = bus.emit('foo')

bus.on('foo', data => {
    console.log(data)
    // => { example: 'data' }
})

emitFoo({ example: 'data' })

```

## develop
Install dev deps with `--legacy-peer-deps`. 

```bash
npm i --legacy--peer-deps
```

## test
```bash
npm test
```

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