/**
 * @file Unified Event Utilities
 * @description Best-of-breed event handling with type safety, middleware, coordination,
 * and reliability features. Consolidates 4 previous implementations into one canonical version.
 *
 * @module shared/event-utils
 * @author Agent 5 - PhD TypeScript Architect
 * @version 2.0.0
 */
/**
 * Generic event handler function type.
 */
export type EventHandler<T = unknown> = (data: T) => void | Promise<void>;
/**
 * Synchronous event handler.
 */
export type SyncEventHandler<T = unknown> = (data: T) => void;
/**
 * Async event handler.
 */
export type AsyncEventHandler<T = unknown> = (data: T) => Promise<void>;
/**
 * Unsubscribe function returned by event subscriptions.
 */
export type Unsubscribe = () => void;
/**
 * Event middleware function.
 */
export type EventMiddleware<T = unknown> = (data: T, next: (data: T) => void | Promise<void>) => void | Promise<void>;
/**
 * Event listener options.
 */
export interface EventListenerOptions {
    /** Call handler only once then auto-remove */
    once?: boolean;
    /** Priority (higher executes first) */
    priority?: number;
    /** Abort signal to auto-remove listener */
    signal?: AbortSignal;
    /** Debounce delay in milliseconds */
    debounce?: number;
    /** Throttle interval in milliseconds */
    throttle?: number;
    /** Source filter (string, regex, or array) */
    sourceFilter?: string | RegExp | string[];
    /** Target filter */
    targetFilter?: string;
    /** Transform data before passing to handler */
    transform?: (data: unknown) => unknown;
    /** Filter events */
    filter?: (data: unknown) => boolean;
}
/**
 * Unified event emitter configuration.
 */
export interface UnifiedEventEmitterOptions {
    /** Maximum listeners per event (warning threshold) */
    maxListeners?: number;
    /** Enable debug logging */
    debug?: boolean;
    /** Error handler for listener errors */
    onError?: (error: Error, event: string) => void;
    /** Enable middleware support */
    enableMiddleware?: boolean;
    /** Enable event deduplication */
    enableDeduplication?: boolean;
    /** Enable event persistence/history */
    enablePersistence?: boolean;
    /** Enable statistics tracking */
    enableStatistics?: boolean;
    /** Enable dead letter queue */
    enableDeadLetters?: boolean;
    /** Deduplication window in milliseconds */
    deduplicationWindow?: number;
    /** Maximum events to persist in history */
    maxPersistedEvents?: number;
    /** Maximum dead letters to keep */
    maxDeadLetters?: number;
    /** Maximum retries for failed deliveries */
    maxRetries?: number;
    /** Retry delay in milliseconds */
    retryDelayMs?: number;
}
/**
 * Event metadata for advanced features.
 */
export interface EventMetadata {
    /** Unique event ID */
    id: string;
    /** Event timestamp */
    timestamp: number;
    /** Source identifier */
    source?: string;
    /** Target identifier */
    target?: string | null;
    /** Event priority */
    priority: number;
    /** Correlation ID for request-response pattern */
    correlationId?: string;
    /** Whether acknowledgment is required */
    requiresAck?: boolean;
    /** Custom metadata */
    custom?: Record<string, unknown>;
}
/**
 * Event with metadata.
 */
export interface EventWithMetadata<T> {
    /** Event name/type */
    event: string;
    /** Event payload */
    payload: T;
    /** Event metadata */
    metadata: EventMetadata;
}
/**
 * Event bus statistics.
 */
export interface EventBusStats {
    /** Total events published */
    totalPublished: number;
    /** Total events delivered */
    totalDelivered: number;
    /** Total delivery failures */
    totalFailures: number;
    /** Current active subscriptions */
    activeSubscriptions: number;
    /** Dead letters count */
    deadLettersCount: number;
    /** Events by type */
    eventsByType: Map<string, number>;
    /** Events by priority */
    eventsByPriority: Record<number, number>;
    /** Average delivery time in milliseconds */
    avgDeliveryTime: number;
}
/**
 * Dead letter entry for failed deliveries.
 */
