API Reference

EventBus is the default-exported class; eventBus is the named-exported global singleton.

Class: EventBus

import EventBus from "@ai-zen/event-bus";

new EventBus()

Creates an event bus instance, internally maintaining subscribers.

const bus = new EventBus();

bus.subscribers

• Type: Map<string, Map<EventHandler, ErrorHandler>>
• Description: A public property storing event subscribers. The key is the event name and the value is a mapping of handler -> errorHandler. Generally you don't need to access it directly.

bus.subscribers.has("greet"); // false

bus.on(name, handler, error?)

• Type: on(name: string, handler: EventHandler, error?: ErrorHandler): Disposable
• Description: Subscribes to an event. Returns a Disposable; calling its dispose() unsubscribes.
• Arguments:
  • name: the event name.
  • handler: the event handler function.
  • error (optional): the error handler function.
• Returns: Disposable.
• Example:

const disposable = bus.on("greet", (name) => {
  console.log(name);
});
disposable.dispose();

bus.off(name, handler)

• Type: off(name: string, handler: EventHandler): boolean
• Description: Unsubscribes the specified handler from the specified event. Returns true on success and false otherwise.
• Example:

const ok = bus.off("greet", handler);

bus.offAll(name)

• Type: offAll(name: string): void
• Description: Clears all handlers and error handlers of the specified event.
• Example:

bus.offAll("greet");

bus.destroy()

• Type: destroy(): void
• Description: Clears all subscriptions and destroys the event bus.
• Example:

bus.destroy();

bus.emit(name, ...args)

• Type: emit(name: string, ...args: any[]): void
• Description: Emits an event, passing args to all subscribed handlers as-is. Only invokes handlers and does not call error handlers.
• Example:

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

bus.error(name, reason)

• Type: error(name: string, reason: any): void
• Description: Dispatches an error to the error handler of the specified event. Only invokes the error handler passed at subscription time.
• Example:

bus.error("load", new Error("boom"));

bus.gather<T>(name, ...args)

• Type: gather<T>(name: string, ...args: any[]): T[]
• Description: Invokes all handlers of the specified event and returns an array of their return results.
• Example:

const results = bus.gather<number>("calc");

bus.gatherMap<T>(name, ...args)

• Type: gatherMap<T>(name: string, ...args: any[]): Map<EventHandler, T>
• Description: Invokes all handlers of the specified event and returns a Map keyed by handler with the return result as the value.
• Example:

const m = bus.gatherMap<number>("calc");

bus.once(name, handler, error?)

• Type: once(name: string, handler: EventHandler, error?: ErrorHandler): Disposable
• Description: Subscribes to an event and automatically unsubscribes after the first time it fires. Returns a Disposable.
• Example:

bus.once("reply", (value) => console.log(value));
bus.emit("reply", "done"); // fires only once

bus.promise(name)

• Type: promise(name: string): Promise<any>
• Description: Returns a Promise that resolves when the event fires; if error is called on that event, the Promise rejects.
• Example:

const result = await bus.promise("reply");
bus.emit("reply", "done");

bus.subscribe / bus.unsubscribe / bus.publish

• Description: These are getter properties returning references to the on / off / emit methods respectively, used as aliases.

bus.subscribe("greet", handler);   // equivalent to bus.on
bus.unsubscribe("greet", handler); // equivalent to bus.off
bus.publish("greet", "AI-Zen");    // equivalent to bus.emit

Named exports

eventBus

A global singleton EventBus instance that can share the same bus across multiple places.

import { eventBus } from "@ai-zen/event-bus";
eventBus.on("greet", handler);

Type definitions

type EventHandler = (...args: any[]) => any; // event handler function
type ErrorHandler = (reason?: any) => void;  // error handler function
type Disposable = { dispose: () => void };   // disposable object

• EventHandler: the event handler function, accepting arbitrary arguments and returning arbitrary results.
• ErrorHandler: the error handler function, accepting an optional reason.
• Disposable: an object with a dispose() method, used to unsubscribe.

Notes

• The type definitions are located in the build artifact dist/EventBus.d.ts.
• The source code is in src/EventBus.ts within the repository.
• For questions about certain behaviors (such as once auto-unsubscription, promise reject trigger conditions, and subscribe / unsubscribe / publish being getter aliases), refer to the implementation in src/EventBus.ts.