import { Listener, SingleOrMultipleListeners } from './types';

/**
 * Event emitter interface for pub/sub pattern.
 *
 * @template T - The type of payload emitted to listeners (defaults to void)
 */
export interface Emitter<T = void> {
    /**
     * Subscribe to events with one or more listeners.
     *
     * @param listeners - Single listener or array of listeners
     * @returns Unsubscribe function (idempotent - safe to call multiple times)
     */
    on(listeners: SingleOrMultipleListeners<T>): VoidFunction;
    /**
     * Subscribe with a mapping function that filters and transforms events.
     *
     * The map function receives the emitted value and returns either:
     * - `{ value: TValue }` - Listener is called with the transformed value
     * - `undefined` - Listener is NOT called (event filtered out)
     *
     * @template TValue - The transformed value type passed to listeners
     * @param map - Transform function that can filter (return undefined) or map values
     * @param listeners - Single listener or array of listeners for transformed values
     * @returns Unsubscribe function
     *
     * @example Filter and transform
     * ```ts
     * const emitter = emitter<{ type: string; data: number }>();
     *
     * // Only listen to 'success' events, extract just the data
     * emitter.on(
     *   (event) => event.type === 'success' ? { value: event.data } : undefined,
     *   (data) => console.log('Success data:', data)
     * );
     * ```
     */
    on<TValue>(map: (value: T) => {
        value: TValue;
    } | undefined, listeners: SingleOrMultipleListeners<TValue>): VoidFunction;
    /**
     * Emit an event to all registered listeners.
     *
     * @param payload - The value to pass to all listeners
     */
    emit(payload: T): void;
    /**
     * Emit an event to all registered listeners in LIFO (reverse) order.
     * Useful for cleanup scenarios where resources should be released
     * in reverse order of acquisition.
     *
     * @param payload - The value to pass to all listeners
     */
    emitLifo(payload: T): void;
    /**
     * Remove all registered listeners.
     */
    clear(): void;
    /**
     * Emit an event to all listeners, then clear all listeners.
     * Useful for one-time events like disposal.
     *
     * @param payload - The value to pass to all listeners
     */
    emitAndClear(payload: T): void;
    /**
     * Emit an event to all listeners in LIFO (reverse) order, then clear.
     * Useful for cleanup scenarios where resources should be released
     * in reverse order of acquisition.
     *
     * @param payload - The value to pass to all listeners
     */
    emitAndClearLifo(payload: T): void;
    /**
     * Emit to all listeners, clear, and "settle" the emitter.
     *
     * After settling:
     * - Any new `on()` call immediately invokes the listener with the settled payload
     * - Returns a no-op unsubscribe function
     * - `emit()` and `emitAndClear()` become no-ops
     *
     * Useful for one-time events where late subscribers should still receive the value
     * (similar to Promise behavior).
     *
     * @param payload - The final value to pass to all listeners
     */
    settle(payload: T): void;
    /** Number of registered listeners */
    readonly size: number;
    /** Whether the emitter has been settled */
    readonly settled: boolean;
}
/**
 * Creates an event emitter for managing and notifying listeners.
 *
 * An emitter provides a simple pub/sub pattern for managing event listeners.
 * It's used internally by signals and effects to manage subscriptions and notifications.
 *
 * Features:
 * - Add listeners that will be notified when events are emitted
 * - Emit events to all registered listeners
 * - Remove listeners via unsubscribe functions
 * - Clear all listeners at once
 * - Safe to call unsubscribe multiple times (idempotent)
 *
 * @template T - The type of payload that will be emitted to listeners (defaults to void)
 * @returns An emitter object with add, emit, and clear methods
 *
 * @example
 * ```ts
 * const eventEmitter = emitter<string>();
 *
 * // Subscribe to events
 * const unsubscribe = eventEmitter.add((message) => {
 *   console.log('Received:', message);
 * });
 *
 * // Emit an event
 * eventEmitter.emit('Hello'); // Logs: "Received: Hello"
 *
 * // Unsubscribe
 * unsubscribe();
 *
 * // Clear all listeners
 * eventEmitter.clear();
 * ```
 */
export declare function emitter<T = void>(initialListeners?: Listener<T>[]): Emitter<T>;
//# sourceMappingURL=emitter.d.ts.map