@okikio/observables 1.0.2

package/esm/events.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Multicast event primitives built on top of the Observable runtime.
+ *
+ * This entrypoint is for the hot side of the library: shared event streams that
+ * multiple consumers can listen to at the same time. It exports `EventBus` for
+ * one-to-many pub/sub, `createEventDispatcher` for named and type-safe events,
+ * and helpers such as `withReplay` and `waitForEvent` for common coordination
+ * patterns.
+ *
+ * Use `Observable` when each subscription should start fresh work. Use this
+ * module when one emission should fan out to many listeners, such as UI events,
+ * app-wide notifications, or workflow status updates.
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+import type { Subscription } from "./_types.js";
+import { Observable } from "./observable.js";
+import { Symbol } from "./symbol.js";
+/**
+ * A multicast event bus that extends {@link Observable<T>}, allowing
+ * emission of values to multiple subscribers and supporting both
+ * Observer-style and async-iterator consumption.
+ *
+ * @typeParam T - The type of values emitted by this bus.
+ *
+ * - Calling {@link emit} delivers the value to all active subscribers.
+ * - Calling {@link close} completes all subscribers and prevents further emissions.
+ * - Implements both {@link Symbol.dispose} and {@link Symbol.asyncDispose}
+ *   for cleanup in synchronous and asynchronous contexts.
+ *
+ * @example
+ * ```ts
+ * import { EventBus } from './EventBus.ts';
+ *
+ * // Create a bus for string messages
+ * const bus = new EventBus<string>();
+ *
+ * // Subscribe using Observer
+ * bus.events.subscribe({
+ *   next(msg) { console.log('Received:', msg); },
+ *   complete()  { console.log('Bus closed'); }
+ * });
+ *
+ * // Emit values
+ * bus.emit('hello');
+ * bus.emit('world');
+ *
+ * // Close the bus
+ * bus.close();
+ * ```
+ */
+export declare class EventBus<T> extends Observable<T> {
+    #private;
+    /**
+     * Synchronous disposal method (for `using` syntax).
+     *
+     * Alias for {@link close}.
+     */
+    [Symbol.dispose]: () => void;
+    [Symbol.asyncDispose]: () => Promise<void>;
+    /**
+     * Construct a new EventBus instance.
+     *
+     * The base {@link Observable} constructor is invoked with the subscriber
+     * registration logic, adding and removing subscribers to the internal set.
+     */
+    constructor();
+    /**
+     * Exposes the bus itself as an {@link Observable<T>} for subscription.
+     *
+     * @returns The current instance as an Observable of T.
+     */
+    get events(): Observable<T>;
+    /**
+     * Emit a value to all active subscribers.
+     *
+     * @param value - The value to deliver.
+     */
+    emit(value: T): void;
+    /**
+     * Close the bus, completing all subscribers and preventing further emits.
+     */
+    close(): void;
+}
+/**
+ * A mapping from event names (keys) to their payload types (values).
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   login: { userId: string };
+ *   logout: void;
+ * }
+ * ```
+ */
+export type EventMap = object;
+/**
+ * The return type of {@link createEventDispatcher}.
+ * Provides a strongly-typed event bus interface.
+ *
+ * @typeParam E - The event map type, mapping event names to payloads.
+ */
+export interface EventDispatcher<E extends EventMap> {
+    /**
+     * Emit an event with the given name and payload.
+     * @param name - The event name.
+     * @param payload - The payload matching the event name.
+     */
+    emit<Name extends keyof E>(name: Name, payload: E[Name]): void;
+    /**
+     * Subscribe to a specific event by name.
+     * Only events with a matching `type` will invoke the handler.
+     * @param name - The event name to listen for.
+     * @param handler - The callback invoked with the event payload.
+     * @returns A subscription object with `unsubscribe()`.
+     */
+    on<Name extends keyof E>(name: Name, handler: (payload: E[Name]) => void): Subscription;
+    /**
+     * Observable stream of all emitted events, carrying `{ type, payload }` objects.
+     */
+    events: EventBus<{
+        type: keyof E;
+        payload: E[keyof E];
+    }>;
+    /**
+     * Close the bus, completing all subscribers and preventing further emits.
+     */
+    close(): void;
+}
+/**
+ * Creates a strongly-typed event bus based on {@link EventBus}, ensuring
+ * that both `emit` and `on` methods enforce matching event names and payload types.
+ *
+ * @typeParam E - The event map type, mapping event names to payloads.
+ *
+ * @returns An object with the following methods:
+ * - `emit(name, payload)`: Emit an event.
+ * - `on(name, handler)`: Subscribe to a specific event.
+ * - `events`: Observable stream of all events.
+ * - `close()`: Close the bus and complete all subscribers.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   message: { text: string };
+ *   error: { code: number; message: string };
+ * }
+ *
+ * const bus = createTypedEventBus<MyEvents>();
+ *
+ * // Subscribe to `message` events
+ * bus.on('message', payload => {
+ *   console.log('New message:', payload.text);
+ * });
+ *
+ * // Emit an event
+ * bus.emit('message', { text: 'Hello World' });
+ *
+ * // Close the bus when done
+ * bus.close();
+ * ```
+ */
+export declare function createEventDispatcher<E extends EventMap>(): EventDispatcher<E>;
+/**
+ * Options for `waitForEvent`.
+ */
+export interface WaitForEventOptions {
+    /**
+     * An AbortSignal to cancel waiting for the event.
+     */
+    signal?: AbortSignal;
+    /**
+     * If true, rejects if the underlying stream completes before the event fires.
+     * @defaultValue false
+     */
+    throwOnClose?: boolean;
+}
+/**
+ * Waits for the next occurrence of a specific event on a typed event bus.
+ * Resolves with the event payload when the named event fires.
+ * Can be aborted or optionally reject if the bus closes first.
+ *
+ * @typeParam E    - The event map type.
+ * @typeParam K    - The specific event key to listen for.
+ *
+ * @param bus      - An object with an `events` Observable emitting `{ type, payload }`.
+ * @param type     - The event name to wait for.
+ * @param options  - Optional signal to abort, and throwOnClose behavior.
+ * @returns A promise resolving to the payload of the event, or rejecting on error/abort/close.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   data: { value: number };
+ *   done: void;
+ * }
+ *
+ * const bus = createTypedEventBus<MyEvents>();
+ *
+ * // somewhere else...
+ * waitForEvent(bus, 'data').then(payload => {
+ *   console.log('Data arrived:', payload.value);
+ * });
+ *
+ * // later
+ * bus.emit('data', { value: 42 });
+ * ```
+ */
+export declare function waitForEvent<E extends EventMap, K extends keyof E>(bus: {
+    events: Observable<{
+        type: keyof E;
+        payload: E[keyof E];
+    }>;
+}, type: K, { signal, throwOnClose }?: WaitForEventOptions): Promise<E[K] | undefined>;
+/**
+ * Controls when the replay buffer connects to the source Observable.
+ *
+ * - `'eager'`: Connects immediately and buffers values even with zero subscribers.
+ *              Like a security camera that's always recording.
+ * - `'lazy'`:  Connects only when the first subscriber arrives, disconnects when
+ *              the last one leaves. Like a motion-activated camera.
+ *
+ * Choose 'eager' for system-critical events you never want to miss.
+ * Choose 'lazy' for expensive operations that shouldn't run without consumers.
+ */
+export type ReplayMode = "eager" | "lazy";
+/**
+ * Configuration options for replay behavior.
+ */
+export interface ReplayOptions {
+    /**
+     * Maximum number of values to buffer.
+     * When the buffer is full, the oldest value is discarded (FIFO).
+     *
+     * @default Infinity (unlimited buffer, use with caution)
+     */
+    count?: number;
+    /**
+     * Determines when to connect to the source Observable.
+     *
+     * @default 'lazy' (resource-efficient, connects on-demand)
+     */
+    mode?: ReplayMode;
+}
+/**
+ * Adds replay capability to an Observable, multicasting values to multiple subscribers
+ * while maintaining a buffer of recent emissions.
+ *
+ * Without replay, each new subscriber triggers a fresh execution of the source Observable:
+ * ```ts
+ * const apiCall = new Observable(subscriber => {
+ *   console.log('Making expensive API call...');
+ *   fetch('/api/data').then(response => subscriber.next(response));
+ * });
+ *
+ * apiCall.subscribe(data1 => {}); // Triggers API call #1
+ * apiCall.subscribe(data2 => {}); // Triggers API call #2 (duplicate!)
+ * ```
+ *
+ * With replay, the source executes once and shares results:
+ * ```ts
+ * const sharedApi = withReplay(apiCall, { count: 1, mode: 'lazy' });
+ *
+ * sharedApi.subscribe(data1 => {}); // Triggers API call
+ * sharedApi.subscribe(data2 => {}); // Gets cached result, no new call!
+ * ```
+ *
+ * ## Memory Considerations
+ *
+ * - Buffer size directly impacts memory usage: `count * sizeof(T)`
+ * - 'eager' mode holds references even with no subscribers (potential memory leak)
+ * - 'lazy' mode clears buffer when all subscribers disconnect (automatic cleanup)
+ * - Consider using finite counts for long-running streams to prevent unbounded growth
+ *
+ * > **Note**: Infinite buffers are by default capped at 1000 items to prevent memory issues.
+ * > The primary reason for this cap is because some runtimes such as Deno and Node.js
+ * > litereally crash when you try to allocate Ininity-sized arrays.
+ *
+ * ## Performance Characteristics
+ *
+ * - Enqueue/Dequeue: O(1) constant time
+ * - New subscriber replay: O(n) where n = buffer size
+ * - Memory overhead: One queue + subscriber set + source subscription
+ *
+ * ## Edge Cases & Gotchas
+ *
+ * 1. **Late subscribers in eager mode**: May receive very old values if the source
+ *    emitted long ago and no cleanup occurred.
+ *
+ * 2. **Infinite buffers**: Without a count limit, buffers grow indefinitely.
+ *    Always set a reasonable count for production use.
+ *
+ * 3. **Error handling**: Errors are multicast to all subscribers but don't clear
+ *    the buffer. New subscribers still get the replay before the error.
+ *
+ * 4. **Completion**: The source completion is multicast, but the replay buffer
+ *    remains accessible to new subscribers (they get replay + completion).
+ *
+ * @param source The source Observable to add replay behavior to
+ * @param options Configuration for replay behavior
+ * @returns A new Observable with replay capability
+ *
+ * @example
+ * ```ts
+ * // Lazy mode - only buffers when subscribers are present
+ * const shared = withReplay(expensive, {
+ *   count: 5,
+ *   mode: 'lazy'  // Only run expensive when needed
+ * });
+ *
+ * // Eager mode - always buffering, like a flight recorder
+ * const eventLog = withReplay(systemEvents, {
+ *   count: 100,
+ *   mode: 'eager'  // Capture events even if no one's listening
+ * });
+ * ```
+ */
+export declare function withReplay<T>(source: Observable<T>, { count, mode }?: ReplayOptions): Observable<T>;
+//# sourceMappingURL=events.d.ts.map

package/esm/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}