@kosdev-code/kos-ui-sdk 2.0.44 → 2.0.45

package/models/models/device/device-registration.d.ts

@@ -3,87 +3,100 @@ import { DeviceModel } from './device-model';
 import { SingletonKosModelRegistrationFactory } from '../../../core';
 
 /**
- * # Device
+ * # Device Model Registration Factory
  *
- * The registration bean includes convenience methods for creating and working with DeviceModel instances.
+ * **KOS Device Identity and Node Configuration Management**
  *
- * ## type
- * The type property is a string that identifies the model type.
- * The type is used to identify the model type in the model registry and to narrow down the model type in type predicates.  It's most frequently
- * used when declaring dependencies on models.
+ * The Device registration factory provides convenient methods for creating and working with DeviceModel instances.
+ * Device models handle device identity, hardware serial numbers, and node configuration within KOS deployments.
  *
- * @example
- * ```typescript
+ * ## Core Registration Properties
+ *
+ * ### type
+ *
+ * Model type identifier used for dependency injection and type narrowing.
+ * Essential for declaring model dependencies in other components.
  *
+ * @example Model Dependency Declaration
+ * ```typescript
  * @kosDependency({modelType: Device.type, id: "deviceId"})
  * private deviceModel: DeviceModel;
  * ```
  *
+ * ### factory
  *
- * ## factory
+ * Creates DeviceModel instances with singleton behavior. Multiple calls return the same instance,
+ * ensuring system-wide device identity consistency.
  *
- * The factory method creates a factory function that can be used to create new DeviceModel instances.
+ * **Singleton Behavior**: Subsequent factory calls return existing instance; options ignored after first creation.
  *
- 
- * As this is a singleton model, the factory function accepts the model options as its argument.
+ * @example Device Creation and Identity Access
+ * ```typescript
+ * const device = Device.factory({
+ *   serialNumber: 'KOS-DEVICE-001',
+ *   name: 'Production Dispenser Alpha',
+ *   nodeId: 'primary-controller'
+ * });
  *
- * If a model with the same model type already exists, the factory function will return the existing model.  The options will be ignored
- * in this case and the existing model will be returned in its current state.
+ * // Access device identity
+ * console.log(`Device: ${device.name} (${device.serialNumber})`);
+ * console.log(`Node: ${device.nodeType}-${device.nodeName}`);
+ * ```
  *
- * @example
+ * @example Multi-node System Coordination
  * ```typescript
- * const model = Device.factory({
- *   // Add option data
- * });
+ * const primaryDevice = Device.factory({ nodeId: 'primary-main' });
+ * const backupDevice = Device.factory({ nodeId: 'secondary-backup' });
+ *
+ * // Coordinate based on node roles
+ * if (primaryDevice.nodeType === 'primary') {
+ *   // Handle primary node responsibilities
+ * }
  * ```
- 
-
  *
- * ## predicate
+ * ### predicate
  *
- * [Typescript type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) function that will identify and narrow down a model to a DeviceModel.
+ * [TypeScript type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates)
+ * for identifying and narrowing models to DeviceModel instances.
  *
- * @example
+ * @example Type Narrowing for Device Operations
  * ```typescript
- *
- * const model: IKosDataModel = ...; // some model
+ * const model: IKosDataModel = getModel(); // some model
  *
  * if (Device.predicate(model)) {
- *    // if the function evaluates to true, the model is narrowed down to DeviceModel
- *    // and the compiler will know that the model has the DeviceModel interface
- *    model.updateAvailability(false);
+ *   // Compiler now knows model is DeviceModel
+ *   console.log(`Device Serial: ${model.serialNumber}`);
+ *   model.updateModel({ name: 'Updated Name' });
  * }
  * ```
  *
- * ## registration
- *
- * The registration property is an object that can be used to simplify registration of the model with the model registry.  The registration object
- * can be spread into the model registration and provides all of the required information to register the model implementation class against the model type.
+ * ### registration
  *
+ * Registration object for model registry integration. Provides all required information
+ * for registering the DeviceModelImpl implementation with the model registry.
  *
- * @example
- *
- * In an application registration file you can declare the model registration as follows:
- *
- * **registration.ts**
+ * @example Model Registry Configuration
  * ```typescript
+ * // registration.ts
  * import { Device } from "@kos-ui/project-models";
  * import { KosModelRegistry } from "@kosdev-code/kos-dispense-sdk";
  *
- * import { initKosProvider } from "@kosdev-code/kos-ui-sdk";
- *
  * KosModelRegistry.dispense
- * .models()
- * .model(Device);
+ *   .models()
+ *   .model(Device);
  * ```
  *
- * ## registration.singleton
- 
- * The device model is a singleton model.  This means that each time the factory function is called , the same instance will be returned.
- * If the model does not yet exist, it will be created passing in the provided options to initialize it.
+ * ## Singleton Architecture
+ *
+ * **Device models use singleton pattern** ensuring system-wide consistency:
+ * - Each device type has exactly one instance
+ * - Subsequent factory calls return existing instance
+ * - Options are ignored after initial creation
+ * - Uses model type as unique identifier
+ * - Guarantees device identity consistency across system
  *
- * Singleton models don't require an ID as they will use the model type as their ID to guarantee uniqueness throughout the system.
- 
- * */
+ * @group KOS Model
+ * @category Device Data
+ */
 export declare const Device: SingletonKosModelRegistrationFactory<DeviceModel, DeviceOptions>;
 //# sourceMappingURL=device-registration.d.ts.map