interface DeadLetterEntry {
    event: string;
    data: unknown;
    metadata: EventMetadata;
    reason: string;
    timestamp: number;
    retryCount: number;
}
/**
 * Standard application events that can be used across modules.
 */
export type AppEvents = {
    'auth:login': {
        userId: string;
        timestamp: number;
    };
    'auth:logout': {
        userId: string;
        reason?: string;
    };
    'auth:sessionExpired': {
        userId: string;
    };
    'auth:tokenRefreshed': {
        accessToken: string;
    };
    'navigation:beforeNavigate': {
        from: string;
        to: string;
    };
    'navigation:afterNavigate': {
        from: string;
        to: string;
    };
    'navigation:blocked': {
        from: string;
        to: string;
        reason: string;
    };
    'data:invalidate': {
        keys: string[];
    };
    'data:update': {
        key: string;
        value: unknown;
    };
    'data:refresh': {
        source: string;
    };
    'ui:themeChange': {
        theme: 'light' | 'dark' | 'system';
    };
    'ui:notification': {
        type: 'info' | 'success' | 'warning' | 'error';
        message: string;
        duration?: number;
    };
    'ui:modalOpen': {
        id: string;
        data?: Record<string, unknown>;
    };
    'ui:modalClose': {
        id: string;
        result?: unknown;
    };
    'error:global': {
        error: Error;
        context?: string;
    };
    'error:network': {
        url: string;
        status: number;
        message: string;
    };
    'error:validation': {
        field: string;
        message: string;
    };
    'performance:slowOperation': {
        operation: string;
        durationMs: number;
    };
    'performance:memoryPressure': {
        level: 'low' | 'moderate' | 'critical';
    };
    'feature:flagChange': {
        key: string;
        value: unknown;
        previousValue: unknown;
    };
    'offlineQueue:expired': {
        id: string;
        url: string;
    };
    'offlineQueue:enqueued': {
        id: string;
        url: string;
    };
    'offlineQueue:processing': {
        count: number;
    };
    'offlineQueue:completed': {
        id: string;
        url: string;
        response: unknown;
    };
    'offlineQueue:failed': {
        id: string;
        url: string;
        error: Error;
    };
    'service:stateChange': {
        service: string;
        from: string;
        to: string;
        health: unknown;
    };
    'service:error': {
        service: string;
        error: Error;
    };
    'service:healthCheck': {
        service: string;
        health: unknown;
    };
    'analytics:consentChanged': {
        consent: unknown;
    };
    'network:online': undefined;
    'network:offline': undefined;
    'network:qualityChange': {
        quality: string;
    };
};
/**
 * Type-safe event emitter interface.
 */
export interface IEventEmitter<Events extends Record<string, unknown>> {
    /**
     * Subscribe to an event.
     */
    on<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>, options?: EventListenerOptions): Unsubscribe;
    /**
     * Subscribe to an event for a single emission.
     */
    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>, options?: Omit<EventListenerOptions, 'once'>): Unsubscribe;
    /**
     * Unsubscribe from an event.
     */
    off<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
    /**
     * Emit an event.
     */
    emit<K extends keyof Events>(event: K, data: Events[K]): void | Promise<void>;
    /**
     * Remove all listeners for an event (or all events if no event specified).
     */
    removeAllListeners<K extends keyof Events>(event?: K): void;
    /**
     * Get listener count for an event.
     */
    listenerCount<K extends keyof Events>(event: K): number;
}
/**
 * Unified event emitter with all best-of-breed features.
 *
 * Features:
 * - Type-safe event maps
 * - Priority listeners
 * - Once-only listeners
 * - Wildcard listeners
 * - Async event handling
 * - Memory leak prevention
 * - Middleware support
 * - Event namespacing
 * - Request-response pattern
 * - Event deduplication
 * - Event persistence and replay
 * - Dead letter queue
 * - Statistics tracking
 * - Debounce/throttle support
 * - AbortSignal support
 *
 * @example
 * ```typescript
 * interface MyEvents {
 *   'user:created': { id: string; name: string };
 *   'user:deleted': { id: string };
 * }
 *
 * const emitter = new UnifiedEventEmitter<MyEvents>();
 *
 * emitter.on('user:created', (data) => {
 *   console.log(`User ${data.name} created`);
 * });
 *
 * emitter.emit('user:created', { id: '1', name: 'John' });
 * ```
 */
