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

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/package.json

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