node-red-contrib-event-calc 0.1.2 → 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-cache.js

@@ -3,53 +3,17 @@
  *
  * Features:
  * - Map<topic, {value, ts, metadata}> for caching latest values
+ * - Stored in global context for visibility in sidebar
  * - EventEmitter for notifying subscribers on updates
- * - Wildcard matching (* for one or more chars, ? for exactly one char)
+ * - Exact topic matching for subscriptions
  * - LRU eviction when maxEntries exceeded
  * - Reference counting for cleanup
  */
 module.exports = function(RED) {
     const EventEmitter = require('events');
 
-    // Shared cache instances per config node ID
-    const cacheInstances = new Map();
-
-    /**
-     * Check if a pattern contains wildcards
-     * @param {string} pattern - Topic pattern
-     * @returns {boolean} - True if pattern contains * or ?
-     */
-    function hasWildcard(pattern) {
-        return pattern && (pattern.includes('*') || pattern.includes('?'));
-    }
-
-    /**
-     * Convert topic pattern to RegExp
-     *
-     * Wildcards:
-     * - '*' (asterisk): Matches one or more characters
-     *   Example: 'sensors/*' matches 'sensors/temp', 'sensors/room1/temp'
-     *
-     * - '?' (question mark): Matches exactly one character
-     *   Example: 'sensor?' matches 'sensor1', 'sensorA' but NOT 'sensor' or 'sensor12'
-     *
-     * @param {string} pattern - Topic pattern with wildcards
-     * @returns {RegExp} - Regular expression for matching
-     */
-    function patternToRegex(pattern) {
-        // Handle empty pattern or just *
-        if (!pattern || pattern === '*') {
-            return /^.+$/;
-        }
-
-        // Escape regex special characters except our wildcards (* and ?)
-        let regexStr = pattern
-            .replace(/[.^$|()[\]{}\\+#/]/g, '\\$&')  // Escape regex special chars (including /)
-            .replace(/\?/g, '.')                      // ? matches exactly one character
-            .replace(/\*/g, '.+');                    // * matches one or more characters
-
-        return new RegExp(`^${regexStr}$`);
-    }
+    // Shared instances for event emitters and subscriptions (not stored in context)
+    const sharedInstances = new Map();
 
     function EventCacheNode(config) {
         RED.nodes.createNode(this, config);
@@ -59,36 +23,47 @@ module.exports = function(RED) {
         node.maxEntries = parseInt(config.maxEntries) || 10000;
         node.ttl = parseInt(config.ttl) || 0; // 0 = no expiry
 
-        // Create or get shared cache instance
-        const cacheKey = node.id;
-        if (!cacheInstances.has(cacheKey)) {
-            cacheInstances.set(cacheKey, {
-                cache: new Map(),
+        // Context key for storing cache data (visible in sidebar)
+        const contextKey = `eventCache_${node.name.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+        const globalContext = node.context().global;
+
+        // Create or get shared instance for emitters/subscriptions (not serializable)
+        const instanceKey = node.id;
+        if (!sharedInstances.has(instanceKey)) {
+            sharedInstances.set(instanceKey, {
                 emitter: new EventEmitter(),
-                // Optimized subscription storage:
-                // - exactSubscriptions: Map<topic, Map<subId, callback>> for O(1) exact match
-                // - wildcardSubscriptions: Map<subId, {pattern, regex, callback}> for pattern matching
-                exactSubscriptions: new Map(),
-                wildcardSubscriptions: new Map(),
+                // Subscription storage: Map<topic, Map<subId, callback>> for O(1) exact match
+                subscriptions: new Map(),
                 users: 0,
                 subscriptionCounter: 0
             });
         }
 
-        const instance = cacheInstances.get(cacheKey);
+        const instance = sharedInstances.get(instanceKey);
         instance.users++;
         instance.emitter.setMaxListeners(100); // Allow many subscribers
 
+        // Initialize cache in global context if not exists
+        if (!globalContext.get(contextKey)) {
+            globalContext.set(contextKey, {});
+        }
+
         // TTL cleanup interval
         let ttlInterval = null;
         if (node.ttl > 0) {
             ttlInterval = setInterval(() => {
                 const now = Date.now();
-                for (const [topic, entry] of instance.cache) {
-                    if (now - entry.ts > node.ttl) {
-                        instance.cache.delete(topic);
+                const cache = globalContext.get(contextKey) || {};
+                let changed = false;
+                for (const topic of Object.keys(cache)) {
+                    if (now - cache[topic].ts > node.ttl) {
+                        delete cache[topic];
+                        changed = true;
                     }
                 }
+                if (changed) {
+                    globalContext.set(contextKey, cache);
+                }
             }, Math.min(node.ttl, 60000)); // Check at most every minute
         }
 
@@ -105,14 +80,26 @@ module.exports = function(RED) {
                 metadata: metadata
             };
 
-            instance.cache.set(topic, entry);
+            const cache = globalContext.get(contextKey) || {};
+            cache[topic] = entry;
 
             // Enforce max entries (LRU eviction - remove oldest)
-            if (instance.cache.size > node.maxEntries) {
-                const firstKey = instance.cache.keys().next().value;
-                instance.cache.delete(firstKey);
+            const keys = Object.keys(cache);
+            if (keys.length > node.maxEntries) {
+                // Find oldest entry
+                let oldestKey = keys[0];
+                let oldestTs = cache[oldestKey].ts;
+                for (const key of keys) {
+                    if (cache[key].ts < oldestTs) {
+                        oldestTs = cache[key].ts;
+                        oldestKey = key;
+                    }
+                }
+                delete cache[oldestKey];
             }
 
+            globalContext.set(contextKey, cache);
+
             // Emit topic-specific update event
             instance.emitter.emit('update', topic, entry);
         };
@@ -123,52 +110,23 @@ module.exports = function(RED) {
          * @returns {object|undefined} - The cached entry {value, ts, metadata} or undefined
          */
         node.getValue = function(topic) {
-            return instance.cache.get(topic);
-        };
-
-        /**
-         * Get all values matching a pattern
-         * @param {string} pattern - Pattern with * and ? wildcards
-         * @returns {Map} - Map of matching topic -> entry
-         */
-        node.getMatching = function(pattern) {
-            const regex = patternToRegex(pattern);
-            const results = new Map();
-
-            for (const [topic, entry] of instance.cache) {
-                if (regex.test(topic)) {
-                    results.set(topic, entry);
-                }
-            }
-
-            return results;
+            const cache = globalContext.get(contextKey) || {};
+            return cache[topic];
         };
 
         /**
-         * Subscribe to updates matching a pattern
-         * Optimized: exact matches use O(1) lookup, wildcards use pattern matching
-         * @param {string} pattern - Topic pattern with wildcards
-         * @param {Function} callback - Called with (topic, entry) on match
+         * Subscribe to updates for a specific topic
+         * @param {string} topic - The exact topic to subscribe to
+         * @param {Function} callback - Called with (topic, entry) on update
          * @returns {string} - Subscription ID for unsubscribe
          */
-        node.subscribe = function(pattern, callback) {
+        node.subscribe = function(topic, callback) {
             const subId = `sub_${++instance.subscriptionCounter}`;
 
-            if (hasWildcard(pattern)) {
-                // Wildcard pattern - store with regex for matching
-                const regex = patternToRegex(pattern);
-                instance.wildcardSubscriptions.set(subId, {
-                    pattern: pattern,
-                    regex: regex,
-                    callback: callback
-                });
-            } else {
-                // Exact match - store in topic-indexed map for O(1) lookup
-                if (!instance.exactSubscriptions.has(pattern)) {
-                    instance.exactSubscriptions.set(pattern, new Map());
-                }
-                instance.exactSubscriptions.get(pattern).set(subId, callback);
+            if (!instance.subscriptions.has(topic)) {
+                instance.subscriptions.set(topic, new Map());
             }
+            instance.subscriptions.get(topic).set(subId, callback);
 
             return subId;
         };
@@ -178,17 +136,11 @@ module.exports = function(RED) {
          * @param {string} subscriptionId - The subscription ID to remove
          */
         node.unsubscribe = function(subscriptionId) {
-            // Try wildcard subscriptions first
-            if (instance.wildcardSubscriptions.delete(subscriptionId)) {
-                return;
-            }
-
-            // Search exact subscriptions
-            for (const [topic, subs] of instance.exactSubscriptions) {
+            for (const [topic, subs] of instance.subscriptions) {
                 if (subs.delete(subscriptionId)) {
                     // Clean up empty topic maps
                     if (subs.size === 0) {
-                        instance.exactSubscriptions.delete(topic);
+                        instance.subscriptions.delete(topic);
                     }
                     return;
                 }
@@ -200,7 +152,8 @@ module.exports = function(RED) {
          * @returns {string[]} - Array of all topic keys
          */
         node.getTopics = function() {
-            return Array.from(instance.cache.keys());
+            const cache = globalContext.get(contextKey) || {};
+            return Object.keys(cache);
         };
 
         /**
@@ -208,23 +161,22 @@ module.exports = function(RED) {
          * @returns {number} - Cache size
          */
         node.size = function() {
-            return instance.cache.size;
+            const cache = globalContext.get(contextKey) || {};
+            return Object.keys(cache).length;
         };
 
         /**
          * Clear all entries from cache
          */
         node.clear = function() {
-            instance.cache.clear();
+            globalContext.set(contextKey, {});
         };
 
-        // Internal: dispatch updates to matching subscriptions
-        // Optimized: O(1) for exact matches, O(w) for wildcard patterns
+        // Internal: dispatch updates to matching subscriptions (O(1) lookup)
         const updateHandler = (topic, entry) => {
-            // First: O(1) lookup for exact subscriptions
-            const exactSubs = instance.exactSubscriptions.get(topic);
-            if (exactSubs) {
-                for (const [subId, callback] of exactSubs) {
+            const subs = instance.subscriptions.get(topic);
+            if (subs) {
+                for (const [subId, callback] of subs) {
                     try {
                         callback(topic, entry);
                     } catch (err) {
@@ -232,17 +184,6 @@ module.exports = function(RED) {
                     }
                 }
             }
-
-            // Second: iterate only wildcard subscriptions (typically fewer)
-            for (const [subId, sub] of instance.wildcardSubscriptions) {
-                if (sub.regex.test(topic)) {
-                    try {
-                        sub.callback(topic, entry);
-                    } catch (err) {
-                        RED.log.error(`[event-cache] Subscription callback error: ${err.message}`);
-                    }
-                }
-            }
         };
         instance.emitter.on('update', updateHandler);
 
@@ -254,11 +195,10 @@ module.exports = function(RED) {
 
             instance.users--;
             if (instance.users <= 0) {
-                instance.cache.clear();
-                instance.exactSubscriptions.clear();
-                instance.wildcardSubscriptions.clear();
+                // Don't clear the context cache - let it persist
+                instance.subscriptions.clear();
                 instance.emitter.removeAllListeners();
-                cacheInstances.delete(cacheKey);
+                sharedInstances.delete(instanceKey);
             }
             done();
         });
@@ -281,11 +221,11 @@ module.exports = function(RED) {
     RED.httpAdmin.get("/event-cache/:id/stats", function(req, res) {
         const node = RED.nodes.getNode(req.params.id);
         if (node) {
-            const instance = cacheInstances.get(node.id);
-            let exactSubCount = 0;
+            const instance = sharedInstances.get(node.id);
+            let subCount = 0;
             if (instance) {
-                for (const subs of instance.exactSubscriptions.values()) {
-                    exactSubCount += subs.size;
+                for (const subs of instance.subscriptions.values()) {
+                    subCount += subs.size;
                 }
             }
             res.json({
@@ -294,9 +234,8 @@ module.exports = function(RED) {
                 maxEntries: node.maxEntries,
                 ttl: node.ttl,
                 subscriptions: {
-                    exact: exactSubCount,
-                    wildcard: instance ? instance.wildcardSubscriptions.size : 0,
-                    exactTopics: instance ? instance.exactSubscriptions.size : 0
+                    count: subCount,
+                    topics: instance ? instance.subscriptions.size : 0
                 }
             });
         } else {
@@ -317,11 +256,17 @@ module.exports = function(RED) {
     // HTTP Admin endpoint to get topics from all caches
     RED.httpAdmin.get("/event-cache/topics/all", function(req, res) {
         const allTopics = new Set();
-        for (const [cacheKey, instance] of cacheInstances) {
-            for (const topic of instance.cache.keys()) {
-                allTopics.add(topic);
+        // Get all event-cache nodes and collect their topics
+        RED.nodes.eachNode(function(n) {
+            if (n.type === 'event-cache') {
+                const cacheNode = RED.nodes.getNode(n.id);
+                if (cacheNode && cacheNode.getTopics) {
+                    for (const topic of cacheNode.getTopics()) {
+                        allTopics.add(topic);
+                    }
+                }
             }
-        }
+        });
         res.json(Array.from(allTopics).sort());
     });
 };