export declare class UnifiedEventEmitter<Events extends Record<string, unknown>> implements IEventEmitter<Events> {
    private readonly config;
    private readonly listeners;
    private readonly middlewares;
    private readonly deduplicationCache;
    private readonly eventHistory;
    private readonly deadLetters;
    private readonly pendingRequests;
    private stats;
    private totalDeliveryTime;
    private cleanupInterval;
    private contextSource?;
    constructor(options?: UnifiedEventEmitterOptions);
    /**
     * Subscribe to an event.
     */
    on<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>, options?: EventListenerOptions): Unsubscribe;
    /**
     * Subscribe to an event for a single emission.
     */
    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>, options?: Omit<EventListenerOptions, 'once'>): Unsubscribe;
    /**
     * Unsubscribe from an event.
     */
    off<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
    /**
     * Emit an event.
     */
    emit<K extends keyof Events>(event: K, data: Events[K]): Promise<void>;
    /**
     * Emit synchronously (fire and forget).
     */
    emitSync<K extends keyof Events>(event: K, data: Events[K]): void;
    /**
     * Remove all listeners for an event (or all events if no event specified).
     */
    removeAllListeners<K extends keyof Events>(event?: K): void;
    /**
     * Get listener count for an event.
     */
    listenerCount<K extends keyof Events>(event: K): number;
    /**
     * Get all registered event names.
     */
    eventNames(): (keyof Events)[];
    /**
     * Wait for an event to be emitted.
     */
    waitFor<K extends keyof Events>(event: K, options?: {
        timeout?: number;
        filter?: (data: Events[K]) => boolean;
    }): Promise<Events[K]>;
    /**
     * Add middleware for an event.
     */
    use<K extends keyof Events>(event: K, middleware: EventMiddleware<Events[K]>): Unsubscribe;
    /**
     * Pipe events from another emitter.
     */
    pipe<K extends keyof Events>(event: K, source: UnifiedEventEmitter<Events>): Unsubscribe;
    /**
     * Set context source for emitted events.
     */
    setContext(source: string): void;
    /**
     * Get context source.
     */
    getContext(): string | undefined;
    /**
     * Request-response pattern: send request and wait for response.
     */
    request<TReq extends keyof Events, TRes extends keyof Events>(requestEvent: TReq, responseEvent: TRes, payload: Events[TReq], timeout?: number): Promise<Events[TRes]>;
    /**
     * Get event history.
     */
    getHistory(): ReadonlyArray<EventWithMetadata<unknown>>;
    /**
     * Replay events from history.
     */
    replay(filter?: (event: EventWithMetadata<unknown>) => boolean): void;
    /**
     * Clear event history.
     */
    clearHistory(): void;
    /**
     * Get dead letters.
     */
    getDeadLetters(): ReadonlyArray<DeadLetterEntry>;
    /**
     * Retry a dead letter.
     */
    retryDeadLetter(index: number): boolean;
    /**
     * Clear dead letters.
     */
    clearDeadLetters(): void;
    /**
     * Get statistics.
     */
    getStats(): EventBusStats;
    /**
     * Reset statistics.
     */
    resetStats(): void;
    /**
     * Clear all data and reset emitter.
     */
    clear(): void;
    /**
     * Dispose the emitter and clean up resources.
     */
    dispose(): void;
    /**
     * Apply middleware chain.
     */
    private applyMiddleware;
    /**
     * Add message to dead letter queue.
     */
    private addDeadLetter;
    /**
     * Clean up deduplication cache.
     */
    private cleanupDeduplicationCache;
}
/**
 * Create a unified event emitter.
 */
