/**
 * @module cancellation
 * Cancellation token support for xBind operations
 *
 * Provides AbortController/AbortSignal integration for enhanced operation control:
 * - Cancellable async operations (fetch, agent.call, transport)
 * - Timeout management with automatic cleanup
 * - Composite signals (multiple cancellation sources)
 * - Resource cleanup on cancellation
 *
 * Architecture:
 * - Uses standard AbortController/AbortSignal (Web API + Node.js)
 * - Timeout wrapper creates time-limited signals
 * - Composite signals combine multiple cancellation sources
 * - Cleanup callbacks ensure proper resource disposal
 *
 * @example
 * ```typescript
 * // Timeout with cancellation
 * const signal = createTimeoutSignal(5000);
 * await xfetch('https://api.example.com', { signal });
 *
 * // Manual cancellation
 * const controller = new AbortController();
 * setTimeout(() => controller.abort(), 1000);
 * await agent.call('tool:action', params, { signal: controller.signal });
 *
 * // Composite signals
 * const timeout = createTimeoutSignal(10000);
 * const manual = new AbortController();
 * const combined = combineSignals([timeout.signal, manual.signal]);
 * await operation({ signal: combined });
 * ```
 */
import type { Result } from '@private.me/shared';
/**
 * Cancellation error thrown when operation is aborted
 */
export declare class CancellationError extends Error {
    reason?: string | undefined;
    context?: Record<string, unknown> | undefined;
    constructor(message: string, reason?: string | undefined, context?: Record<string, unknown> | undefined);
}
/**
 * Cleanup callback type for resource disposal
 */
export type CleanupCallback = () => void | Promise<void>;
/**
 * Timeout signal controller with cleanup
 */
export interface TimeoutController {
    /** Abort signal that triggers on timeout */
    signal: AbortSignal;
    /** Clear timeout (prevents abort) */
    clear: () => void;
    /** Remaining time in milliseconds */
    remaining: () => number;
}
/**
 * Options for creating timeout signals
 */
export interface TimeoutOptions {
    /** Timeout in milliseconds */
    timeout: number;
    /** Optional reason message */
    reason?: string;
    /** Optional context for debugging */
    context?: Record<string, unknown>;
}
/**
 * Create an AbortSignal that triggers after a timeout
 *
 * Automatically aborts the signal after the specified duration.
 * Useful for setting time limits on async operations.
 *
 * @param timeout - Timeout in milliseconds
 * @param options - Optional reason and context
 * @returns TimeoutController with signal and clear function
 *
 * @example
 * ```typescript
 * const timeout = createTimeoutSignal(5000);
 * try {
 *   await fetch('https://api.example.com', { signal: timeout.signal });
 * } catch (error) {
 *   if (error.name === 'AbortError') {
 *     console.log('Request timed out after 5s');
 *   }
 * } finally {
 *   timeout.clear(); // Clean up timer
 * }
 * ```
 */
export declare function createTimeoutSignal(timeout: number, options?: Omit<TimeoutOptions, 'timeout'>): TimeoutController;
/**
 * Combine multiple AbortSignals into a single signal
 *
 * The combined signal aborts when ANY of the source signals abort.
 * Useful for operations with multiple cancellation sources (timeout, user action, etc.).
 *
 * @param signals - Array of signals to combine
 * @returns Combined AbortSignal
 *
 * @example
 * ```typescript
 * const timeout = createTimeoutSignal(10000);
 * const userCancel = new AbortController();
 * const combined = combineSignals([timeout.signal, userCancel.signal]);
 *
 * // Either timeout OR user cancellation will abort
 * await fetch('https://api.example.com', { signal: combined });
 * ```
 */
export declare function combineSignals(signals: AbortSignal[]): AbortSignal;
/**
 * Register cleanup callback to run when signal is aborted
 *
 * Ensures resources are properly disposed when operation is cancelled.
 * Cleanup runs immediately if signal is already aborted.
 *
 * @param signal - AbortSignal to monitor
 * @param cleanup - Cleanup callback
 *
 * @example
 * ```typescript
 * const controller = new AbortController();
 * const connection = await openConnection();
 *
 * onCancellation(controller.signal, async () => {
 *   console.log('Cleaning up connection...');
 *   await connection.close();
 * });
 *
 * // Later...
 * controller.abort(); // Cleanup runs automatically
 * ```
 */
