@rosepetal/node-red-contrib-utils 1.1.1

package/nodes/io/array-select.js

@@ -0,0 +1,187 @@
+/**
+ * @file Node.js logic for the Array-Select node with single output and flexible selection.
+ * @author Rosepetal
+ */
+
+module.exports = function(RED) {
+  function ArraySelectNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    
+    // Store configuration
+    node.inputPath = config.inputPath || 'payload';
+    node.inputPathType = config.inputPathType || 'msg';
+    node.outputPath = config.outputPath || 'payload';
+    node.outputPathType = config.outputPathType || 'msg';
+    node.selection = config.selection || '0';
+    node.asArray = config.asArray || false;
+
+    // Set initial status
+    node.status({ 
+      fill: "blue", 
+      shape: "dot", 
+      text: `Ready: ${node.selection}` 
+    });
+
+    /**
+     * Parse selection string and return indices
+     * @param {string} selection - Selection string (e.g., "0", "1,3,5", "1:4", "0::2")
+     * @param {number} arrayLength - Length of input array
+     * @returns {Array} Array of indices or null if invalid
+     */
+    function parseSelection(selection, arrayLength) {
+      if (!selection || selection.trim() === '') return null;
+      
+      const sel = selection.trim();
+      
+      try {
+        // Single index (e.g., "2" or "-1")
+        if (/^-?\d+$/.test(sel)) {
+          const index = parseInt(sel);
+          const normalizedIndex = index < 0 ? arrayLength + index : index;
+          if (normalizedIndex >= 0 && normalizedIndex < arrayLength) {
+            return [normalizedIndex];
+          }
+          return null;
+        }
+        
+        // Multiple indices (e.g., "0,2,4")
+        if (sel.includes(',')) {
+          const indices = sel.split(',').map(s => {
+            const index = parseInt(s.trim());
+            return index < 0 ? arrayLength + index : index;
+          }).filter(i => i >= 0 && i < arrayLength);
+          return indices.length > 0 ? indices : null;
+        }
+        
+        // Range (e.g., "1:4" or "1:4:2")
+        if (sel.includes(':')) {
+          const parts = sel.split(':');
+          if (parts.length === 2) {
+            // Simple range: start:end
+            let start = parseInt(parts[0]) || 0;
+            let end = parseInt(parts[1]) || arrayLength;
+            start = start < 0 ? arrayLength + start : start;
+            end = end < 0 ? arrayLength + end : end;
+            
+            const indices = [];
+            for (let i = Math.max(0, start); i < Math.min(arrayLength, end); i++) {
+              indices.push(i);
+            }
+            return indices.length > 0 ? indices : null;
+          } else if (parts.length === 3) {
+            // Step range: start:end:step
+            let start = parseInt(parts[0]) || 0;
+            let end = parseInt(parts[1]) || arrayLength;
+            let step = parseInt(parts[2]) || 1;
+            start = start < 0 ? arrayLength + start : start;
+            end = end < 0 ? arrayLength + end : end;
+            
+            if (step <= 0) step = 1;
+            
+            const indices = [];
+            for (let i = Math.max(0, start); i < Math.min(arrayLength, end); i += step) {
+              indices.push(i);
+            }
+            return indices.length > 0 ? indices : null;
+          }
+        }
+        
+        return null;
+      } catch (err) {
+        return null;
+      }
+    }
+
+    // Handle incoming messages
+    node.on('input', function(msg, send, done) {
+      try {
+        // Get data from configured input path
+        let inputArray;
+        if (node.inputPathType === 'msg') {
+          inputArray = RED.util.getMessageProperty(msg, node.inputPath);
+        } else if (node.inputPathType === 'flow') {
+          inputArray = node.context().flow.get(node.inputPath);
+        } else if (node.inputPathType === 'global') {
+          inputArray = node.context().global.get(node.inputPath);
+        }
+
+        // Validate input is an array
+        if (!Array.isArray(inputArray)) {
+          node.warn(`Input must be an array. Received: ${typeof inputArray}`);
+          node.status({ fill: "red", shape: "ring", text: "Invalid input: not an array" });
+          return done?.();
+        }
+
+        if (inputArray.length === 0) {
+          node.warn('Input array is empty');
+          node.status({ fill: "yellow", shape: "ring", text: "Empty array" });
+          return done?.();
+        }
+
+        // Process selection
+        const indices = parseSelection(node.selection, inputArray.length);
+        
+        if (indices && indices.length > 0) {
+          const selectedItems = indices.map(idx => inputArray[idx]);
+          
+          // Determine output format
+          const result = (node.asArray || selectedItems.length > 1) ? selectedItems : selectedItems[0];
+          
+          // Create clean output message with only the selected result
+          let outputMsg = {};
+          
+          // Set output based on configured path
+          if (node.outputPathType === 'msg') {
+            RED.util.setMessageProperty(outputMsg, node.outputPath, result, true);
+          } else if (node.outputPathType === 'flow') {
+            node.context().flow.set(node.outputPath, result);
+            // For flow context, send minimal message (no payload)
+          } else if (node.outputPathType === 'global') {
+            node.context().global.set(node.outputPath, result);
+            // For global context, send minimal message (no payload)
+          }
+          
+          node.status({ 
+            fill: "green", 
+            shape: "dot", 
+            text: `Selected ${selectedItems.length} from [${inputArray.length}]` 
+          });
+          
+          send(outputMsg);
+        } else {
+          // Invalid selection
+          node.warn(`Invalid selection "${node.selection}" for array of length ${inputArray.length}`);
+          node.status({ fill: "red", shape: "ring", text: "Invalid selection" });
+          return done?.();
+        }
+
+        // Reset status after a delay
+        setTimeout(() => {
+          node.status({ 
+            fill: "blue", 
+            shape: "dot", 
+            text: `Ready: ${node.selection}` 
+          });
+        }, 2000);
+
+        done?.();
+
+      } catch (err) {
+        node.status({ fill: "red", shape: "ring", text: "Error" });
+        if (done) {
+          done(err);
+        } else {
+          node.error(err, msg);
+        }
+      }
+    });
+
+    // Clean up on node removal
+    node.on('close', function() {
+      node.status({});
+    });
+  }
+
+  RED.nodes.registerType("rp-array-select", ArraySelectNode);
+};