package/models/models/device/device-registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/device/device-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkFK;AACL,eAAO,MAAM,MAAM,kEAMjB,CAAC"}
+{"version":3,"file":"device-registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/device/device-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AACH,eAAO,MAAM,MAAM,kEAMjB,CAAC"}

package/models/models/device/types/index.d.ts

@@ -1,5 +1,47 @@
+/**
+ * Configuration options for Device model instances.
+ *
+ * Defines device identity and node-specific parameters for KOS device modeling.
+ * Device models represent the physical device identity and node configuration
+ * within a KOS system deployment.
+ *
+ * @example Basic Device Configuration
+ * ```typescript
+ * const deviceOptions: DeviceOptions = {
+ *   serialNumber: 'KOS-DEVICE-12345',
+ *   name: 'Main Beverage Dispenser',
+ *   nodeId: 'primary-node-01'
+ * };
+ *
+ * const device = Device.factory(deviceOptions);
+ * ```
+ *
+ * @kosService core.device
+ * @group KOS Model
+ * @category Service Integration
+ */
 export interface DeviceOptions {
+  /**
+   * Unique device serial number from hardware.
+   *
+   * Retrieved from the device's hardware identification system.
+   * Used for warranty tracking, support, and device-specific configuration.
+   */
   serialNumber?: string;
+
+  /**
+   * Human-readable device name for identification.
+   *
+   * Typically configured during device setup and used in administrative
+   * interfaces for device identification and management.
+   */
   name?: string;
+
+  /**
+   * Node identifier within the KOS deployment.
+   *
+   * Identifies the specific node role and instance within a multi-node
+   * KOS deployment. Format typically follows 'type-instance' pattern.
+   */
   nodeId?: string;
 }

package/models/models/future/future-aware.d.ts

@@ -1,5 +1,45 @@
 import { FutureAwareContainer, FutureContainer, IFutureModel, MultiFutureAware } from './future-types';
 
+/**
+ * Future handler for managing multiple concurrent long-running operations.
+ *
+ * Provides comprehensive lifecycle management for models that coordinate multiple
+ * device operations simultaneously. Each Future is tracked with its own alias
+ * and receives automatic progress updates and cleanup when operations complete.
+ *
+ * @example Managing Multiple Operations
+ * ```typescript
+ * @kosModel("device-maintenance-model")
+ * export class DeviceMaintenanceModel implements FutureContainer {
+ *   futureHandler: MultipleFutureHandler;
+ *
+ *   constructor(modelId: string, options: any, context: KosCreationContext) {
+ *     this.id = modelId;
+ *     this.futureHandler = new MultipleFutureHandler(this);
+ *   }
+ *
+ *   async startCalibration(deviceId: string): Promise<CalibrationResult> {
+ *     const future = await this.createFuture('/device/calibrate', { deviceId });
+ *     this.futureHandler.addFuture(future, `calibration-${deviceId}`);
+ *     return future;
+ *   }
+ *
+ *   async startCleaning(deviceId: string): Promise<CleaningResult> {
+ *     const future = await this.createFuture('/device/clean', { deviceId });
+ *     this.futureHandler.addFuture(future, `cleaning-${deviceId}`);
+ *     return future;
+ *   }
+ *
+ *   onFutureUpdate(future: IFutureModel): void {
+ *     // Handle progress updates from any managed Future
+ *     console.log(`${future.id}: ${future.progress}% complete`);
+ *   }
+ * }
+ * ```
+ *
+ * @group KOS Model
+ * @category Asynchronous Operations
+ */
 export declare class MultipleFutureHandler<T extends {} = Record<string, unknown>> implements FutureAwareContainer<T>, MultiFutureAware<T> {
     private futures;
     private defaultContext;
@@ -14,6 +54,48 @@ export declare class MultipleFutureHandler<T extends {} = Record<string, unknown
     getFuture(alias?: string): IFutureModel<T> | undefined;
     get futureMap(): Map<string, IFutureModel<T>>;
 }
