/**
 * @fileoverview Async iterator API for xBind message streams.
 *
 * Provides modern async iteration patterns for consuming message streams
 * with backpressure handling, stream cancellation, and error propagation.
 *
 * @example
 * ```typescript
 * // Subscribe to messages with async iteration
 * for await (const message of agent.subscribe({ from: 'did:key:alice' })) {
 *   console.log('Received:', message.payload);
 * }
 * ```
 *
 * @module async-iterators
 */
import type { Agent, AgentMessage } from './agent.js';
/**
 * Options for message stream subscription.
 */
export interface MessageStreamOptions {
    /**
     * Filter messages by sender DID.
     * If undefined, accepts messages from all senders.
     */
    readonly from?: string;
    /**
     * Filter messages by scope.
     * If undefined, accepts messages with any scope.
     */
    readonly scope?: string;
    /**
     * Maximum number of buffered messages before backpressure.
     * When buffer is full, new messages are dropped until consumed.
     * Default: 100
     */
    readonly bufferSize?: number;
    /**
     * Signal to abort the stream.
     * When aborted, the iterator completes and cleans up resources.
     */
    readonly signal?: AbortSignal;
    /**
     * Allow cleartext messages (signed but not encrypted).
     * Default: false
     */
    readonly allowCleartext?: boolean;
}
/**
 * Async iterable message stream.
 *
 * Implements AsyncIterableIterator for use with `for await...of` syntax.
 * Handles backpressure, cancellation, and error propagation.
 */
export declare class MessageStream implements AsyncIterableIterator<AgentMessage> {
    private readonly agent;
    private readonly options;
    private readonly state;
    constructor(agent: Agent, options?: MessageStreamOptions);
    /**
     * Handle incoming envelope from transport.
     * @internal
     */
    private handleEnvelope;
    /**
     * Close the stream with optional error.
     * @internal
     */
    private close;
    /**
     * Get next message from the stream.
     *
     * Returns a promise that resolves when:
     * - A message is available in the buffer
     * - A new message arrives from the transport
     * - The stream is closed
     *
     * @returns Promise resolving to iterator result
     */
    next(): Promise<IteratorResult<AgentMessage>>;
    /**
     * Return method for iterator protocol.
     * Closes the stream and completes iteration.
     *
     * @param _value - Optional value (ignored)
     * @returns Promise resolving to done result
     */
    return(_value?: unknown): Promise<IteratorResult<AgentMessage>>;
    /**
     * Throw method for iterator protocol.
     * Closes the stream with error.
     *
     * @param error - Error to propagate
     * @returns Promise resolving to done result
     */
    throw(error?: unknown): Promise<IteratorResult<AgentMessage>>;
    /**
     * Make this object async iterable.
     * Enables `for await...of` syntax.
     *
     * @returns This stream instance
     */
    [Symbol.asyncIterator](): AsyncIterableIterator<AgentMessage>;
    /**
     * Get number of buffered messages.
     * Useful for monitoring backpressure.
     */
    get bufferedCount(): number;
    /**
     * Check if stream is closed.
     */
    get closed(): boolean;
    /**
     * Get stream error if any.
     */
    get error(): Error | undefined;
}
/**
 * Options for batch message collection.
 */
export interface CollectOptions extends MessageStreamOptions {
    /**
     * Maximum number of messages to collect.
     * Stream completes after collecting this many messages.
     * If undefined, collects indefinitely until stream ends.
     */
    readonly limit?: number;
    /**
     * Timeout in milliseconds.
     * Stream completes after this duration regardless of message count.
     * If undefined, no timeout (waits indefinitely).
     */
    readonly timeout?: number;
}
/**
 * Collect messages from a stream into an array.
 *
 * Useful for batch processing or testing. Stream completes when:
 * - Limit is reached
 * - Timeout expires
 * - Stream is aborted via signal
 *
 * @param agent - Agent instance to collect messages from
 * @param options - Collection options
 * @returns Promise resolving to array of messages
 *
 * @example
 * ```typescript
 * // Collect up to 10 messages with 5 second timeout
 * const messages = await collectMessages(agent, {
 *   from: 'did:key:alice',
 *   limit: 10,
 *   timeout: 5000
 * });
 * ```
 */
