@schibsted/pulse-sdk 8.0.0-alpha.16 → 8.0.0-alpha.18

package/dist/types/EventBus/EventBus.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A strongly-typed event bus for browser apps.
+ * - Keeps the latest payload for each event (stateful).
+ * - Can bridge to DOM CustomEvents for non-module scripts.
+ *
+ * @example
+ *   type Events = {
+ *     'tracker:ready': { tracker: the-tracker-instance };
+ *   };
+ *
+ *   export const bus = createEventBus<Events>({ domBridge: true, namespace: 'pulse' })
+ *
+ *   bus.on('tracker:ready', ({ tracker }) => { ... });
+ *
+ *   window.addEventListener('pulse:tracker:ready', (e) => {
+ *     // e is CustomEvent with detail: { payload: { tracker }, __origin }
+ *   });
+ *
+ *   bus.emit('tracker:ready', { tracker });
+ */
+/**
+ * Listener callback.
+ */
+export type Listener<T> = (payload: T) => void | Promise<void>;
+/**
+ * Base Event type, tying the key to a string type.
+ * It is meant to be extended further.
+ */
+type EventDict = Record<string, unknown>;
+/**
+ * Enforcing only string keys for events.
+ */
+type EKey<E extends EventDict> = Extract<keyof E, string>;
+/**
+ * Unsubscribe function type.
+ */
+export type Unsubscribe = () => void;
+/**
+ * What options to use when creating the bus.
+ */
+export interface EventBusOptions {
+    /**
+     * Mirror events to the DOM via CustomEvent and also consume them.
+     * */
+    domBridge?: boolean;
+    /**
+     * DOM event namespace prefix (e.g., 'pulse' => 'pulse:tracker:ready').
+     * */
+    namespace?: string;
+    /**
+     * If true, DOM bridge listeners do not re-emit events back into this bus
+     * when they originated here (prevents loops). Usually leave this `true`.
+     */
+    preventBridgeEcho?: boolean;
+}
+/**
+ * Public interface of the event bus.
+ * Requires the EventDict interface to be extended with specific events.
+ */
+export interface IEventBus<Events extends EventDict> {
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    on<EventKey extends EKey<Events>>(eventKey: EventKey, fn: Listener<Events[EventKey]>): Unsubscribe;
+    /**
+     * Subscribe to an event, but only for the next emission. Returns an unsubscribe function.
+     * @param eventKey
+     * @param eventHandler
+     */
+    once<EventKey extends EKey<Events>>(eventKey: EventKey, eventHandler: Listener<Events[EventKey]>): Unsubscribe;
+    /**
+     * Unsubscribe a specific listener from an event.
+     * @param eventKey
+     * @param eventHandler
+     */
+    off<EventKey extends EKey<Events>>(eventKey: EventKey, eventHandler: Listener<Events[EventKey]>): void;
+    /**
+     * Emit an event with a payload.
+     * @param eventKey
+     * @param payload
+     */
+    emit<EventKey extends EKey<Events>>(eventKey: EventKey, payload: Events[EventKey]): void;
+    /**
+     * Get the latest payload emitted for an event (if any).
+     */
+    getState<EventKey extends EKey<Events>>(eventKey: EventKey): Events[EventKey] | undefined;
+    /**
+     * Subscribe and immediately receive the current state if it exists.
+     * @returns an unsubscribe function.
+     */
+    onWithState<EventKey extends EKey<Events>>(event: EventKey, eventHandler: Listener<Events[EventKey]>): Unsubscribe;
+    /**
+     * Promise that resolves on the next event emission (or when a predicate matches).
+     * Pass a predicate to resolve only on specific payloads.
+     * @param eventKey
+     * @param predicate
+     * @returns Promise of the payload.
+     */
+    waitFor<EventKey extends EKey<Events>>(eventKey: EventKey, predicate?: (payload: Events[EventKey]) => boolean): Promise<Events[EventKey]>;
+    /**
+     * Destroy all listeners and DOM bridge hooks (if any).
+     */
+    destroy(): void;
+}
+export declare function createEventBus<Events extends EventDict>(options?: EventBusOptions): IEventBus<Events>;
+export {};