/**
 * Stream Helpers
 *
 * Standardized utilities for handling async iterables and stream operations
 * with proper error handling, timeouts, and iteration limits.
 */
export interface StreamTimeoutOptions {
    /** Timeout in milliseconds between iterations */
    timeoutMs: number;
    /** Custom error message for timeout */
    errorMessage?: string;
}
export interface SafeStreamReadOptions {
    /** Context for error logging */
    context?: string;
    /** Whether to release the lock on error */
    releaseLockOnError?: boolean;
    /** Maximum number of retry attempts for transient errors */
    maxRetries?: number;
}
export interface SafeStreamReadResult<T> {
    /** Whether the read was successful */
    success: boolean;
    /** The value read from the stream (if successful and not done) */
    value?: T;
    /** Whether the stream is done */
    done: boolean;
    /** Error if the read failed */
    error?: Error;
}
export interface StreamErrorContext {
    /** Source of the stream error */
    source: string;
    /** Operation being performed when error occurred */
    operation?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Wraps an async iterable with a timeout between iterations.
 *
 * If no value is yielded within the timeout period, throws a TimeoutError.
 * This is useful for preventing infinite waits on streaming responses.
 *
 * @example
 * ```typescript
 * // Add 30 second timeout between chunks
 * for await (const chunk of withStreamTimeout(stream, { timeoutMs: 30000 })) {
 *   process.stdout.write(chunk);
 * }
 * ```
 */
export declare function withStreamTimeout<T>(asyncIterable: AsyncIterable<T>, options: StreamTimeoutOptions): AsyncGenerator<T, void, undefined>;
/**
 * Safely reads from a ReadableStreamDefaultReader with error handling.
 *
 * Wraps the read operation with proper error catching and optional retry logic.
 * Returns a result object instead of throwing, making it easier to handle errors.
 *
 * @example
 * ```typescript
 * const reader = response.body?.getReader();
 * if (!reader) throw new Error('No body');
 *
 * while (true) {
 *   const result = await safeStreamRead(reader, { context: 'OllamaStream' });
 *   if (!result.success) {
 *     handleStreamError(result.error!, { source: 'OllamaProvider' });
 *     break;
 *   }
 *   if (result.done) break;
 *   processChunk(result.value);
 * }
 * ```
 */
export declare function safeStreamRead<T>(reader: ReadableStreamDefaultReader<T>, options?: SafeStreamReadOptions): Promise<SafeStreamReadResult<T>>;
/**
 * Limits the number of iterations on an async iterator to prevent infinite loops.
 *
 * This is a safety mechanism for streams that might not terminate properly.
 * When the max is reached, the iterator is gracefully terminated.
 *
 * @example
 * ```typescript
 * // Limit to 1000 chunks maximum
 * for await (const chunk of withMaxIterations(stream, 1000)) {
 *   processChunk(chunk);
 * }
 * ```
 */
export declare function withMaxIterations<T>(asyncIterable: AsyncIterable<T>, maxIterations: number, options?: {
    /** Callback when max iterations reached */
    onMaxReached?: (count: number) => void;
    /** Context for logging */
    context?: string;
}): AsyncGenerator<T, void, undefined>;
/**
 * Standardized error logging for stream operations.
 *
 * Provides consistent error formatting and logging for all stream-related errors.
 * Also categorizes errors to help with debugging and monitoring.
 *
 * @example
 * ```typescript
 * try {
 *   for await (const chunk of stream) {
 *     processChunk(chunk);
 *   }
 * } catch (error) {
 *   handleStreamError(error, {
 *     source: 'OllamaProvider',
 *     operation: 'streaming response',
 *     metadata: { model: 'llama3.1' }
 *   });
 * }
 * ```
 */
export declare function handleStreamError(error: unknown, context: StreamErrorContext): {
    message: string;
    category: 'timeout' | 'network' | 'parse' | 'abort' | 'unknown';
    isRetryable: boolean;
};
/**
 * Creates an AbortController with automatic timeout.
 *
 * Returns both the controller and a cleanup function to cancel the timeout.
 *
 * @example
 * ```typescript
 * const { controller, cleanup } = createTimeoutController(30000);
 * try {
 *   const response = await fetch(url, { signal: controller.signal });
 *   // process response
 * } finally {
 *   cleanup();
 * }
 * ```
 */
export declare function createTimeoutController(timeoutMs: number): {
    controller: AbortController;
    cleanup: () => void;
};
/**
 * Combines multiple AsyncIterables into one, yielding values as they arrive.
 *
 * Useful for merging multiple streams into a single stream.
 *
 * @example
 * ```typescript
 * const combined = mergeAsyncIterables([stream1, stream2, stream3]);
 * for await (const value of combined) {
 *   console.log(value);
 * }
 * ```
 */
export declare function mergeAsyncIterables<T>(iterables: AsyncIterable<T>[]): AsyncGenerator<T, void, undefined>;
/**
 * Drains an async iterable, consuming all values without processing.
 *
 * Useful for ensuring a stream is fully consumed (e.g., for cleanup).
 *
 * @example
 * ```typescript
 * // Ensure stream is fully consumed even if we don't need all values
 * await drainAsyncIterable(response.body);
 * ```
 */
export declare function drainAsyncIterable<T>(asyncIterable: AsyncIterable<T>, options?: {
    maxIterations?: number;
}): Promise<number>;
