https://github.com/open-draft/strict-event-emitter
Type-safe EventEmitter for browser and Node.js.
https://github.com/open-draft/strict-event-emitter
emitter events typed
Last synced: 3 months ago
JSON representation
Type-safe EventEmitter for browser and Node.js.
- Host: GitHub
- URL: https://github.com/open-draft/strict-event-emitter
- Owner: open-draft
- Created: 2020-12-17T11:49:25.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-06T09:37:48.000Z (11 months ago)
- Last Synced: 2024-10-11T23:05:29.577Z (8 months ago)
- Topics: emitter, events, typed
- Language: TypeScript
- Homepage: https://npm.im/strict-event-emitter
- Size: 237 KB
- Stars: 60
- Watchers: 3
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Strict Event Emitter
A type-safe implementation of `EventEmitter` for browser and Node.js.
## Motivation
Despite event emitters potentially accepting any runtime value, defining a strict event contract is crucial when developing complex event-driven architectures. Unfortunately, the native type definitions for Node's `EventEmitter` annotate event names as `string`, which forbids any stricter type validation.
```js
// index.js
const emitter = new EventEmitter()
// Let's say our application expects a "ping"
// event with the number payload.
emitter.on('ping', (n: number) => {})
// We can, however, emit a different event by mistake.
emitter.emit('pong', 1)
// Or even the correct event with the wrong data.
emitter.emit('ping', 'wait, not a number')
```
The purpose of this library is to provide an `EventEmitter` instance that can accept a generic describing the expected events contract.
```ts
import { Emitter } from 'strict-event-emitter'
// Define a strict events contract where keys
// represent event names and values represent
// the list of arguments expected in ".emit()".
type Events = {
ping: [number]
}
const emitter = new Emitter()
emitter.addListener('ping', (n) => {
// "n" argument type is inferred as "number'.
})
emitter.emit('ping', 10) // OK
emitter.emit('unknown', 10) // TypeError (invalid event name)
emitter.emit('ping', 'wait, not a number') // TypeError (invalid data)
```
This library is also a custom `EventEmitter` implementation, which makes it compatible with other environments, like browsers or React Native.
## Getting started
### Install
```bash
npm install strict-event-emitter
```
### Use
```ts
import { Emitter } from 'strict-event-emitter'
// 1. Define a type that describes your events.
// Set event names as the keys, and their expected payloads as values.
type Events = {
connect: [id: string]
disconnect: [id: string]
}
// 2. Create a strict emitter and pass the previously defined "Events"
// as its first generic argument.
const emitter = new Emitter()
// 3. Use the "emitter" the same way you'd use the regular "EventEmitter" instance.
emitter.addListener('connect', (id) => {})
emitter.emit('connect', 'abc-123')
```
## License
MIT