// ---------------  LogBlock ---------------

/**
 * Configuration options for LogBlock model instances.
 *
 * These options define the metadata and boundaries for a log block, including
 * line numbering, timing information, and stream identification. Used when
 * creating new log blocks or updating existing block metadata.
 *
 * @example Basic Configuration
 * ```typescript
 * const blockOptions: LogBlockOptions = {
 *   nodeId: 'primary',
 *   stream: 'application-logs',
 *   blockNum: 5,
 *   startLineNum: 401,
 *   endLineNum: 500,
 *   startTime: new Date('2024-01-01T10:00:00Z'),
 *   endTime: new Date('2024-01-01T10:05:00Z'),
 *   lineCount: 100
 * };
 *
 * const logBlock = LogBlock.instance('app-block-5')
 *   .options(blockOptions)
 *   .build();
 * ```
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export interface LogBlockOptions {
  /**
   * Node identifier where the log block originates.
   *
   * Specifies which KOS device node contains this log block.
   * Used for routing and organization in multi-node environments.
   */
  nodeId: string;

  /**
   * Name of the log stream this block belongs to.
   *
   * Identifies the parent stream that contains this block.
   * Used for organization and cross-referencing with LogStreamModel.
   */
  stream: string;

  /**
   * Sequential block number within the stream.
   *
   * Used for ordering blocks chronologically within a stream.
   * Blocks are automatically sorted by this number in containers.
   */
  blockNum: number;

  /**
   * Global line number where this block starts.
   *
   * The first line number in this block relative to the entire stream.
   * Used for accurate line numbering across the complete log stream.
   */
  startLineNum: number;

  /**
   * Global line number where this block ends.
   *
   * The last line number in this block relative to the entire stream.
   * Used with startLineNum to define the block's line range.
   */
  endLineNum: number;

  /**
   * Timestamp when this log block period began.
   *
   * Used for time-based filtering and analysis of log blocks.
   */
  startTime: Date;

  /**
   * Timestamp when this log block period ended.
   *
   * Used with startTime to define the temporal range of the block.
   */
  endTime: Date;

  /**
   * Total number of log lines in this block.
   *
   * Should equal (endLineNum - startLineNum + 1). Used for
   * validation and progress tracking during block loading.
   */
  lineCount: number;
}

// ---------------  LogBlockContainer ---------------

/**
 * Configuration options for LogBlockContainer model instances.
 *
 * Currently an empty interface but reserved for future container-level
 * configuration options such as block sorting preferences, memory limits,
 * or automatic cleanup policies.
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
// eslint-disable-next-line @typescript-eslint/no-empty-interface
export interface LogBlockContainerOptions {}

/**
 * Data exchange format for log block information from KOS topics.
 *
 * Used in topic handlers for log block events, representing block metadata
 * as received from the KOS system. Similar to LogBlockOptions but uses
 * timestamp numbers instead of Date objects for serialization efficiency.
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export interface LogBlockType {
  /** Node identifier where the log block originates */
  nodeId: string;
  /** Name of the log stream this block belongs to */
  stream: string;
  /** Sequential block number within the stream */
  blockNum: number;
  /** Global line number where this block starts */
  startLineNum: number;
  /** Global line number where this block ends */
  endLineNum: number;
  /** Timestamp when this log block period began (milliseconds since epoch) */
  startTime: number;
  /** Timestamp when this log block period ended (milliseconds since epoch) */
  endTime: number;
  /** Total number of log lines in this block */
  lineCount: number;
}

/**
 * Data exchange format for log lines with block metadata from KOS topics.
 *
 * Used in topic handlers for log line events, containing both the actual
 * log lines and the block metadata. Extends LogBlockType with the lines array.
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export interface LogLinesType {
  /** Node identifier where the log block originates */
  nodeId: string;
  /** Name of the log stream this block belongs to */
  stream: string;
  /** Sequential block number within the stream */
  blockNum: number;
  /** Global line number where this block starts */
  startLineNum: number;
  /** Global line number where this block ends */
  endLineNum: number;
  /** Timestamp when this log block period began (milliseconds since epoch) */
  startTime: number;
  /** Timestamp when this log block period ended (milliseconds since epoch) */
  endTime: number;
  /** Total number of log lines in this block */
  lineCount: number;
  /** Array of actual log line strings */
  lines: string[];
}
