@rosepetal/node-red-contrib-utils 1.1.1

package/nodes/promise-reader/promise-reader.html

@@ -0,0 +1,100 @@
+<script type="text/javascript">
+    RED.nodes.registerType('rp-promise-reader', {
+        category: 'RP Utils',
+        color: '#a6bbcf',
+        defaults: {
+            name: { value: "rp-promise-reader", validate: function(v) { return v.length > 0; }, required: false },
+            fieldToRead: { value: "promises", validate: function(v) { return v !== ""; }, required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-clock-o',
+        label: function() {
+            return this.name || "promise reader";
+        },
+
+        oneditprepare: function() {
+            $('#node-input-fieldToRead').typedInput({
+                type: 'msg',
+                types: ['msg']
+            });
+        }
+        
+    });
+</script>
+
+<script type="text/html" data-template-name="rp-promise-reader">
+    <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>
+
+    <div class="form-row">
+        <label for="node-input-fieldToRead"><i class="fa fa-folder"></i> Field to read</label>
+        <input type="text" id="node-input-fieldToRead" placeholder="e.g., post.async">
+    </div>
+</script>
+
+
+
+<script type="text/html" data-help-name="rp-promise-reader">
+    <p><strong>The Promise Reader node</strong> resolves arrays of promises and aggregates their results into the message object. This node is essential for handling asynchronous operations from nodes like the inferencer, which use promise-based processing for concurrent inference requests.</p>
+
+    <h3>Purpose</h3>
+    <p>When nodes perform asynchronous operations (like sending inference requests to multiple servers), they return promises instead of immediate results. The Promise Reader collects these promises, waits for all to complete using <code>Promise.all()</code>, then merges the resolved data back into the message flow.</p>
+
+    <h3>Parameters</h3>
+    <ul>
+        <li><strong>Name:</strong> Display name for the node instance.</li>
+        <li><strong><a id="promise-field-param">Field to read</a>:</strong> Message field path containing the promise array. Defaults to <code>promises</code> (reads from <code>msg.promises</code>). Can use dot notation for nested fields like <code>inference.promises</code>.</li>
+    </ul>
+
+    <h3>Input Requirements</h3>
+    <p>The specified message field must contain an <strong>array</strong> of valid JavaScript promises</li>
+
+    <h3>Processing Behavior</h3>
+    <ol>
+        <li><strong>Promise Collection:</strong> Extracts promise array from specified message field</li>
+        <li><strong>Parallel Resolution:</strong> Uses <code>Promise.all()</code> to wait for all promises simultaneously</li>
+        <li><strong>Result Aggregation:</strong> Merges resolved data into the message object using <code>Object.assign()</code></li>
+        <li><strong>Performance Tracking:</strong> Aggregates timing information from all resolved promises</li>
+        <li><strong>Cleanup:</strong> Removes the original promise array from the message</li>
+    </ol>
+
+    <h3>Output Format</h3>
+    <p>Resolved promise data is merged directly into the message object:</p>
+    <pre>{
+  // Original message fields preserved
+  payload: {...},
+  
+  // Merged results from resolved promises
+  detections: [...],    // Inference results
+  confidence: 0.95,     // Aggregated confidence
+  
+  // Performance metrics
+  performance: {
+    "rp-promise-reader": {
+      startTime: 1640995200000,
+      endTime: 1640995201500,
+      milliseconds: 1500
+    }
+  }
+  // Original promises array removed
+}</pre>
+
+    <h3>Integration Examples</h3>
+    <ul>
+        <li><strong>After Inferencer:</strong> Use default field <code>promises</code> to resolve inference results from multiple concurrent servers</li>
+        <li><strong>Custom Async Nodes:</strong> Specify custom field paths like <code>custom.asyncResults</code> for specialized use cases</li>
+    </ul>
+
+    <h3>Error Handling</h3>
+    <ul>
+        <li><strong>Invalid Input:</strong> Warns if field doesn't contain an array and passes message unchanged</li>
+        <li><strong>Non-Promise Elements:</strong> Errors if array contains non-promise objects</li>
+        <li><strong>Promise Rejection:</strong> Logs warnings for rejected promises but continues processing others</li>
+        <li><strong>Missing Field:</strong> Warns and passes message unchanged if specified field doesn't exist</li>
+    </ul>
+
+    <p><strong>Performance Tip:</strong> This node waits for the slowest promise to complete. For optimal performance, ensure all upstream async operations have appropriate timeouts.</p>
+</script>

package/nodes/promise-reader/promise-reader.js

@@ -0,0 +1,118 @@
+module.exports = function(RED) {
+    function PromiseReaderNode(config) {
+        RED.nodes.createNode(this, config);
+        var node = this;
+
+        function deleteNestedProperty(obj, path) {
+            const parts = path.split('.');
+            const last = parts.pop();
+            const ref = parts.reduce((acc, part) => acc && acc[part], obj);
+
+            if (ref && last in ref) {
+                delete ref[last];
+            }
+        }
+
+        function deepMerge(target, source) {
+            const result = { ...target };
+            for (const key in source) {
+                if (source.hasOwnProperty(key)) {
+                    if (typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key]) &&
+                        typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])) {
+                        result[key] = deepMerge(result[key], source[key]);
+                    } else {
+                        result[key] = source[key];
+                    }
+                }
+            }
+            return result;
+        }
+
+        function extractPerformanceEntries(obj, entries = []) {
+            if (!obj || typeof obj !== 'object') return entries;
+
+            if (obj.startTime && obj.endTime) {
+                entries.push(obj);
+            } else {
+                for (const key in obj) {
+                    if (obj.hasOwnProperty(key)) {
+                        extractPerformanceEntries(obj[key], entries);
+                    }
+                }
+            }
+            return entries;
+        }
+
+        node.on('input', function(msg) {
+            const promisesPath = config.fieldToRead || 'promises';
+            const fieldPath = promisesPath.split('.');
+            const promises = fieldPath.reduce((obj, key) => obj && obj[key], msg);
+
+            if (!promises || !Array.isArray(promises)) {
+                node.warn(`msg.${promisesPath} must be an array of promises`);
+                node.send(msg)
+                return;
+            }
+            const allArePromises = promises.every(promise => 
+                promise instanceof Promise || 
+                (promise && typeof promise.then === 'function' && typeof promise.catch === 'function')
+            );
+            if (!allArePromises) {
+                node.error(`All elements in msg.${promisesPath} must be promises`);
+                return;
+            }
+
+            let aggregatedPerformance = {
+                startTime: null,
+                endTime: null
+            };
+
+            Promise.all(promises)
+                .then(resolvedValues => {
+                    resolvedValues.forEach(value => {
+                        if (value && value.performance) {
+                            const performanceEntries = extractPerformanceEntries(value.performance);
+                            performanceEntries.forEach(entry => {
+                                if (aggregatedPerformance.startTime === null || entry.startTime < aggregatedPerformance.startTime) {
+                                    aggregatedPerformance.startTime = entry.startTime;
+                                }
+                                if (aggregatedPerformance.endTime === null || entry.endTime > aggregatedPerformance.endTime) {
+                                    aggregatedPerformance.endTime = entry.endTime;
+                                }
+                            });
+                        }
+
+                        if (value && typeof value === 'object') {
+                            Object.keys(value).forEach(key => {
+                                if (msg[key] === undefined) {
+                                    msg[key] = value[key];
+                                } else if (typeof msg[key] === 'object' && msg[key] !== null && !Array.isArray(msg[key]) &&
+                                           typeof value[key] === 'object' && value[key] !== null && !Array.isArray(value[key])) {
+                                    msg[key] = deepMerge(msg[key], value[key]);
+                                } else {
+                                    msg[key] = value[key];
+                                }
+                            });
+                        }
+                    });
+
+                    if (aggregatedPerformance.startTime !== null && aggregatedPerformance.endTime !== null) {
+                        aggregatedPerformance.milliseconds = new Date(aggregatedPerformance.endTime) - new Date(aggregatedPerformance.startTime);
+                    } else {
+                        aggregatedPerformance.milliseconds = null;
+                    }
+
+                    msg.performance = msg.performance || {};
+                    msg.performance[node.name] = aggregatedPerformance;
+
+                    deleteNestedProperty(msg, promisesPath);
+
+                    node.send(msg);
+                })
+                .catch(e => node.warn(e));
+        });
+    }
+
+
+    RED.nodes.registerType("rp-promise-reader", PromiseReaderNode);
+};