+/**
+ * Future handler for managing single long-running operations with simplified API.
+ *
+ * Provides streamlined lifecycle management for models that typically handle
+ * one operation at a time. Automatically tracks progress and provides reactive
+ * status information for UI integration.
+ *
+ * @example Single Operation Management
+ * ```typescript
+ * @kosModel("brewing-system-model")
+ * export class BrewingSystemModel implements FutureContainer {
+ *   futureHandler: FutureHandler;
+ *
+ *   constructor(modelId: string, options: any, context: KosCreationContext) {
+ *     this.id = modelId;
+ *     this.futureHandler = new FutureHandler(this);
+ *   }
+ *
+ *   async startBrewingCycle(recipe: Recipe): Promise<BrewingResult> {
+ *     const future = await this.createFuture('/brewing/start', { recipe });
+ *     this.futureHandler.addFuture(future);
+ *     return future;
+ *   }
+ *
+ *   get isOperationActive(): boolean {
+ *     return this.futureHandler.status !== 'NOT_RESOLVED';
+ *   }
+ *
+ *   get operationProgress(): number {
+ *     return this.futureHandler.progress;
+ *   }
+ *
+ *   onFutureUpdate(future: IFutureModel): void {
+ *     // Handle progress updates from the active Future
+ *     console.log(`Brewing: ${future.progress}% complete`);
+ *   }
+ * }
+ * ```
+ *
+ * @group KOS Model
+ * @category Asynchronous Operations
+ */
 export declare class FutureHandler<T extends object = Record<string, unknown>> implements FutureAwareContainer<T> {
     private disposer?;
     private _future?;

package/models/models/future/future-aware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"future-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-aware.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,qBAAqB,CAAC,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACvE,YAAW,oBAAoB,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAEvD,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAC3B,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,MAAM;IAQnE,IAAI,UAAU,sBAEb;IAED,IAAI,MAAM,gCAET;IACD,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM;IAWjD,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM;IAM3B,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM;IAKxB,IAAI,SAAS,iCAEZ;CACF;AAED,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACnE,YAAW,oBAAoB,CAAC,CAAC,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAE9B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAC3B,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;IAK1C,YAAY;IAMZ,IAAI,MAAM,gCAET;IACD,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAIxC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAWjC,cAAc,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAEjE,IAAI,UAAU,sBAEb;IACD,IAAI,aAAa,WAEhB;IAED,IAAI,MAAM,WAET;IAED,IAAI,QAAQ,WAEX;IAEK,MAAM;CAUb"}
+{"version":3,"file":"future-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-aware.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,qBAAqB,CAAC,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACvE,YAAW,oBAAoB,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAEvD,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAC3B,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,MAAM;IAQnE,IAAI,UAAU,sBAEb;IAED,IAAI,MAAM,gCAET;IACD,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM;IAajD,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM;IAM3B,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM;IAKxB,IAAI,SAAS,iCAEZ;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACnE,YAAW,oBAAoB,CAAC,CAAC,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAE9B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAC3B,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;IAK1C,YAAY;IAMZ,IAAI,MAAM,gCAET;IACD,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAIxC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAWjC,cAAc,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAEjE,IAAI,UAAU,sBAEb;IACD,IAAI,aAAa,WAEhB;IAED,IAAI,MAAM,WAET;IAED,IAAI,QAAQ,WAEX;IAEK,MAAM;CAUb"}

package/models/models/future/future-model.d.ts

