EventBus Event Management Library

EventBus is a TypeScript event management library used to decouple event delivery between modules. It is backed by the native Map to store subscribers (name -> Map<handler, errorHandler>), providing subscribe/unsubscribe, one-time subscription, Promise-ification, result aggregation and error dispatch capabilities.

Core Features

• Subscribe / Unsubscribe: on / off / offAll / destroy; on / once return a Disposable, making lifecycle management easy.
• One-time subscription: once automatically unsubscribes after the event fires once.
• Promise-ification: promise returns a Promise that resolves when the event fires and rejects on error.
• Aggregate results: gather / gatherMap retrieve the return results of all handlers.
• Error handling: the error method plus ErrorHandler dispatch errors to the corresponding event's error handler.
• Aliases: subscribe / unsubscribe / publish are equivalent to on / off / emit respectively.
• Zero dependency: relies only on the built-in Map; no third-party runtime dependencies.
• Global singleton: the named export eventBus can share the same bus across multiple places.

Requirements

• Node.js runtime (supports ESM and the native Map).
• TypeScript or a JS environment with static type support (built-in .d.ts type declarations).
• The package is published as an ESM module ("type": "module" in package.json).

Installation

npm install @ai-zen/event-bus
# or
pnpm add @ai-zen/event-bus

Quick Example

import EventBus, { eventBus } from "@ai-zen/event-bus";

const bus = new EventBus();

bus.on("greet", (name: string) => {
  console.log(`Hello, ${name}!`);
});

bus.emit("greet", "AI-Zen"); // Hello, AI-Zen!

For more complete usage, see Getting Started and API Reference.

References

• Getting Started — installation, creating instances, subscribe/unsubscribe, and once/promise/gather and error handling examples.
• API Reference — full documentation of on, off, emit, once, promise, gather, gatherMap, error, etc.