package/nodes/util/block-detect.html

@@ -0,0 +1,85 @@
+<script type="text/javascript">
+    (function() {
+        RED.nodes.registerType('rp-block-detect', {
+            category: 'RP Utils',
+            color: '#F4C95D',
+            defaults: {
+                name: { value: "" },
+                intervalMs: { value: 1000, required: true, validate: RED.validators.number() },
+                thresholdMs: { value: 120, required: true, validate: RED.validators.number() },
+                consecutive: { value: 1, required: true, validate: RED.validators.number() },
+                cooldown: { value: 30000, required: true, validate: RED.validators.number() },
+                showStats: { value: true }
+            },
+            inputs: 0,
+            outputs: 0,
+            icon: "font-awesome/fa-shield",
+            label: function() {
+                return this.name || "block detect";
+            },
+            oneditprepare: function() {
+                $("#node-input-showStats").prop("checked", this.showStats !== false);
+            },
+            oneditsave: function() {
+                this.showStats = $("#node-input-showStats").is(":checked");
+            }
+        });
+    })();
+</script>
+
+<script type="text/x-red" data-template-name="rp-block-detect">
+    <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="Event loop watchdog">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-thresholdMs"><i class="fa fa-bolt"></i> Threshold (ms)</label>
+        <input type="number" id="node-input-thresholdMs" min="1" step="10">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-intervalMs"><i class="fa fa-clock-o"></i> Sample interval (ms)</label>
+        <input type="number" id="node-input-intervalMs" min="100" step="100">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-consecutive"><i class="fa fa-repeat"></i> Consecutive hits</label>
+        <input type="number" id="node-input-consecutive" min="1" step="1">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-cooldown"><i class="fa fa-hourglass-half"></i> Cooldown (ms)</label>
+        <input type="number" id="node-input-cooldown" min="1000" step="1000">
+    </div>
+
+    <div class="form-row">
+        <label></label>
+        <input type="checkbox" id="node-input-showStats" checked>
+        <label for="node-input-showStats" style="width: auto;">Show live delay metrics</label>
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="rp-block-detect">
+    <p>Continuously monitors Node-RED's event loop for blocking work that would slow down flows.</p>
+
+    <h3>How it works</h3>
+    <p>The node samples <code>monitorEventLoopDelay</code> (or falls back to timer drift) and raises an alert when the measured delay exceeds the configured threshold for a number of consecutive samples.</p>
+
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Threshold (ms)<span class="property-type">number</span></dt>
+        <dd>Maximum allowed event loop delay before the node treats a sample as blocking.</dd>
+        <dt>Sample interval (ms)<span class="property-type">number</span></dt>
+        <dd>How often to collect a measurement. Lower values catch spikes sooner but cost a little more CPU.</dd>
+        <dt>Consecutive hits<span class="property-type">number</span></dt>
+        <dd>Number of back-to-back samples that must exceed the threshold before an alert is emitted.</dd>
+        <dt>Cooldown (ms)<span class="property-type">number</span></dt>
+        <dd>Minimum time between alerts so your logs do not flood when something stays blocked.</dd>
+        <dt>Show live delay metrics<span class="property-type">boolean</span></dt>
+        <dd>Toggle live status text that displays the current average and max delay.</dd>
+    </dl>
+
+    <h3>Usage</h3>
+    <p>Drop the node anywhere in a flow (it has no wires) to keep a lightweight background watchdog running. Use multiple instances with different thresholds if you want per-flow granularity.</p>
+</script>

