heatingpro-efficiency/README.md

Utility functions for MonitoringPro efficiency calculations with flexible unit support (GJ, kWh, MWh)

# MonitoringPro Utils

Utility functions for MonitoringPro efficiency calculations with flexible unit support.

## Installation

```bash
npm install heatingpro-efficiency
```

## Usage

```javascript
const { computeEfficiency, areMetersBeingWrittenOff } = require('heatingpro-efficiency');

// Compute efficiency for data in GJ (default)
const result1 = computeEfficiency(row, prevRow, monthlyEffectivityConstant);

// Compute efficiency with field units mapping
const result2 = computeEfficiency(row, prevRow, monthlyEffectivityConstant, fieldUnits);

// Check if meters are being written off
const metersActive = areMetersBeingWrittenOff(valuesData, fieldUnits);
```

## Functions

### `computeEfficiency(row, prevRow, monthlyEffectivityConstant, fieldUnits)`

Computes efficiency based on heat meter readings and gas consumption.

**Parameters:**
- `row` - Current row data object
- `prevRow` - Previous row data object  
- `monthlyEffectivityConstant` - Monthly effectivity constant value
- `fieldUnits` (optional) - Object mapping field names to their units (e.g., `{ "VO1": "mwh" }`)

**Returns:** Object with `ucinnost` (efficiency) and `heatUnits` values

### `areMetersBeingWrittenOff(valuesData, fieldUnits)`

Checks if heat meters (VO1-VO8, MT TUV) exist and are being written off.

**Parameters:**
- `valuesData` - Array of row data objects
- `fieldUnits` (optional) - Object mapping field names to their units

**Returns:** `true` if meters exist and are being written off, `false` otherwise

## Supported Heat Units

- **GJ** (Gigajoules) - Default unit, converts using 1 GJ = 277.778 kWh
- **kWh** (Kilowatt-hours) - No conversion needed
- **MWh** (Megawatt-hours) - Converts using 1 MWh = 1000 kWh

## Version History

- **1.0.8** - Fixed efficiency calculation bug:
  - Removed incorrect `* 10` multiplier that caused efficiency values to be 10x too high
  - Added meter reset detection for gas and heat meters
  - Improved validation for negative differences and edge cases
  - Added comprehensive test suite
- **1.0.7** - Added `areMetersBeingWrittenOff` function to check if heat meters exist and are being written off
- **1.0.6** - Previous version
- **1.0.5** - Added flexible unit support for heat calculations

## Testing

Run tests with:
```bash
npm test
```

Run tests in watch mode:
```bash
npm run test:watch
```

Generate coverage report:
```bash
npm run test:coverage
```

## License

ISC