import { StatePropertyTypes } from '../../types';


/**
 * 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 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 = 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;
}
