strict-event-emitter

What is strict-event-emitter?

The 'strict-event-emitter' npm package is a TypeScript-first event emitter library that provides strong typing for event names and payloads. It ensures type safety and helps avoid common mistakes when working with events in TypeScript projects.

What are strict-event-emitter's main functionalities?

Basic Event Emission

This feature allows you to emit and listen to events with strong typing. The event name and payload are type-checked, ensuring that only valid events and payloads are used.

const { StrictEventEmitter } = require('strict-event-emitter');

interface Events {
  greet: string;
}

const emitter = new StrictEventEmitter<Events>();
emitter.on('greet', (message) => {
  console.log(message);
});
emitter.emit('greet', 'Hello, world!');

Typed Event Listeners

This feature allows you to define multiple events with different payload types. The event listeners are type-checked to ensure they handle the correct payload structure.

const { StrictEventEmitter } = require('strict-event-emitter');

interface Events {
  greet: string;
  farewell: { message: string; code: number };
}

const emitter = new StrictEventEmitter<Events>();
emitter.on('farewell', (data) => {
  console.log(data.message, data.code);
});
emitter.emit('farewell', { message: 'Goodbye!', code: 200 });

Removing Event Listeners

This feature allows you to remove specific event listeners, ensuring that they no longer respond to emitted events. This is useful for cleaning up resources and avoiding memory leaks.

const { StrictEventEmitter } = require('strict-event-emitter');

interface Events {
  greet: string;
}

const emitter = new StrictEventEmitter<Events>();
const greetListener = (message: string) => {
  console.log(message);
};
emitter.on('greet', greetListener);
emitter.off('greet', greetListener);
emitter.emit('greet', 'Hello, world!'); // No output, listener removed

Other packages similar to strict-event-emitter

eventemitter3

EventEmitter3 is a high-performance event emitter for Node.js and the browser. It is similar to strict-event-emitter but does not provide TypeScript-first strong typing for event names and payloads. It is more focused on performance and simplicity.

mitt

Mitt is a tiny (~200 bytes) functional event emitter. It is similar to strict-event-emitter in that it provides a simple API for emitting and listening to events, but it lacks the strong typing and TypeScript-first approach of strict-event-emitter.

node-event-emitter

Node Event Emitter is a lightweight event emitter library for Node.js. It provides basic event emission and listener functionality similar to strict-event-emitter but does not offer the same level of type safety and TypeScript integration.

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.

// 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.

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<Events>()
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

npm install strict-event-emitter

Use

import { Emitter } from 'strict-event-emitter'

// 1. Define an interface that describes your events.
// Set event names as the keys, and their expected payloads as values.
interface 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<Events>()

// 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