node-red-contrib-event-calc 0.1.4 → 2.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+Personal Use License
+
+Copyright (c) 2025 Holger Amort
+
+This software is provided for personal, non-commercial use only.
+
+You may:
+- Use this software for personal projects
+- Modify the software for your own use
+- Share the software with attribution
+
+You may not:
+- Use this software for commercial purposes without permission
+- Sell or sublicense this software
+- Remove this license notice
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For commercial licensing inquiries, contact the author.

package/README.md

@@ -1,10 +1,10 @@
 # node-red-contrib-event-calc
 
-Node-RED nodes for event caching and calculations with topic wildcard patterns.
+Node-RED nodes for event caching and streaming calculations with a local pub/sub event hub.
 
 ## 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.
+This package provides a local in-memory event hub with topic-based publish/subscribe and latest-value caching for reactive data flows within Node-RED. Stream data from MQTT, OPC-UA, or any source, then perform calculations that trigger automatically when values update.
 
 ## Architecture
 
@@ -13,14 +13,14 @@ This package provides a central cache for event/streaming data values with react
 │  event-cache (config node)                                   │
 │  • Stores: Map<topic, {value, ts, metadata}>                │
 │  • Event emitter for topic updates                           │
-│  • Wildcard pattern matching                                 │
+│  • LRU eviction, optional TTL                                │
 └──────────────────────────────────────────────────────────────┘
          │                    │                    │
     ┌────▼────┐         ┌────▼────┐         ┌────▼────┐
     │event-in │         │event-   │         │event-   │
     │         │         │topic    │         │calc     │
     │ pushes  │         │subscribes│        │multi-sub│
-    │to cache │         │to pattern│        │+ expr   │
+    │to cache │         │to topic  │        │+ expr   │
     └─────────┘         └─────────┘         └─────────┘
 ```
 
@@ -53,30 +53,30 @@ The original message passes through, allowing insertion into existing flows.
 
 ### event-topic
 
-Subscribes to a topic pattern and outputs when matching topics update.
+Subscribes to a topic and outputs when that topic updates.
 
 **Properties:**
-- **Topic Pattern**: Pattern with wildcards (`?` for single level, `*` for any levels)
+- **Topic**: Exact topic to subscribe to
 - **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
+- `msg.topic`: Change subscription topic
+- `msg.payload = 'refresh'`: Output current cached value
 
 ### event-calc
 
 Subscribes to multiple topics and evaluates an expression when values update.
 
 **Properties:**
-- **Input Variables**: Map variable names to topic patterns
+- **Input Variables**: Map variable names to topics
 - **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
+- **External Trigger**: When enabled, any incoming message triggers calculation using cached values
 
 **Output:**
 ```json
@@ -92,19 +92,27 @@ Subscribes to multiple topics and evaluates an expression when values update.
 }
 ```
 
-## Wildcard Patterns
+### event-json
 
-Two wildcards are supported:
+Bidirectional JSON envelope converter for MQTT messaging.
 
-| 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 |
+**Behavior:**
+- **Unwrap**: If payload is `{value, topic?, timestamp?}`, extracts to msg properties
+- **Wrap**: If payload is any other value, wraps as `{timestamp, topic, value}`
 
-- `?` matches exactly one character
-- `*` matches one or more characters
+**Usage:**
+```
+[MQTT in] → [event-json] → [event-in]     (unwrap JSON from broker)
+[event-topic] → [event-json] → [MQTT out] (wrap for broker)
+```
+
+### event-simulator
+
+Generates simulated data for testing. Supports sine waves, random values, and ramps.
+
+### event-chart
+
+Real-time charting node for visualizing cached event data.
 
 ## Examples
 
@@ -121,13 +129,21 @@ Two wildcards are supported:
   trigger: all
 ```
 
