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

package/models/models/kos-time/kos-time-model.d.ts

@@ -2,7 +2,65 @@ import { DateBean, KosTimeOptions, TimeBean } from './types';
 import { IKosDataModel, IKosModelLogger, KosContextLogger, KosCreationContext, PublicModelInterface } from '../../../core';
 
 export declare const MODEL_TYPE = "kos-time-model";
+/**
+ * KOS Time Model - System time management with real-time synchronization and timezone control.
+ *
+ * This singleton model provides centralized control over system time, date, and timezone settings
+ * with automatic event propagation when changes occur. Essential for applications that need to
+ * synchronize time-based operations, schedule events, or maintain consistent timestamps across
+ * the system.
+ *
+ * ## Key Features
+ * - **System Time Control** - Update system hours, minutes, and seconds programmatically
+ * - **Date Management** - Set system date including month, day, and year
+ * - **Timezone Handling** - Change and track timezone with automatic updates
+ * - **Real-time Events** - Automatic notifications when time, date, or timezone changes
+ * - **EventBus Integration** - Publishes changes to internal EventBus for UI updates
+ * - **WebSocket Sync** - Changes propagate across all connected clients
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to three KOS topics for time synchronization:
+ * - **`/kos/time/time`** - Fired when system time changes (hour/minute/second)
+ * - **`/kos/time/day`** - Fired when the date changes (day rollover or manual change)
+ * - **`/kos/time/timezone`** - Fired when timezone is updated
+ *
+ * Additionally, the model publishes to internal EventBus topics:
+ * - `TIME_CHANGE` - For UI components to react to time updates
+ * - `DAY_CHANGE` - For date-dependent UI updates
+ * - `TIMEZONE_CHANGE` - For timezone-aware components
+ *
+ * ## Common Use Cases
+ * - **System Clock Management** - Synchronize device time with server time
+ * - **Scheduled Operations** - Trigger events based on time changes
+ * - **Multi-timezone Support** - Handle devices in different time zones
+ * - **Time-based UI Updates** - Keep clocks and calendars synchronized
+ * - **Audit Logging** - Ensure consistent timestamps across the system
+ * - **Day Rollover Handling** - Reset daily counters or refresh data
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const timeModel = KosTime.instance().build();
+ *
+ * // Update system time and date
+ * await timeModel.updateSystemTime({ hour: 15, min: 45, sec: 30 });
+ * await timeModel.updateSystemDate({ month: 3, day: 15, year: 2024 });
+ * await timeModel.updateSystemTimezone('America/New_York');
+ * ```
+ *
+ * @group KOS Model
+ * @category System Integration
+ * @useDeclaredType
+ *
+ * @see {@link TimeBean} - Time value structure (hour, minute, second)
+ * @see {@link DateBean} - Date value structure (month, day, year)
+ * @see {@link KosTimeOptions} - Configuration options for time model
+ */
 export type KosTimeModel = PublicModelInterface<KosTimeModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class KosTimeModelImpl implements IKosModelLogger, IKosDataModel {
     id: string;
     logger: KosContextLogger;
@@ -28,9 +86,15 @@ export declare class KosTimeModelImpl implements IKosModelLogger, IKosDataModel
     handleTimeChange(): void;
     handleDayChange(): void;
     handleTimeZoneChange(): Promise<void>;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
     private retrieveTimezone;
     setTimezone(tz: string): void;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
 }
 //# sourceMappingURL=kos-time-model.d.ts.map

package/models/models/kos-time/kos-time-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-time-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-time/kos-time-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAM3C,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;AAClE,qBACa,gBAAiB,YAAW,eAAe,EAAE,aAAa;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,kBAAkB;IAO7B;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;OAGG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM;IAK3C,gBAAgB,IAAI,IAAI;IAMxB,eAAe,IAAI,IAAI;IAMjB,oBAAoB;IAQpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,gBAAgB;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAGhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B"}
+{"version":3,"file":"kos-time-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-time/kos-time-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;AAElE;;;GAGG;AACH,qBACa,gBAAiB,YAAW,eAAe,EAAE,aAAa;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,kBAAkB;IAO7B;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAIrC;;;OAGG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM;IAK3C,gBAAgB,IAAI,IAAI;IAMxB,eAAe,IAAI,IAAI;IAMjB,oBAAoB;IAQ1B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,gBAAgB;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAItB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAI5B"}

