@kosdev-code/kos-ui-sdk 2.0.40 → 2.1.0

package/models/models/state-bean/types/index.d.ts

@@ -1,24 +1,132 @@
 import { StatePropertyTypes } from '../../types';
-import { IKosDataModel } from '../../../core';
 
 
+/**
+ * Configuration options for StateBean model instances.
+ *
+ * This interface defines the configuration options for the StateBean model,
+ * specifying which state path the model should monitor for real-time updates.
+ *
+ * @example Basic StateBean Model Creation
+ * ```typescript
+ * // Monitor device operational status
+ * const deviceState = StateBean.instance('device-status')
+ *   .options({ path: 'device.operational.status' })
+ *   .build();
+ *
+ * // Monitor system health metrics
+ * const healthState = StateBean.instance('system-health')
+ *   .options({ path: 'system.health.metrics' })
+ *   .build();
+ * ```
+ *
+ * @example Path Patterns
+ * ```typescript
+ * // Different path patterns for different use cases
+ * const networkOptions: StateBeanOptions = {
+ *   path: 'network.interfaces.primary' // Network interface state
+ * };
+ *
+ * const pumpOptions: StateBeanOptions = {
+ *   path: 'assembly.pumps.status' // Pump system state
+ * };
+ *
+ * const brewingOptions: StateBeanOptions = {
+ *   path: 'beverage.brewing.process' // Brewing process state
+ * };
+ * ```
+ *
+ * @example Hierarchical State Organization
+ * ```typescript
+ * // Use dot notation for hierarchical state paths
+ * const parentState = StateBean.instance('parent')
+ *   .options({ path: 'system' })
+ *   .build();
+ *
+ * const childState = StateBean.instance('child')
+ *   .options({ path: 'system.subsystem.component' })
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category State Management
+ */
 export interface StateBeanOptions {
+  /**
+   * State path to monitor for updates using dot notation hierarchy.
+   * This path corresponds to the WebSocket topic `/kos/state/{path}` for real-time updates.
+   *
+   * @example "device.operational.status"
+   * @example "network.interfaces.primary"
+   * @example "assembly.pumps.status"
+   */
   path: string;
 }
 
+/**
+ * Type-safe keys for state properties within a StateBean.
+ *
+ * @template T - The state property type mapping
+ */
 type StateKeys<T extends Record<string, StatePropertyTypes>> = keyof T;
+
+/**
+ * Reactive Map-based storage for state properties with type safety.
+ *
+ * This Map provides efficient storage and retrieval of state properties with automatic
+ * reactivity through MobX observables. The Map structure allows for dynamic property
+ * addition/removal while maintaining type safety for known properties.
+ *
+ * @example Accessing State Properties
+ * ```typescript
+ * // Define typed state interface
+ * interface PumpState {
+ *   active: boolean;
+ *   flowRate: number;
+ *   temperature: number;
+ *   lastMaintenance: string;
+ * }
+ *
+ * const pumpState = StateBean.instance('pump-monitor')
+ *   .options({ path: 'assembly.pumps.pump1' })
+ *   .build() as StateBean<PumpState>;
+ *
+ * // Type-safe property access
+ * const isActive = pumpState.props.get('active') as boolean;
+ * const currentFlow = pumpState.props.get('flowRate') as number;
+ * const temp = pumpState.props.get('temperature') as number;
+ * const maintenance = pumpState.props.get('lastMaintenance') as string;
+ * ```
+ *
+ * @template T - The state property type mapping
+ *
+ * @group KOS Model
+ * @category Types
+ */
 export type StatePropsMap<T> = Map<StateKeys<T>, T[keyof T]>;
 
 /**
- * State Bean Model
- * @category Model
+ * State Bean Model interface - maintains the state of KOS device state properties.
+ *
+ * This interface represents the public API for StateBean models, providing reactive
+ * access to device state properties through an observable Map structure. The interface
+ * supports real-time synchronization with device state via WebSocket topics.
+ *
+ * @group KOS Model
+ * @category Model Interface
  */
 export interface StateBeanModel<