-### Monitor All Sensors
+### Time-based Calculations (External Trigger)
 
 ```
-[any-input: sensors/*] → [event-in] → [cache]
+[inject: every 1 min] → [event-calc (external trigger)] → [MQTT out]
+  inputs: a = sensors/power
+          b = sensors/voltage
+  expression: a * b
+```
+
+### MQTT Round-trip with JSON Envelope
 
-[event-topic: sensors/*] → [debug]
-  outputFormat: all
+```
+[MQTT in] → [event-json] → [event-in] → [cache]
+
+[event-calc] → [event-json] → [MQTT out]
 ```
 
 ### Calculate Power (Voltage × Current)
@@ -188,27 +204,6 @@ Two wildcards are supported:
 | `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:
@@ -223,12 +218,8 @@ cache.setValue('topic/path', 42, { source: 'sensor' });
 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) => {
+const subId = cache.subscribe('sensors/room1/temp', (topic, entry) => {
     console.log(`${topic} = ${entry.value}`);
 });
 
@@ -242,6 +233,14 @@ const topics = cache.getTopics();
 cache.clear();
 ```
 
+## HTTP Admin Endpoints
+
+```
+GET  /event-cache/:id/stats   - Cache statistics
+GET  /event-cache/:id/topics  - List all topics
+POST /event-cache/:id/clear   - Clear cache
+```
+
 ## License
 
-MIT
+Personal Use License - See [LICENSE](LICENSE) file.

package/nodes/event-calc.html

@@ -13,7 +13,8 @@
             inputMappings: { value: [] },
             expression: { value: "" },
             triggerOn: { value: "any" },
-            outputTopic: { value: "calc/result" }
+            outputTopic: { value: "calc/result" },
+            externalTrigger: { value: false }
         },
         inputs: 1,
         outputs: 2,
@@ -213,6 +214,11 @@
         <label for="node-input-outputTopic"><i class="fa fa-bookmark"></i> Output Topic</label>
         <input type="text" id="node-input-outputTopic" placeholder="calc/result">
     </div>
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-input-externalTrigger" style="width:auto; margin-right:5px;">
+        <label for="node-input-externalTrigger" style="width:auto;"> External Trigger - calculate on any input message</label>
+    </div>
 </script>
 
 <script type="text/html" data-help-name="event-calc">
@@ -233,6 +239,8 @@
         </dd>
         <dt>Output Topic</dt>
         <dd>Topic for output messages.</dd>
+        <dt>External Trigger</dt>
+        <dd>When enabled, any incoming message will trigger a calculation using the current cached values. Useful for time-based or event-driven calculations.</dd>
     </dl>
 
     <h3>Inputs</h3>

package/nodes/event-calc.js

@@ -66,6 +66,7 @@ module.exports = function(RED) {
         node.expression = config.expression || '';
         node.triggerOn = config.triggerOn || 'any';
         node.outputTopic = config.outputTopic || 'calc/result';
+        node.externalTrigger = config.externalTrigger || false;
 
         const subscriptionIds = [];
 
@@ -239,6 +240,14 @@ module.exports = function(RED) {
                 node.status({ fill: "blue", shape: "dot", text: "expr updated" });
             }
 
+            // External trigger: any incoming message triggers calculation
+            if (node.externalTrigger) {
+                const triggerSource = msg.topic || '_external';
+                tryCalculate(triggerSource, latestValues);
+                done();
+                return;
+            }
+
             // Force recalculation (use special topic to bypass self-output check)
             if (msg.payload === 'recalc' || msg.topic === 'recalc') {
                 if (latestValues.size > 0) {

package/nodes/event-json.html

@@ -0,0 +1,58 @@
+<script type="text/javascript">
+    RED.nodes.registerType('event-json', {
+        category: 'event calc',
+        color: '#758467',
+        defaults: {
+            name: { value: "" }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-exchange",
+        label: function() {
+            return this.name || "event json";
+        },
+        paletteLabel: "event json"
+    });
+</script>
+
+<script type="text/html" data-template-name="event-json">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="event-json">
+    <p>Bidirectional JSON envelope converter. Automatically detects direction.</p>
+
+    <h3>Behavior</h3>
+    <dl class="message-properties">
+        <dt>Unwrap (JSON to Message)</dt>
+        <dd>If payload is <code>{value, topic?, timestamp?}</code>, extracts value to <code>msg.payload</code> and copies topic/timestamp to msg.</dd>
+        <dt>Wrap (Message to JSON)</dt>
+        <dd>If payload is any other value, wraps it as <code>{timestamp, topic, value}</code>.</dd>
+    </dl>
+
+    <h3>Examples</h3>
+    <h4>Wrap (before MQTT publish)</h4>
+    <pre>
+Input:  msg.topic = "sensor/temp", msg.payload = 25.5
+Output: msg.payload = {
+    timestamp: 1704900000000,
+    topic: "sensor/temp",
+    value: 25.5
+}</pre>
+
+    <h4>Unwrap (after MQTT subscribe)</h4>
+    <pre>
+Input:  msg.payload = '{"timestamp":1704900000000,"topic":"sensor/temp","value":25.5}'
+Output: msg.topic = "sensor/temp"
+        msg.payload = 25.5
+        msg.timestamp = 1704900000000</pre>
+
+    <h3>Status</h3>
+    <ul>
+        <li><b>Green "wrapped"</b> - Created JSON envelope</li>
+        <li><b>Blue "unwrapped"</b> - Extracted from JSON envelope</li>
+    </ul>
+</script>

package/nodes/event-json.js

@@ -0,0 +1,69 @@
+/**
+ * event-json - Bidirectional JSON envelope converter
+ *
+ * Automatically detects direction:
+ * - Object with {value, topic?, timestamp?} -> extracts to msg
+ * - Any other payload -> wraps in {timestamp, topic, value}
+ */
+module.exports = function(RED) {
+    function EventJsonNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        node.on('input', function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+            done = done || function(err) { if (err) node.error(err, msg); };
+
+            try {
+                let data = msg.payload;
+
+                // If string, try to parse as JSON
+                if (typeof data === 'string') {
+                    try {
+                        data = JSON.parse(data);
+                    } catch (e) {
+                        // Not JSON string - wrap it
+                        msg.payload = {
+                            timestamp: Date.now(),
+                            topic: msg.topic,
+                            value: msg.payload
+                        };
+                        node.status({ fill: "green", shape: "dot", text: "wrapped" });
+                        send(msg);
+                        done();
+                        return;
+                    }
+                }
+
+                // Check if it's an envelope object (has 'value' property)
+                if (typeof data === 'object' && data !== null && 'value' in data) {
+                    // Unwrap: extract from envelope
+                    if (data.topic) {
+                        msg.topic = data.topic;
+                    }
+                    if (data.timestamp) {
+                        msg.timestamp = data.timestamp;
+                    }
+                    msg.payload = data.value;
+                    node.status({ fill: "blue", shape: "dot", text: "unwrapped" });
+                } else {
+                    // Wrap: create envelope
+                    msg.payload = {
+                        timestamp: Date.now(),
+                        topic: msg.topic,
+                        value: data
+                    };
+                    node.status({ fill: "green", shape: "dot", text: "wrapped" });
+                }
+
+                send(msg);
+                done();
+            } catch (err) {
+                node.status({ fill: "red", shape: "ring", text: "error" });
+                done(err);
+            }
+        });
+    }
+
+    RED.nodes.registerType("event-json", EventJsonNode);
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-red-contrib-event-calc",
-  "version": "0.1.4",
-  "description": "Node-RED nodes for event caching and calculations with topic wildcard patterns",
+  "version": "2.0.1",
+  "description": "Node-RED nodes for event caching and calculations",
   "author": {
     "name": "Holger Amort"
   },
