@orkestrel/emitter

The foundational observable primitive: a typed, synchronous event emitter that a stateful entity owns as a #emitter field and exposes through a readonly emitter property, fanning each event out to its listeners in the current tick and isolating a throwing listener from its siblings.

Create an emitter with the createEmitter function, subscribe with on or once, and call emit to fan an event out to its listeners. Own one as a #emitter field where an entity of your own reports lifecycle transitions, and pass an error handler to receive a listener's throw. Part of the @orkestrel line.

Install

npm install @orkestrel/emitter

Requirements

• Node.js >= 22.12.0
• ESM and CommonJS builds

Usage

import { createEmitter } from '@orkestrel/emitter'

// The event map names each event and the argument tuple its listeners receive.
type ClockEventMap = {
	tick: readonly [at: number]
	done: readonly []
}

const clock = createEmitter<ClockEventMap>({
	on: { done: () => stop() }, // initial listeners wired at construction
	error: (error, event) => logger.warn(`listener for "${event}" threw`, error),
})

const onTick = (at: number) => render(at)
clock.on('tick', onTick) // `at` is typed `number` from the map
clock.emit('tick', Date.now()) // synchronous — every `tick` listener runs now
clock.once('done', () => cleanup()) // removes itself after its first call
clock.off('tick', onTick) // remove a listener by its original handler
clock.count() // live listener count, total or per-event
clock.clear() // drop listeners, total or per-event; emitter stays usable
clock.destroy() // teardown — drops every listener, flips `destroyed`

createEmitter(options) (or new Emitter(options)) returns an EmitterInterface<TMap>. The reserved on option wires initial listeners at construction; the optional error option receives any listener's throw as (error, event) so emit never has to rethrow — with no error handler, a throw is swallowed silently. emit never stops on a throw: every listener runs regardless, and every throw surfaces (not only the first).

Guide

For the full surface — the Emitter class, EmitterInterface, and the listener-isolation contract — see guides/emitter.md.

Package

Published as a single typed entry point per the exports field in package.json.

License

MIT © Orkestrel — see LICENSE.