import { IKosDataModel } from '../../../core';
import { FutureEndState } from '../../services/future';
/**
 * Basic Future delegation interface for models that hold a single Future reference.
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 2
 */
export interface FutureDelegate<T extends {} = Record<string, unknown>> {
    future?: IFutureModel<T>;
}
/**
 * Container pattern for managing multiple Future operations in KOS models.
 *
 * Provides comprehensive Future management capabilities for models that handle
 * multiple concurrent long-running operations with centralized lifecycle management.
 *
 * @example Basic Future Container
 * ```typescript
 * @kosModel("device-operations-model")
 * export class DeviceOperationsModel implements FutureContainer {
 *   futureHandler: FutureAwareContainer;
 *
 *   constructor(modelId: string, options: any, context: KosCreationContext) {
 *     this.id = modelId;
 *     this.futureHandler = new FutureHandler(this);
 *   }
 *
 *   onFutureUpdate(future: IFutureModel, alias?: string): void {
 *     // Handle progress updates from any managed Future
 *     console.log(`Operation ${alias || future.id}: ${future.progress}%`);
 *   }
 * }
 * ```
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 2
 */
export interface FutureContainer<T extends {} = Record<string, unknown>> {
    futureHandler: FutureAwareContainer<T>;
    onFutureUpdate?: (future: IFutureModel<T>, alias?: string) => void;
}
/**
 * Advanced pattern for models managing multiple named Future operations.
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 7
 */
export interface MultiFutureAware<T extends {} = Record<string, unknown>> {
    futureMap: Map<string, IFutureModel<T>>;
}
/**
 * Container interface providing comprehensive Future lifecycle management.
 *
 * Handles multiple concurrent Futures with operations for adding, removing,
 * and querying Future instances. Essential for complex models that coordinate
 * multiple device operations simultaneously.
 *
 * @example Future Container Operations
 * ```typescript
 * // Add new Future with optional alias
 * container.addFuture(calibrationFuture, 'pump-calibration');
 *
 * // Query specific Future
 * const future = container.getFuture('pump-calibration');
 *
 * // Remove completed Future
 * container.removeFuture('pump-calibration');
 *
 * // Get all active Futures
 * const activeFutures = container.allFutures;
 * ```
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 2
 */
export interface FutureAwareContainer<T extends {} = Record<string, unknown>> extends FutureDelegate<T> {
    removeFuture(alias?: string): void;
    getFuture(alias?: string): IFutureModel<T> | undefined;
    addFuture(future: IFutureModel<T>, alias?: string): void;
    allFutures: IFutureModel<T>[];
    onFutureUpdate?: (future: IFutureModel<T>, alias?: string) => void;
}
/**
 * Simplified interface for models that need basic Future awareness.
 *
 * Provides essential Future status information without full container complexity.
 * Ideal for models that typically handle single operations or need simple
 * Future integration.
 *
 * @example Basic Future Awareness
 * ```typescript
 * function OperationStatus({ model }: { model: FutureAware }) {
 *   return (
 *     <div>
 *       <p>Status: {model.status}</p>
 *       <progress value={model.progress} max={100} />
 *       <p>Time remaining: {model.timeRemaining}</p>
 *       {model.status === 'IN_PROGRESS' && (
 *         <button onClick={() => model.cancel()}>Cancel</button>
 *       )}
 *     </div>
 *   );
 * }
 * ```
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 2
 */
export interface FutureAware {
    readonly statusFuture?: IFutureModel;
    status: string;
    progress: number;
    timeRemaining: string;
    cancel: () => Promise<void>;
}
/**
 * Configuration options for Future model instances.
 *
 * Defines the initial state and parameters for Future operations including
 * progress tracking, client data attachment, and namespace configuration.
 *
 * @remarks
 * Used to identify additional data that can be set on the model during
 * instantiation. It is expected that implementers will set these properties
 * in the constructor. The value <strong>might</strong> be overridden by
 * subsequent lifecycle methods or updates.
 *
 * @example Basic Future Options
 * ```typescript
 * const futureOptions: IFutureModelOptions = {
 *   id: 'calibration-123',
 *   namespace: 'kos',
 *   progress: 0,
 *   clientData: { deviceId: 'pump-S4', targetRate: 1.2 }
 * };
 *
 * const future = FutureFactory.instance('my-future')
 *   .options(futureOptions)
 *   .build();
 * ```
 *
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @kosApiLevel 2
 */
