/**
 * Event Bus Mediator Types for Declarative Infrastructure API
 *
 * This module defines the interfaces for the Event Bus Mediator pattern,
 * enabling decoupled event-driven communication between resources.
 *
 * @module declarative-api/mediator.types
 */
import type { IBaseEvent } from './event.types';
import type { ISpecification } from './specification.types';
/**
 * Event handler function type.
 *
 * @typeParam T - The event type being handled
 */
export type EventHandler<T extends IBaseEvent> = (event: T) => void | Promise<void>;
/**
 * Request handler function type for request/response pattern.
 *
 * @typeParam TRequest - The request type
 * @typeParam TResponse - The response type
 */
export type RequestHandler<TRequest, TResponse> = (request: TRequest) => Promise<TResponse>;
/**
 * Subscription handle returned when subscribing to events.
 *
 * Used to unsubscribe from events.
 */
export interface Subscription {
    /** Unique subscription identifier */
    readonly id: string;
    /** Unsubscribe from the event */
    unsubscribe(): void;
}
/**
 * Event log entry for debugging and audit purposes.
 */
export interface EventLogEntry {
    /** Event type */
    readonly eventType: string;
    /** Timestamp when the event was published */
    readonly timestamp: Date;
    /** Number of handlers that received the event */
    readonly handlerCount: number;
    /** Whether all handlers completed successfully */
    readonly success: boolean;
    /** Error message if any handler failed */
    readonly error?: string;
}
/**
 * Event Bus Mediator interface.
 *
 * Implements the Mediator pattern for decoupled event-driven communication.
 * Resources communicate through the mediator, not directly.
 *
 * Validates: Requirements 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
 */
export interface IEventBusMediator {
    /**
     * Publish an event to all subscribers synchronously.
     *
     * All handlers are invoked in order. If a handler throws,
     * subsequent handlers are still invoked.
     *
     * @typeParam T - The event type
     * @param event - The event to publish
     */
    publish<T extends IBaseEvent>(event: T): void;
    /**
     * Publish an event to all subscribers asynchronously.
     *
     * All handlers are invoked concurrently. Returns when all
     * handlers have completed.
     *
     * @typeParam T - The event type
     * @param event - The event to publish
     * @returns Promise that resolves when all handlers complete
     */
    publishAsync<T extends IBaseEvent>(event: T): Promise<void>;
    /**
     * Subscribe to events of a specific type.
     *
     * @typeParam T - The event type
     * @param eventType - The event type string to subscribe to
     * @param handler - The handler function to invoke
     * @returns Subscription handle for unsubscribing
     */
    subscribe<T extends IBaseEvent>(eventType: T['type'], handler: EventHandler<T>): Subscription;
    /**
     * Subscribe to events with a filter specification.
     *
     * Only events that satisfy the specification will be
     * passed to the handler.
     *
     * @typeParam T - The event type
     * @param eventType - The event type string to subscribe to
     * @param handler - The handler function to invoke
     * @param filter - Specification to filter events
     * @returns Subscription handle for unsubscribing
     */
    subscribeWithFilter<T extends IBaseEvent>(eventType: T['type'], handler: EventHandler<T>, filter: ISpecification<T>): Subscription;
    /**
     * Send a request and wait for a response.
     *
     * Uses the request/response pattern for synchronous queries.
     *
     * @typeParam TRequest - The request type
     * @typeParam TResponse - The response type
     * @param requestType - The request type identifier
     * @param request - The request payload
     * @returns Promise resolving to the response
     * @throws Error if no handler is registered for the request type
     */
    request<TRequest, TResponse>(requestType: string, request: TRequest): Promise<TResponse>;
    /**
     * Register a handler for a request type.
     *
     * Only one handler can be registered per request type.
     *
     * @typeParam TRequest - The request type
     * @typeParam TResponse - The response type
     * @param requestType - The request type identifier
     * @param handler - The handler function
     * @throws Error if a handler is already registered for the request type
     */
    registerRequestHandler<TRequest, TResponse>(requestType: string, handler: RequestHandler<TRequest, TResponse>): void;
    /**
     * Unregister a request handler.
     *
     * @param requestType - The request type identifier
     * @returns True if a handler was unregistered, false if none existed
     */
    unregisterRequestHandler(requestType: string): boolean;
    /**
     * Get the event log for debugging.
     *
     * @param limit - Maximum number of entries to return (default: 100)
     * @returns Array of event log entries
     */
    getEventLog(limit?: number): readonly EventLogEntry[];
    /**
     * Clear the event log.
     */
    clearEventLog(): void;
    /**
     * Get the number of subscribers for an event type.
     *
     * @param eventType - The event type string
     * @returns Number of subscribers
     */
    getSubscriberCount(eventType: string): number;
    /**
     * Check if a request handler is registered.
     *
     * @param requestType - The request type identifier
     * @returns True if a handler is registered
     */
    hasRequestHandler(requestType: string): boolean;
}