export declare function onCancellation(signal: AbortSignal, cleanup: CleanupCallback): void;
/**
 * Check if signal is aborted and throw CancellationError if so
 *
 * Useful for checking cancellation at specific points in long-running operations.
 *
 * @param signal - AbortSignal to check
 * @param context - Optional context for error
 * @throws CancellationError if signal is aborted
 *
 * @example
 * ```typescript
 * async function processLargeDataset(data: unknown[], signal?: AbortSignal) {
 *   for (const item of data) {
 *     throwIfAborted(signal, { item: item.id });
 *     await processItem(item);
 *   }
 * }
 * ```
 */
export declare function throwIfAborted(signal?: AbortSignal, context?: Record<string, unknown>): void;
/**
 * Wrap a promise with cancellation support
 *
 * If signal aborts before promise resolves, returns error result.
 * Otherwise returns the promise's result.
 *
 * @param promise - Promise to wrap
 * @param signal - AbortSignal for cancellation
 * @returns Result wrapper around promise
 *
 * @example
 * ```typescript
 * const timeout = createTimeoutSignal(5000);
 * const result = await withCancellation(
 *   fetch('https://api.example.com'),
 *   timeout.signal
 * );
 *
 * if (!result.ok) {
 *   console.error('Request cancelled:', result.error.message);
 * }
 * ```
 */
export declare function withCancellation<T>(promise: Promise<T>, signal?: AbortSignal): Promise<Result<T, CancellationError>>;
/**
 * Create a cancellable delay
 *
 * Returns a promise that resolves after the specified duration,
 * but can be cancelled early via signal.
 *
 * @param ms - Delay in milliseconds
 * @param signal - Optional AbortSignal for cancellation
 * @returns Promise that resolves after delay or rejects on cancellation
 *
 * @example
 * ```typescript
 * const controller = new AbortController();
 *
 * // Start 10s delay
 * const delayPromise = delay(10000, controller.signal);
 *
 * // Cancel after 2s
 * setTimeout(() => controller.abort(), 2000);
 *
 * try {
 *   await delayPromise; // Throws CancellationError after 2s
 * } catch (error) {
 *   console.log('Delay cancelled');
 * }
 * ```
 */
export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
/**
 * Retry an operation with cancellation support
 *
 * Attempts operation multiple times with exponential backoff.
 * Respects cancellation signal between retry attempts.
 *
 * @param operation - Async operation to retry
 * @param options - Retry configuration
 * @returns Result of operation
 *
 * @example
 * ```typescript
 * const timeout = createTimeoutSignal(30000);
 *
 * const result = await withRetry(
 *   async () => {
 *     const res = await fetch('https://api.example.com');
 *     if (!res.ok) throw new Error('Request failed');
 *     return res.json();
 *   },
 *   {
 *     maxAttempts: 5,
 *     initialDelay: 1000,
 *     multiplier: 2,
 *     signal: timeout.signal,
 *   }
 * );
 * ```
 */
export declare function withRetry<T>(operation: () => Promise<T>, options?: {
    maxAttempts?: number;
    initialDelay?: number;
    multiplier?: number;
    signal?: AbortSignal;
    shouldRetry?: (error: unknown, attempt: number) => boolean;
}): Promise<Result<T, Error>>;
/**
 * Create a manual cancellation controller with helper methods
 *
 * Extends AbortController with additional utilities for common patterns.
 *
 * @returns Enhanced controller with helper methods
 *
 * @example
 * ```typescript
 * const controller = createCancellationController();
 *
 * // Start operation
 * const promise = longRunningOperation({ signal: controller.signal });
 *
 * // Cancel with custom reason
 * controller.cancel('User requested cancellation');
 *
 * // Check if cancelled
 * if (controller.isCancelled) {
 *   console.log('Operation was cancelled');
 * }
 * ```
 */
export declare function createCancellationController(): {
    /** Abort signal for cancellation */
    signal: AbortSignal;
    /** True if operation has been cancelled */
    readonly isCancelled: boolean;
    /** Reason for cancellation (if any) */
    readonly reason: string | undefined;
    /** Cancel the operation with optional reason */
    cancel(reason?: string): void;
    /** Throw if cancelled */
    throwIfCancelled(context?: Record<string, unknown>): void;
};
/**
 * Check if an error is a cancellation error
 *
 * @param error - Error to check
 * @returns True if error is from cancellation
 *
 * @example
 * ```typescript
 * try {
 *   await operation({ signal });
 * } catch (error) {
 *   if (isCancellationError(error)) {
 *     console.log('Operation was cancelled');
 *   } else {
 *     console.error('Operation failed:', error);
 *   }
 * }
 * ```
 */
export declare function isCancellationError(error: unknown): error is CancellationError;
