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

EventEmitter mirror that restricts emitting/handling events other than specified in an interface.

Features

• Restricts emitting of the unknown event types.
• Infers emitted data types from the listener's call signature.

Motivation

The native EventEmitter class uses a generic string to describe what type of events can be emitted. In most cases you design a strict set of events that you expect your emitter to emit/listen to. This package helps you to type-annotate an emitter instance to produce type violations if an unknown event is emitted/listened to.

const emitter = new EventEmitter()

emitter.addListener('ping', (n: number) => {})

// The "pong" event is not expected, but will be emitted anyway.
// The data passed to the event is incompatible with the expected type.
emitter.emit('pong', 'not a number')

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

interface EventsMap {
  ping: (n: number) => void
}

const emitter = new StrictEventEmitter<EventsMap>()
emitter.addListener('ping', (n) => {
  // "n" argument type is inferred as "number'.
})

emitter.emit('ping', 10) // OK
emitter.emit('ping', 'wait, not a number') // TypeError
emitter.emit('unknown', 10) // TypeError

This library is a superset class of the native EventEmitter with only the type definition logic attached. There's no additional functionality present.

Getting started

Install

npm install strict-event-emitter

Use

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

// 1. Define an interface that describes your events.
// Set event names as the keys, and their listner functions as the values.
interface EventsMap {
  connect: (id: string) => void
  disconnect: (id: string) => void
}

// 2. Create a strict emitter and pass the previously defined "EventsMap"
// as its first generic argument.
const emitter = new StrictEventEmitter<EventsMap>()

// 3. Use the "emitter" the same way you'd use the regular "EventEmitter" instance.
emitter.addListner('connect', (id) => {})
emitter.emit('connect', 'abc-123')

License

MIT