ee-ts

Type-safe event emitters (for TypeScript)

Features

• strict event names
• type-checking for emitted data
• flexible listeners() generator method
• add/remove listeners during emit
• great for sub-classing
• one-time listeners
• default handlers

Example

import { EventEmitter as EE } from 'ee-ts'

type User = { name: string }

// All possible events must be explicitly defined as methods here.
// The return type can be non-void because the `emit` method returns the last non-void value.
// The return type can never be required, because `void` is implicitly added to every event.
interface Events {
  login(user: User): void
  logout(): string
}

// Make your subclass generic to let users add their own events.
class App<T = {}> extends EE<T & Events> {
  // You _cannot_ emit user-added events from here, though.
  someMethod(this: App) {
    this.emit('logout')
  }
}

type UserEvents = { test(): void }
let app = new App<UserEvents>()

// Emit your custom event.
app.emit('test')

// The type of `user` is inferred.
app.on('login', user => {
  console.log(user.name) // user.name is string
})

// Invalid argument types are caught.
app.one('login', (invalid: boolean) => {}) // [ts] Type 'User' is not assignable to type 'boolean'.

// Invalid return values are caught.
app.one('logout', () => true) // [ts] Type 'boolean' is not assignable to type 'string | void'.

// Unknown event names are caught.
app.emit('invalid') // [ts] Argument of type '"invalid"' is not assignable to parameter of type '"login" | "logout"'.

Subclassing

This library was designed with subclassing in mind.

• The internal cache is non-enumerable
• Few public methods: on, one, off, emit, listeners
• Override _onEventHandled(key: string) to know when an event has at least one listener
• Override _onEventUnhandled(key: string) to know when an event has no listeners

Disposables

When you pass an array as the last argument of on, one, or EE.unhandle, an object is pushed onto it. This object has a dispose(): void method, which you should call to remove the associated listener from its event.

This is a useful way of grouping listeners together.

import { EventEmitter, Disposable } from 'ee-ts'

const ee = new EventEmitter<{ foo(): void }>()

const disposables: Disposable[] = []

let count = 0
const fn = ee.on('foo', () => count++, disposables)

assert(disposables.length == 1)

disposables[0].dispose()
ee.emit('foo')

assert(count == 0)

API Reference

The type signatures below are not 100% accurate. They're here to give you a general idea of the API. Find the real type signatures in the source code or VS Code.

on(key: string, fn: Function, disposables?: Disposable[]): Function

Add a listener to the given event key.

Use the one method to add a one-time listener.

Returns: the fn argument

on(map: { [key: string]: Function }, disposables?: Disposable[]): this

Add every listener value to its associated event key.

Use the one method to add one-time listeners.

off(key: string, fn?: Function): this

Remove a listener for the given event key.

Omit the fn argument to remove all listeners for the given event key.

Call off('*') to remove all listeners for every event key.

emit(key: string, ...args: any[]): any

Emit an event to listeners associated with the given event key.

You can safely add/remove listeners from inside a listener.

Returns: last non-void value returned by a listener

listeners(key: string): IterableIterator<Function>

Create a generator of the listeners for the given event key.

Use this with for..of or spread it into an array. Read more about generators here.

Static methods

unhandle(ee: EventEmitter, key: string, fn: Function, disposables?: Disposable[]): Function

Set the default handler for an event key.

The default handler is called when no other listeners exist for the same event key.

keys(ee: EventEmitter): string[]

Get an array of event keys that have listeners.

count(ee: EventEmitter, key: string): number

Get the number of listeners an event has.

has(ee: EventEmitter, key: string): boolean

Check if an event has listeners.

Returns: true when the given event key has >= 1 listener.