package/nodes/io/queue.html

@@ -0,0 +1,119 @@
+<script type="text/javascript">
+    RED.nodes.registerType('rp-queue', {
+        category: 'RP Utils',
+        color: '#87CEEB',
+        defaults: {
+            name: { value: "" },
+            mode: { value: "queue-size" },
+            maxQueueSize: { value: 0 },
+            intervalMilliseconds: { value: 0 },
+            timeout: { value: 0 }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-clock-o",
+        label: function() {
+            if (this.name) return this.name;
+            return "Queue";
+        },
+        oneditprepare: function() {
+            const modeField = $("#node-input-mode");
+            const queueRow = $("#node-row-maxQueueSize");
+            const timeoutRow = $("#node-row-timeout");
+            const queueTip = $("#node-tip-maxQueueSize");
+            const timeoutTip = $("#node-tip-timeout");
+
+            function toggleModeFields() {
+                const mode = modeField.val();
+                if (mode === 'timeout') {
+                    queueRow.hide();
+                    queueTip.hide();
+                    timeoutRow.show();
+                    timeoutTip.show();
+                } else {
+                    queueRow.show();
+                    queueTip.show();
+                    timeoutRow.hide();
+                    timeoutTip.hide();
+                }
+            }
+
+            modeField.on("change", toggleModeFields);
+            toggleModeFields();
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="rp-queue">
+    <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>
+
+    <hr>
+
+    <div class="form-row">
+        <label for="node-input-mode"><i class="fa fa-exchange"></i> Mode</label>
+        <select id="node-input-mode">
+            <option value="queue-size">Queue Size Limit</option>
+            <option value="timeout">Timeout</option>
+        </select>
+    </div>
+    <div class="form-tips">
+        <b>Tip:</b> Pick a mode to decide whether the node caps how many messages can wait or keeps unlimited entries that expire after a timeout.
+    </div>
+
+    <div class="form-row" id="node-row-maxQueueSize">
+        <label for="node-input-maxQueueSize"><i class="fa fa-list"></i> Max Queue Size</label>
+        <input type="number" id="node-input-maxQueueSize" min="0" step="1" style="width: 70%;" placeholder="0">
+    </div>
+    <div class="form-tips" id="node-tip-maxQueueSize">
+        <b>Tip:</b> When using the queue-size mode, this field limits how many messages are buffered; extra messages are dropped until space frees up.
+    </div>
+
+    <div class="form-row" id="node-row-timeout">
+        <label for="node-input-timeout"><i class="fa fa-hourglass-half"></i> Timeout (ms)</label>
+        <input type="number" id="node-input-timeout" min="0" step="1" style="width: 70%;" placeholder="0">
+    </div>
+    <div class="form-tips" id="node-tip-timeout">
+        <b>Tip:</b> Timeout mode keeps buffering all messages but removes entries that stay longer than this value, keeping the data fresh.
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-intervalMilliseconds"><i class="fa fa-clock-o"></i> Interval (ms)</label>
+        <input type="number" id="node-input-intervalMilliseconds" min="0" step="1" style="width: 70%;" placeholder="0">
+    </div>
+    <div class="form-tips">
+        <b>Tip:</b> Interval enforces a minimum delay between forwarded messages; set to 0 to send as fast as possible.
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="rp-queue">
+    <p>Buffers incoming messages and releases them with optional rate limiting and expiration control.</p>
+
+    <h3>Mode</h3>
+    <p>Choose between a queue-size limit or a timeout strategy; only the controls for the selected mode are applied.</p>
+
+    <h3>Configuration</h3>
+    <dl class="message-properties">
+        <dt>Mode <span class="property-type">enum</span></dt>
+        <dd>Select <code>Queue Size Limit</code> to cap the number of buffered messages or <code>Timeout</code> to drop entries after a duration.</dd>
+        <dt>Max Queue Size <span class="property-type">number</span></dt>
+        <dd>Valid only in queue-size mode. Determines how many messages can be held before incoming data is ignored.</dd>
+        <dt>Timeout (ms) <span class="property-type">number</span></dt>
+        <dd>Valid only in timeout mode. Messages that stay longer than this millisecond value are removed before they reach the output.</dd>
+        <dt>Interval (ms) <span class="property-type">number</span></dt>
+        <dd>Minimum time to wait between forwarded messages. Zero means send immediately when data is available.</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>The interval ensures a steady pace by adding delays between sends when configured.</li>
+    </ul>
+
+    <h3>Status</h3>
+    <p>The node status reflects whether the queue is idle, holding messages, or actively sending.</p>
+</script>

package/nodes/io/queue.js

@@ -0,0 +1,191 @@
+/**
+ * @file Node.js logic for the Queue node providing buffering and rate limiting.
+ */
+
+module.exports = function (RED) {
+  function QueueNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    /* ────────────────────────────
+       ░░ 1.  Read configuration ░░
+       ──────────────────────────── */
+    const parsedMax = parseInt(config.maxQueueSize, 10);
+    const parsedInterval = parseInt(config.intervalMilliseconds, 10);
+    const parsedTimeout = parseInt(config.timeout, 10);
+    const parsedMode = config.mode;
+
+    node.maxQueueSize = Number.isInteger(parsedMax) && parsedMax > 0 ? parsedMax : 0;
+    node.intervalMs =
+      Number.isInteger(parsedInterval) && parsedInterval > 0 ? parsedInterval : 0;
+    node.timeoutMs =
+      Number.isInteger(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : 0;
+
+    node.mode =
+      parsedMode === 'timeout' || parsedMode === 'queue-size'
+        ? parsedMode
+        : 'legacy';
+
+    const useQueueLimit = node.mode !== 'timeout';
+    const useTimeout = node.mode !== 'queue-size';
+
+    /* ────────────────────────────
+       ░░ 2.  Internal state      ░░
+       ──────────────────────────── */
+    const state = {
+      queue: [],
+      timer: null,
+      lastSent: 0
+    };
+
+    setStatusIdle();
+
+    /* ────────────────────────────
+       ░░ 3.  Helper functions    ░░
+       ──────────────────────────── */
+    function setStatusIdle() {
+      node.status({ fill: 'blue', shape: 'dot', text: 'Idle' });
+    }
+
+    function setStatusQueued() {
+      node.status({
+        fill: 'yellow',
+        shape: 'dot',
+        text: `Queued: ${state.queue.length}`
+      });
+    }
+
+    function clearTimer() {
+      if (state.timer) {
+        clearTimeout(state.timer);
+        state.timer = null;
+      }
+    }
+
+    function pruneExpired() {
+      if (!useTimeout || node.timeoutMs <= 0 || state.queue.length === 0) {
+        return 0;
+      }
+
+      const now = Date.now();
+      let dropped = 0;
+
+      while (state.queue.length > 0) {
+        const oldest = state.queue[0];
+        if (now - oldest.enqueuedAt >= node.timeoutMs) {
+          state.queue.shift();
+          dropped += 1;
+        } else {
+          break;
+        }
+      }
+
+      if (dropped > 0) {
+        node.warn(`Queue node dropped ${dropped} message(s) due to timeout.`);
+      }
+
+      return dropped;
+    }
+
+    function scheduleNextSend() {
+      clearTimer();
+
+      pruneExpired();
+
+      if (state.queue.length === 0) {
+        setStatusIdle();
+        return;
+      }
+
+      const now = Date.now();
+      const elapsed = state.lastSent ? now - state.lastSent : Number.POSITIVE_INFINITY;
+      let delay = 0;
+
+      if (node.intervalMs > 0 && Number.isFinite(elapsed) && elapsed < node.intervalMs) {
+        delay = node.intervalMs - elapsed;
+      }
+
+      const sendFn = () => {
+        state.timer = null;
+        attemptSend();
+      };
+
+      state.timer = setTimeout(sendFn, Math.max(delay, 0));
+
+      setStatusQueued();
+    }
+
+    function attemptSend() {
+      pruneExpired();
+
+      if (state.queue.length === 0) {
+        setStatusIdle();
+        return;
+      }
+
+      const now = Date.now();
+      const elapsed = state.lastSent ? now - state.lastSent : Number.POSITIVE_INFINITY;
+
+      if (node.intervalMs > 0 && Number.isFinite(elapsed) && elapsed < node.intervalMs) {
+        scheduleNextSend();
+        return;
+      }
+
+      const entry = state.queue.shift();
+      if (!entry) {
+        scheduleNextSend();
+        return;
+      }
+
+      state.lastSent = now;
+      node.status({
+        fill: 'green',
+        shape: 'dot',
+        text: `Sending (remaining ${state.queue.length})`
+      });
+
+      node.send(entry.msg);
+      scheduleNextSend();
+    }
+
+    /* ────────────────────────────
+       ░░ 4.  Input handler       ░░
+       ──────────────────────────── */
+    node.on('input', function (msg, _send, done) {
+      try {
+        pruneExpired();
+
+        if (
+          useQueueLimit &&
+          node.maxQueueSize > 0 &&
+          state.queue.length >= node.maxQueueSize
+        ) {
+          node.warn(
+            `Queue node at capacity (${node.maxQueueSize}). Incoming message ignored.`
+          );
+          setStatusQueued();
+          return done?.();
+        }
+
+        state.queue.push({ msg, enqueuedAt: Date.now() });
+        setStatusQueued();
+        attemptSend();
+        done?.();
+      } catch (err) {
+        node.status({ fill: 'red', shape: 'ring', text: 'Error' });
+        done ? done(err) : node.error(err, msg);
+      }
+    });
+
+    /* ────────────────────────────
+       ░░ 5.  Cleanup             ░░
+       ──────────────────────────── */
+    node.on('close', function () {
+      clearTimer();
+      state.queue.length = 0;
+      setStatusIdle();
+    });
+  }
+
+  RED.nodes.registerType('rp-queue', QueueNode);
+};