@kosdev-code/kos-ui-sdk 0.1.0-dev.5053

package/models/models/config-bean-prop/types/index.d.ts

@@ -0,0 +1,352 @@
+import { ConfigPropertyTypes } from '../../types';
+import { IKosDataModel } from '../../core';
+import { SchemaNodeType, SchemaOptionsType } from '../../../services/config-bean';
+import { UnitConverter } from '../../../decorators';
+
+
+/**
+ * Unit conversion configuration for KosConfigProperty instances.
+ *
+ * Defines how configuration property values should be converted between backend
+ * storage units (typically SI) and regional display units. The converter enables
+ * automatic unit conversion based on device region while maintaining precision.
+ *
+ * @example Temperature Conversion
+ * ```typescript
+ * const temperatureConverter: ConfigPropConverter = {
+ *   measure: 'temperature',
+ *   from: { unit: 'kelvin', system: 'si' }, // Backend storage
+ *   to: { system: 'auto' } // Auto-detect regional display
+ * };
+ * ```
+ *
+ * @example Volume Conversion with Specific Units
+ * ```typescript
+ * const volumeConverter: ConfigPropConverter = {
+ *   measure: 'volume',
+ *   from: { unit: 'liter' }, // Backend in liters
+ *   to: { unit: 'fluid-ounce', system: 'imperial' } // Force US fluid ounces
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export interface ConfigPropConverter {
+  /**
+   * The physical measure being converted (temperature, volume, pressure, etc.).
+   * This helps the system understand what type of conversion to perform.
+   */
+  measure?: string;
+
+  /**
+   * Source unit configuration (typically backend storage units).
+   * Defines the unit system and specific unit that values are stored in.
+   */
+  from?: UnitConverter;
+
+  /**
+   * Target unit configuration (display units).
+   * Defines how values should be displayed to users, including regional preferences.
+   */
+  to?: UnitConverter;
+}
+
+/**
+ * Formatting options for numeric configuration property display values.
+ *
+ * Supports both static formatting options and dynamic formatting based on unit system.
+ * Built on top of the Intl.NumberFormat API for internationalization support.
+ *
+ * @example Static Formatting Options
+ * ```typescript
+ * const staticFormatter: FormatOptions = {
+ *   style: 'unit',
+ *   unit: 'celsius',
+ *   maximumFractionDigits: 1
+ * };
+ * ```
+ *
+ * @example Dynamic System-Based Formatting
+ * ```typescript
+ * const dynamicFormatter: FormatOptions = (system: string) => {
+ *   if (system === 'imperial') {
+ *     return { style: 'unit', unit: 'fahrenheit', maximumFractionDigits: 0 };
+ *   }
+ *   return { style: 'unit', unit: 'celsius', maximumFractionDigits: 1 };
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export type FormatOptions =
+  | Intl.NumberFormatOptions
+  | ((system: string) => Intl.NumberFormatOptions);
+
+/**
+ * Option definition for enumerated configuration properties.
+ *
+ * Represents a single selectable option with a display label and internal value.
+ * Used for configuration properties that have predefined valid values.
+ *
+ * @example Basic Options
+ * ```typescript
+ * const optionsList: OptionsType[] = [
+ *   { label: 'Low Speed', value: 'low' },
+ *   { label: 'Medium Speed', value: 'medium' },
+ *   { label: 'High Speed', value: 'high' }
+ * ];
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export interface OptionsType {
+  /** The internal value used by the system */
+  value: string;
+  /** The human-readable display label */
+  label: string;
+}
+
+/**
+ * Options provider for configuration properties with enumerated values.
+ *
+ * Can be either a static list of options or a dynamic function that generates
+ * options based on the current unit system. Useful for configuration properties
+ * that need different option sets based on regional settings.
+ *
+ * @example Static Options List
+ * ```typescript
+ * const staticOptions: OptionsExpander = [
+ *   { label: 'Automatic', value: 'auto' },
+ *   { label: 'Manual', value: 'manual' },
+ *   { label: 'Disabled', value: 'disabled' }
+ * ];
+ * ```
+ *
+ * @example Dynamic System-Based Options
+ * ```typescript
+ * const dynamicOptions: OptionsExpander = (system: string, schemaOptions?: string[]) => {
+ *   const baseOptions = [
+ *     { label: 'Automatic', value: 'auto' },
+ *     { label: 'Manual', value: 'manual' }
+ *   ];
+ *
+ *   // Add system-specific options
+ *   if (system === 'imperial') {
+ *     baseOptions.push({ label: 'Imperial Mode', value: 'imperial' });
+ *   } else if (system === 'metric') {
+ *     baseOptions.push({ label: 'Metric Mode', value: 'metric' });
+ *   }
+ *
+ *   return baseOptions;
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export type OptionsExpander =
+  | OptionsType[]
+  | ((system: string, options?: string[]) => OptionsType[]);
+
+/**
+ * Configuration options for KosConfigProperty instances.
+ *
+ * These options define how individual configuration properties access and display
+ * values from the backend configuration system. They specify the configuration path,
+ * attribute name, and optional unit conversion and formatting behavior.
+ *
+ * @example Basic Property Configuration
+ * ```typescript
+ * const pumpRateOptions: ConfigBeanPropOptions = {
+ *   path: 'assembly:core:board:micro:pump:S4',
+ *   attribute: 'nominalRate'
+ * };
+ * ```
+ *
+ * @example Property with Unit Conversion
+ * ```typescript
+ * const temperatureOptions: ConfigBeanPropOptions = {
+ *   path: 'assembly:core:board:cooling',
+ *   attribute: 'targetTemperature',
+ *   converter: {
+ *     measure: 'temperature',
+ *     from: { unit: 'kelvin' },
+ *     to: { system: 'auto' }
+ *   },
+ *   formatter: {
+ *     style: 'unit',
+ *     maximumFractionDigits: 1
+ *   }
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export interface ConfigBeanPropOptions {
+  /**
+   * The hierarchical configuration path using colon-separated notation.
+   *
+   * This path identifies the specific configuration bean that contains
+   * the target attribute. Must match the path used by the parent ConfigBeanModel.
+   *
+   * @example Common Configuration Paths
+   * ```typescript
+   * // Hardware component configuration
+   * path: 'assembly:core:board:micro:pump:S4'
+   *
+   * // System-level configuration
+   * path: 'system:app'
+   *
+   * // Service configuration
+   * path: 'kos:service:CANPumpMgr'
+   * ```
+   */
+  path: string;
+
+  /**
+   * The specific attribute name within the configuration bean.
+   *
+   * This identifies which property within the configuration bean
+   * this KosConfigProperty instance should access and manage.
+   *
+   * @example Attribute Examples
+   * ```typescript
+   * attribute: 'nominalRate'      // For pump flow rates
+   * attribute: 'targetTemperature' // For temperature settings
+   * attribute: 'enabled'          // For boolean flags
+   * attribute: 'retryCount'       // For numeric counters
+   * ```
+   */
+  attribute: string;
+
+  /**
+   * Optional unit conversion configuration.
+   *
+   * When provided, enables automatic conversion between backend storage units
+   * and regional display units. If omitted, no unit conversion is performed.
+   *
+   * @example Temperature Conversion
+   * ```typescript
+   * converter: {
+   *   from: { unit: 'kelvin', system: 'si' },
+   *   to: { system: 'auto' } // Auto-detect regional system
+   * }
+   * ```
+   */
+  converter?: { from?: UnitConverter; to?: UnitConverter };
+
+  /**
+   * Optional display formatting configuration.
+   *
+   * Configures how numeric values are formatted for display, including
+   * decimal places, units, and locale-specific formatting rules.
+   *
+   * @example Custom Formatting
+   * ```typescript
+   * formatter: {
+   *   style: 'unit',
+   *   unit: 'celsius',
+   *   maximumFractionDigits: 1,
+   *   minimumFractionDigits: 1
+   * }
+   * ```
+   */
+  formatter?: FormatOptions;
+
+  /**
+   * Optional predefined options for enumerated properties.
+   *
+   * Provides a list of valid values for configuration properties that
+   * have discrete options rather than continuous values.
+   *
+   * @example Static Options
+   * ```typescript
+   * optionsExpander: [
+   *   { label: 'Low', value: 'low' },
+   *   { label: 'Medium', value: 'medium' },
+   *   { label: 'High', value: 'high' }
+   * ]
+   * ```
+   */
+  optionsExpander?: OptionsExpander;
+
+  /**
+   * Optional custom service base path.
+   *
+   * When provided, overrides the default configuration service endpoint.
+   * Useful for testing, development, or alternative service implementations.
+   *
+   * @default undefined (uses default KOS configuration service path)
+   */
+  serviceBasePath?: string;
+}
+
+/**
+ * Individual configuration property with automatic unit conversion and regional formatting.
+ *
+ * Provides type-safe access to specific configuration attributes with built-in unit conversion
+ * between backend storage units (typically SI) and regional display units.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const pumpRate = KosConfigProperty.create('pump-rate', {
+ *   path: 'assembly:core:board:micro:pump:S4',
+ *   attribute: 'nominalRate'
+ * });
+ * ```
+ *
+ * @group KOS Model
+ * @category Configuration
+ */
+export interface KosConfigProperty<
+  PropertyType extends ConfigPropertyTypes = ConfigPropertyTypes
+> extends ConfigBeanPropOptions,
+    IKosDataModel {
+  /** Unique identifier for the config property instance */
+  id: string;
+
+  /** Optional custom service base path for configuration endpoints */
+  serviceBasePath?: string;
+
+  /** The unit of measure for the property after regional conversion (e.g., "°F", "mL/s") */
+  readonly unit?: string;
+
+  /** The property value converted to regional units */
+  readonly value?: PropertyType;
+
+  /** The raw backend value before any unit conversion (typically SI units) */
+  readonly rawValue?: PropertyType;
+
+  /** The property value with appropriate decimal precision for display */
+  readonly significantValue?: PropertyType;
+
+  /** The previous value before the last update */
+  readonly previousValue?: PropertyType;
+
+  /** Formatted string representation of the value with units and localization */
+  readonly displayValue?: string;
+
+  /** Display configuration options from the backend schema */
+  readonly displayOptions?: SchemaOptionsType;
+
+  /** Available enumerated options for this property (if applicable) */
+  readonly options?: OptionsType[];
+
+  /** The data type of this property as defined in the backend schema */
+  readonly schemaType: SchemaNodeType | "enum";
+
+  /** Optional format specifier from the backend schema (e.g., "s", "ml", "drt") */
+  readonly schemaFormat?: string;
+
+  /**
+   * Updates the property value and persists it to the backend.
+   * Automatically handles unit conversion from display units to backend storage units.
+   *
+   * @param value The new value in display units
+   */
+  updateProperty: (value: PropertyType | string) => void;
+}

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

