arvo-event-handler/dist/utils/SimpleEventBroker/index.d.ts

Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.

import type { ArvoEvent } from 'arvo-core';
import type { EventBusListener, EventBusOptions } from './types';
/**
 * A simple event broker for handling local event-driven workflows within function scope.
 * Ideal for composing function handlers and coordinating local business logic steps.
 *
 * @description
 * Use SimpleEventBroker when you need:
 * - Local event handling within a function's execution scope
 * - Decoupling steps in a business process
 * - Simple composition of handlers for a workflow
 * - In-memory event management for a single operation
 *
 * Not suitable for:
 * - Long-running processes or persistent event storage
 * - Cross-process or distributed event handling
 * - High-throughput event processing (>1000s events/sec)
 * - Mission critical or fault-tolerant systems
 * - Complex event routing or filtering
 *
 * Typical use cases:
 * - Coordinating steps in a registration process
 * - Managing validation and processing workflows
 * - Decoupling business logic steps
 * - Local event-driven state management
 *
 * @example
 * ```typescript
 * // During a registration flow
 * const broker = new SimpleEventBroker({ ... });
 *
 * broker.subscribe('validation.complete', async (event) => {
 *   // Handle validation results
 * });
 *
 * broker.subscribe('user.created', async (event) => {
 *   // Handle user creation side effects
 * });
 *
 * await broker.publish({
 *   to: 'validation.complete',
 *   payload: userData
 * });
 * ```
 */
export declare class SimpleEventBroker {
    private readonly subscribers;
    private readonly queue;
    readonly events: ArvoEvent[];
    private readonly maxQueueSize;
    private readonly onError;
    private isProcessing;
    private readonly eventProcessDelay;
    constructor(options: EventBusOptions);
    /**
     * All event types that have registered listeners.
     */
    get topics(): string[];
    /**
     * Subscribe to a specific event type
     * @param topic - Event type to subscribe to
     * @param handler - Function to handle the event
     * @param assertUnique - Asserts the uniqne-ness of the handler.
     *                       If true, then only one handler per topic
     *                                otherwise, throws error
     * @returns Unsubscribe function
     */
    subscribe(topic: string, handler: EventBusListener, assertUnique?: boolean): () => void;
    /**
     * Publish an event to subscribers
     * @param event - Event to publish
     * @throws Error if queue is full or event has no topic
     */
    publish(event: ArvoEvent): Promise<void>;
    /**
     * Current number of events in queue
     */
    get queueLength(): number;
    /**
     * Number of subscribers for a given topic
     */
    getSubscriberCount(topic: string): number;
    /**
     * Processes queued events asynchronously, ensuring sequential execution.
     * Handles error cases and maintains the processing state.
     *
     * @remarks
     * - Only one instance of processQueue runs at a time
     * - Events are processed in FIFO order
     * - Failed event handlers trigger onError callback
     * - All handlers for an event are processed in parallel
     *
     * @throws Propagates any unhandled errors from event processing
     */
    private processQueue;
}