Interface MessageBus

ReadonlyisDisposed

addListener

• addListener(listener: MessageListener): void

  Adds a message listener that will be notified of every message published on this message bus, regardless of topic.

  Listeners are invoked before any topic-specific subscribers. This allows observing messages even if no subscriber exists or if a subscriber throws an unrecoverable error.

  Parameters

  • listener: MessageListener

    A callback invoked with the topic and message data.

  Returns void

createChildBus

• createChildBus(options?: Partial<ChildMessageBusOptions>): MessageBus

  Creates a new child bus linked to this one for hierarchical broadcasting.

  Messages with children broadcast direction will be propagated to it.

  Parameters

  • Optionaloptions: Partial<ChildMessageBusOptions>

  Returns MessageBus

dispose

• dispose(): void

  Disposes the message bus, all its child buses, and all active subscriptions.

  After disposal, neither this bus nor any child buses can be used for publishing or subscribing.

  Returns void

publish

• publish(topic: Topic<void>): void

  Publishes a new message without any associated data to the specified topic.

  Parameters

  • topic: Topic<void>

    The topic to publish the message to.

  Returns void

  Example

  messageBus.publish(PingTopic);
  Copy

• publish<T>(topic: Topic<T>, data: T): void

  Publishes a new message with associated data to the specified topic.

  Type Parameters

  • T

  Parameters

  • topic: Topic<T>

    The topic to publish the message to.
  • data: T

    The data payload to send with the message.

  Returns void

  Example

  messageBus.publish(CommandTopic, "shutdown");
  Copy

removeListener

• removeListener(listener: MessageListener): void

  Removes a previously added message listener.

  Parameters

  • listener: MessageListener

    The listener to remove.

  Returns void

subscribe

• subscribe<T>(topic: Topic<T>): LazyAsyncSubscription<T>

  Creates a lazily-initialized subscription to the specified topic that is also an AsyncIterableIterator.

  This allows consuming published messages using the for await ... of syntax. If an async iteration completes or ends early (e.g., via break, return, or an error), the subscription is automatically disposed.

  The subscription is created lazily: the first call to next() or single() triggers the underlying registration. If the consumer never starts an iteration or never awaits a message, no subscription is created.

  Type Parameters

  • T

  Parameters

  • topic: Topic<T>

    The topic to subscribe to.

  Returns LazyAsyncSubscription<T>

  Example

  const subscription = messageBus.subscribe(CommandTopic);
  
  for await (const command of subscription) {
    switch (command) {
      case "shutdown":
        // ...
        break;
      case "restart":
        // ...
        break;
    }
  }
  Copy

• subscribe<T extends [any, ...any[]]>(
      topics: Topics<T>,
  ): LazyAsyncSubscription<T[number]>

  Type Parameters

  • T extends [any, ...any[]]

  Parameters

  • topics: Topics<T>

  Returns LazyAsyncSubscription<T[number]>

• subscribe<T>(topic: Topic<T>, handler: MessageHandler<T>): Subscription

  Subscribes to the specified topic with a callback.

  The subscription is established immediately, and you can call Subscription.dispose to unsubscribe.

  Type Parameters

  • T

  Parameters

  • topic: Topic<T>

    The topic to subscribe to.
  • handler: MessageHandler<T>

    A callback invoked on each topic message.

  Returns Subscription

  Example

  const subscription = messageBus.subscribe(CommandTopic, (command) => {
    switch (command) {
      case "shutdown":
        // ...
        break;
      case "restart":
        // ...
        break;
    }
  });
  
  // Later
  subscription.dispose();
  Copy

• subscribe<T extends [any, ...any[]]>(
      topics: Topics<T>,
      handler: MessageHandler<T[number]>,
  ): Subscription

  Type Parameters

  • T extends [any, ...any[]]

  Parameters

  • topics: Topics<T>
  • handler: MessageHandler<T[number]>

  Returns Subscription

subscribeOnce

• subscribeOnce<T>(topic: Topic<T>): Promise<T>

  Subscribes once to the specified topic, returning a promise that resolves with the next published message.

  The subscription will be automatically disposed after receiving the message. This allows awaiting a single message without manual subscription management.

  Type Parameters

  • T

  Parameters

  • topic: Topic<T>

    The topic to subscribe to.

  Returns Promise<T>

  Example

  const command = await messageBus.subscribeOnce(CommandTopic);
  console.log(`Received command: ${command}`);
  Copy

• subscribeOnce<T extends [any, ...any[]]>(topics: Topics<T>): Promise<T[number]>

  Type Parameters

  • T extends [any, ...any[]]

  Parameters

  • topics: Topics<T>

  Returns Promise<T[number]>

• subscribeOnce<T>(topic: Topic<T>, handler: MessageHandler<T>): Subscription

  Subscribes once to the specified topic with a callback.

  The callback is invoked with the next message, after which the subscription is disposed.

  Type Parameters

  • T

  Parameters

  • topic: Topic<T>

    The topic to subscribe to.
  • handler: MessageHandler<T>

    A callback invoked on the next topic message.

  Returns Subscription

  Example

  // Automatically unsubscribes after the next message
  messageBus.subscribeOnce(CommandTopic, (command) => {
    console.log(`Received command: ${command}`);
  });
  Copy

• subscribeOnce<T extends [any, ...any[]]>(
      topics: Topics<T>,
      handler: MessageHandler<T[number]>,
  ): Subscription

  Type Parameters

  • T extends [any, ...any[]]

  Parameters

  • topics: Topics<T>
  • handler: MessageHandler<T[number]>

  Returns Subscription

withLimit

• withLimit(limit: number): SubscriptionBuilder

  Sets the maximum number of messages to receive for the next subscription.

  When the specified limit is reached, the subscription is automatically disposed.

  Parameters

  • limit: number

    The maximum number of messages to receive.

  Returns SubscriptionBuilder

withPriority

• withPriority(priority: number): SubscriptionBuilder

  Sets the priority for the next subscription.

  Higher priority (lower number) subscriptions are notified before lower priority (higher value) ones. The default priority value is 1.

  Parameters

  • priority: number

    A priority value, where a lower number means higher priority.

  Returns SubscriptionBuilder