@@ -9,19 +9,18 @@
     "node-red",
     "events",
     "cache",
-    "wildcards",
     "reactive",
     "calculation",
     "streaming"
   ],
-  "license": "MIT",
-  "homepage": "https://github.com/ErnstHolger/node-red#readme",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/ErnstHolger/node-red-contrib-event-calc#readme",
   "bugs": {
-    "url": "https://github.com/ErnstHolger/node-red/issues"
+    "url": "https://github.com/ErnstHolger/node-red-contrib-event-calc/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ErnstHolger/node-red.git"
+    "url": "git+https://github.com/ErnstHolger/node-red-contrib-event-calc.git"
   },
   "node-red": {
     "version": ">=2.0.0",
@@ -30,6 +29,7 @@
       "event-in": "nodes/event-in.js",
       "event-topic": "nodes/event-topic.js",
       "event-calc": "nodes/event-calc.js",
+      "event-json": "nodes/event-json.js",
       "event-simulator": "nodes/event-simulator.js",
       "event-chart": "nodes/event-chart.js"
     }
@@ -38,7 +38,19 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "publish:dry": "npm publish --dry-run"
+    "deploy": "npm link",
+    "deploy:patch": "npm version patch --no-git-tag-version && npm link",
+    "deploy:minor": "npm version minor --no-git-tag-version && npm link",
+    "deploy:major": "npm version major --no-git-tag-version && npm link",
+    "publish:dry": "npm publish --dry-run",
+    "publish:patch": "npm version patch && npm publish && start https://flows.nodered.org/add/node",
+    "publish:minor": "npm version minor && npm publish && start https://flows.nodered.org/add/node",
+    "publish:major": "npm version major && npm publish && start https://flows.nodered.org/add/node",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:headed": "playwright test --headed"
   },
