node-red-contrib-looptimer-advanced 1.1.0

Sends the msg through the first output, then continues to do so in a loop, once per the duration specified, until a payload of 'stop' or 'STOP' is received. Supports override with messages!

npm install node-red-contrib-looptimer-advanced

Highlights

• 🔁 Repeat a message once per interval (milliseconds to days) with an optional maximum loop count and maximum run time.
• 🛑 Stop with a payload, ⏸ pause and ▶ resume without losing the loop counter or the timeout budget.
• 🧩 Reconfigure per message with msg.loop: interval, limits and commands, no redeploy needed.
• 🎯 Exact counts: optionally make Max Loops mean the total number of messages, including a single call, and optionally skip the immediate first message.
• 📊 Loop counters: msg.loopstate with the count, the remaining loops and the elapsed time, and a status command to ask for them.
• 🧵 One loop per topic: run a separate loop for every msg.topic in one node, or ignore new messages while a loop runs.
• ⏲️ Pause timeout: resume or stop automatically when a pause lasts too long.
• 🔌 Typed settings: read the interval and the limits from msg., flow., global. or env.
• 🎯 No drift: every tick is due at a fixed time after the start, also after a pause.
• 🧪 Tested and dependency free: plain timers, an automated test suite and CI on Node.js 18 – 24.
• 🔒 Backwards compatible: flows built with 0.0.x keep working unchanged, every new feature is opt-in.

Installation

Use Menu → Manage palette → Install and search for node-red-contrib-looptimer-advanced, or:

cd ~/.node-red
npm install node-red-contrib-looptimer-advanced

Requires Node-RED 3.0+ and Node.js 18+. Older runtimes can stay on 0.0.x.

Quick start

An example flow is included (Import → Examples in the editor, or paste the file). In short:

1. Wire an inject node into looptimer-advanced, set Loop Every to 1 Second and Max Loops to 10.
2. Output 1 emits your message immediately and then once per second; output 2 reports max loops reached.
3. Send a message with payload stop to the same node to end the loop early.

stateDiagram-v2
    [*] --> Running: any message
    Running --> Running: tick (output 1)
    Running --> Paused: pause
    Paused --> Running: resume
    Running --> [*]: stop / max loops / timeout (output 2)
    Paused --> [*]: stop
    Running --> Running: new message restarts the loop

Outputs

Controlling the loop

Pausing freezes the remaining time of the current interval, the loop counter and the timeout budget. Resuming continues from exactly there. Stopping while paused works too.

Pause timeout

Set Pause Timeout (and After Timeout: resume or stop the loop) to get the loop going again, or end it, when a pause lasts too long. Output 2 then sends resumed / stopped with msg.reason = "pause timeout". Resuming or stopping by hand cancels the timeout.

Status command

A status command sends a message with payload status and msg.loopstate on output 2, for example to show the progress on a dashboard. When no loop is running msg.loopstate.state is idle.

Overriding settings with msg.loop

// Function node: loop every 30 seconds, at most 10 times
msg.loop = { duration: 30, units: "Second", maxloops: 10 };
return msg;

Overrides stay in effect for the following messages (as they always did). In a function node create the object first: msg.loop = { maxloops: 5 };, never msg.loop.maxloops = 5 on its own.

How loops are counted

By default the first message is not part of the loop, so Max Loops 5 gives 6 messages: 1 original + 5 loops. This keeps compatibility with node-red-contrib-looptimer.

Tick Max Loops counts the first message too (or send msg.loop.totalcount = true) for exact counts:

Without Send the first message immediately (or msg.loop.sendfirst = false) nothing goes out at the start, the first message follows after the first interval. Max Loops 5 then gives 5 messages, and with counts the first message too it is the same number.

Loop counters (msg.loopstate)

Tick Add the loop counters as msg.loopstate (or send msg.loop.loopstate = true) and every message carries:

New messages while a loop runs

The setting New message decides what a message does that arrives while a loop is running:

Typed settings

Loop Every, Max Loops and Max Timeout are typed inputs: next to a fixed number they can be read from msg., flow., global. or an environment variable (env). The value is read for every message that starts a loop, and has to be a number, otherwise the node reports an error and does not start. Overrides in msg.loop are applied on top.

Versioning

Since 1.0.0 the package follows Semantic Versioning and keeps a changelog in the Keep a Changelog format.

Releases are tagged vX.Y.Z on GitHub. The old 0.0.x numbering was one increment per change and carried no compatibility promise. 1.0.0 marks the first release with a stable, tested public interface: the node's properties, msg.loop and the output payloads.

Upgrading

From 1.0.x to 1.1: nothing to change, every new setting is off by default and existing nodes keep their behavior. The only visible difference is that the ticks no longer drift: a long loop now sends its messages at fixed times after the start instead of a little later every time.

Upgrading from 0.0.x

Nothing to change in your flows. What is different:

• The loop dependency is gone and the node runs on plain timers. A stop that arrived between two iterations is no longer lost, and no timer is left running after stop or redeploy.
• A loop that hits its maximum timeout now always reports timeout on output 2 (before it sometimes ended silently). The old single-call workaround (maxloops: 0 with a tiny maxtimeout) still works.
• Invalid msg.loop values are reported through normal error handling, so a Catch node sees them.
• Minimum versions: Node-RED 3.0 and Node.js 18.
• A payload of pause, resume or status is only treated as a command when the option is ticked. Existing nodes have it off, so such payloads loop like any other value.

Contributing

Issues and pull requests are welcome.

git clone https://github.com/Haxiboy/node-red-contrib-looptimer-advanced.git
cd node-red-contrib-looptimer-advanced
npm install
npm test

Credits and license

Based on node-red-contrib-looptimer and node-red-contrib-looptimer2, with the addition of per-message overrides, pause/resume, loop counters, one loop per topic, typed settings and exact counting. Released under the Apache-2.0 license.