node-red-contrib-event-calc 0.1.1

package/README.md

@@ -0,0 +1,247 @@
+# node-red-contrib-event-calc
+
+Node-RED nodes for event caching and calculations with topic wildcard patterns.
+
+## Overview
+
+This package provides a central cache for event/streaming data values with reactive updates. It enables subscription to topic patterns and calculations when values change, making it easy to build event-driven data processing flows.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  event-cache (config node)                                   │
+│  • Stores: Map<topic, {value, ts, metadata}>                │
+│  • Event emitter for topic updates                           │
+│  • Wildcard pattern matching                                 │
+└──────────────────────────────────────────────────────────────┘
+         │                    │                    │
+    ┌────▼────┐         ┌────▼────┐         ┌────▼────┐
+    │event-in │         │event-   │         │event-   │
+    │         │         │topic    │         │calc     │
+    │ pushes  │         │subscribes│        │multi-sub│
+    │to cache │         │to pattern│        │+ expr   │
+    └─────────┘         └─────────┘         └─────────┘
+```
+
+## Installation
+
+```bash
+npm install node-red-contrib-event-calc
+```
+
+Or install directly from the Node-RED palette manager.
+
+## Nodes
+
+### event-cache (Config Node)
+
+Central cache that stores topic values and manages subscriptions. Configure:
+
+- **Max Entries**: Maximum topics to cache (default: 10000). Oldest entries removed when exceeded.
+- **TTL**: Time-to-live in milliseconds. Set to 0 for no expiry.
+
+### event-in
+
+Receives messages from any upstream node and pushes values to the cache.
+
+**Properties:**
+- **Topic Field**: Where to get the topic (default: `msg.topic`)
+- **Value Field**: Where to get the value (default: `msg.payload`)
+
+The original message passes through, allowing insertion into existing flows.
+
+### event-topic
+
+Subscribes to a topic pattern and outputs when matching topics update.
+
+**Properties:**
+- **Topic Pattern**: Pattern with wildcards (`?` for single level, `*` for any levels)
+- **Output Format**:
+  - *Value only*: `msg.payload` = value
+  - *Full entry*: `msg.payload` = `{value, ts, metadata}`
+  - *All matching*: `msg.payload` = `{topic1: value1, topic2: value2, ...}`
+- **Output on deploy**: Emit cached values when flow starts
+
+**Dynamic control via input:**
+- `msg.pattern`: Change subscription pattern
+- `msg.payload = 'refresh'`: Output all currently cached values
+
+### event-calc
+
+Subscribes to multiple topics and evaluates an expression when values update.
+
+**Properties:**
+- **Input Variables**: Map variable names to topic patterns
+- **Expression**: JavaScript expression using the variables
+- **Trigger**: When to calculate
+  - *Any input updates*: Calculate on every update
+  - *Only when all inputs have values*: Wait for all values
+
+**Output:**
+```json
+{
+  "topic": "calc/result",
+  "payload": 21.5,
+  "inputs": {
+    "a": { "topic": "sensors/room1/temp", "value": 22, "ts": 1704000000000 },
+    "b": { "topic": "sensors/room2/temp", "value": 21, "ts": 1704000001000 }
+  },
+  "expression": "(a + b) / 2",
+  "trigger": "sensors/room1/temp"
+}
+```
+
+## Wildcard Patterns
+
+Two wildcards are supported:
+
+| Pattern | Matches | Doesn't Match |
+|---------|---------|---------------|
+| `sensor?` | `sensor1`, `sensorA` | `sensor`, `sensor12` |
+| `sensors/*` | `sensors/temp`, `sensors/room1/temp` | `sensors` (nothing after /) |
+| `*/temp` | `room/temp`, `sensors/temp` | `temp` (nothing before /) |
+| `*` | Any topic with 1+ chars | Empty string |
+
+- `?` matches exactly one character
+- `*` matches one or more characters
+
+## Examples
+
+### Average Temperature
+
+```
+[inject: room1/temp] → [event-in] → [cache]
+[inject: room2/temp] → [event-in] → [cache]
+
+[event-calc] → [debug]
+  inputs: a = sensors/room1/temp
+          b = sensors/room2/temp
+  expression: (a + b) / 2
+  trigger: all
+```
+
+### Monitor All Sensors
+
+```
+[any-input: sensors/*] → [event-in] → [cache]
+
+[event-topic: sensors/*] → [debug]
+  outputFormat: all
+```
+
+### Calculate Power (Voltage × Current)
+
+```
+[event-calc]
+  inputs: v = power/voltage
+          i = power/current
+  expression: v * i
+  topic: power/watts
+```
+
+## Built-in Functions
+
+### Math
+| Function | Description |
+|----------|-------------|
+| `min(a, b, ...)` | Minimum value |
+| `max(a, b, ...)` | Maximum value |
+| `abs(x)` | Absolute value |
+| `sqrt(x)` | Square root |
+| `pow(base, exp)` | Power |
+| `log(x)`, `log10(x)` | Logarithms |
+| `floor(x)`, `ceil(x)` | Rounding |
+| `sin(x)`, `cos(x)`, `tan(x)` | Trigonometry |
+| `PI`, `E` | Constants |
+
+### Aggregation
+| Function | Description |
+|----------|-------------|
+| `sum(a, b, ...)` | Sum of values |
+| `avg(a, b, ...)` | Average of values |
+| `count(a, b, ...)` | Count of values |
+
+### Utility
+| Function | Description |
+|----------|-------------|
+| `round(value, decimals)` | Round to N decimals |
+| `clamp(value, min, max)` | Constrain to range |
+| `map(value, inMin, inMax, outMin, outMax)` | Scale between ranges |
+| `lerp(a, b, t)` | Linear interpolation |
+| `ifelse(cond, trueVal, falseVal)` | Conditional |
+| `between(value, min, max)` | Range check (returns boolean) |
+| `delta(current, previous)` | Difference |
+| `pctChange(current, previous)` | Percentage change |
+
+## Expression Examples
+
+| Expression | Description |
+|------------|-------------|
+| `a + b` | Sum |
+| `avg(a, b)` | Average |
+| `max(a, b, c)` | Maximum |
+| `sqrt(a*a + b*b)` | Pythagorean |
+| `round(a, 2)` | Round to 2 decimals |
+| `clamp(a, 0, 100)` | Constrain 0-100 |
+| `map(a, 0, 1023, 0, 100)` | Scale ADC to % |
+| `ifelse(a > b, 'high', 'low')` | Conditional |
+| `pctChange(a, b)` | % change from b to a |
+
+## Scalability
+
+The event-cache is optimized for high subscriber counts:
+
+| Subscription Type | Lookup Complexity | Best For |
+|-------------------|-------------------|----------|
+| Exact topic (e.g., `sensors/room1/temp`) | O(1) | High-frequency updates, many subscribers |
+| Wildcard pattern (e.g., `sensors/*`) | O(w) | Flexible matching, fewer patterns |
+
+Where `w` = number of wildcard subscriptions (typically much smaller than total subscribers).
+
+**Example performance:**
+- 1000 exact subscriptions to different topics: O(1) per update
+- 10 wildcard patterns + 1000 exact subscriptions: O(10) per update
+- Pure wildcard subscriptions: O(n) per update
+
+**Recommendations for high scale:**
+- Prefer exact topic matches when possible
+- Use wildcards sparingly for monitoring/logging
+- Check stats endpoint: `GET /event-cache/:id/stats`
+
+## API (for custom nodes)
+
+The event-cache node exposes methods for programmatic access:
+
+```javascript
+const cache = RED.nodes.getNode(configId);
+
+// Set a value
+cache.setValue('topic/path', 42, { source: 'sensor' });
+
+// Get a value
+const entry = cache.getValue('topic/path');
+// { value: 42, ts: 1704000000000, metadata: { source: 'sensor' } }
+
+// Get matching values
+const temps = cache.getMatching('sensors/*');
+// Map { 'sensors/room1/temp' => {...}, 'sensors/room2/temp' => {...} }
+
+// Subscribe to updates
+const subId = cache.subscribe('sensors/*', (topic, entry) => {
+    console.log(`${topic} = ${entry.value}`);
+});
+
+// Unsubscribe
+cache.unsubscribe(subId);
+
+// Get all topics
+const topics = cache.getTopics();
+
+// Clear cache
+cache.clear();
+```
+
+## License
+
+MIT

package/examples/event-calc-example.json

@@ -0,0 +1,184 @@
+[
+    {
+        "id": "event-calc-example-flow",
+        "type": "tab",
+        "label": "Event Calc Example",
+        "disabled": false,
+        "info": "This flow demonstrates the event-calc nodes:\n- event-in: feeds data into the cache\n- event-topic: subscribes to topic patterns\n- event-calc: performs calculations on cached values"
+    },
+    {
+        "id": "cache1",
+        "type": "event-cache",
+        "name": "Main Cache",
+        "maxEntries": "10000",
+        "ttl": "0"
+    },
+    {
+        "id": "inject-temp1",
+        "type": "inject",
+        "z": "event-calc-example-flow",
+        "name": "Room 1 Temp",
+        "props": [
+            { "p": "topic", "vt": "str" },
+            { "p": "payload" }
+        ],
+        "topic": "sensors/room1/temp",
+        "payload": "",
+        "payloadType": "date",
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "x": 130,
+        "y": 100,
+        "wires": [["random-temp1"]]
+    },
+    {
+        "id": "random-temp1",
+        "type": "function",
+        "z": "event-calc-example-flow",
+        "name": "Random 20-25",
+        "func": "msg.payload = 20 + Math.random() * 5;\nreturn msg;",
+        "outputs": 1,
+        "x": 300,
+        "y": 100,
+        "wires": [["event-in1"]]
+    },
+    {
+        "id": "inject-temp2",
+        "type": "inject",
+        "z": "event-calc-example-flow",
+        "name": "Room 2 Temp",
+        "props": [
+            { "p": "topic", "vt": "str" },
+            { "p": "payload" }
+        ],
+        "topic": "sensors/room2/temp",
+        "payload": "",
+        "payloadType": "date",
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "x": 130,
+        "y": 160,
+        "wires": [["random-temp2"]]
+    },
+    {
+        "id": "random-temp2",
+        "type": "function",
+        "z": "event-calc-example-flow",
+        "name": "Random 18-23",
+        "func": "msg.payload = 18 + Math.random() * 5;\nreturn msg;",
+        "outputs": 1,
+        "x": 300,
+        "y": 160,
+        "wires": [["event-in1"]]
+    },
+    {
+        "id": "event-in1",
+        "type": "event-in",
+        "z": "event-calc-example-flow",
+        "name": "",
+        "cache": "cache1",
+        "topicField": "topic",
+        "valueField": "payload",
+        "x": 490,
+        "y": 130,
+        "wires": [[]]
+    },
+    {
+        "id": "event-topic1",
+        "type": "event-topic",
+        "z": "event-calc-example-flow",
+        "name": "All Temps",
+        "cache": "cache1",
+        "pattern": "sensors/*/temp",
+        "outputFormat": "value",
+        "outputOnStart": false,
+        "x": 490,
+        "y": 240,
+        "wires": [["debug-topic"]]
+    },
+    {
+        "id": "debug-topic",
+        "type": "debug",
+        "z": "event-calc-example-flow",
+        "name": "Topic Updates",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "payload",
+        "statusType": "auto",
+        "x": 690,
+        "y": 240,
+        "wires": []
+    },
+    {
+        "id": "event-calc1",
+        "type": "event-calc",
+        "z": "event-calc-example-flow",
+        "name": "Avg Temp",
+        "cache": "cache1",
+        "inputMappings": [
+            { "name": "a", "pattern": "sensors/room1/temp" },
+            { "name": "b", "pattern": "sensors/room2/temp" }
+        ],
+        "expression": "(a + b) / 2",
+        "triggerOn": "all",
+        "outputTopic": "calc/avg_temp",
+        "x": 490,
+        "y": 320,
+        "wires": [["debug-calc"]]
+    },
+    {
+        "id": "debug-calc",
+        "type": "debug",
+        "z": "event-calc-example-flow",
+        "name": "Calculation",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "payload",
+        "statusType": "auto",
+        "x": 690,
+        "y": 320,
+        "wires": []
+    },
+    {
+        "id": "comment1",
+        "type": "comment",
+        "z": "event-calc-example-flow",
+        "name": "1. Click inject buttons to simulate sensor readings",
+        "info": "",
+        "x": 220,
+        "y": 40,
+        "wires": []
+    },
+    {
+        "id": "comment2",
+        "type": "comment",
+        "z": "event-calc-example-flow",
+        "name": "2. event-topic outputs when any temp updates",
+        "info": "",
+        "x": 590,
+        "y": 200,
+        "wires": []
+    },
+    {
+        "id": "comment3",
+        "type": "comment",
+        "z": "event-calc-example-flow",
+        "name": "3. event-calc computes average (waits for both values)",
+        "info": "",
+        "x": 620,
+        "y": 280,
+        "wires": []
+    }
+]

package/nodes/event-cache.html

@@ -0,0 +1,30 @@
+<script type="text/javascript">
+    RED.nodes.registerType('event-cache', {
+        category: 'config',
+        defaults: {
+            name: { value: "" },
+            maxEntries: { value: 10000, validate: RED.validators.number() },
+            ttl: { value: 0, validate: RED.validators.number() }
+        },
+        label: function() {
+            return this.name || "Event Cache";
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="event-cache">
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="Event Cache">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-maxEntries"><i class="fa fa-database"></i> Max Entries</label>
+        <input type="number" id="node-config-input-maxEntries" placeholder="10000">
+        <div class="form-tips">Maximum number of topics to cache. Oldest entries are removed when limit is reached.</div>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-ttl"><i class="fa fa-clock-o"></i> TTL (ms)</label>
+        <input type="number" id="node-config-input-ttl" placeholder="0">
+        <div class="form-tips">Time-to-live in milliseconds. Set to 0 for no expiry.</div>
+    </div>
+</script>