Node-RED Loop Processing Nodes

0.5.1 · active · verified Wed Apr 22

This package provides three essential Node-RED nodes designed to facilitate flow looping within the Node-RED environment: `counter-loop`, `array-loop`, and `while-loop`. The `counter-loop` node enables `for-loop`-like behavior using a configurable counter, defining initial, terminal, and increment values. The `array-loop` node iterates over elements within a standard JavaScript array, akin to `forEach` or `for-of`, exposing the current key and value. The `while-loop` node executes based on a dynamic conditional expression. Currently at version 0.5.1, the package is actively maintained with a steady cadence of minor updates, frequently addressing bug fixes and introducing new features such as loop time limitations for `while-loop` and explicit variable resetting for iterative nodes. It significantly enhances Node-RED's capabilities by providing structured control flow mechanisms for repetitive tasks, which are not inherently available through basic core nodes.

Common errors

```
Error: Cannot find module 'node-red-contrib-loop-processing' or Nodes not appearing in palette after installation.
```
cause The package was not correctly installed via npm into Node-RED's user directory, or Node-RED was not restarted after the installation was completed.

fix Open your terminal, navigate to your Node-RED user directory (typically `~/.node-red`), and execute `npm install node-red-contrib-loop-processing`. After successful installation, restart your Node-RED instance.
```
Flow appears to be stuck in an infinite loop, or 'while-loop' unexpectedly exits before the condition should be false.
```
cause The condition expression in the `while-loop` node never evaluates to `false`, causing an infinite loop, or the internal loop time limit (introduced in v0.5.0) was reached, forcing termination.

fix Carefully verify the condition expression configured in your `while-loop` node to ensure it will eventually resolve to `false`. If a time limit is being hit, adjust the `while-loop` node's timeout settings if your design truly requires a longer loop, or refactor your flow logic to process data in smaller, discrete steps to avoid long-running iterations.

Warnings

gotcha For `counter-loop` and `array-loop`, the loop variables (e.g., `msg.payload.counter` or `msg.payload.key`) are persistent within the flow context by default. Failing to explicitly reset them (to `null`, `undefined`, or an empty string) after a loop finishes can lead to incorrect behavior or unexpected results in subsequent loop executions, especially in complex multi-loop scenarios.
Fix: After a loop completes, use a `change` node or a `function` node to explicitly set the relevant loop variable property (e.g., `msg.payload.counter`) to `null`, `undefined`, or an empty string before initiating another loop that relies on the same variable.
gotcha The `while-loop` node, starting from version 0.5.0, includes an internal loop time limitation designed to prevent accidental infinite loops. If your intended loop duration legitimately exceeds this internal safeguard, the loop may prematurely terminate, sending the flow to its 'false' (exit) output before the specified condition is truly met.
Fix: Review the `while-loop` node's configuration in the Node-RED editor to understand the default time limit. If longer durations are required, adjust this setting cautiously while ensuring that your loop condition is guaranteed to eventually become false to prevent system resource exhaustion.
gotcha The `array-loop` node is specifically designed to iterate over numerically indexed arrays. Providing an associative array (a JavaScript object used as a key-value map) instead of a proper array will not yield the expected iteration behavior and may result in errors or only partial processing of object keys.
Fix: Ensure that the input property for the `array-loop` node is a standard JavaScript array (`[]`). If you need to iterate over properties of an object, use a preceding `function` node to convert the object's keys or values into an array, or consider alternative Node-RED patterns for object processing.

Install

npm install node-red-contrib-loop-processing npm
yarn add node-red-contrib-loop-processing yarn
pnpm add node-red-contrib-loop-processing pnpm

Quickstart

This quickstart JSON demonstrates how to install the package and configure a basic `counter-loop` node in Node-RED, iterating a counter from 0 to 5 and logging each step, while also showing the loop completion.

{
  "id": "e9a6e1a4.9c488",
  "type": "tab",
  "label": "Loop Processing Quickstart",
  "disabled": false,
  "info": "Quickstart for node-red-contrib-loop-processing\n\n1. **Install:** `npm install node-red-contrib-loop-processing` in your Node-RED user directory (~/.node-red), then restart Node-RED.\n2. **Drag & Drop:** Place an 'Inject' node, a 'counter-loop' node, and two 'Debug' nodes on the canvas.\n3. **Configure counter-loop:**\n   - Property: `msg.payload.counter`\n   - Initial value: `0`\n   - Terminal value: `5`\n   - Operator: `<=`\n   - Increment value: `1`\n   - Check 'Reset counter when loop exits'.\n4. **Connect:**\n   - Inject node -> counter-loop input\n   - counter-loop 'true' output -> Debug node (set to display `msg.payload.counter`)\n   - counter-loop 'false' output -> Debug node (set to display 'Loop Finished')\n5. **Deploy and Test:** Click the inject button to see the counter increment in the debug sidebar."
}

view raw JSON →