export declare function createEventEmitter<Events extends Record<string, unknown>>(options?: UnifiedEventEmitterOptions): UnifiedEventEmitter<Events>;
/**
 * Create a scoped event emitter with namespace.
 */
export declare function createScopedEmitter<Events extends Record<string, unknown>>(namespace: string, baseEmitter?: UnifiedEventEmitter<Record<string, unknown>>): UnifiedEventEmitter<Events>;
/**
 * Global event bus instance.
 */
export declare const globalEventBus: UnifiedEventEmitter<AppEvents>;
/**
 * Shorthand for common event operations.
 */
export declare const events: {
    emit: <K extends keyof AppEvents>(event: K, data: AppEvents[K]) => Promise<void>;
    on: <K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>, options?: EventListenerOptions) => Unsubscribe;
    once: <K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>, options?: Omit<EventListenerOptions, "once">) => Unsubscribe;
    off: <K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>) => void;
    waitFor: <K extends keyof AppEvents>(event: K, options?: {
        timeout?: number;
        filter?: ((data: AppEvents[K]) => boolean) | undefined;
    }) => Promise<AppEvents[K]>;
};
/**
 * Create a handler that only executes once per unique key within a time window.
 */
export declare function dedupeHandler<T>(handler: EventHandler<T>, keyFn: (data: T) => string, windowMs: number): EventHandler<T>;
/**
 * Create a handler that batches events and calls the handler with all events.
 */
export declare function batchHandler<T>(handler: (events: T[]) => void | Promise<void>, intervalMs: number): EventHandler<T>;
/**
 * Create a handler that filters events based on a predicate.
 */
export declare function filterHandler<T>(handler: EventHandler<T>, predicate: (data: T) => boolean): EventHandler<T>;
/**
 * Create a handler that transforms event data before passing to handler.
 */
export declare function mapHandler<T, U>(handler: EventHandler<U>, transform: (data: T) => U): EventHandler<T>;
/**
 * Combine multiple handlers into one.
 */
export declare function combineHandlers<T>(...handlers: EventHandler<T>[]): EventHandler<T>;
/**
 * Add event listener with automatic cleanup.
 */
export declare function addEventListener<K extends keyof WindowEventMap>(target: Window, event: K, handler: (event: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): Unsubscribe;
export declare function addEventListener<K extends keyof DocumentEventMap>(target: Document, event: K, handler: (event: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): Unsubscribe;
export declare function addEventListener<K extends keyof HTMLElementEventMap>(target: HTMLElement, event: K, handler: (event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): Unsubscribe;
/**
 * Create a disposable event listener that cleans up when signal is aborted.
 */
export declare function addDisposableEventListener<K extends keyof WindowEventMap>(target: Window, event: K, handler: (event: WindowEventMap[K]) => void, signal: AbortSignal, options?: Omit<AddEventListenerOptions, 'signal'>): void;
/**
 * Create and dispatch a custom event.
 */
export declare function dispatchCustomEvent<T>(target: EventTarget, eventName: string, detail: T, options?: Omit<CustomEventInit<T>, 'detail'>): boolean;
/**
 * Listen for a custom event with typed detail.
 */
export declare function onCustomEvent<T>(target: EventTarget, eventName: string, handler: (detail: T) => void, options?: boolean | AddEventListenerOptions): Unsubscribe;
/**
 * Constructor type for mixin pattern.
 */
type Constructor<T = object> = new (...args: unknown[]) => T;
/**
 * Event emitter mixin for classes.
 */
export declare function withEvents<T extends Constructor, Events extends Record<string, unknown>>(Base: T): T & Constructor<{
    events: UnifiedEventEmitter<Events>;
}>;
/**
 * @deprecated Use UnifiedEventEmitter instead
 */
export declare const SimpleEventEmitter: typeof UnifiedEventEmitter;
/**
 * @deprecated Use UnifiedEventEmitter instead
 */
export declare const EventEmitter: typeof UnifiedEventEmitter;
export {};