-  T extends Record<string, StatePropertyTypes> = any
-> extends StateBeanOptions,
-    IKosDataModel {
+  T extends Record<string, StatePropertyTypes> = Record<
+    string,
+    StatePropertyTypes
+  >
+> {
+  /** Unique model identifier */
   id: string;
+  /** State path being monitored */
   path: string;
+  /** Reactive Map of state properties */
   props: StatePropsMap<T>;
+  /** Update model configuration */
   updateModel(options: StateBeanOptions): void;
 }

package/models/models/state-prop/state-prop-model.d.ts

@@ -1,19 +1,96 @@
 import { KosStateProp, StatePropOptions } from './types';
 import { StatePropertyTypes } from '../types';
 import { StateBeanModel } from '../state-bean/types';
+import { PublicModelInterface } from '../../../core/types';
 import { IKosModelLogger, KosContextLogger, KosCreationContext } from '../../../core';
 
 export declare const MODEL_TYPE = "state-prop-model";
-export declare class StatePropModelImpl<T extends StatePropertyTypes = any> implements KosStateProp<T>, IKosModelLogger {
+/**
+ * StateProp - Focused access to individual state properties with dependency on StateBean.
+ *
+ * The StateProp model provides targeted access to a single property within a StateBean,
+ * offering a focused interface for components or services that only need to monitor
+ * specific state values. This model automatically manages its dependency on the underlying
+ * StateBean and provides reactive access to individual property values.
+ *
+ * ## Key Features
+ * - **Single Property Focus** - Access one specific property from a StateBean path
+ * - **Automatic StateBean Dependency** - Manages StateBean dependency transparently
+ * - **Type-safe Value Access** - Strongly typed property value with generic support
+ * - **Reactive Updates** - Automatically updates when underlying StateBean changes
+ * - **Simplified Interface** - Clean `.value` accessor for property values
+ * - **String Conversion** - Built-in `toString()` method for display purposes
+ *
+ * ## StateBean Integration
+ * StateProp models automatically create and manage dependencies on StateBean models:
+ * - **Automatic Dependency** - Creates StateBean with matching path automatically
+ * - **Shared StateBean** - Multiple StateProp models can share the same StateBean
+ * - **Lifecycle Management** - Proper initialization and cleanup of dependencies
+ * - **Real-time Synchronization** - Inherits WebSocket updates from StateBean
+ *
+ * ## Common Use Cases
+ * - **Single Value Components** - React components that only need one state property
+ * - **Conditional Logic** - Enable/disable functionality based on specific state
+ * - **Status Indicators** - Display individual status flags or measurements
+ * - **Property Validation** - Monitor specific properties for validation rules
+ * - **Focused Updates** - Reduce re-renders by tracking only needed properties
+ * - **Service Dependencies** - Services that depend on specific state values
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const deviceOnline = StateProp.instance('device-online')
+ *   .options({
+ *     path: 'device.operational.status',
+ *     attribute: 'online'
+ *   })
+ *   .build();
+ *
+ * // Access focused property value with type safety
+ * const isOnline = deviceOnline.value as boolean;
+ * console.log(`Status: ${deviceOnline.toString()}`);
+ * ```
+ *
+ * @group KOS Model
+ * @category State Management
+ * @useDeclaredType
+ *
+ * @see {@link StatePropOptions} - Configuration options for StateProp model
+ * @see {@link StatePropertyTypes} - Supported property value types
+ * @see {@link StateBean} - Underlying state collection model
+ * @see {@link StateBeanOptions} - StateBean configuration options
+ */
+export type StateProp<T extends StatePropertyTypes = StatePropertyTypes> = PublicModelInterface<StatePropModelImpl<T>>;
+/**
+ * @ignore
+ * @internal
+ */
+export declare class StatePropModelImpl<T extends StatePropertyTypes = StatePropertyTypes> implements KosStateProp<T>, IKosModelLogger {
+    /** Unique identifier for the model instance */
     id: string;
+    /** State path being monitored (same as dependent StateBean) */
     path: string;
+    /** Specific attribute name to access within the state path */
     attribute: string;
+    /** Context logger for debugging and diagnostics */
     logger: KosContextLogger;
+    /** Automatic dependency on StateBean for the specified path */
     stateBean: StateBeanModel;
     constructor(modelId: string, options: StatePropOptions, context: KosCreationContext);
+    /** The current value of the specific attribute, with type safety */
     get value(): T | undefined;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
+    /**
+     * Converts the current property value to string for display purposes.
+     * @returns String representation of the property value, or empty string if undefined
+     */
     toString(): string;
 }
 //# sourceMappingURL=state-prop-model.d.ts.map

package/models/models/state-prop/state-prop-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-prop-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/state-prop/state-prop-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9D,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAG7C,qBACa,kBAAkB,CAAC,CAAC,SAAS,kBAAkB,GAAG,GAAG,CAChE,YAAW,YAAY,CAAC,CAAC,CAAC,EAAE,eAAe;IAE3C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IAOzB,SAAS,EAAG,cAAc,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB;IAW7B,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAEzB;IAIK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"state-prop-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/state-prop/state-prop-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9D,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IACrE,oBAAoB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;AAI9C;;;GAGG;AACH,qBACa,kBAAkB,CAC7B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACjD,YAAW,YAAY,CAAC,CAAC,CAAC,EAAE,eAAe;IAE3C,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,CAAC;IAEzB,+DAA+D;IAM/D,SAAS,EAAG,cAAc,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB;IAW7B,oEAAoE;IACpE,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAEzB;IAID;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/models/models/state-prop/types/index.d.ts

@@ -1,20 +1,68 @@
 import { StatePropertyTypes } from '../../types';
-import { IKosDataModel } from '../../../core';
 
 
+/**
+ * Configuration options for StateProp model instances.
+ *
+ * This interface defines the configuration options for the StateProp model,
+ * specifying which state path and attribute the model should monitor for
+ * focused property access.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const deviceOnline = StateProp.instance('device-online')
+ *   .options({
+ *     path: 'device.operational.status',
+ *     attribute: 'online'
+ *   })
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category State Management
+ */
 export interface StatePropOptions {
+  /**
+   * State path to monitor, matching the StateBean path structure.
+   * Uses dot notation hierarchy corresponding to `/kos/state/{path}` WebSocket topic.
+   *
+   * @example "device.operational.status"
+   * @example "assembly.pumps.pump1"
+   * @example "system.health.metrics"
+   */
   path: string;
+
+  /**
+   * Specific attribute name within the state path to access.
+   * This corresponds to a property key within the StateBean's properties Map.
+   *
+   * @example "online"
+   * @example "temperature"
+   * @example "flowRate"
+   * @example "active"
+   */
   attribute: string;
 }
 
 /**
- * State Property Model manages the state of a single state bean property
- * @category Model
+ * State Property Model interface - manages access to a single state property.
+ *
+ * This interface represents the public API for StateProp models, providing focused
+ * access to individual properties within a StateBean through automatic dependency
+ * management and reactive value updates.
+ *
+ * @group KOS Model
+ * @category Model Interface
  */
-
-export interface KosStateProp<T extends StatePropertyTypes = any>
-  extends StatePropOptions,
-    IKosDataModel {
+export interface KosStateProp<
+  T extends StatePropertyTypes = StatePropertyTypes
+> {
+  /** Unique model identifier */
   id: string;
+  /** State path being monitored */
+  path: string;
+  /** Specific attribute name within the state path */
+  attribute: string;
+  /** Current property value (reactive) */
   value: T | undefined;
 }

package/models/models/storage-device/storage-device-container-model.d.ts

@@ -7,10 +7,297 @@ import { IKosIdentifiable, IKosModelHolder, PublicModelInterface } from '../../.
 
 export declare const MODEL_TYPE = "storage-device-container-model";
 export declare const TOPIC_STORAGE_AVAILABILITY = "/kos/storage";
+/**
+ * StorageDeviceContainer - Manages collections of storage devices with real-time discovery.
+ *
+ * The StorageDeviceContainer model provides centralized management of multiple storage devices
+ * connected to KOS systems. It automatically discovers devices through REST API calls and
+ * maintains real-time synchronization via WebSocket topics, handling device insertion,
+ * removal, and state updates across the entire storage ecosystem.
+ *
+ * ## Key Features
+ * - **Automatic Device Discovery** - Scans and loads all available storage devices
+ * - **Real-time Synchronization** - WebSocket updates for insertion/removal events
+ * - **Collection Management** - Add, remove, and query storage device collections
+ * - **Availability Monitoring** - Track overall storage availability status
+ * - **Volume Access** - Direct access to managed storage device instances
+ * - **Parent-Child Architecture** - Proper lifecycle management for contained devices
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to these KOS topics for real-time synchronization:
+ * - **`/kos/storage`** - Storage device availability changes (insertion/removal events)
+ *   - Payload: `StorageDeviceResponse[]` - Array of current storage device states
+ *   - Triggers automatic model updates, additions, and removals
+ *   - Handles both physical device changes and mount/unmount operations
+ *
+ * ## Storage Management Operations
+ * The container provides comprehensive storage device management:
+ * - **Device Lifecycle**: Automatic creation and cleanup of StorageDevice models
+ * - **State Synchronization**: Real-time updates from system storage changes
+ * - **Collection Queries**: Access devices by ID, status, or availability
+ * - **Volume Tracking**: Monitor mounted and available storage volumes
+ *
+ * ## Common Use Cases
+ * - **Storage Management Dashboard** - Display all connected storage devices
+ * - **File Transfer Interface** - Select available storage for operations
+ * - **System Monitoring** - Track storage availability and health
+ * - **Backup Management** - Identify backup destination devices
+ * - **Multi-node Storage** - Manage distributed storage across KOS nodes
+ * - **Device Diagnostics** - Monitor storage device runtime and status
+ *
+ * @example Basic Storage Container Usage
+ * ```typescript
+ * // Create storage device container for system management
+ * const storageContainer = StorageDeviceContainer.instance('main-storage')
+ *   .options({}) // Empty configuration - behavior driven by discovery
+ *   .build();
+ *
+ * // Check overall storage availability
+ * console.log(`Storage available: ${storageContainer.isStorageInserted}`);
+ * console.log(`Total volumes: ${storageContainer.volumes.length}`);
+ *
+ * // Access individual storage devices
+ * const usbDevice = storageContainer.getModel('usb-drive-1');
+ * if (usbDevice && !usbDevice.removed) {
+ *   console.log(`USB device mounted at: ${usbDevice.mountDir}`);
+ * }
+ * ```
+ *
+ * @example Storage Device Discovery and Management
+ * ```typescript
+ * // Container automatically handles device discovery
+ * const storageManager = StorageDeviceContainer.instance('storage-mgr')
+ *   .options({})
+ *   .build();
+ *
+ * // Monitor storage changes with reactive patterns
+ * const monitorStorageChanges = () => {
+ *   // Container automatically updates via /kos/storage topic
+ *   const availableDevices = storageManager.data.filter(device =>
+ *     !device.removed && device.mountDir
+ *   );
+ *
+ *   const localDevices = availableDevices.filter(device => device.local);
+ *   const remoteDevices = availableDevices.filter(device => !device.local);
+ *
+ *   console.log(`Available storage: ${availableDevices.length} devices`);
+ *   console.log(`Local: ${localDevices.length}, Remote: ${remoteDevices.length}`);
+ *
+ *   return {
+ *     total: availableDevices.length,
+ *     local: localDevices.length,
+ *     remote: remoteDevices.length,
+ *     devices: availableDevices
+ *   };
+ * };
+ * ```
+ *
+ * @example React Storage Management Interface
+ * ```typescript
+ * const StorageManagerComponent: React.FC = kosComponent(() => {
+ *   const storageContainer = useModel(StorageDeviceContainer, 'storage-manager');
+ *
+ *   // Reactive data automatically updates via WebSocket
+ *   const availableDevices = storageContainer.volumes.filter(device =>
+ *     !device.removed && device.mountDir
+ *   );
+ *
+ *   const removedDevices = storageContainer.volumes.filter(device =>
+ *     device.removed
+ *   );
+ *
+ *   return (
+ *     <div className="storage-manager">
+ *       <div className="storage-status">
+ *         <h2>Storage Overview</h2>
+ *         <div className="status-indicator">
+ *           <span className={storageContainer.isStorageInserted ? 'online' : 'offline'}>
+ *             {storageContainer.isStorageInserted ? 'Storage Available' : 'No Storage'}
+ *           </span>
+ *         </div>
+ *         <div className="device-count">
+ *           Total Devices: {storageContainer.volumes.length}
+ *         </div>
+ *       </div>
+ *
+ *       <div className="device-sections">
+ *         <section className="available-devices">
+ *           <h3>Available Storage ({availableDevices.length})</h3>
+ *           {availableDevices.map(device => (
+ *             <StorageDeviceCard key={device.id} device={device} />
+ *           ))}
+ *         </section>
+ *
+ *         {removedDevices.length > 0 && (
+ *           <section className="removed-devices">
+ *             <h3>Recently Removed ({removedDevices.length})</h3>
+ *             {removedDevices.map(device => (
+ *               <StorageDeviceCard key={device.id} device={device} />
+ *             ))}
+ *           </section>
+ *         )}
+ *       </div>
+ *     </div>
+ *   );
+ * });
+ * ```
+ *
+ * @example Storage Device Filtering and Queries
+ * ```typescript
+ * // Create storage container for advanced device management
+ * const storageController = StorageDeviceContainer.instance('storage-ctrl')
+ *   .options({})
+ *   .build();
+ *
+ * // Helper functions for device filtering
+ * const getStorageQueries = (container: StorageDeviceContainer) => ({
+ *   // Get all available (mounted and not removed) devices
+ *   getAvailableDevices: () =>
+ *     container.data.filter(device => !device.removed && device.mountDir),
+ *
+ *   // Get devices by specific node
+ *   getDevicesByNode: (nodeId: string) =>
+ *     container.data.filter(device => device.nodeId === nodeId),
+ *
+ *   // Get local vs remote devices
+ *   getLocalDevices: () =>
+ *     container.data.filter(device => device.local),
+ *
+ *   // Get devices by vendor
+ *   getDevicesByVendor: (vendor: string) =>
+ *     container.data.filter(device =>
+ *       device.vendor.toLowerCase().includes(vendor.toLowerCase())
+ *     ),
+ *
+ *   // Get backup-suitable devices (available with sufficient runtime)
+ *   getBackupDevices: () =>
+ *     container.data.filter(device =>
+ *       !device.removed &&
+ *       device.mountDir &&
+ *       device.runTimeMs > 300000 // More than 5 minutes runtime
+ *     ),
+ *
+ *   // Get device statistics
+ *   getStorageStats: () => {
+ *     const devices = container.data;
+ *     return {
+ *       total: devices.length,
+ *       available: devices.filter(d => !d.removed && d.mountDir).length,
+ *       removed: devices.filter(d => d.removed).length,
+ *       local: devices.filter(d => d.local).length,
+ *       remote: devices.filter(d => !d.local).length,
+ *       averageRuntime: devices.reduce((sum, d) => sum + d.runTimeMs, 0) / devices.length
+ *     };
+ *   }
+ * });
+ *
+ * // Usage examples
+ * const queries = getStorageQueries(storageController);
+ *
+ * console.log('Storage Statistics:', queries.getStorageStats());
+ * console.log('Available Devices:', queries.getAvailableDevices().length);
+ * console.log('Backup-Ready Devices:', queries.getBackupDevices().length);
+ * ```
+ *
+ * @example WebSocket Topic Synchronization
+ * ```typescript
+ * // The container automatically handles /kos/storage topic updates
+ * const storageSync = StorageDeviceContainer.instance('sync-demo')
+ *   .options({})
+ *   .build();
+ *
+ * // Topic payload structure: StorageDeviceResponse[]
+ * // Example payload when device is inserted:
+ * // [
+ * //   {
+ * //     id: "usb-drive-new",
+ * //     mountDir: "/media/usb-new",
+ * //     vendor: "Kingston",
+ * //     model: "DataTraveler",
+ * //     label: "KINGSTON_32GB",
+ * //     nodeId: "primary",
+ * //     local: true,
+ * //     removed: false,
+ * //     runTimeMs: 0,
+ * //     syspath: "/sys/devices/usb/new"
+ * //   }
+ * // ]
+ *
+ * // Container automatically:
+ * // 1. Compares payload with existing models
+ * // 2. Removes models not in payload (device unplugged)
+ * // 3. Updates existing models with new state
+ * // 4. Creates new models for discovered devices
+ * // 5. Maintains parent-child relationships
+ *
+ * // Monitor changes reactively
+ * const logStorageChanges = () => {
+ *   const currentDevices = storageSync.data.map(device => ({
+ *     id: device.id,
+ *     vendor: device.vendor,
+ *     mounted: !!device.mountDir,
+ *     removed: device.removed
+ *   }));
+ *
+ *   console.log('Current Storage State:', currentDevices);
+ * };
+ * ```
+ *
+ * @example Multi-Node Storage Architecture
+ * ```typescript
+ * // Container manages storage across distributed KOS nodes
+ * const distributedStorage = StorageDeviceContainer.instance('distributed')
+ *   .options({})
+ *   .build();
+ *
+ * // Analyze storage distribution across nodes
+ * const analyzeStorageDistribution = () => {
+ *   const nodeGroups = distributedStorage.data.reduce((groups, device) => {
+ *     const nodeId = device.nodeId;
+ *     if (!groups[nodeId]) {
+ *       groups[nodeId] = {
+ *         nodeId,
+ *         devices: [],
+ *         available: 0,
+ *         totalRuntime: 0
+ *       };
+ *     }
+ *
+ *     groups[nodeId].devices.push(device);
+ *     if (!device.removed && device.mountDir) {
+ *       groups[nodeId].available++;
+ *     }
+ *     groups[nodeId].totalRuntime += device.runTimeMs;
+ *
+ *     return groups;
+ *   }, {} as Record<string, any>);
+ *
+ *   // Display node distribution
+ *   Object.values(nodeGroups).forEach((node: any) => {
+ *     const avgRuntime = node.totalRuntime / node.devices.length;
+ *     console.log(`Node ${node.nodeId}:`);
+ *     console.log(`  Devices: ${node.devices.length}`);
+ *     console.log(`  Available: ${node.available}`);
+ *     console.log(`  Avg Runtime: ${Math.round(avgRuntime / 60000)}min`);
+ *   });
+ *
+ *   return nodeGroups;
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Management
+ *
+ * @see {@link StorageDevice} - Individual storage device model
+ * @see {@link StorageDeviceOptions} - Configuration options for storage devices
+ * @see {@link StorageDeviceContainerOptions} - Container configuration options
+ * @see {@link StorageDeviceResponse} - API response structure for device discovery
+ */
+export type StorageDeviceContainer = PublicModelInterface<StorageDeviceContainerModelImpl>;
 export type StorageDeviceContainerModel = PublicModelInterface<StorageDeviceContainerModelImpl>;
 /**
- * Storage Device Container Model
- * @category Model
+ * @ignore
+ * @internal
  */
 export declare class StorageDeviceContainerModelImpl implements IKosIdentifiable, IKosModelHolder<StorageDeviceModel>, IKosDataModel {
     id: string;

package/models/models/storage-device/storage-device-container-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-device-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/storage-device/storage-device-container-model.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAIpB,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EACV,6BAA6B,EAE9B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,UAAU,mCAAmC,CAAC;AAE3D,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AAEzD,MAAM,MAAM,2BAA2B,GACrC,oBAAoB,CAAC,+BAA+B,CAAC,CAAC;AAExD;;;GAGG;AACH,qBACa,+BACX,YACE,gBAAgB,EAChB,eAAe,CAAC,kBAAkB,CAAC,EACnC,aAAa;IAEf,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAyC;gBAEhE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,6BAA6B,EACtC,OAAO,EAAE,kBAAkB;IAY7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,2CAET;IACD,IAAI,IAAI,yBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,kBAAkB;IAIlC,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,IAAI,iBAAiB,YAEpB;IAED,IAAI,OAAO,yBAEV;IAMD,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,EAAE;IA6BpD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAc5B"}
+{"version":3,"file":"storage-device-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/storage-device/storage-device-container-model.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAIpB,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EACV,6BAA6B,EAE9B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,UAAU,mCAAmC,CAAC;AAE3D,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6RG;AACH,MAAM,MAAM,sBAAsB,GAChC,oBAAoB,CAAC,+BAA+B,CAAC,CAAC;AAExD,MAAM,MAAM,2BAA2B,GACrC,oBAAoB,CAAC,+BAA+B,CAAC,CAAC;AAExD;;;GAGG;AACH,qBACa,+BACX,YACE,gBAAgB,EAChB,eAAe,CAAC,kBAAkB,CAAC,EACnC,aAAa;IAEf,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAyC;gBAEhE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,6BAA6B,EACtC,OAAO,EAAE,kBAAkB;IAY7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,2CAET;IACD,IAAI,IAAI,yBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,kBAAkB;IAIlC,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,IAAI,iBAAiB,YAEpB;IAED,IAAI,OAAO,yBAEV;IAMD,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,EAAE;IA6BpD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAc5B"}