Function listenEventOnce

  • listenEventOnce<T extends unknown = any>(
        clientId: string,
        topicName: string,
        filterFn: (event: T) => boolean,
        fn: (data: T) => void,
    ): () => void

    Subscribes to a custom event on the swarm bus service for a single occurrence, executing a callback when the event matches a filter.

    This function sets up a one-time listener for events with a specified topic on the swarm's bus service, invoking the provided callback with the event's payload when the event is received and passes the filter condition. It is wrapped in beginContext for a clean execution environment, logs the operation if enabled, and enforces restrictions on reserved topic names (defined in DISALLOWED_EVENT_SOURCE_LIST). The callback is queued to ensure sequential processing, and the listener unsubscribes after the first matching event. The function supports a wildcard client ID ("*") for listening to all clients or validates a specific client session. It returns an unsubscribe function to cancel the listener prematurely.

    Type Parameters

    • T extends unknown = any

      The type of the payload data, defaulting to any if unspecified.

    Parameters

    • clientId: string

      The unique identifier of the client session, or "*" for all clients.

    • topicName: string

      The name of the event topic to listen for.

    • filterFn: (event: T) => boolean

      Filter function that determines if the event should trigger the callback.

    • fn: (data: T) => void

      Callback function executed when a matching event is received.

    Returns () => void

    Throws

    If the topicName is a reserved event source (e.g., "agent-bus"), or if the clientId is not "*" and no session exists.

    Example

    const unsubscribe = listenEventOnce(
      "client-123",
      "custom-topic",
      (data) => data.value > 0,
      (data) => console.log(data)
    );
    // Logs payload once when "custom-topic" event with value > 0 is received
    unsubscribe(); // Cancels listener if not yet triggered

Settings

Member Visibility