export declare function collectMessages(agent: Agent, options?: CollectOptions): Promise<AgentMessage[]>;
/**
 * Transform message stream with async mapping function.
 *
 * Enables functional-style stream processing with backpressure preservation.
 *
 * @param stream - Source message stream
 * @param fn - Async transform function
 * @returns Async iterable of transformed values
 *
 * @example
 * ```typescript
 * const stream = agent.subscribe({ from: 'did:key:alice' });
 * const payloads = mapStream(stream, async (msg) => msg.payload);
 *
 * for await (const payload of payloads) {
 *   console.log('Payload:', payload);
 * }
 * ```
 */
export declare function mapStream<T, U>(stream: AsyncIterable<T>, fn: (value: T) => Promise<U> | U): AsyncIterableIterator<U>;
/**
 * Filter message stream with async predicate.
 *
 * Only yields messages that satisfy the predicate.
 *
 * @param stream - Source message stream
 * @param predicate - Async filter predicate
 * @returns Async iterable of filtered messages
 *
 * @example
 * ```typescript
 * const stream = agent.subscribe({ scope: 'notifications' });
 * const urgent = filterStream(stream, async (msg) =>
 *   msg.payload.priority === 'high'
 * );
 *
 * for await (const message of urgent) {
 *   await handleUrgent(message);
 * }
 * ```
 */
export declare function filterStream<T>(stream: AsyncIterable<T>, predicate: (value: T) => Promise<boolean> | boolean): AsyncIterableIterator<T>;
/**
 * Take first N messages from stream.
 *
 * Stream completes after yielding N messages.
 *
 * @param stream - Source message stream
 * @param count - Maximum messages to take
 * @returns Async iterable with at most count messages
 *
 * @example
 * ```typescript
 * const stream = agent.subscribe();
 * const first5 = takeStream(stream, 5);
 *
 * for await (const message of first5) {
 *   console.log('Message:', message);
 * }
 * ```
 */
export declare function takeStream<T>(stream: AsyncIterable<T>, count: number): AsyncIterableIterator<T>;
/**
 * Merge multiple message streams into one.
 *
 * Yields messages from all streams as they arrive.
 * Completes when all source streams complete.
 *
 * @param streams - Array of source streams
 * @returns Async iterable of merged messages
 *
 * @example
 * ```typescript
 * const stream1 = agent.subscribe({ from: 'did:key:alice' });
 * const stream2 = agent.subscribe({ from: 'did:key:bob' });
 * const merged = mergeStreams([stream1, stream2]);
 *
 * for await (const message of merged) {
 *   console.log('From:', message.sender);
 * }
 * ```
 */
export declare function mergeStreams<T>(streams: AsyncIterable<T>[]): AsyncIterableIterator<T>;
declare module './agent.js' {
    interface Agent {
        /**
         * Subscribe to incoming messages as an async iterable stream.
         *
         * Enables modern async iteration patterns with `for await...of` syntax.
         * Handles backpressure, cancellation, and error propagation.
         *
         * @param options - Stream subscription options
         * @returns Async iterable message stream
         *
         * @example
         * ```typescript
         * // Subscribe to all messages from Alice
         * for await (const message of agent.subscribe({ from: 'did:key:alice' })) {
         *   console.log('Received:', message.payload);
         * }
         *
         * // With abort signal
         * const controller = new AbortController();
         * setTimeout(() => controller.abort(), 5000); // 5 second timeout
         *
         * for await (const message of agent.subscribe({ signal: controller.signal })) {
         *   console.log('Message:', message);
         * }
         * ```
         */
        subscribe(options?: MessageStreamOptions): MessageStream;
    }
}
/**
 * Add subscribe method to Agent prototype.
 * @internal
 */
export declare function installAsyncIterators(AgentClass: typeof Agent): void;
