@empathyco/x-components/types/x-bus/x-bus.d.ts

Empathy X Components

import type { AnyFunction, Dictionary } from '@empathyco/x-utils';
import type { Observable } from 'rxjs';
import type { EmittedData, Emitter, Emitters, EventPayload, Priority, SubjectPayload, XBus, XPriorityBusEventMetadata, XPriorityQueueNodeData } from './x-bus.types';
import type { XPriorityQueue } from './x-priority-queue';
/**
 * A default {@link XBus} implementation using a
 * {@link XPriorityQueue | priority queue} as its data structure to
 * prioritise the emission of events. The priorities are preconfigured based on event naming.
 *
 * @public
 */
export declare class XPriorityBus<SomeEvents extends Dictionary, SomeEventMetadata extends XPriorityBusEventMetadata> implements XBus<SomeEvents, SomeEventMetadata> {
    /**
     * A {@link XPriorityQueue | priority queue} to store the events to
     * emit.
     *
     * @internal
     */
    protected queue: XPriorityQueue<SomeEvents, XPriorityQueueNodeData<SomeEvents, SomeEventMetadata>>;
    /**
     * A dictionary associating a priority to a key.
     *
     * @example
     * ```ts
     * const priorities: Dictionary<number> = {
     *   '^StartsWith': 2,
     *   Contains: 4,
     *   EndWith$: 8
     * }
     * ```
     *
     * @internal
     */
    protected priorities: Dictionary<Priority>;
    /**
     * The default value to use as priority for an event that doesn't have defined neither a custom
     * priority nor its name doesn't match any key of the {@link XPriorityBus.priorities | priorities} dictionary.
     *
     * @internal
     */
    protected defaultEventPriority: number;
    /**
     * A list of functions to execute when an event is emitted.
     *
     * @internal
     */
    protected emitCallbacks: AnyFunction[];
    /**
     * A dictionary to store the created event emitters.
     *
     * @internal
     */
    protected emitters: Emitters<SomeEvents, SomeEventMetadata>;
    /**
     * A pending flush operation timeout identifier or undefined if there's none pending.
     *
     * @internal
     */
    protected pendingFlushId?: number;
    /**
     * A list of pending pop operations timeout identifiers.
     *
     * @internal
     */
    protected pendingPopsIds: number[];
    /**
     * Creates a new instance of a {@link XPriorityBus}.
     *
     * @param config - A configuration object to initialise the bus.
     * - param config.queue - A {@link XPriorityQueue | priority queue} to store the events.
     * - param config.priorities - A Dictionary defining the priorities associated to a given string.
     * - param config.emitCallbacks - A list of functions to execute when an event is emitted.
     * - param config.defaultEventPriority - A default priority to assigned to an event.
     */
    constructor(config?: {
        queue?: XPriorityQueue<SomeEvents, XPriorityQueueNodeData<SomeEvents, SomeEventMetadata>>;
        priorities?: Dictionary<number>;
        emitCallbacks?: AnyFunction[];
        defaultEventPriority?: number;
    });
    /**
     * Emits an event. See {@link XBus.emit}.
     *
     * @param event - Event to be emitted.
     * @param payload - Event payload.
     * @param metadata - Extra event data.
     *
     * @returns A promise that is resolved the moment the event is emitted.
     */
    emit<SomeEvent extends keyof SomeEvents>(event: SomeEvent, payload?: EventPayload<SomeEvents, SomeEvent>, metadata?: SomeEventMetadata): Promise<EmittedData<SomeEvents, SomeEvent, SomeEventMetadata>>;
    /**.
     * Retrieves the event priority based on:
     * - the defined event metadata priority
     * - the priority associated to the matching preconfigured priority key
     * - the configured {@link XPriorityBus.defaultEventPriority | defaultEventPriority} is assigned (by default, the min safe integer).
     *
     * @param event - The event to get the priority from.
     * @param metadata - The event metadata.
     *
     * @returns The priority for the given event.
     *
     * @internal
     */
    protected getEventPriority(event: keyof SomeEvents, metadata: SomeEventMetadata): Priority;
    /**
     * Processes the events stored in the
     * {@link XPriorityQueue | priority queue} and resolves each event
     * whenever it is emitted.
     *
     * @remarks If another 'flushQueue' operation is running, it is discarded and a new one is
     * executed. The pending popping operations are also discarded.
     *
     * @internal
     */
    protected flushQueue(): void;
    /**
     * Discards existing pending pop operations and empties the array.
     *
     * @internal
     */
    private clearPendingPopsIds;
    /**
     * Retrieves an observable for the event. See {@link XBus.on}.
     *
     * @param event - Event to retrieve the observable for.
     * @param withMetadata - Option to retrieve an observable with extra data about the event.
     *
     * @returns The emitter for the event passed.
     */
    on<SomeEvent extends keyof SomeEvents>(event: SomeEvent, withMetadata?: boolean): typeof withMetadata extends true ? Observable<SubjectPayload<EventPayload<SomeEvents, SomeEvent>, SomeEventMetadata>> : Observable<EventPayload<SomeEvents, SomeEvent>>;
    /**
     * Retrieves an event {@link Emitter} for the given event.
     *
     * @param event - The event to retrieve the {@link Emitter} for.
     *
     * @returns The {@link Emitters} for the passed event.
     *
     * @internal
     */
    protected getEmitter<SomeEvent extends keyof SomeEvents>(event: SomeEvent): Emitter<SomeEvents, SomeEvent, SomeEventMetadata>;
    /**
     * Creates an event {@link Emitter} for the given event.
     *
     * @remarks The emitter is implemented with a
     * {@Link https://www.learnrxjs.io/learn-rxjs/subjects/replaysubject | ReplaySubject} to allow any
     * new subscriber receive the last emitted value.
     *
     * @param event - The event to create the {@link Emitter} for.
     *
     * @internal
     */
    protected createEmitter<SomeEvent extends keyof SomeEvents>(event: SomeEvent): void;
}
//# sourceMappingURL=x-bus.d.ts.map