@@ -0,0 +1,258 @@
+import { DeviceOptions } from './types';
+import { IKosDataModel, IKosIdentifiable, KosCreationContext, PublicModelInterface } from '../../../core';
+
+export declare const MODEL_TYPE = "device-model";
+export declare const TOPIC_CRITICAL_DATA_CHANGED = "/kos/criticalData/changed";
+export declare const TOPIC_CRITICAL_DATA_AVAILABLE = "/kos/criticalData/available";
+export declare const TOPIC_CRITICAL_DATA_UNAVAILABLE = "/kos/criticalData/unavailable";
+/**
+ * KOS Device Model - Device Identity and Node Configuration Management
+ *
+ * The Device model provides centralized management of device identity, node configuration,
+ * and hardware identification within KOS systems. It handles device serial numbers,
+ * names, and node topology information essential for system coordination and administration.
+ *
+ * ## Key Features
+ *
+ * ### Device Identity Management
+ * - **Serial Number Tracking**: Hardware-based device identification
+ * - **Name Management**: Human-readable device naming for administration
+ * - **Node Configuration**: Multi-node deployment topology handling
+ *
+ * ### Real-time Synchronization
+ * - **Critical Data Events**: Automatic updates on system data changes
+ * - **WebSocket Integration**: Live device state synchronization
+ * - **Lazy Loading**: Efficient data retrieval when needed
+ *
+ * ### Node Topology Support
+ * - **Node Type/Name Parsing**: Automatic node identifier decomposition
+ * - **Multi-node Deployments**: Support for complex system architectures
+ * - **Role-based Configuration**: Node-specific parameter management
+ *
+ * ## Common Integration Patterns
+ *
+ * ### System Administration Dashboards
+ * ```typescript
+ * const device = Device.factory({
+ *   serialNumber: 'KOS-DEV-001',
+ *   name: 'Production Dispenser Alpha',
+ *   nodeId: 'primary-main'
+ * });
+ *
+ * // Access device identity
+ * console.log(`Device: ${device.name}`);
+ * console.log(`Serial: ${device.serialNumber}`);
+ * console.log(`Node: ${device.nodeType}-${device.nodeName}`);
+ * ```
+ *
+ * ### Multi-node System Coordination
+ * ```typescript
+ * const primaryDevice = Device.factory({
+ *   nodeId: 'primary-controller'
+ * });
+ *
+ * const secondaryDevice = Device.factory({
+ *   nodeId: 'secondary-backup'
+ * });
+ *
+ * // Coordinate based on node roles
+ * if (primaryDevice.nodeType === 'primary') {
+ *   // Handle primary node logic
+ * }
+ * ```
+ *
+ * ### Device Registration and Setup
+ * ```typescript
+ * const newDevice = Device.factory({
+ *   serialNumber: await getHardwareSerial(),
+ *   name: userProvidedName,
+ *   nodeId: deploymentConfiguration.nodeId
+ * });
+ *
+ * // Device automatically loads additional data
+ * // from critical data events
+ * ```
+ *
+ * ## Real-time Updates
+ *
+ * The Device model automatically responds to critical data changes:
+ * - Monitors `/kos/criticalData/changed` and `/kos/criticalData/available` topics
+ * - Updates serial number and configuration when system data becomes available
+ * - Maintains consistency across device restarts and configuration changes
+ *
+ * ## Singleton Behavior
+ *
+ * Device models use singleton pattern - each device type has one instance:
+ * - Subsequent factory calls return the existing instance
+ * - Options are ignored after first creation
+ * - Ensures system-wide device identity consistency
+ *
+ * This is an alias for the implementation {@link DeviceModelImpl}.
+ *
+ * @interface
+ * @group KOS Model
+ * @category Device Data
+ * @useDeclaredType
+ */
+export type DeviceModel = PublicModelInterface<DeviceModelImpl>;
+export declare class DeviceModelImpl implements IKosDataModel, IKosIdentifiable {
+    id: string;
+    private logger;
+    private _serialNumber;
+    /**
+     * Hardware-based device serial number for unique identification.
+     *
+     * Returns the device's hardware serial number or "unassigned" if not yet loaded.
+     * Serial numbers are typically retrieved from the device's hardware identification
+     * system during critical data events.
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({});
+     *
+     * // Check if serial number is available
+     * if (device.serialNumber !== "unassigned") {
+     *   console.log(`Device Serial: ${device.serialNumber}`);
+     * }
+     * ```
+     */
+    get serialNumber(): string | "unassigned";
+    private _name;
+    /**
+     * Human-readable device name for administrative identification.
+     *
+     * Returns the configured device name or "unassigned" if not yet set.
+     * Device names are typically configured during device setup and used
+     * in administrative interfaces for device identification and management.
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({
+     *   name: 'Main Production Dispenser'
+     * });
+     *
+     * console.log(`Device Name: ${device.name}`);
+     * // Output: "Device Name: Main Production Dispenser"
+     * ```
+     */
+    get name(): string | "unassigned";
+    private _nodeId;
+    /**
+     * Full node identifier within the KOS deployment.
+     *
+     * Returns the complete node ID or "unassigned" if not yet configured.
+     * Node IDs follow the pattern "type-instance" (e.g., "primary-main", "secondary-backup")
+     * and identify the specific node role and instance within multi-node deployments.
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({
+     *   nodeId: 'primary-controller'
+     * });
+     *
+     * console.log(`Node ID: ${device.nodeId}`);
+     * // Output: "Node ID: primary-controller"
+     * ```
+     *
+     * @see {@link nodeType} for extracting the node type portion
+     * @see {@link nodeName} for extracting the node name portion
+     */
+    get nodeId(): string | "unassigned";
+    /**
+     * Node type extracted from the node identifier.
+     *
+     * Returns the first part of the node ID (before the hyphen).
+     * For node ID "primary-controller", this returns "primary".
+     * Used for role-based logic and node coordination.
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({
+     *   nodeId: 'primary-controller'
+     * });
+     *
+     * console.log(`Node Type: ${device.nodeType}`);
+     * // Output: "Node Type: primary"
+     *
+     * // Role-based coordination
+     * if (device.nodeType === 'primary') {
+     *   // Handle primary node responsibilities
+     * }
+     * ```
+     */
+    get nodeType(): string;
+    /**
+     * Node name extracted from the node identifier.
+     *
+     * Returns the second part of the node ID (after the hyphen).
+     * For node ID "primary-controller", this returns "controller".
+     * Used for instance-specific identification within node types.
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({
+     *   nodeId: 'secondary-backup'
+     * });
+     *
+     * console.log(`Node Name: ${device.nodeName}`);
+     * // Output: "Node Name: backup"
+     *
+     * // Instance-specific logic
+     * if (device.nodeName === 'backup') {
+     *   // Handle backup node configuration
+     * }
+     * ```
+     */
+    get nodeName(): string;
+    constructor(modelId: string, _options: DeviceOptions, context: KosCreationContext);
+    /**
+     * Update the device model with new configuration options.
+     *
+     * Allows dynamic updating of device identity and node configuration.
+     * Any undefined values will be set to "unassigned". This method is typically
+     * called internally during device data loading or external configuration changes.
+     *
+     * @param options - Device configuration options to apply
+     *
+     * @example
+     * ```typescript
+     * const device = Device.factory({});
+     *
+     * // Update with new device information
+     * device.updateModel({
+     *   serialNumber: 'KOS-DEVICE-12345',
+     *   name: 'Updated Dispenser Name',
+     *   nodeId: 'primary-main'
+     * });
+     *
+     * console.log(device.serialNumber); // "KOS-DEVICE-12345"
+     * console.log(device.name);         // "Updated Dispenser Name"
+     * console.log(device.nodeId);       // "primary-main"
+     * ```
+     *
+     * @example Partial Updates
+     * ```typescript
+     * // Only update specific fields
+     * device.updateModel({
+     *   name: 'New Device Name'
+     *   // serialNumber and nodeId remain unchanged
+     * });
+     * ```
+     */
+    updateModel(options: DeviceOptions): void;
+    private loadDeviceData;
+    private loadSerialNumber;
+    /**
+     * Handle critical data changes to load the serial number at the appropriate time.
+     */
+    handleCriticalDataChanged(): Promise<void>;
+    /**
+     * @internal
+     */
+    init(): Promise<void>;
+    /**
+     * @internal
+     */
+    load(): Promise<void>;
+}
+//# sourceMappingURL=device-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"device-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/device/device-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEhB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,6BAA6B,gCAAgC,CAAC;AAC3E,eAAO,MAAM,+BAA+B,kCAAkC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC,eAAe,CAAC,CAAC;AAEhE,qBACa,eAAgB,YAAW,aAAa,EAAE,gBAAgB;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAAwB;IAE7C;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,YAAY,CAExC;IAED,OAAO,CAAC,KAAK,CAAwB;IAErC;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,YAAY,CAEhC;IAED,OAAO,CAAC,OAAO,CAAwB;IAEvC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,MAAM,IAAI,MAAM,GAAG,YAAY,CAElC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,QAAQ,IAAI,MAAM,CAGrB;gBAGC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,kBAAkB;IAS7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;YAM3B,cAAc;YAYd,gBAAgB;IAU9B;;OAEG;IAKG,yBAAyB;IAO/B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}