node-red-contrib-loop 1.0.1
Node-RED nodes to looping (fixed steps, condition based or iterating over arrays, objects, maps, sets, string).
Creating loops is the commont programming technique. The node-red-contrib-loop node provides support for them in Node-RED.
You can choose between three kinds of loops. The loop with a fixed count of repeatitons, the loop based on evaluating a condition or the loop itearating on an iterable enumeration.
Common Description
You can control the loop by sending msg.command
to the input. If it contains a break
string, the loop will be finished imediately. If it contains a restart
string, the loop will start again from the first value.
The node has two outputs: end of loop and step of loop. The first output is used at the end when the loop is left. Connect the second output to the input through your loop processing nodes, i.e. create the loop.
Nodes in the processing loop connected to step of loop output will get msg.loop
object with the following property:
index
- the counter incremented by 1 from 0
It may contain more properties, but they depend on the kind of loop. See bellow for each loop-kind section. You can select one of the properties to be placed to msg.payload
. Use the Loop Payload property in the editor form for this.
On the end of loop output you will get msg.loop
object with the following properties:
broken
- true if the loop has receivedbreak
commandtimeout
- true if the timeout has expiredpassed.total
- the total number of passes through the loop, included all restartspassed.last
- number of passes through the loop from the last restart or startrestarts
- number of times the loop was restarted
You will also get msg.payload
on end of loop output. It is optional which value it should contain. You can choose between last payload from the loop and original payload which the node received on the input at the start. Use End Payload in the editor form to choose.
You can limit time for loops for all three kinds. Use Time Limit in the editor form or msg.limit
on the fly. Time is specified in milliseconds.
“Fixed Count” Loop Kind
Use this loop kind when you wan a fixed number of repeatitions with the numeric counter.
The Count field specifies the number of passes through loop. You can omit it and use msg.count
on the fly.
The Initial Value field specifies the value from which the counter should count. You can omit it and use msg.initial
on the fly.
The Step Value field specifies the step increment or decrement for the counter.
Nodes in the processing branch connected to step of loop output will get msg.loop
object with the following additional properties:
value
- counter valuecount
- requested count of passes through the loopinitial
- value from which the counter startedstep
- value used to increment or decrement the counter
“Condition” Loop Kind
Use this loop kind when you need a loop based on some condition.
You need to define the condition in the Condition field. You can choose from three languages.
JavaScript - Condition written as code in JavaScript language. Condition evaluation will use the result of the last part. The loop will continue if it is
true
, otherwise the loop will finish. Examples:
msg.payload !== "done"
roses = global.get("roses"); global.set("roses", ++roses); roses <= 100
JavaScript code is executed in the sandbox with a limited environment similar to the function node.JSONata - Condition as a JSONata expression. The loop will continue if the expression is evaluated as
true
, otherwise the loop will finish. Examples:
msg.payload in [1,2,3,5,7,13,21]
$globalContext("status") or msg.size > 10
Regex - Regular Expression used with test() function aplied to
msg.payload
. The loop will continue if it matches, otherwise the loop will finish. Examples:
file[0-9].txt
^[a-zA-Z0-9]+: .*
The next three examples do the same work (test if the string ends with "Z" character) in different languages with different speed:
msg.payload.substr(-1) != "Z"
$substring(msg.payload, -1) != "Z"
.*[^Z]
The JavaScript is the fastest and the Regex is the slowest in this case. However, this may be different for more complex expressions. And not everthing is easy or possible to write in each of these languages. For example, Regex is only useful for comparing strings but it is also the best choice for complex search patterns.
You can choose if a condition should be evaluated befor or after the loop. The difference is in evaluating the condition for the initial values in the first case. Compared to classic programing, the first optinon is “while‥do” loop and the second one is “do‥while” / “repeat‥until” loop.
The msg.loop
has no additional properties for this loop kind.
“Enumeration” Loop Kind
Use this loop kind when you want to iterate over some enumeration. It must be iterable, which are the following: Array, Typed Array, Object, Map, Set and String.
You nedd to specify enumeration in the Enumeration field as a property of the message, flow or global context. You can also specify it directly as JSON or a normal string.
Nodes in the processing branch connected to the step of loop output will get a msg.loop
object with the following additional properties:
value
- iterated item valuekey
- iterated item key; for general object and Map onlyenumeration
- object it iterates over
Usage Examples
The examples are available in the examples folder. You can import it directly from Node-RED.
License
Node is pulished under MIT License. See LICENSE file.