package/nodes/util/block-detect.js

@@ -0,0 +1,136 @@
+/**
+ * @file Node-RED logic for the block-detect node.
+ * Monitors the Node.js event loop delay to detect blocking work.
+ */
+const { performance, monitorEventLoopDelay } = require('perf_hooks');
+
+module.exports = function(RED) {
+  function BlockDetectNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const intervalMs = sanitizeNumber(config.intervalMs, 1000, 100);
+    const thresholdMs = sanitizeNumber(config.thresholdMs, 120, 1);
+    const resolutionMs = 20; // Medium resolution for event-loop histogram (ms)
+    const consecutive = Math.max(1, Math.round(sanitizeNumber(config.consecutive, 1, 1)));
+    const cooldownMs = sanitizeNumber(config.cooldown, 30000, 1000);
+    const showStats = config.showStats !== false;
+
+    let overThresholdCount = 0;
+    let lastAlertAt = 0;
+    let timer = null;
+    let histogram = null;
+    let fallbackPrev = performance.now();
+    let monitorAvailable = typeof monitorEventLoopDelay === 'function';
+
+    if (monitorAvailable) {
+      histogram = monitorEventLoopDelay({ resolution: resolutionMs });
+      histogram.enable();
+    } else {
+      node.warn('monitorEventLoopDelay not available; falling back to coarse timer drift detection.');
+    }
+
+    node.status({ fill: 'grey', shape: 'ring', text: 'monitoring…' });
+
+    timer = setInterval(() => {
+      const stats = monitorAvailable
+        ? readHistogramStats(histogram)
+        : readFallbackStats();
+
+      if (showStats) {
+        const color = stats.max >= thresholdMs ? (stats.alert ? 'red' : 'yellow') : 'green';
+        const shape = stats.max >= thresholdMs ? 'ring' : 'dot';
+        node.status({
+          fill: color,
+          shape,
+          text: `avg ${stats.mean.toFixed(1)}ms | max ${stats.max.toFixed(1)}ms`
+        });
+      } else {
+        if (stats.alert) {
+          node.status({ fill: 'red', shape: 'dot', text: 'blocking detected' });
+        } else if (stats.max >= thresholdMs) {
+          node.status({ fill: 'yellow', shape: 'ring', text: 'high loop delay' });
+        } else {
+          node.status({ fill: 'green', shape: 'dot', text: 'ok' });
+        }
+      }
+
+      if (stats.max >= thresholdMs) {
+        overThresholdCount += 1;
+      } else {
+        overThresholdCount = 0;
+      }
+
+      if (overThresholdCount >= consecutive) {
+        const now = Date.now();
+        if (now - lastAlertAt >= cooldownMs) {
+          emitAlert(stats);
+          lastAlertAt = now;
+        }
+        overThresholdCount = 0;
+      }
+    }, intervalMs);
+
+    node.on('close', function() {
+      if (timer) {
+        clearInterval(timer);
+      }
+      if (histogram) {
+        histogram.disable();
+      }
+    });
+
+    function emitAlert(stats) {
+      const message =
+        `Detected potential blocking: max ${stats.max.toFixed(1)} ms ` +
+        `(avg ${stats.mean.toFixed(1)} ms, min ${stats.min.toFixed(1)} ms, threshold ${thresholdMs} ms).`;
+
+      node.warn(message);
+    }
+
+    function readHistogramStats(hist) {
+      const mean = Number.isFinite(hist.mean) ? hist.mean / 1e6 : 0;
+      const max = Number.isFinite(hist.max) ? hist.max / 1e6 : 0;
+      const min = Number.isFinite(hist.min) ? hist.min / 1e6 : 0;
+      hist.reset();
+      return {
+        mean,
+        max,
+        min,
+        alert: max >= thresholdMs
+      };
+    }
+
+    function readFallbackStats() {
+      const now = performance.now();
+      const delta = now - fallbackPrev;
+      fallbackPrev = now;
+      const delay = Math.max(0, delta - intervalMs);
+      return {
+        mean: delay,
+        max: delay,
+        min: delay,
+        alert: delay >= thresholdMs
+      };
+    }
+  }
+
+  RED.nodes.registerType('rp-block-detect', BlockDetectNode, {
+    defaults: {
+      name: { value: '' },
+      intervalMs: { value: 1000 },
+      thresholdMs: { value: 120 },
+      consecutive: { value: 1 },
+      cooldown: { value: 30000 },
+      showStats: { value: true }
+    }
+  });
+};
+
+function sanitizeNumber(value, fallback, min) {
+  const num = Number(value);
+  if (Number.isFinite(num)) {
+    return Math.max(min, num);
+  }
+  return fallback;
+}

