Events bus

The full API surface of the singleton events instance.

Subscribe

events.subscribe(event: string, callback: Function): EventSubscription
events.on(event, callback): EventSubscription            // alias
events.addEventListener(event, callback): EventSubscription  // alias

Returns:

type EventSubscription = {
  callback: Function;
  event: string;
  dispatch(...args: any[]): any;        // call the callback directly
  unsubscribe(): void;
};

Hold the returned subscription and call unsubscribe() when you no longer want the callback.

Trigger

events.trigger(event: string, ...args: any[]): any
events.emit(event, ...args): any                   // alias

Behavior:

• Calls every callback registered for event in subscription order.
• If a callback returns false, the chain stops and trigger returns false. Use this for “veto” patterns.
• Otherwise the last non-undefined return value is returned.

events.subscribe("save.before", (data) => {
  if (!isValid(data)) return false;     // vetoes the save
});

const ok = events.trigger("save.before", payload);
if (ok === false) return;

Trigger all (no short-circuit)

events.triggerAll(event: string, ...args: any[]): EventTriggerResponse

type EventTriggerResponse = {
  event: string;
  length: number;       // number of callbacks invoked
  results: any[];       // all non-undefined return values
};

Use when you want every handler to run regardless of return values — analytics, multi-listener notifications, aggregations.

Async variants

events.triggerAsync(event, ...args): Promise<any>
events.triggerAllAsync(event, ...args): Promise<EventTriggerResponse>

Callbacks are awaited in subscription order, not in parallel. If you need parallel dispatch, do it yourself:

await Promise.all(
  events.subscriptions("flush").map(s => s.dispatch(data)),
);

triggerAsync also honors the return false short-circuit (after awaiting the offending callback).

Inspect / unsubscribe

events.subscriptions(event: string): EventSubscription[]
events.unsubscribe(event?: string): this    // detach one event or all
events.off(event?: string): this            // alias

Calling unsubscribe() with no argument wipes the whole bus. Useful in test teardown.

Direct dispatch (skip the bus)

The returned EventSubscription.dispatch(...args) invokes the callback directly without going through the trigger pipeline. Useful when you want to fire one specific listener without notifying the rest.

const sub = events.subscribe("ping", (n) => n * 2);
sub.dispatch(21);   // 42