evnty/build/signal.d.ts

Async-first, reactive event handling library for complex event flows in browser and Node.js

import { Async } from './async.js';
/**
 * Promise-based async coordination primitive.
 * `emit()` resolves the pending `receive()` promise (shared across callers).
 * Reusable - after each emission a new round of `receive()` calls can be made.
 * Disposable via `[Symbol.dispose]()` or an optional AbortSignal.
 *
 * @template T The type of value that this signal carries.
 *
 * @example
 * ```typescript
 * const signal = new Signal<string>();
 *
 * const promise = signal.receive();
 * signal.emit('hello');
 * await promise; // 'hello'
 * ```
 */
export declare class Signal<T> extends Async<T, boolean> {
    #private;
    readonly [Symbol.toStringTag] = "Signal";
    /**
     * Merges multiple source signals into a target signal.
     * Values from any source signal are emitted to the target signal.
     * The merge continues until the target signal is disposed.
     *
     * Note: When the target is disposed, iteration stops after the next value
     * from each source. For immediate cleanup, dispose source signals directly.
     *
     * @param target The signal that will receive values from all sources
     * @param signals The source signals to merge from
     *
     * @example
     * ```typescript
     * // Create a target signal and source signals
     * const target = new Signal<string>();
     * const source1 = new Signal<string>();
     * const source2 = new Signal<string>();
     *
     * // Merge sources into target
     * Signal.merge(target, source1, source2);
     *
     * // Values from any source appear in target
     * const promise = target.receive();
     * source1.emit('Hello');
     * const value = await promise; // 'Hello'
     * ```
     */
    static merge<T>(target: Signal<T>, ...signals: Signal<T>[]): void;
    /**
     * Creates a new Signal instance.
     *
     * @param abortSignal An optional AbortSignal that can be used to cancel the signal operation.
     *
     * @example
     * ```typescript
     * // Create a signal with abort capability
     * const controller = new AbortController();
     * const signal = new Signal<number>(controller.signal);
     *
     * // Signal can be cancelled
     * controller.abort('Operation cancelled');
     * ```
     */
    constructor(abortSignal?: AbortSignal);
    /**
     * Sends a value to the waiting receiver, if any.
     *
     * @param value - The value to send.
     * @returns `true` if the value was emitted.
     */
    emit(value: T): boolean;
    /**
     * Waits for the next value to be sent to this signal. If the signal has been aborted
     * or disposed, this method rejects with Error('Disposed').
     *
     * @returns A promise that resolves with the next value sent to the signal.
     *
     * @example
     * ```typescript
     * const signal = new Signal<string>();
     *
     * // Wait for a value
     * const valuePromise = signal.receive();
     *
     * // Send a value from elsewhere
     * signal.emit('Hello');
     *
     * const value = await valuePromise; // 'Hello'
     * ```
     */
    receive(): Promise<T>;
    dispose(): void;
}