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.

1// index.js
2const emitter = new EventEmitter()
3
4// Let's say our application expects a "ping"
5// event with the number payload.
6emitter.on('ping', (n: number) => {})
7
8// We can, however, emit a different event by mistake.
9emitter.emit('pong', 1)
10
11// Or even the correct event with the wrong data.
12emitter.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.

1import { Emitter } from 'strict-event-emitter'
2
3// Define a strict events contract where keys
4// represent event names and values represent
5// the list of arguments expected in ".emit()".
6type Events = {
7  ping: [number]
8}
9
10const emitter = new Emitter<Events>()
11emitter.addListener('ping', (n) => {
12  // "n" argument type is inferred as "number'.
13})
14
15emitter.emit('ping', 10) // OK
16emitter.emit('unknown', 10) // TypeError (invalid event name)
17emitter.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

1npm install strict-event-emitter

Use

1import { Emitter } from 'strict-event-emitter'
2
3// 1. Define an interface that describes your events.
4// Set event names as the keys, and their expected payloads as values.
5interface Events {
6  connect: [id: string]
7  disconnect: [id: string]
8}
9
10// 2. Create a strict emitter and pass the previously defined "Events"
11// as its first generic argument.
12const emitter = new Emitter<Events>()
13
14// 3. Use the "emitter" the same way you'd use the regular "EventEmitter" instance.
15emitter.addListener('connect', (id) => {})
16emitter.emit('connect', 'abc-123')

License

MIT