package/nodes/util/clean-debug.html

@@ -0,0 +1,201 @@
+<script type="text/javascript">
+    (function() {
+        function toggleCompleteField($complete, type) {
+            const $textInput = $complete.typedInput('input');
+            if (type === "full") {
+                if ($textInput && $textInput.length) {
+                    $textInput.prop("disabled", true).addClass("disabled");
+                }
+                $("#node-input-complete-full-label").show();
+            } else {
+                if ($textInput && $textInput.length) {
+                    $textInput.prop("disabled", false).removeClass("disabled");
+                }
+                $("#node-input-complete-full-label").hide();
+            }
+        }
+
+        RED.nodes.registerType('rp-clean-debug', {
+            category: 'RP Utils',
+            paletteLabel: 'clean debug',
+            color: '#E2D96E',
+            inputs: 1,
+            outputs: 0,
+            icon: 'font-awesome/fa-bug',
+            align: 'right',
+            defaults: {
+                name: { value: "" },
+                active: { value: true },
+                tosidebar: { value: true },
+                console: { value: false },
+                complete: { value: "payload" },
+                targetType: { value: "msg" },
+                clean: { value: true }
+            },
+            label: function() {
+                if (this.name) {
+                    return this.name;
+                }
+                return this.clean === false ? "debug" : "clean debug";
+            },
+            labelStyle: function() {
+                return this.name ? "node_label_italic" : "";
+            },
+            button: {
+                toggle: "active",
+                visible: function() {
+                    return true;
+                },
+                onclick: function() {
+                    var node = this;
+                    var desiredState = node.active;
+
+                    sendCleanDebugToggle(node, desiredState, function() {
+                        var historyEvent = {
+                            t: 'edit',
+                            node: node,
+                            changes: {
+                                active: !node.active
+                            },
+                            dirty: node.dirty,
+                            changed: node.changed,
+                            callback: function(ev) {
+                                sendCleanDebugToggle(ev.node, ev.node.active);
+                            }
+                        };
+
+                        node.changed = true;
+                        node.dirty = true;
+                        RED.nodes.dirty(true);
+                        RED.history.push(historyEvent);
+                        RED.view.redraw();
+                    }, function() {
+                        node.active = !node.active;
+                        RED.view.redraw();
+                        RED.notify("Failed to update Clean Debug state", "error");
+                    });
+                }
+            },
+            oneditprepare: function() {
+                const $complete = $("#node-input-complete");
+                $complete.typedInput({
+                    default: 'msg',
+                    types: [
+                        'msg',
+                        'flow',
+                        'global',
+                        'str',
+                        'num',
+                        'bool',
+                        'json',
+                        'bin',
+                        'date',
+                        'jsonata',
+                        'env',
+                        {
+                            value: 'full',
+                            label: 'complete msg object',
+                            hasValue: false
+                        }
+                    ],
+                    typeField: "#node-input-targetType"
+                });
+
+                toggleCompleteField($complete, $complete.typedInput('type'));
+
+                $complete.on("change", function() {
+                    toggleCompleteField($complete, $complete.typedInput('type'));
+                });
+
+                $("#node-input-tosidebar").prop("checked", this.tosidebar !== false);
+                $("#node-input-console").prop("checked", this.console === true);
+                $("#node-input-clean").prop("checked", this.clean !== false);
+            },
+            oneditsave: function() {
+                this.tosidebar = $("#node-input-tosidebar").is(":checked");
+                this.console = $("#node-input-console").is(":checked");
+                this.clean = $("#node-input-clean").is(":checked");
+            }
+        });
+    })();
+</script>
+
+<script type="text/x-red" data-template-name="rp-clean-debug">
+    <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>
+
+    <div class="form-row">
+        <label for="node-input-complete"><i class="fa fa-dot-circle-o"></i> Output</label>
+        <input type="text" id="node-input-complete" style="width: 70%;">
+        <input type="hidden" id="node-input-targetType">
+        <span id="node-input-complete-full-label" style="display: none;">complete msg object</span>
+    </div>
+
+    <div class="form-row">
+        <label></label>
+        <input type="checkbox" id="node-input-tosidebar" checked>
+        <label for="node-input-tosidebar" style="width: auto;">Send to debug sidebar</label>
+    </div>
+
+    <div class="form-row">
+        <label></label>
+        <input type="checkbox" id="node-input-console">
+        <label for="node-input-console" style="width: auto;">Also log to console</label>
+    </div>
+
+    <div class="form-row">
+        <label></label>
+        <input type="checkbox" id="node-input-clean" checked>
+        <label for="node-input-clean" style="width: auto;">Clean heavy payloads (images/buffers)</label>
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="rp-clean-debug">
+    <p>An enhanced drop-in replacement for the core Debug node that filters out heavy binary/image payloads by default to keep the debug sidebar responsive.</p>
+
+    <h3>Details</h3>
+    <p>The Clean Debug node mirrors the behaviour of the standard Debug node while adding an optional cleaning step that replaces Buffers, typed arrays, data URLs and large Base64 strings with short placeholders.</p>
+
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Output<span class="property-type">typed input</span></dt>
+        <dd>Select the message property (or expression) to show in the debug sidebar. Choose <strong>complete msg object</strong> to inspect the whole message.</dd>
+        <dt>Send to debug sidebar<span class="property-type">boolean</span></dt>
+        <dd>Publish the result to the editor sidebar. Disable if you only want console/status output.</dd>
+        <dt>Also log to console<span class="property-type">boolean</span></dt>
+        <dd>Write the formatted output to the Node-RED runtime log.</dd>
+        <dt>Clean heavy payloads<span class="property-type">boolean</span></dt>
+        <dd>When enabled (default), large Buffers, Base64 strings and data URLs are replaced with concise placeholders so they do not flood the UI.</dd>
+        <dt>Enabled<span class="property-type">boolean</span></dt>
+        <dd>Temporarily disable the node without removing it from your flow.</dd>
+    </dl>
+
+    <h3>Notes</h3>
+    <ul>
+        <li>Disabling the clean option restores the exact behaviour of the built-in Debug node.</li>
+        <li>The cleaning step only affects what is displayed; the original message object is left untouched.</li>
+    </ul>
+</script>
+
+<script type="text/javascript">
+    function sendCleanDebugToggle(node, desiredState, onSuccess, onError) {
+        $.ajax({
+            url: "rp-clean-debug/" + node.id,
+            type: "POST",
+            data: JSON.stringify({ active: desiredState }),
+            contentType: "application/json; charset=utf-8",
+            success: function(resp) {
+                if (typeof onSuccess === "function") {
+                    onSuccess(resp);
+                }
+            },
+            error: function(jqXHR, textStatus, errorThrown) {
+                if (typeof onError === "function") {
+                    onError(jqXHR, textStatus, errorThrown);
+                }
+            }
+        });
+    }
+</script>