import { FlowControlOptions } from './kos-topic-handler-flow-control';
import { IKosDataModel } from '../kosModel';
import { DependencyLifecycle } from '../../types';
import { ApiCallback } from '../../../common/events';

/**
 * Extended ApiCallback that includes wildcard capture data for handlers with trailing wildcards
 */
export interface ApiCallbackWithWildcard<T = string> extends ApiCallback<T> {
    wildcardCapture?: Record<string, string>;
}
/**
 * Utility function to extract trailing wildcard from a topic pattern and actual topic
 * @internal - exported for testing
 */
export declare function extractTrailingWildcard(pattern: string, actualTopic: string, wildcardName?: string): Record<string, string>;
/**
 * Check if a topic pattern has a trailing wildcard
 * @internal - exported for testing
 */
export declare function hasTrailingWildcard(pattern: string): boolean;
/**
 * Configuration parameters for defining a Kos topic handler function within a Kos Data Model class.
 *
 * @typeparam Response - The type of the raw response payload received from the topic.
 * @typeparam Model - The type of the Kos Data Model to which the topic handler belongs.
 * @typeparam TransformedResponse - The type of the transformed response payload after applying the transformation function.
 */
export interface IKosTopicHandlerParams<Response = any, Model extends IKosDataModel = any, TransformedResponse = Response> {
    /**
     * The topic or array of topics to which the handler should respond.
     */
    topic: string | string[];
    /**
     * A conditional function that determines whether the handler should be invoked based on the received payload and the Kos Data Model instance.
     * If not provided, the handler will always be invoked when a matching topic is received.
     *
     * @param payload - The transformed payload received from the topic.
     * @param model - The Kos Data Model instance to which the topic handler belongs.
     * @returns `true` if the handler should be invoked, `false` otherwise.
     */
    condition?: (payload: TransformedResponse, model: Model, raw: Response) => boolean;
    /**
     * A transformation function that converts the raw response payload into a desired format.
     * If not provided, the payload will be used as is.
     *
     * @param payload - The raw response payload received from the topic.
     * @returns The transformed payload in the desired format.
     */
    transform?: (payload: Response) => TransformedResponse;
    /**
     * Indicates whether the topic handler should listen for WebSocket messages.
     * If set to `true`, the handler will be invoked when WebSocket messages with matching topics are received.
     * Default is `false`.
     */
    websocket?: boolean;
    /**
     * @internal
     */
    fos?: boolean;
    /**
     * @internal
     */
    bridge?: boolean;
    lifecycle?: DependencyLifecycle;
    /**
     * @internal
     */
    skipParse?: boolean;
    destinationAddress?: string;
    /**
     * Debounce events - only emit after a period of inactivity
     * @example debounce: 1000 // Wait 1 second after last event
     * @example debounce: { delay: 1000, discardIntermediate: true } // Only keep last value
     */
    debounce?: number | {
        delay: number;
        /** If true, only keeps the last value. If false (default), accumulates all values */
        discardIntermediate?: boolean;
    };
    /**
     * Throttle events - limit emissions to once per interval
     * @example throttle: 500 // At most once every 500ms
     * @example throttle: { interval: 500, discardIntermediate: true } // Only keep first value in window
     */
    throttle?: number | {
        interval: number;
        /** If true, only keeps the first value in window. If false (default), accumulates all values */
        discardIntermediate?: boolean;
    };
    /**
     * Buffer events and emit them as an array after time window or max size
     */
    buffer?: {
        /** Time window to collect events (ms) */
        time: number;
        /** Maximum number of events to buffer */
        maxSize?: number;
    };
    /**
     * Filter events based on a predicate function
     * Note: This operates on the raw payload before transformation
     */
    filter?: (payload: Response) => boolean;
    /**
     * Only handle the event once, then automatically unsubscribe
     */
    once?: boolean;
    /**
     * Replay the last N events to new handlers
     */
    replay?: {
        /** Number of events to remember and replay */
        bufferSize: number;
    };
    /**
     * Named wildcard capture for trailing /* patterns.
     * When enabled, the portion after the /* is parsed and passed to the handler.
     * You can optionally specify a name for the captured segment.
     *
     * @example
     * ```typescript
     * @kosTopicHandler({
     *   topic: "/config/system/*",
     *   websocket: true,
     *   wildcardName: "configPath"
     * })
     * handleConfigUpdate(payload: ConfigData, raw: ApiCallbackWithWildcard<any>) {
     *   // raw.wildcardCapture.configPath contains everything after "/config/system/"
     * }
     * ```
     */
    wildcardName?: string;
    /**
     * Advanced flow control options using async iterators internally.
     * Enables sophisticated event processing patterns like batching, backpressure,
     * on-the-fly transforms, and rate limiting.
     *
     * @example
     * ```typescript
     * @kosTopicHandler({
     *   topic: 'sensor.data',
     *   websocket: true,
     *   flow: {
     *     batch: { size: 50, window: 1000 },
     *     transform: (events) => aggregateEvents(events),
     *     backpressure: { maxConcurrent: 3 }
     *   }
     * })
     * handleProcessedEvents(aggregatedData) {
     *   // Receives transformed, batched data with backpressure control
     * }
     * ```
     */
    flow?: FlowControlOptions<Response, TransformedResponse>;
}
/**
 * Decorator for defining a Kos topic handler function within a Kos Data Model class.
 *
 * @param params - An object containing configuration parameters for the topic handler.
 * @returns A decorator function.
 *
 * @example Basic usage:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'temperature/update',
 *   websocket: true
 * })
 * handleTemperature(payload: TemperatureData) { }
 * ```
 *
 * @example Debounced handling:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'rapid/updates',
 *   websocket: true,
 *   debounce: 1000 // Wait 1 second after last event
 * })
 * handleRapidUpdates(payload: UpdateData) { }
 * ```
 *
 * @example Buffered batch processing:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'log/entry',
 *   websocket: true,
 *   buffer: { time: 5000, maxSize: 100 }
 * })
 * handleLogBatch(entries: LogEntry[]) { }
 * ```
 *
 * @example Trailing wildcard with custom name:
 * ```typescript
 * @kosTopicHandler({
 *   topic: '/config/system/*',
 *   websocket: true,
 *   wildcardName: 'configPath'
 * })
 * handleConfigUpdate(payload: ConfigData, raw: ApiCallbackWithWildcard<any>) {
 *   // raw.wildcardCapture.configPath = "network/timeout" (everything after "/config/system/")
 * }
 * ```
 *
 * @example Trailing wildcard with PropKeys:
 * ```typescript
 * const DEVICE_ID = createPropKey<DeviceModel>('deviceId');
 *
 * @kosTopicHandler({
 *   topic: `/devices/${DEVICE_ID}/sensors/*`,
 *   websocket: true,
 *   wildcardName: 'sensorPath'
 * })
 * handleSensorEvent(payload: SensorData, raw: ApiCallbackWithWildcard<any>) {
 *   // raw.wildcardCapture.sensorPath = "temperature/reading" (everything after device-specific prefix)
 * }
 * ```
 * @category KOS Model Decorator
 */
export declare function kosTopicHandler<Response = any, Model extends IKosDataModel = any, TransformedResponse = Response>({ topic, condition, transform, websocket, fos, bridge, skipParse, lifecycle, destinationAddress, debounce, throttle, buffer, filter, once, replay, wildcardName, flow, }: IKosTopicHandlerParams<Response, Model, TransformedResponse>): (target: any, _propertyKey: string, descriptor: PropertyDescriptor) => void;
//# sourceMappingURL=kosTopicHandler.d.ts.map