aieventjs
v0.6.0
Published
Small, strict, typed event emitter — on() returns an unsubscribe function, once is built-in, AbortSignal is first-class, dispose() is idempotent, wildcard '*' handlers preserved. Mitt-shaped API; ai*js conventions everywhere else.
Maintainers
Readme
aieventjs
Small, strict, typed event emitter with ai*js lifecycle conventions: on() returns unsubscribe, once is built in, AbortSignal is first-class, wildcard handlers are supported, and dispose() is idempotent.
Status: 0.6.0 - stable 1.0-track surface. The root entry is the public API.
Install
pnpm add aieventjsimport { createEmitter } from "aieventjs";Quick Start
type Events = {
"score/change": { value: number };
"scene/end": void;
};
const events = createEmitter<Events>();
const off = events.on("score/change", ({ value }) => {
console.log(value);
});
events.on("*", (type, payload) => console.log(type, payload), { sampleRate: 0.1 });
events.emit("score/change", { value: 10 });
off();
events.dispose();Core API
createEmitter<Events>(options?)creates a typed emitter.on(type, handler, options?)subscribes and returns an unsubscribe function.on("*", wildcard, options?)subscribes to every event after type-matched handlers.once(type, handler)is shorthand foron(type, handler, { once: true }), for typed events and"*"alike.off(type, handler?),clear(), anddispose()remove handlers at different scopes.emit(type, payload)dispatches synchronously over a snapshot of handlers.- Options:
signal,once,captureErrorsfor typed,sampleRatefor wildcard,throttleMsfor typed and wildcard.
Sharp Edges
- Default error policy is mitt-like: the first throwing handler aborts dispatch. Use
captureHandlerErrorsor per-handlercaptureErrorsto swallow/report and continue; report callbacks always get the event name as a string. - Wildcard handlers receive
(type, payload), not just payload. once("*", handler)is equivalent toon("*", handler, { once: true }).- A nested
emit()from a handler runs to completion before the outer dispatch resumes; the outer dispatch skips handlers removed meanwhile (unsubscribe,off,clear,dispose, abort), andoncehandlers go inert before their first call. throttleMsusesperformance.now()(monotonic); system-clock corrections do not affect throttle windows.sampleRateis wildcard-only and usesMath.random()per dispatch.- Misuse throws
EmitterErrorfromon()/once()before anything is registered: a handler that is not a function, asignalthat is not anAbortSignal, or an invalid option. dispose()is permanent; after it,on/once/emit/off/clearall throwEmitterDisposedError. Onlydispose()itself and previously returned unsubscribe functions are safe no-ops post-dispose.
AI Context
- Short index:
llms.txt - Full generated context:
llms-full.txt - Stability contract:
STABILITY.md - Current review backlog:
REVIEW.md - Release history:
CHANGELOG.md
License
MIT
