@rosepetal/node-red-contrib-utils 1.1.1 → 1.1.3

package/docs/nodes/io/queue.md

@@ -16,9 +16,14 @@ The `queue` node buffers incoming messages, enforces a minimum interval between
 - **Incoming Message**: Any Node-RED message to be enqueued.
 
 ### Outputs
-- **Queued Message**: Messages are forwarded in FIFO order while respecting the configured interval.
-
-When timeout mode is selected, messages that exceed the configured timeout are silently discarded with a warning in the node's log.
+- **Output 1**: Messages forwarded in FIFO order while respecting the configured interval.
+- **Output 2**: Messages dropped due to timeout or overflow, with metadata:
+  - `msg.meta.queueDropped` - Always `true`
+  - `msg.meta.queueDropReason` - Either `"timeout"` or `"overflow"`
+  - `msg.meta.queuedDuration` - Time spent in queue before timeout (timeout drops only)
+  - `msg.meta.queueTimeout` - Configured timeout value in ms (timeout drops only)
+  - `msg.meta.queueSize` - Queue size when overflow occurred (overflow drops only)
+  - `msg.meta.queueMaxSize` - Configured max queue size (overflow drops only)
 
 ## Configuration Options
 
@@ -47,11 +52,13 @@ When timeout mode is selected, messages that exceed the configured timeout are s
 - Messages are processed in first-in-first-out order.
 - The node emits messages immediately when the interval requirement has already been satisfied.
 - If necessary, the node waits the remaining interval before releasing the next message.
-- When messages expire due to timeout (and timeout mode is active) they are removed from the queue and a warning is logged.
+- When messages expire due to timeout (and timeout mode is active) they are sent to output 2 with metadata and a warning is logged.
+- When the queue overflows (queue-size mode) excess messages are sent to output 2 with metadata.
 - Node status indicates whether the queue is idle, holding messages, or actively sending.
 
 ## Best Practices
 
 - Pair with Array nodes to control the rate of batch processing pipelines.
 - Use timeouts to keep sensor readings or camera frames current.
-- Combine with Catch or Status nodes to monitor when the queue reaches capacity or drops messages.
+- Connect output 2 to logging, alerting, or fallback processing to handle dropped messages.
+- Use `msg.meta.queueDropReason` to differentiate between timeout and overflow scenarios in downstream logic.

package/nodes/io/queue.html

@@ -10,7 +10,8 @@
             timeout: { value: 0 }
         },
         inputs: 1,
-        outputs: 1,
+        outputs: 2,
+        outputLabels: ["output", "dropped"],
         icon: "font-awesome/fa-clock-o",
         label: function() {
             if (this.name) return this.name;
@@ -106,11 +107,28 @@
         <dd>Minimum time to wait between forwarded messages. Zero means send immediately when data is available.</dd>
     </dl>
 
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>Output 1 <span class="property-type">message</span></dt>
+        <dd>Successfully queued messages released according to the interval setting.</dd>
+        <dt>Output 2 <span class="property-type">message</span></dt>
+        <dd>Messages dropped due to timeout expiration or queue overflow. Includes metadata:
+            <ul>
+                <li><code>msg.meta.queueDropped</code> - Always <code>true</code></li>
+                <li><code>msg.meta.queueDropReason</code> - Either <code>"timeout"</code> or <code>"overflow"</code></li>
+                <li><code>msg.meta.queuedDuration</code> - Time in queue before timeout (timeout only)</li>
+                <li><code>msg.meta.queueTimeout</code> - Configured timeout value (timeout only)</li>
+                <li><code>msg.meta.queueSize</code> - Current queue size (overflow only)</li>
+                <li><code>msg.meta.queueMaxSize</code> - Configured max size (overflow only)</li>
+            </ul>
+        </dd>
+    </dl>
+
     <h3>Behavior</h3>
     <ul>
         <li>Messages are processed in FIFO order while respecting the selected mode.</li>
-        <li>Queue-size mode enforces a hard cap, rejecting excess messages.</li>
-        <li>Timeout mode keeps buffering but evicts stale entries before sending.</li>
+        <li>Queue-size mode enforces a hard cap; excess messages go to output 2 with <code>overflow</code> reason.</li>
+        <li>Timeout mode keeps buffering but evicts stale entries to output 2 with <code>timeout</code> reason.</li>
         <li>The interval ensures a steady pace by adding delays between sends when configured.</li>
     </ul>
 

package/nodes/io/queue.js

@@ -68,23 +68,32 @@ module.exports = function (RED) {
       }
 
       const now = Date.now();
-      let dropped = 0;
+      const expiredEntries = [];
 
       while (state.queue.length > 0) {
         const oldest = state.queue[0];
         if (now - oldest.enqueuedAt >= node.timeoutMs) {
-          state.queue.shift();
-          dropped += 1;
+          expiredEntries.push(state.queue.shift());
         } else {
           break;
         }
       }
 
-      if (dropped > 0) {
-        node.warn(`Queue node dropped ${dropped} message(s) due to timeout.`);
+      if (expiredEntries.length > 0) {
+        node.warn(`Queue node dropped ${expiredEntries.length} message(s) due to timeout.`);
+        // Send expired messages to output 2 with metadata
+        for (const entry of expiredEntries) {
+          const droppedMsg = entry.msg;
+          droppedMsg.meta = droppedMsg.meta || {};
+          droppedMsg.meta.queueDropped = true;
+          droppedMsg.meta.queueDropReason = 'timeout';
+          droppedMsg.meta.queuedDuration = now - entry.enqueuedAt;
+          droppedMsg.meta.queueTimeout = node.timeoutMs;
+          node.send([null, droppedMsg]);
+        }
       }
 
-      return dropped;
+      return expiredEntries.length;
     }
 
     function scheduleNextSend() {
@@ -144,7 +153,7 @@ module.exports = function (RED) {
         text: `Sending (remaining ${state.queue.length})`
       });
 
-      node.send(entry.msg);
+      node.send([entry.msg, null]);
       scheduleNextSend();
     }
 