package/models/models/kos-time/types/index.d.ts

@@ -1,13 +1,96 @@
+/**
+ * Time value structure for system time operations.
+ *
+ * Represents a specific time of day with hour, minute, and second components.
+ * Used when updating system time through the KosTime model.
+ *
+ * @example
+ * ```typescript
+ * const morningTime: TimeBean = {
+ *   hour: 9,    // 9 AM (24-hour format)
+ *   min: 30,    // 30 minutes
+ *   sec: 0      // 0 seconds
+ * };
+ *
+ * const afternoonTime: TimeBean = {
+ *   hour: 15,   // 3 PM (24-hour format)
+ *   min: 45,
+ *   sec: 30
+ * };
+ *
+ * await timeModel.updateSystemTime(morningTime);
+ * ```
+ *
+ * @kosService core.kos-time
+ * @category System Integration
+ * @category Time Management
+ */
 export interface TimeBean {
+  /** Hour in 24-hour format (0-23) */
   hour: number;
+  /** Minutes (0-59) */
   min: number;
+  /** Seconds (0-59) */
   sec: number;
 }
 
+/**
+ * Date value structure for system date operations.
+ *
+ * Represents a specific calendar date with month, day, and year components.
+ * Used when updating system date through the KosTime model.
+ *
+ * @example
+ * ```typescript
+ * const newYear: DateBean = {
+ *   month: 1,   // January
+ *   day: 1,     // 1st
+ *   year: 2024  // 2024
+ * };
+ *
+ * const independence: DateBean = {
+ *   month: 7,   // July
+ *   day: 4,     // 4th
+ *   year: 2024
+ * };
+ *
+ * await timeModel.updateSystemDate(newYear);
+ * ```
+ *
+ * @kosService core.kos-time
+ * @category System Integration
+ * @category Time Management
+ */
 export interface DateBean {
+  /** Month (1-12, where 1 = January, 12 = December) */
   month: number;
+  /** Day of the month (1-31, depending on month) */
   day: number;
+  /** Full year (e.g., 2024) */
   year: number;
 }
 