@@ -27,7 +27,7 @@ declare class FutureModel implements IFutureModel {
      */
     constructor(modelId: string, options: IFutureModelOptions, context: KosCreationContext);
     /**
-     * @category Lifecycle
+     * @internal
      *
      * @remarks
      * No action is taken as part of the load lifecycle method.
@@ -35,6 +35,9 @@ declare class FutureModel implements IFutureModel {
      * In future additional information about the workspace could be loaded
      */
     load(): Promise<void>;
+    /**
+     * @internal
+     */
     unload(): void;
     /**
      * @category Action
@@ -48,16 +51,42 @@ declare class FutureModel implements IFutureModel {
      * @see cancelFutureService
      */
     cancelFuture(): Promise<void>;
+    /**
+     * Gets the current status of the future operation.
+     *
+     * @returns Status string: "NOT_ACTIVE", "IN_PROGRESS", "Success", or "Fail"
+     *
+     * @example Monitor Status
+     * ```typescript
+     * if (future.status === "IN_PROGRESS") {
+     *   console.log(`Operation running: ${future.progress}% complete`);
+     * } else if (future.status === "Success") {
+     *   console.log("Operation completed successfully!");
+     * }
+     * ```
+     */
     get status(): FutureEndState | "IN_PROGRESS" | "NOT_ACTIVE";
+    /**
+     * Gets human-readable time remaining for the operation.
+     *
+     * @returns Formatted time string (e.g., "5 minutes", "30 seconds") or empty string if unknown
+     *
+     * @example Display Time Remaining
+     * ```typescript
+     * const timeLeft = future.timeRemaining;
+     * if (timeLeft) {
+     *   console.log(`${timeLeft} remaining`);
+     * }
+     * ```
+     */
     get timeRemaining(): string;
     /**
+     * @internal
      * @category Subscription
-     * Updates the Future model when a `kos.future/ID` event
+     * Updates the Future model when a `kos.future/{ID}` event
      * is received from the server.
      *
-     *
-     * @param data - the raw callback
-     * @param data.body - the Future that was updated.
+     * @param future - the Future that was updated.
      * @see FutureResponse
      */
     handleFutureUpdated(future: FutureResponse): void;

package/models/models/future/future-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"future-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-model.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EAGd,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOxE,UAAU,WAAY,SAAQ,YAAY;CAAG;AAI7C;;;;;;;GAOG;AACH,cACM,WAAY,YAAW,YAAY;IACvC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAGuB;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,kBAAkB;IAwB7B;;;;;;;OAOG;IACG,IAAI;IAIV,MAAM;IAMN;;;;;;;;;;OAUG;IACG,YAAY;IASlB,IAAI,MAAM,kDAMT;IAED,IAAI,aAAa,WAoChB;IAID;;;;;;;;;OASG;IAIH,mBAAmB,CAAC,MAAM,EAAE,cAAc;CAM3C;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"future-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-model.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EAGd,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOxE,UAAU,WAAY,SAAQ,YAAY;CAAG;AAI7C;;;;;;;GAOG;AACH,cACM,WAAY,YAAW,YAAY;IACvC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAGuB;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,kBAAkB;IAwB7B;;;;;;;OAOG;IACG,IAAI;IAIV;;OAEG;IACH,MAAM;IAMN;;;;;;;;;;OAUG;IACG,YAAY;IASlB;;;;;;;;;;;;;OAaG;IACH,IAAI,MAAM,kDAMT;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,aAAa,WAoChB;IAID;;;;;;;;OAQG;IAIH,mBAAmB,CAAC,MAAM,EAAE,cAAc;CAM3C;AAED,eAAe,WAAW,CAAC"}

package/models/models/future/future-types.d.ts

@@ -1,23 +1,123 @@
 import { FutureEndState } from '../../services/future';
 import { IKosDataModel } from '../../../core';
 
+/**
+ * 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>) => void;
+    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>) => void;
+    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;
@@ -26,16 +126,35 @@ export interface FutureAware {
     cancel: () => Promise<void>;
 }
 /**
- * Additional properties that can be passed into the constructor in order
- * to set initial values
+ * 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 overriden by
+ * 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.
  *
- * @category future
+ * @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;
@@ -59,9 +178,83 @@ export interface IFutureModelOptions<T extends {} = Record<string, unknown>> {
     note?: string;
 }
 /**
- * Represents the public interface of a `IFutureModel`
+ * 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
  *
- * @category Model
+ * @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;

package/models/models/future/future-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"future-types.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"future-types.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/future/future-types.ts"],"names":[],"mappings":"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"}

package/models/models/future-container/future-container-model.d.ts

@@ -70,7 +70,7 @@ declare class FutureContainerModel implements IFutureContainerModel {
      * actions on elements in a collection without requiring the models to have
      * explicit knowledge of the operation being performed.
      *
-     * @category KOS Model
+     * @group KOS Model
      * @internal
      */
     /**
@@ -85,7 +85,7 @@ declare class FutureContainerModel implements IFutureContainerModel {
      * relationship.
      *
      * @returns - the collection of Future models maintained by this model.
-     * @category KOS Model
+     * @group KOS Model
      * @internal
      */
     /**