@@ -161,8 +170,15 @@ module.exports = function (RED) {
           state.queue.length >= node.maxQueueSize
         ) {
           node.warn(
-            `Queue node at capacity (${node.maxQueueSize}). Incoming message ignored.`
+            `Queue node at capacity (${node.maxQueueSize}). Incoming message dropped.`
           );
+          // Send overflow message to output 2 with metadata
+          msg.meta = msg.meta || {};
+          msg.meta.queueDropped = true;
+          msg.meta.queueDropReason = 'overflow';
+          msg.meta.queueSize = state.queue.length;
+          msg.meta.queueMaxSize = node.maxQueueSize;
+          node.send([null, msg]);
           setStatusQueued();
           return done?.();
         }

package/nodes/util/clean-debug.js

@@ -102,8 +102,7 @@ module.exports = function registerCleanDebugNode(RED) {
         return;
       }
 
-      const format = detectValueType(value);
-      const debugMessage = {
+      var debugMessage = {
         id: node.id,
         z: node.z,
         _alias: node._alias,
@@ -112,13 +111,45 @@ module.exports = function registerCleanDebugNode(RED) {
         property: node.targetType === "full" ? "msg" : node.complete,
         propertyType: node.targetType,
         clean: node.clean,
-        format,
         msg: value,
         _msgid: msg && msg._msgid
       };
 
+      encodeDebugValue(debugMessage);
+
       RED.comms.publish("debug", debugMessage);
     }
+
+    /**
+     * Encode debugMsg.msg and set debugMsg.format in-place so the value
+     * matches the format expected by Node-RED's debug-utils.js in the editor.
+     * RED.util.encodeObject expects the whole debug message object — it reads
+     * from debugMsg.msg and sets debugMsg.msg + debugMsg.format in-place.
+     * @param {object} debugMsg
+     */
+    function encodeDebugValue(debugMsg) {
+      var value = debugMsg.msg;
+      if (value === null || typeof value === "undefined") {
+        debugMsg.format = (value === null) ? "null" : "undefined";
+        debugMsg.msg = (value === null) ? "null" : "(undefined)";
+      } else if (typeof value === "object") {
+        try {
+          RED.util.encodeObject(debugMsg, { maxLength: DEFAULT_DEBUG_MAX_LENGTH });
+        } catch (_e) {
+          debugMsg.format = "error";
+          debugMsg.msg = "Failed to encode debug value";
+        }
+      } else if (typeof value === "boolean") {
+        debugMsg.format = "boolean";
+        debugMsg.msg = value.toString();
+      } else if (typeof value === "number") {
+        debugMsg.format = "number";
+        debugMsg.msg = value.toString();
+      } else {
+        debugMsg.format = "string[" + ("" + value).length + "]";
+        debugMsg.msg = "" + value;
+      }
+    }
   }
 
   /**
@@ -330,30 +361,6 @@ module.exports = function registerCleanDebugNode(RED) {
     return `[${type} withheld: ${detail}]`;
   }
 
-  /**
-   * Detect broad value type to help the editor render icons.
-   * @param {*} value
-   */
-  function detectValueType(value) {
-    if (value === null) {
-      return "null";
-    }
-    if (value && typeof value === "object" && value.type === "Buffer" && Array.isArray(value.data)) {
-      return "buffer";
-    }
-    const t = typeof value;
-    if (t === "string" || t === "number" || t === "boolean" || t === "bigint") {
-      return t;
-    }
-    if (Array.isArray(value)) {
-      return "array";
-    }
-    if (value instanceof Date) {
-      return "date";
-    }
-    return "object";
-  }
-
   /**
    * Format for console/log output.
    * @param {*} value

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosepetal/node-red-contrib-utils",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Utility and I/O nodes for Node-RED, including array helpers and file saving.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"