Complete general functions

helper/measurements/README.md

@@ -0,0 +1,89 @@
+# Measurement System Documentation
+
+This system provides a flexible way to store, retrieve, and analyze measurement data using a chainable API.
+
+## Basic Usage
+
+```javascript
+const { MeasurementContainer } = require('./index');
+const container = new MeasurementContainer({ windowSize: 20 });
+
+// Set values
+container.type('pressure').variant('measured').position('upstream').value(100).unit('psi');
+
+// Get values
+const upstreamPressure = container.type('pressure').variant('measured').position('upstream').getCurrentValue();
+console.log(`Upstream pressure: ${upstreamPressure}`);
+```
+
+## Chainable API Methods
+
+### Setting Context
+- `type(typeName)` - Set the measurement type (pressure, flow, etc.)
+- `variant(variantName)` - Set the variant (measured, predicted, etc.)
+- `position(positionName)` - Set the position (upstream, downstream, etc.)
+
+### Setting Data
+- `value(val, [timestamp])` - Add a value with optional timestamp
+- `unit(unitName)` - Set the measurement unit
+
+### Getting Data
+- `get()` - Get the measurement object
+- `getCurrentValue()` - Get the most recent value
+- `getAverage()` - Calculate average of all values
+- `getMin()` - Get minimum value
+- `getMax()` - Get maximum value
+
+### Calculations
+- `difference()` - Calculate difference between upstream and downstream positions
+
+### Listing Available Data
+- `getTypes()` - Get all measurement types 
+- `listVariants()` - List variants for current type
+- `listPositions()` - List positions for current type and variant
+
+## Example Workflows
+
+### Setting and retrieving values
+```javascript
+// Set a measurement
+container.type('flow')
+         .variant('measured')
+         .position('upstream')
+         .value(120)
+         .unit('gpm');
+
+// Retrieve the same measurement
+const flow = container.type('flow')
+                     .variant('measured')
+                     .position('upstream')
+                     .getCurrentValue();
+```
+
+### Calculating differences
+```javascript
+// Set upstream and downstream measurements
+container.type('pressure').variant('measured').position('upstream').value(100).unit('psi');
+container.type('pressure').variant('measured').position('downstream').value(95).unit('psi');
+
+// Calculate the difference
+const diff = container.type('pressure').variant('measured').difference();
+console.log(`Pressure drop: ${diff.currentDiff} ${diff.unit}`);
+```
+
+### Working with historical data
+```javascript
+// Add multiple values
+container.type('temperature')
+         .variant('measured')
+         .position('outlet')
+         .value(72)
+         .value(74)
+         .value(73)
+         .unit('F');
+
+// Get statistics
+const avg = container.type('temperature').variant('measured').position('outlet').getAverage();
+const min = container.type('temperature').variant('measured').position('outlet').getMin();
+const max = container.type('temperature').variant('measured').position('outlet').getMax();
+```