+/**
+ * Configuration options for KosTime model instances.
+ *
+ * Currently an empty interface but reserved for future time-related
+ * configuration options such as default timezone, time format preferences,
+ * or synchronization settings.
+ *
+ * @example
+ * ```typescript
+ * const options: KosTimeOptions = {
+ *   // Future options will be added here
+ * };
+ *
+ * const timeModel = KosTime.instance()
+ *   .options(options)
+ *   .build();
+ * ```
+ *
+ * @kosService core.kos-time
+ * @category Model Configuration
+ * @category System Integration
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface KosTimeOptions {}

package/models/models/log-block/log-block-container-model.d.ts

@@ -6,7 +6,139 @@ import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 import { IKosModelContainer } from '../../../core/core/kos-container-model';
 
 export declare const MODEL_TYPE = "log-block-container-model";
+/**
+ * Log Block Container Model - Manages multiple log blocks with automatic sorting and organization.
+ *
+ * This container model manages collections of LogBlockModel instances, providing organized access
+ * to log blocks with automatic sorting by block number. It serves as the storage layer within
+ * LogStreamModel instances, handling the efficient organization and retrieval of log blocks
+ * that make up a complete log stream.
+ *
+ * ## Key Features
+ * - **Automatic Sorting** - Maintains blocks sorted by block number for sequential access
+ * - **Block Management** - Add, remove, and retrieve log blocks efficiently
+ * - **Memory Organization** - Organized storage of log blocks within streams
+ * - **Stream Integration** - Essential component of LogStreamModel architecture
+ * - **Sequential Access** - Optimized for accessing blocks in chronological order
+ *
+ * ## Architecture Role
+ * The container fits into the log streaming architecture as:
+ * - **LogStreamModel** uses LogBlockContainerModel to organize its blocks
+ * - **LogBlockContainerModel** manages multiple LogBlockModel instances
+ * - **LogBlockModel** contains the actual log lines and metadata
+ * - Automatic sorting by blockNum ensures proper sequential log ordering
+ *
+ * ## Common Use Cases
+ * - **Stream Block Storage** - Central storage for all blocks within a log stream
+ * - **Sequential Block Access** - Navigate through log blocks in chronological order
+ * - **Block Organization** - Maintain sorted collections of log segments
+ * - **Memory Management** - Efficiently organize log data for stream processing
+ * - **Block Lifecycle** - Handle adding and removing blocks as streams evolve
+ *
+ * @example Container Usage Within Stream
+ * ```typescript
+ * // Typically used internally by LogStreamModel
+ * const logStream = LogStream.instance('system-logs').build();
+ * await logStream.load();
+ *
+ * // Access the container through the stream
+ * const blockContainer = logStream._blocks; // Internal container
+ * const blocks = logStream.blocks; // Public access to blocks
+ *
+ * // Container automatically sorts blocks by blockNum
+ * console.log(`Stream has ${blocks.length} blocks`);
+ * blocks.forEach(block => {
+ *   console.log(`Block ${block.blockNum}: ${block.lineCount} lines`);
+ * });
+ * ```
+ *
+ * @example Direct Container Operations
+ * ```typescript
+ * // Create container (typically done internally)
+ * const container = LogBlockContainer.instance('log-blocks')
+ *   .options({})
+ *   .build();
+ *
+ * // Add blocks to container
+ * const block1 = LogBlock.instance('block-1')
+ *   .options({
+ *     nodeId: 'primary',
+ *     stream: 'app-logs',
+ *     blockNum: 1,
+ *     startLineNum: 1,
+ *     endLineNum: 100,
+ *     startTime: new Date('2024-01-01T10:00:00Z'),
+ *     endTime: new Date('2024-01-01T10:05:00Z'),
+ *     lineCount: 100
+ *   })
+ *   .build();
+ *
+ * const block2 = LogBlock.instance('block-2')
+ *   .options({
+ *     nodeId: 'primary',
+ *     stream: 'app-logs',
+ *     blockNum: 2,
+ *     startLineNum: 101,
+ *     endLineNum: 200,
+ *     startTime: new Date('2024-01-01T10:05:00Z'),
+ *     endTime: new Date('2024-01-01T10:10:00Z'),
+ *     lineCount: 100
+ *   })
+ *   .build();
+ *
+ * container.addModel(block1);
+ * container.addModel(block2);
+ *
+ * // Blocks are automatically sorted by blockNum
+ * const sortedBlocks = container.data;
+ * console.log(`First block: ${sortedBlocks[0].blockNum}`); // 1
+ * console.log(`Second block: ${sortedBlocks[1].blockNum}`); // 2
+ * ```
+ *
+ * @example React Block List Component
+ * ```typescript
+ * const BlockList: React.FC<{ container: LogBlockContainerModel }> = kosComponent(({ container }) => {
+ *   return (
+ *     <div className="block-list">
+ *       <h3>Log Blocks ({container.data.length})</h3>
+ *       <div className="blocks">
+ *         {container.data.map(block => (
+ *           <div key={block.id} className="block-item">
+ *             <div className="block-header">
+ *               <span className="block-num">Block {block.blockNum}</span>
+ *               <span className="line-range">
+ *                 Lines {block.startLineNum}-{block.endLineNum}
+ *               </span>
+ *             </div>
+ *             <div className="block-details">
+ *               <span>Stream: {block.stream}</span>
+ *               <span>Lines: {block.lineCount}</span>
+ *               <span>Loaded: {block.lines.length}</span>
+ *             </div>
+ *             <div className="block-time">
+ *               {block.startTime.toLocaleString()} - {block.endTime.toLocaleString()}
+ *             </div>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * });
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @interface
+ *
+ * @see {@link LogStreamModel} - Parent stream model that uses this container
+ * @see {@link LogBlockModel} - Individual log blocks managed by this container
+ * @see {@link LogBlockContainerOptions} - Configuration options for the container
+ */
 export type LogBlockContainerModel = PublicModelInterface<LogBlockContainerModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogBlockContainerModelImpl implements IKosIdentifiable, IKosModelHolder<LogBlockModel>, IKosDataModel {
     id: string;
     private logger;

package/models/models/log-block/log-block-container-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-block-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-container-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAEtD,MAAM,MAAM,sBAAsB,GAChC,oBAAoB,CAAC,0BAA0B,CAAC,CAAC;AAEnD,qBACa,0BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa;IAE1E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAoC;gBAE3D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,kBAAkB;IAa7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,sCAET;IACD,IAAI,IAAI,oBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa;IAI7B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"log-block-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-container-model.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,UAAU,8BAA8B,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,MAAM,MAAM,sBAAsB,GAChC,oBAAoB,CAAC,0BAA0B,CAAC,CAAC;AAEnD;;;GAGG;AACH,qBACa,0BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa;IAE1E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACvB,OAAO,CAAC,OAAO,CAAoC;gBAE3D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,kBAAkB;IAa7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,sCAET;IACD,IAAI,IAAI,oBAEP;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa;IAI7B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/models/models/log-block/log-block-model.d.ts

@@ -4,7 +4,192 @@ import { IKosIdentifiable } from '../../../core/core/types';
 import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 
 export declare const MODEL_TYPE = "log-block-model";
+/**
+ * Log Block Model - Individual log data block management within streaming log systems.
+ *
+ * This model represents a single block of log data within a LogStreamModel, providing efficient
+ * memory management and organized access to log lines. Log blocks are the fundamental storage
+ * units that enable high-performance log streaming by breaking large log streams into
+ * manageable, sequential segments with precise line numbering and timing information.
+ *
+ * ## Key Features
+ * - **Block-based Storage** - Efficient memory usage through segmented log storage
+ * - **Line Management** - Precise line numbering with start/end tracking
+ * - **Time-based Organization** - Temporal ordering with start and end timestamps
+ * - **Dynamic Loading** - On-demand synchronization of log lines from source
+ * - **Incremental Updates** - Add new lines without full reload
+ * - **Stream Integration** - Seamless integration with LogStreamModel containers
+ *
+ * ## Architecture Relationship
+ * LogBlock works as a component within the broader log streaming architecture:
+ * - **LogStreamModel** contains multiple LogBlockModels via LogBlockContainerModel
+ * - **LogBlockContainerModel** manages and sorts blocks by block number
+ * - **LogBlockModel** stores the actual log lines and metadata for a specific segment
+ * - This design enables efficient memory usage and fast access to recent log data
+ *
+ * ## Common Use Cases
+ * - **Memory-efficient Log Storage** - Break large log streams into manageable blocks
+ * - **Sequential Log Access** - Navigate through log history by block
+ * - **Selective Loading** - Load only needed blocks for performance
+ * - **Log Line Management** - Add, retrieve, and manage individual log entries
+ * - **Time-based Log Analysis** - Filter and analyze logs by time ranges
+ * - **Stream Synchronization** - Keep log blocks synchronized with source streams
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * // Typically accessed through LogStreamModel, not created directly
+ * const logStream = LogStream.instance('app-logs')
+ *   .options({ name: 'application-logs', nodeId: 'primary' })
+ *   .build();
+ *
+ * await logStream.load();
+ *
+ * // Access blocks within the stream
+ * const blocks = logStream.blocks;
+ * const currentBlock = logStream.currentBlock;
+ *
+ * if (currentBlock) {
+ *   console.log(`Block ${currentBlock.blockNum}`);
+ *   console.log(`Lines: ${currentBlock.startLineNum}-${currentBlock.endLineNum}`);
+ *   console.log(`Time range: ${currentBlock.startTime} to ${currentBlock.endTime}`);
+ *   console.log(`Line count: ${currentBlock.lineCount}`);
+ * }
+ * ```
+ *
+ * @example Block Line Management
+ * ```typescript
+ * // Access through log stream
+ * const logStream = LogStream.instance('system-logs').build();
+ * const block = logStream.currentBlock;
+ *
+ * if (block) {
+ *   // Get current lines
+ *   console.log(`Block has ${block.lines.length} loaded lines`);
+ *
+ *   // Add new lines (typically done automatically by stream)
+ *   block.addLines(['New log entry 1', 'New log entry 2']);
+ *
+ *   // Sync with remote source
+ *   await block.syncLines();
+ *
+ *   // Process lines
+ *   block.lines.forEach((line, index) => {
+ *     const globalLineNum = block.startLineNum + index;
+ *     console.log(`Line ${globalLineNum}: ${line}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example Block Analysis and Filtering
+ * ```typescript
+ * // Analyze blocks within a stream
+ * const logStream = LogStream.instance('error-logs').build();
+ * await logStream.load();
+ *
+ * // Find blocks within a time range
+ * const startTime = new Date('2024-01-01T00:00:00Z');
+ * const endTime = new Date('2024-01-01T23:59:59Z');
+ *
+ * const blocksInRange = logStream.blocks.filter(block =>
+ *   block.startTime >= startTime && block.endTime <= endTime
+ * );
+ *
+ * console.log(`Found ${blocksInRange.length} blocks in date range`);
+ *
+ * // Process error logs from specific blocks
+ * for (const block of blocksInRange) {
+ *   await block.syncLines(); // Ensure lines are loaded
+ *
+ *   const errorLines = block.lines
+ *     .map((line, index) => ({ line, lineNum: block.startLineNum + index }))
+ *     .filter(({ line }) => line.includes('ERROR'));
+ *
+ *   if (errorLines.length > 0) {
+ *     console.log(`Block ${block.blockNum} has ${errorLines.length} errors`);
+ *     errorLines.forEach(({ line, lineNum }) => {
+ *       console.log(`Line ${lineNum}: ${line}`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Block Container Integration
+ * ```typescript
+ * // Access blocks through their container
+ * const logStream = LogStream.instance('debug-logs').build();
+ * const blockContainer = logStream.blocks; // This is a LogBlockContainerModel
+ *
+ * // Blocks are automatically sorted by block number
+ * const sortedBlocks = blockContainer.data;
+ * console.log(`Stream has ${sortedBlocks.length} blocks`);
+ *
+ * // Get specific block by ID
+ * const blockId = 'debug-logs-block-5';
+ * const specificBlock = blockContainer.getModel(blockId);
+ *
+ * if (specificBlock) {
+ *   console.log(`Block ${specificBlock.blockNum} loaded`);
+ *   await specificBlock.syncLines();
+ * }
+ *
+ * // Add new block to container (typically done automatically)
+ * const newBlockOptions: LogBlockOptions = {
+ *   nodeId: 'primary',
+ *   stream: 'debug-logs',
+ *   blockNum: 10,
+ *   startLineNum: 1000,
+ *   endLineNum: 1099,
+ *   startTime: new Date(),
+ *   endTime: new Date(Date.now() + 60000),
+ *   lineCount: 100
+ * };
+ *
+ * const newBlock = LogBlock.instance('debug-logs-block-10')
+ *   .options(newBlockOptions)
+ *   .build();
+ *
+ * blockContainer.addModel(newBlock);
+ * ```
+ *
+ * @example Block Update and Synchronization
+ * ```typescript
+ * const block = logStream.currentBlock;
+ *
+ * if (block) {
+ *   // Update block metadata (typically done by stream management)
+ *   const updatedOptions: LogBlockOptions = {
+ *     ...block,
+ *     endLineNum: block.endLineNum + 50,
+ *     endTime: new Date(),
+ *     lineCount: block.lineCount + 50
+ *   };
+ *
+ *   block.updateModel(updatedOptions);
+ *
+ *   // Sync to get new lines
+ *   await block.syncLines();
+ *
+ *   console.log(`Block now has ${block.lines.length} lines loaded`);
+ *   console.log(`Updated end time: ${block.endTime}`);
+ * }
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamModel} - Parent stream model that contains log blocks
+ * @see {@link LogBlockContainerModel} - Container that manages multiple log blocks
+ * @see {@link LogBlockOptions} - Configuration options for log block instances
+ * @see {@link LogBlockType} - Type definition for block data exchange
+ * @see {@link LogLinesType} - Type definition for line data with block metadata
+ */
 export type LogBlockModel = PublicModelInterface<LogBlockModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogBlockModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
     private logger;

package/models/models/log-block/log-block-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-block-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,GAAG,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAiBvB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAehC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQ3C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAS5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"log-block-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoLG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE;;;GAGG;AACH,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,GAAG,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAiBvB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAehC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQ3C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAS5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}