-  "dependencies": {}
+  "devDependencies": {
+    "@playwright/test": "^1.57.0"
+  }
 }

package/playwright.config.js

@@ -0,0 +1,22 @@
+// @ts-check
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:1880',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+});

package/tests/external-trigger.spec.js

@@ -0,0 +1,141 @@
+// @ts-check
+const { test, expect } = require('@playwright/test');
+
+test.describe('Event Calc - External Trigger Feature', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate to Node-RED editor
+    await page.goto('/');
+    // Wait for Node-RED to load
+    await page.waitForSelector('#red-ui-palette', { timeout: 30000 });
+  });
+
+  test('should show External Trigger checkbox in event-calc node configuration', async ({ page }) => {
+    // Search for the event-calc node in the palette
+    const paletteSearch = page.locator('#red-ui-palette-search input');
+    await paletteSearch.fill('event calc');
+
+    // Wait for search results
+    await page.waitForTimeout(500);
+
+    // Find the event-calc node in the palette
+    const eventCalcNode = page.locator('.red-ui-palette-node[data-palette-type="event-calc"]');
+    await expect(eventCalcNode).toBeVisible();
+
+    // Drag the node to the workspace
+    const workspace = page.locator('#red-ui-workspace-chart');
+    await eventCalcNode.dragTo(workspace);
+
+    // Double-click on the newly created node to open the editor
+    // First find the node in the workspace
+    const nodeInWorkspace = page.locator('.red-ui-flow-node-group').last();
+    await nodeInWorkspace.dblclick();
+
+    // Wait for the edit dialog to open
+    await page.waitForSelector('.red-ui-editor', { timeout: 5000 });
+
+    // Verify the External Trigger checkbox exists
+    const externalTriggerCheckbox = page.locator('#node-input-externalTrigger');
+    await expect(externalTriggerCheckbox).toBeVisible();
+
+    // Verify it's unchecked by default
+    await expect(externalTriggerCheckbox).not.toBeChecked();
+
+    // Check the checkbox
+    await externalTriggerCheckbox.check();
+    await expect(externalTriggerCheckbox).toBeChecked();
+
+    // Verify the label is correct
+    const label = page.locator('label[for="node-input-externalTrigger"]');
+    await expect(label).toContainText('External Trigger');
+    await expect(label).toContainText('calculate on any input message');
+  });
+
+  test('should toggle External Trigger checkbox', async ({ page }) => {
+    // Search for the event-calc node
+    const paletteSearch = page.locator('#red-ui-palette-search input');
+    await paletteSearch.fill('event calc');
+    await page.waitForTimeout(500);
+
+    // Find and drag the node
+    const eventCalcNode = page.locator('.red-ui-palette-node[data-palette-type="event-calc"]');
+    const workspace = page.locator('#red-ui-workspace-chart');
+    await eventCalcNode.dragTo(workspace);
+
+    // Open the node editor
+    const nodeInWorkspace = page.locator('.red-ui-flow-node-group').last();
+    await nodeInWorkspace.dblclick();
+    await page.waitForSelector('.red-ui-editor', { timeout: 5000 });
+
+    const externalTriggerCheckbox = page.locator('#node-input-externalTrigger');
+
+    // Toggle on
+    await externalTriggerCheckbox.check();
+    await expect(externalTriggerCheckbox).toBeChecked();
+
+    // Toggle off
+    await externalTriggerCheckbox.uncheck();
+    await expect(externalTriggerCheckbox).not.toBeChecked();
+
+    // Toggle on again
+    await externalTriggerCheckbox.check();
+    await expect(externalTriggerCheckbox).toBeChecked();
+  });
+
+  test('should persist External Trigger setting after save', async ({ page }) => {
+    // Search for event-cache node first (required config)
+    const paletteSearch = page.locator('#red-ui-palette-search input');
+    await paletteSearch.fill('event cache');
+    await page.waitForTimeout(500);
+
+    // Add event-cache config node if needed
+    const eventCacheNode = page.locator('.red-ui-palette-node[data-palette-type="event-cache"]');
+    if (await eventCacheNode.isVisible()) {
+      const workspace = page.locator('#red-ui-workspace-chart');
+      await eventCacheNode.dragTo(workspace);
+
+      // Configure the cache node
+      const cacheNodeInWorkspace = page.locator('.red-ui-flow-node-group').last();
+      await cacheNodeInWorkspace.dblclick();
+      await page.waitForSelector('.red-ui-editor', { timeout: 5000 });
+
+      // Set a name for the cache
+      const nameInput = page.locator('#node-input-name');
+      await nameInput.fill('Test Cache');
+
+      // Save the cache node
+      const doneButton = page.locator('.red-ui-tray-footer button').filter({ hasText: 'Done' });
+      await doneButton.click();
+      await page.waitForTimeout(500);
+    }
+
+    // Now add the event-calc node
+    await paletteSearch.clear();
+    await paletteSearch.fill('event calc');
+    await page.waitForTimeout(500);
+
+    const eventCalcNode = page.locator('.red-ui-palette-node[data-palette-type="event-calc"]');
+    const workspace = page.locator('#red-ui-workspace-chart');
+    await eventCalcNode.dragTo(workspace);
+
+    // Open the node editor
+    const calcNodeInWorkspace = page.locator('.red-ui-flow-node-group').last();
+    await calcNodeInWorkspace.dblclick();
+    await page.waitForSelector('.red-ui-editor', { timeout: 5000 });
+
+    // Check the External Trigger checkbox
+    const externalTriggerCheckbox = page.locator('#node-input-externalTrigger');
+    await externalTriggerCheckbox.check();
+
+    // Save the node configuration
+    const doneButton = page.locator('.red-ui-tray-footer button').filter({ hasText: 'Done' });
+    await doneButton.click();
+    await page.waitForTimeout(500);
+
+    // Reopen the node editor
+    await calcNodeInWorkspace.dblclick();
+    await page.waitForSelector('.red-ui-editor', { timeout: 5000 });
+
+    // Verify the checkbox is still checked
+    await expect(externalTriggerCheckbox).toBeChecked();
+  });
+});