export interface IFutureModelOptions<T extends {} = Record<string, unknown>> {
    id: string;
    tracker?: string;
    progress?: number;
    remainingTimeMs?: number;
    endState?: FutureEndState;
    reason?: string;
    namespace?: string;
    reasonData?: {
        name: string;
        version: string;
    } | {
        vmId: string;
        target: string;
    } | {
        vmId: string;
        target: string;
    }[];
    clientData?: T;
    note?: string;
}
/**
 * Future - Reactive long-running operation management for KOS devices and applications.
 *
 * The Future model provides comprehensive tracking and management of asynchronous operations
 * with real-time progress updates, cancellation support, and automatic lifecycle management.
 * Essential for building responsive user interfaces that handle time-consuming operations.
 *
 * ## Key Features
 * - **Real-Time Progress Tracking** - Live updates via WebSocket topics with percentage completion
 * - **Cancellation Support** - Ability to cancel in-progress operations safely
 * - **Automatic Cleanup** - Models self-destruct when operations complete or fail
 * - **Status Management** - Clear status reporting (NOT_ACTIVE, IN_PROGRESS, Success, Fail)
 * - **Time Estimation** - Remaining time calculations with localized formatting
 * - **Client Data Attachment** - Associate custom data with future operations
 * - **Namespace Support** - Separate futures for different services (kos, studio, etc.)
 *
 * ## Operation Lifecycle
 * Futures progress through distinct states with automatic status management:
 * - **NOT_ACTIVE** - Operation not yet started or queued
 * - **IN_PROGRESS** - Operation actively executing with progress updates
 * - **Success** - Operation completed successfully (triggers automatic cleanup)
 * - **Fail** - Operation failed with error details (triggers automatic cleanup)
 *
 * ## Common Use Cases
 * - **Device Operations** - Track pump calibration, system diagnostics, configuration updates
 * - **File Transfers** - Monitor upload/download progress with cancellation support
 * - **System Updates** - Track firmware updates, package installations, system maintenance
 * - **Data Processing** - Monitor analysis operations, report generation, bulk operations
 * - **VM Management** - Track VM creation, deployment, and lifecycle operations
 *
 * @example Basic Future Tracking
 * ```typescript
 * const calibrationFuture = FutureFactory.instance('calibration-op')
 *   .options({
 *     id: 'pump-cal-123',
 *     namespace: 'kos',
 *     clientData: { pumpId: 'S4', targetRate: 0.9 }
 *   })
 *   .build();
 *
 * // Monitor progress
 * console.log(`Status: ${calibrationFuture.status}`);
 * console.log(`Progress: ${calibrationFuture.progress}%`);
 * console.log(`Time remaining: ${calibrationFuture.timeRemaining}`);
 *
 * // Cancel if needed
 * await calibrationFuture.cancelFuture();
 * ```
 *
 * @example React Integration
 * ```typescript
 * function CalibrationProgress({ futureId }: { futureId: string }) {
 *   const future = useFuture(futureId);
 *
 *   return (
 *     <div>
 *       <progress value={future.progress} max={100} />
 *       <p>{future.timeRemaining} remaining</p>
 *       {future.status === 'IN_PROGRESS' && (
 *         <button onClick={() => future.cancelFuture()}>
 *           Cancel Operation
 *         </button>
 *       )}
 *     </div>
 *   );
 * }
 * ```
 *
 * @interface
 * @kosService core.future-aware
 * @group KOS Model
 * @category Asynchronous Operations
 * @useDeclaredType
 *
 * @see {@link IFutureModelOptions} - Configuration options for Future instances
 * @see {@link FutureAware} - Interface for models that integrate with Futures
 * @see {@link FutureContainer} - Container pattern for managing multiple Futures
 * @kosApiLevel 2
 */
export interface IFutureModel<T extends {} = Record<string, unknown>> extends IKosDataModel, Omit<IFutureModelOptions<T>, "modifyFuture"> {
    id: string;
    progress: number;
    remainingTimeMs: number;
    endState?: FutureEndState;
    reason?: string;
    reasonData?: {
        vmId: string;
        target: string;
    } | {
        vmId: string;
        target: string;
    }[];
    clientData?: T;
    note?: string;
    futureId: string;
    status: string;
    cancelFuture: () => Promise<void>;
    timeRemaining: string;
}
//# sourceMappingURL=future-types.d.ts.map