Interface IFutureModel<T>

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

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();
Copy

Example: React Integration

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>
  );
}
Copy

Use Declared Type

See

• IFutureModelOptions - Configuration options for Future instances
• FutureAware - Interface for models that integrate with Futures
• FutureContainer - Container pattern for managing multiple Futures