iobroker.utility-monitor 1.4.6 → 1.5.1

package/lib/calculator.js

@@ -1,25 +1,37 @@
+const helpers = require('./utils/helpers');
+
 /**
- * Calculator module for nebenkosten-monitor
- * Provides utility functions for gas conversion, cost calculation, and consumption aggregation
+ * @file Calculator module for utility consumption and cost calculations.
+ * Contains functions for gas conversion, cost calculation, and tariff handling.
+ * @module calculator
  */
 
 /**
- * Converts gas volume from m³ to kWh
- * Formula: kWh = m³ × Brennwert × Z-Zahl
+ * Converts gas volume from cubic meters (m³) to kilowatt-hours (kWh).
+ * The conversion uses the standard German gas billing formula:
+ * kWh = m³ × Brennwert (calorific value) × Z-Zahl (state number)
+ * Brennwert: Energy content per cubic meter, typically 9.5-11.5 kWh/m³.
+ * Z-Zahl: Correction factor for temperature and pressure differences.
  *
- * @param {number} m3 - Volume in cubic meters
- * @param {number} brennwert - Calorific value (typically ~11.5 kWh/m³)
- * @param {number} zZahl - Z-number/state number (typically ~0.95)
- * @returns {number} Energy in kWh
+ * @param {number} m3 - Gas volume in cubic meters (must be >= 0)
+ * @param {number} brennwert - Calorific value in kWh/m³ (must be > 0)
+ * @param {number} zZahl - State number (must be > 0 and <= 1)
+ * @returns {number} Energy consumption in kWh
+ * @throws {RangeError} If parameters are outside valid ranges
  */
 function convertGasM3ToKWh(m3, brennwert = 11.5, zZahl = 0.95) {
-    if (typeof m3 !== 'number' || typeof brennwert !== 'number' || typeof zZahl !== 'number') {
-        throw new TypeError('All parameters must be numbers');
-    }
-    if (m3 < 0 || brennwert <= 0 || zZahl <= 0 || zZahl > 1) {
-        throw new RangeError('Invalid parameter values');
+    const cleanM3 = helpers.ensureNumber(m3);
+    const cleanBrennwert = helpers.ensureNumber(brennwert);
+    const cleanZZahl = helpers.ensureNumber(zZahl);
+
+    // Validate parameters
+    if (cleanM3 < 0 || cleanBrennwert <= 0 || cleanZZahl <= 0 || cleanZZahl > 1) {
+        throw new RangeError(
+            'Invalid parameters for gas conversion: m3 must be >= 0, brennwert must be > 0, zZahl must be > 0 and <= 1',
+        );
     }
-    return m3 * brennwert * zZahl;
+
+    return cleanM3 * cleanBrennwert * cleanZZahl;
 }
 
 /**
@@ -52,74 +64,14 @@ function calculateCost(consumption, price) {
 }
 
 /**
- * Ensures a value is a number, handling German decimal commas if provided as string.
- *
- * @param {any} value - Value to convert
- * @returns {number}
- */
-function ensureNumber(value) {
-    if (value === undefined || value === null || value === '') {
-        return 0;
-    }
-    if (typeof value === 'string') {
-        const normalized = value.replace(',', '.');
-        const parsed = parseFloat(normalized);
-        return isNaN(parsed) ? 0 : parsed;
-    }
-    const num = Number(value);
-    return isNaN(num) ? 0 : num;
-}
-
-/**
- * Rounds a number to specified decimal places
+ * Checks if the current time falls within the High Tariff (HT) period.
+ * German electricity providers often offer dual-tariff rates:
+ * HT (Haupttarif): Higher rate during peak hours (typically 6:00-22:00)
+ * NT (Nebentarif): Lower rate during off-peak hours (typically 22:00-6:00)
  *
- * @param {number|string} value - Value to round
- * @param {number} decimals - Number of decimal places (default: 2)
- * @returns {number} Rounded value
- */
-function roundToDecimals(value, decimals = 2) {
-    const numValue = ensureNumber(value);
-    const factor = Math.pow(10, decimals);
-    return Math.round(numValue * factor) / factor;
-}
-
-/**
- * Parses a German date string (DD.MM.YYYY) into a Date object
- *
- * @param {string} dateStr - Date string in format DD.MM.YYYY
- * @returns {Date|null} Date object or null if invalid
- */
-function parseGermanDate(dateStr) {
-    if (!dateStr || typeof dateStr !== 'string') {
-        return null;
-    }
-    const parts = dateStr.trim().split('.');
-    if (parts.length !== 3) {
-        return null;
-    }
-    let day = parseInt(parts[0], 10);
-    let month = parseInt(parts[1], 10) - 1; // Month is 0-indexed
-    let year = parseInt(parts[2], 10);
-
-    // Handle 2-digit years (e.g. 25 -> 2025)
-    if (year < 100) {
-        year += 2000;
-    }
-
-    if (isNaN(day) || isNaN(month) || isNaN(year)) {
-        return null;
-    }
-
-    // Create date at noon to avoid timezone shift issues (especially with ISO export)
-    return new Date(year, month, day, 12, 0, 0);
-}
-
-/**
- * Checks if the current time is within the High Tariff (HT) period
- *
- * @param {object} config - Adapter configuration
- * @param {string} type - Utility type: 'gas' or 'strom'
- * @returns {boolean} True if current time is HT, false if NT
+ * @param {object} config - Adapter configuration object with HT/NT settings
+ * @param {string} type - Utility type identifier: 'gas', 'strom', 'wasser', or 'pv'
+ * @returns {boolean} True if current time is within HT period, false for NT
  */
 function isHTTime(config, type) {
     if (!config || !type) {
@@ -180,75 +132,18 @@ const DEFAULTS = {
     MIN_CONSUMPTION: 0,
 };
 
-/**
- * Formats a Date object to YYYY-MM-DD HH:mm:ss string
- *
- * @param {Date} date - Date object
- * @returns {string|null} Formatted date string or null
- */
-function formatDateString(date) {
-    if (!date) {
-        return null;
-    }
-    if (!(date instanceof Date)) {
-        // If it's already a string, try to parse and re-format, or just return if it handles
-        // But the error said "calculator.formatDateString is not a function", so we need it here.
-        return null;
-    }
-
-    const pad = num => num.toString().padStart(2, '0');
-    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
-}
-
-/**
- * Parses a date string (ISO or standard format)
- *
- * @param {string} dateStr - Date string
- * @returns {Date|null} Date object or null
- */
-function parseDateString(dateStr) {
-    if (!dateStr) {
-        return null;
-    }
-    const date = new Date(dateStr);
-    if (isNaN(date.getTime())) {
-        return null;
-    }
-    return date;
-}
-
-/**
- * Checks if a year is a leap year
- *
- * @param {number} year - Year to check
- * @returns {boolean} True if leap year
- */
-function isLeapYear(year) {
-    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
-}
-
-/**
- * Calculates the difference in months between two dates
- *
- * @param {Date} startDate - Start date
- * @param {Date} endDate - End date
- * @returns {number} Difference in months
- */
-function getMonthsDifference(startDate, endDate) {
-    return (endDate.getFullYear() - startDate.getFullYear()) * 12 + (endDate.getMonth() - startDate.getMonth());
-}
-
 module.exports = {
     convertGasM3ToKWh,
     getCurrentPrice,
     calculateCost,
-    ensureNumber,
-    roundToDecimals,
-    parseGermanDate,
     isHTTime,
-    formatDateString,
-    parseDateString,
-    isLeapYear,
-    getMonthsDifference,
     DEFAULTS,
+    // Re-export helpers for backward compatibility
+    ensureNumber: helpers.ensureNumber,
+    roundToDecimals: helpers.roundToDecimals,
+    parseGermanDate: helpers.parseGermanDate,
+    formatDateString: helpers.formatDateString,
+    parseDateString: s => helpers.parseGermanDate(s),
+    isLeapYear: helpers.isLeapYear,
+    getMonthsDifference: helpers.getMonthsDifference,
 };

package/lib/consumptionManager.js

@@ -1,11 +1,12 @@
 'use strict';
 
 const calculator = require('./calculator');
+const { getConfigType } = require('./utils/typeMapper');
 const stateManager = require('./stateManager');
 
 /**
- * ConsumptionManager handles all sensor-related logic,
- * including initialization, unit conversion, and sensor updates.
+ * ConsumptionManager handles utility initialization and price updates.
+ * NOTE: Sensor handling has been moved to MultiMeterManager since v1.4.6.
  */
 class ConsumptionManager {
     /**
@@ -13,22 +14,6 @@ class ConsumptionManager {
      */
     constructor(adapter) {
         this.adapter = adapter;
-        this.lastSensorValues = {};
-    }
-
-    /**
-     * Maps internal utility type to config/state name
-     *
-     * @param {string} type - gas, water, or electricity
-     * @returns {string} - gas, wasser, or strom
-     */
-    getConfigType(type) {
-        const mapping = {
-            electricity: 'strom',
-            water: 'wasser',
-            gas: 'gas',
-        };
-        return mapping[type] || type;
     }
 
     /**
@@ -50,7 +35,7 @@ class ConsumptionManager {
         // State structure is now created by MultiMeterManager per meter (v1.4.6)
         // Old createUtilityStateStructure removed - states are created under type.meterName.*
 
-        const configType = this.getConfigType(type);
+        const configType = getConfigType(type);
         const sensorDPKey = `${configType}SensorDP`;
         const sensorDP = this.adapter.config[sensorDPKey];
 
@@ -79,244 +64,16 @@ class ConsumptionManager {
         }
 
         // Note: All initialization moved to MultiMeterManager in v1.4.6:
+        // - State creation (per meter)
         // - Sensor value restoration (per meter)
         // - Period start timestamps (per meter)
+        // - Initial yearly consumption calculation (per meter)
         // - Current price updates (per meter)
         // - Cost calculations (per meter)
+        // - Billing countdown (per meter)
         // Old type-level states (gas.info.*, gas.statistics.*) are no longer used
 
-        // Initialize yearly consumption from initial reading if set
-        // NOTE: This is now handled per meter by MultiMeterManager in v1.4.6
-        // This legacy code path should not execute for new setups, but is kept for safety
-        const initialReadingKey = `${configType}InitialReading`;
-        const initialReading = this.adapter.config[initialReadingKey] || 0;
-
-        if (initialReading > 0 && sensorDP) {
-            // Get the main meter name to use the correct path
-            const mainMeterNameKey = `${configType}MainMeterName`;
-            const mainMeterName = this.adapter.config[mainMeterNameKey] || 'main';
-            const basePath = `${type}.${mainMeterName}`;
-
-            const sensorState = await this.adapter.getForeignStateAsync(sensorDP);
-            if (sensorState && typeof sensorState.val === 'number') {
-                let currentRaw = sensorState.val;
-
-                // Apply offset if configured (in original unit)
-                const offsetKey = `${configType}Offset`;
-                const offset = this.adapter.config[offsetKey] || 0;
-                if (offset !== 0) {
-                    currentRaw = currentRaw - offset;
-                    this.adapter.log.debug(`Applied offset for ${type}: -${offset}, new value: ${currentRaw}`);
-                }
-                let yearlyConsumption = Math.max(0, currentRaw - initialReading);
-
-                // For gas: convert m³ to kWh AFTER calculating the difference
-                if (type === 'gas') {
-                    const brennwert = this.adapter.config.gasBrennwert || 11.5;
-                    const zZahl = this.adapter.config.gasZahl || 0.95;
-                    const yearlyVolume = yearlyConsumption;
-                    yearlyConsumption = calculator.convertGasM3ToKWh(yearlyConsumption, brennwert, zZahl);
-                    await this.adapter.setStateAsync(`${basePath}.consumption.yearlyVolume`, yearlyVolume, true);
-                    this.adapter.log.info(
-                        `Init yearly ${type}: ${yearlyConsumption.toFixed(2)} kWh = ${(currentRaw - initialReading).toFixed(2)} m³ (current: ${currentRaw.toFixed(2)} m³, initial: ${initialReading} m³)`,
-                    );
-                } else {
-                    this.adapter.log.info(
-                        `Init yearly ${type}: ${yearlyConsumption.toFixed(2)} (current: ${currentRaw.toFixed(2)}, initial: ${initialReading})`,
-                    );
-                }
-
-                await this.adapter.setStateAsync(`${basePath}.consumption.yearly`, yearlyConsumption, true);
-                if (typeof this.adapter.updateCosts === 'function') {
-                    await this.adapter.updateCosts(type);
-                }
-            }
-        }
-
-        // Note: Billing countdown is now handled per meter by billingManager.updateBillingCountdown()
-        // which is called during checkPeriodResets()
-
-        this.adapter.log.debug(`Initial cost calculation completed for ${type}`);
-    }
-
-    /**
-     * Handles sensor value updates
-     *
-     * NOTE: This method is DEPRECATED since v1.4.6!
-     * All sensor updates are now handled by MultiMeterManager.handleSensorUpdate()
-     * This method remains only as fallback but should NEVER be called in normal operation.
-     *
-     * @param {string} type - Utility type
-     * @param {string} sensorDP - Sensor datapoint ID
-     * @param {number} value - New sensor value
-     */
-    async handleSensorUpdate(type, sensorDP, value) {
-        this.adapter.log.warn(
-            `consumptionManager.handleSensorUpdate() called - this is deprecated! All sensors should be handled by MultiMeterManager.`,
-        );
-
-        if (typeof value !== 'number' || value < 0) {
-            this.adapter.log.warn(`Invalid sensor value for ${type}: ${value}`);
-            return;
-        }
-
-        this.adapter.log.debug(`[DEPRECATED] Sensor update for ${type}: ${value}`);
-
-        const now = Date.now();
-        let consumption = value;
-        let consumptionM3 = null;
-
-        const configType = this.getConfigType(type);
-
-        // Apply offset FIRST
-        const offsetKey = `${configType}Offset`;
-        const offset = this.adapter.config[offsetKey] || 0;
-        if (offset !== 0) {
-            consumption = consumption - offset;
-            this.adapter.log.debug(`Applied offset for ${type}: -${offset}, new value: ${consumption}`);
-        }
-
-        // For gas, convert m³ to kWh
-        if (type === 'gas') {
-            const brennwert = this.adapter.config.gasBrennwert || 11.5;
-            const zZahl = this.adapter.config.gasZahl || 0.95;
-            consumptionM3 = consumption;
-            await this.adapter.setStateAsync(`${type}.info.meterReadingVolume`, consumption, true);
-            consumption = calculator.convertGasM3ToKWh(consumption, brennwert, zZahl);
-            consumption = calculator.roundToDecimals(consumption, 2);
-        }
-
-        // Update meter reading
-        await this.adapter.setStateAsync(`${type}.info.meterReading`, consumption, true);
-
-        // Calculate deltas
-        const lastValue = this.lastSensorValues[sensorDP];
-        this.lastSensorValues[sensorDP] = consumption;
-
-        if (lastValue === undefined || consumption < lastValue) {
-            if (lastValue !== undefined && consumption < lastValue) {
-                this.adapter.log.warn(
-                    `${type}: Sensor value decreased (${lastValue} -> ${consumption}). Assuming meter reset or replacement.`,
-                );
-            }
-            if (typeof this.adapter.updateCosts === 'function') {
-                await this.adapter.updateCosts(type);
-            }
-            return;
-        }
-
-        const delta = consumption - lastValue;
-        this.adapter.log.debug(`${type} delta: ${delta}`);
-
-        // Track volume for gas
-        if (type === 'gas') {
-            const brennwert = this.adapter.config.gasBrennwert || 11.5;
-            const zZahl = this.adapter.config.gasZahl || 0.95;
-            const deltaVolume = delta / (brennwert * zZahl);
-
-            const dailyVolume = await this.adapter.getStateAsync(`${type}.consumption.dailyVolume`);
-            const monthlyVolume = await this.adapter.getStateAsync(`${type}.consumption.monthlyVolume`);
-            const yearlyVolume = await this.adapter.getStateAsync(`${type}.consumption.yearlyVolume`);
-
-            await this.adapter.setStateAsync(
-                `${type}.consumption.dailyVolume`,
-                calculator.roundToDecimals((dailyVolume?.val || 0) + deltaVolume, 2),
-                true,
-            );
-            await this.adapter.setStateAsync(
-                `${type}.consumption.monthlyVolume`,
-                calculator.roundToDecimals((monthlyVolume?.val || 0) + deltaVolume, 2),
-                true,
-            );
-            await this.adapter.setStateAsync(
-                `${type}.consumption.yearlyVolume`,
-                calculator.roundToDecimals((yearlyVolume?.val || 0) + deltaVolume, 3),
-                true,
-            );
-        }
-
-        // Update consumption values
-        const dailyState = await this.adapter.getStateAsync(`${type}.consumption.daily`);
-        await this.adapter.setStateAsync(
-            `${type}.consumption.daily`,
-            calculator.roundToDecimals((dailyState?.val || 0) + delta, 2),
-            true,
-        );
-
-        const monthlyState = await this.adapter.getStateAsync(`${type}.consumption.monthly`);
-        await this.adapter.setStateAsync(
-            `${type}.consumption.monthly`,
-            calculator.roundToDecimals((monthlyState?.val || 0) + delta, 2),
-            true,
-        );
-
-        // HT/NT tracking
-        const htNtEnabledKey = `${configType}HtNtEnabled`;
-        if (this.adapter.config[htNtEnabledKey]) {
-            const isHT = calculator.isHTTime(this.adapter.config, configType);
-            const suffix = isHT ? 'HT' : 'NT';
-
-            const dHTNT = await this.adapter.getStateAsync(`${type}.consumption.daily${suffix}`);
-            await this.adapter.setStateAsync(
-                `${type}.consumption.daily${suffix}`,
-                calculator.roundToDecimals((dHTNT?.val || 0) + delta, 2),
-                true,
-            );
-
-            const mHTNT = await this.adapter.getStateAsync(`${type}.consumption.monthly${suffix}`);
-            await this.adapter.setStateAsync(
-                `${type}.consumption.monthly${suffix}`,
-                calculator.roundToDecimals((mHTNT?.val || 0) + delta, 2),
-                true,
-            );
-
-            const yHTNT = await this.adapter.getStateAsync(`${type}.consumption.yearly${suffix}`);
-            await this.adapter.setStateAsync(
-                `${type}.consumption.yearly${suffix}`,
-                calculator.roundToDecimals((yHTNT?.val || 0) + delta, 2),
-                true,
-            );
-        }
-
-        // Yearly consumption
-        const initialReadingKey = `${configType}InitialReading`;
-        const initialReading = this.adapter.config[initialReadingKey] || 0;
-
-        if (initialReading > 0) {
-            let yearlyAmount;
-            if (type === 'gas') {
-                const yearlyM3 = Math.max(0, (consumptionM3 || 0) - initialReading);
-                await this.adapter.setStateAsync(
-                    `${type}.consumption.yearlyVolume`,
-                    calculator.roundToDecimals(yearlyM3, 2),
-                    true,
-                );
-                const brennwert = this.adapter.config.gasBrennwert || 11.5;
-                const zZahl = this.adapter.config.gasZahl || 0.95;
-                yearlyAmount = calculator.convertGasM3ToKWh(yearlyM3, brennwert, zZahl);
-            } else {
-                yearlyAmount = Math.max(0, consumption - initialReading);
-            }
-            await this.adapter.setStateAsync(
-                `${type}.consumption.yearly`,
-                calculator.roundToDecimals(yearlyAmount, 2),
-                true,
-            );
-        } else {
-            const yState = await this.adapter.getStateAsync(`${type}.consumption.yearly`);
-            await this.adapter.setStateAsync(
-                `${type}.consumption.yearly`,
-                calculator.roundToDecimals((yState?.val || 0) + delta, 2),
-                true,
-            );
-        }
-
-        if (typeof this.adapter.updateCosts === 'function') {
-            await this.adapter.updateCosts(type);
-        }
-
-        await this.adapter.setStateAsync(`${type}.consumption.lastUpdate`, now, true);
-        await this.adapter.setStateAsync(`${type}.info.lastSync`, now, true);
+        this.adapter.log.debug(`${type} initialization delegated to MultiMeterManager`);
     }
 
     /**
@@ -327,7 +84,7 @@ class ConsumptionManager {
      * @param {string} type - Utility type
      */
     async updateCurrentPrice(type) {
-        const configType = this.getConfigType(type);
+        const configType = getConfigType(type);
 
         // Get all meters for this type
         const meters = this.adapter.multiMeterManager?.getMetersForType(type) || [];