@inteli.city/node-red-contrib-exec-collection 1.0.3 → 1.0.5

package/node.queue.html

@@ -0,0 +1,359 @@
+<!--* header -->
+<script type="text/markdown" data-help-name="node.queue">
+## node.queue
+
+Sends code to a pool of persistent Node.js workers. Each message renders the Nunjucks template into JavaScript, dispatches it to a free worker, and returns whatever `console.log()` prints as `msg.payload`.
+
+**Mental model:** you are not running a script — you are sending code to a running Node.js engine. State persists between messages on the same worker.
+
+---
+
+## Queue
+
+Controls how many Node.js workers run concurrently. The status badge shows `waiting (executing/limit)`:
+
+| Status | Meaning |
+|---|---|
+| Blue dot `0 (0/2)` | Workers running, all idle |
+| Blue ring `0 (2/2)` | All workers executing |
+| Blue ring `3 (2/2)` | 3 messages waiting, both workers busy |
+| Grey dot `0 (0/2)` | No workers (idle timeout or not started) |
+
+Workers start lazily on the first message. After 20 minutes idle, all workers are killed and restart on the next message.
+
+The **⏹ button** in the node editor header kills all workers immediately — no redeploy needed. A confirmation dialog appears whenever workers are alive (executing or idle).
+
+---
+
+## Writing templates
+
+Nunjucks renders `{{ }}` expressions before the worker sees the code. All `msg` values are strings after rendering.
+
+**Always wrap string variables in JS quotes:**
+
+```js
+const name = "{{ payload }}";   // correct
+const name = {{ payload }};     // wrong — syntax error if payload is a string
+```
+
+Numbers can be injected directly:
+
+```js
+const x = {{ payload }};   // safe when payload is a number
+```
+
+**Warning:** Nunjucks evaluates `{{ }}` everywhere — including inside `//` and `/* */` comments. Do not put Nunjucks expressions inside comments. Comments are stripped before rendering, so they have no effect on output anyway.
+
+---
+
+## Output
+
+Use `console.log()` to produce output. Each call emits one message (in Delimited mode with `\n` delimiter).
+
+```js
+console.log("hello");  // → one message: "hello"
+console.log("world");  // → one message: "world"
+```
+
+`console.warn()` and `console.error()` go to stderr and become node warnings — they do not affect `msg.payload`.
+
+The bottom row controls how output is handled:
+
+**Output format** — how each segment is parsed (plain text, JSON, YAML, XML).
+
+**Mode** — how output is split into messages:
+- **Delimited** (default): buffers output and splits on the delimiter (`\n` by default). Each `console.log()` produces one message.
+- **Raw**: emits each output chunk immediately with no buffering. Chunks may not align with `console.log()` calls.
+
+**Delimiter** — only visible in Delimited mode. Supports escape sequences: `\n`, `\t`, `\r`, or any literal string.
+
+---
+
+## Persistent state
+
+Each worker's context persists across all messages it handles:
+
+```js
+if (!global.counter) {
+    global.counter = 0;
+}
+
+global.counter++;
+console.log(global.counter);
+```
+
+With Queue > 1, state is **per-worker** — no shared state between workers.
+
+---
+
+## require()
+
+`require` is available in the worker context and resolves from Node-RED's environment:
+
+```js
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+console.log(JSON.stringify({ platform: os.platform(), home: os.homedir() }));
+```
+
+---
+
+## Output modes
+
+| Mode | Result |
+|---|---|
+| Plain text | stdout as string (trimmed) |
+| Parsed JSON | `JSON.parse(stdout)` |
+| Parsed YAML | YAML-parsed stdout |
+| Parsed XML | XML-parsed stdout |
+
+---
+
+[Full documentation](https://www.npmjs.com/package/@inteli.city/node-red-contrib-exec-collection) · [Nunjucks templating](https://mozilla.github.io/nunjucks/templating.html)
+</script>
+
+<!--* styles -->
+<style>
+    #node-nq-kill-btn:hover { color: #d9534f !important; }
+    #node-nq-kill-btn.is-executing { color: #d9534f !important; }
+</style>
+
+<!--* node-design -->
+<script type="text/html" data-template-name="node.queue">
+    <div class="form-row" style="position:relative;">
+        <label for="node-input-name">
+            <i class="fa fa-tag"></i>
+            <span data-i18n="node-red:common.label.name"></span>
+        </label>
+        <div style="display: inline-block; width: calc(100% - 140px)">
+            <input type="text" id="node-input-name" style="width:100%;" data-i18n="[placeholder]node-red:common.label.name">
+        </div>
+        <button id="node-nq-kill-btn"
+                title="Kill running workers"
+                style="position:absolute; right:5px; top:50%; transform:translateY(-50%); z-index:5;
+                       background:transparent; border:none; padding:6px 8px; margin-left:10px; cursor:pointer;
+                       color:#888; font-size:13px; line-height:1;">
+            <i class="fa fa-stop"></i>
+        </button>
+    </div>
+
+    <div class="form-row">
+        <label>
+            <i class="fa fa-sign-out"></i>
+            <span>Queue</span>
+        </label>
+        <input style="width:60px" type="number" id="node-input-queue" value="1">
+    </div>
+
+    <div class="form-row" style="position: relative;">
+        <label>
+            <i class="fa fa-code"></i>
+            <span>Template</span>
+        </label>
+
+        <div style="position: absolute; right:0; display:inline-block; text-align: right; font-size: 0.8em;">
+            <input type="hidden" id="node-input-template" autofocus="autofocus">
+            <button id="node-template-expand-editor" class="red-ui-button red-ui-button-small"><i class="fa fa-expand"></i></button>
+        </div>
+    </div>
+    <div class="form-row node-text-editor-row">
+        <div style="height: 300px; min-height:150px;" class="node-text-editor" id="node-input-template-editor"></div>
+    </div>
+
+    <div class="form-row" style="margin-bottom:0px; white-space:nowrap;">
+        <label for="node-input-output"><i class="fa fa-long-arrow-right"></i> <span data-i18n="node-red:template.label.output"></span></label>
+        <select id="node-input-output" style="width:90px;">
+            <option value="str">Plain text</option>
+            <option value="parsedJSON">Parsed JSON</option>
+            <option value="parsedYAML">Parsed YAML</option>
+            <option value="parsedXML">Parsed XML</option>
+        </select>
+
+        <label style="margin-left:14px;" for="node-input-field"><i class="fa fa-ellipsis-h"></i> <span data-i18n="node-red:common.label.property"></span></label>
+        <input style="margin-left:-14px; width:118px;" type="text" id="node-input-field" placeholder="payload">
+        <input style="margin-left:-14px; width:118px;" type="hidden" id="node-input-fieldType">
+
+        <label style="margin-left:14px;">
+            <i class="fa fa-random"></i>
+            <span>Parsing</span>
+        </label>
+        <select id="node-input-streamMode" style="width:90px; margin-left:-20px;">
+            <option value="delimited">Delimited</option>
+            <option value="raw">Raw</option>
+        </select>
+        <input type="text" id="node-input-delimiter" style="margin-left:4px; width:46px;" placeholder="\n">
+    </div>
+    <div id="node-nq-raw-hint" style="display:none; text-align:right; margin-top:3px; font-size:0.75em; color:#aaa;">
+        Raw output may produce incomplete messages.
+    </div>
+</script>
+
+<!--* javascript -->
+<script type="text/javascript">
+    RED.nodes.registerType('node.queue', {
+        color: "rgb(100, 180, 140)",
+        category: 'function',
+        defaults: {
+            name:        { value: "" },
+            queue:       { value: 1 },
+            streamMode:  { value: "delimited" },
+            delimiter:   { value: "\\n", validate: function(v) { return typeof v === 'string' && v.length > 0; } },
+            template:    { value: "// All msg values render as strings. Wrap in quotes for JS string literals.\n// WARNING: Nunjucks evaluates {{ }} everywhere, including inside // comments.\n\nconst data = \"{{ payload }}\"\nconsole.log(data)" },
+            output:      { value: "str" },
+            field:       { value: "payload", validate: RED.validators.typedInput("fieldType") },
+            fieldType:   { value: "msg" },
+            currentLine: { value: { row: 0, column: 0 } }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "cog.png",
+        label: function() {
+            return this.name || "node.queue";
+        },
+        labelStyle: function() {
+            return this.name ? "node_label_italic" : "";
+        },
+        oneditprepare: function() {
+            var that = this;
+
+            if (!this.field)     { this.field     = 'payload'; }
+            if (!this.fieldType) { this.fieldType = 'msg'; }
+
+            $("#node-input-field").typedInput({
+                default: 'msg',
+                types: ['msg', 'flow', 'global'],
+                typeField: $("#node-input-fieldType")
+            });
+
+            function updateStreamUI() {
+                var mode    = $("#node-input-streamMode").val();
+                var $sel    = $("#node-input-streamMode");
+                var $rawOpt = $sel.find("option[value='raw']");
+                if (mode === 'raw') {
+                    $("#node-input-delimiter").hide();
+                    $("#node-nq-raw-hint").show();
+                    $sel.css("color", "#b8860b");
+                    $rawOpt.text("⚠ Raw");
+                    $sel.attr("title", "Raw mode emits unprocessed chunks — messages may be incomplete.");
+                } else {
+                    $("#node-input-delimiter").show();
+                    $("#node-nq-raw-hint").hide();
+                    $sel.css("color", "");
+                    $rawOpt.text("Raw");
+                    $sel.removeAttr("title");
+                }
+            }
+            $("#node-input-streamMode").on("change", updateStreamUI);
+            updateStreamUI();
+
+            this.editor = RED.editor.createEditor({
+                id: 'node-input-template-editor',
+                mode: 'ace/mode/javascript',
+                value: $("#node-input-template").val()
+            });
+
+            if (this.currentLine === undefined) { this.currentLine = { row: 0, column: 0 }; }
+            this.editor.resize(true);
+            this.editor.scrollToLine(this.currentLine.row + 1, true, true, function() {});
+            this.editor.gotoLine(this.currentLine.row + 1, this.currentLine.column + 1, true);
+
+            RED.popover.tooltip(
+                $("#node-template-expand-editor"),
+                RED._("node-red:common.label.expand")
+            );
+
+            $("#node-template-expand-editor").on("click", function(e) {
+                e.preventDefault();
+                var value = that.editor.getValue();
+                RED.editor.editText({
+                    mode: 'javascript',
+                    value: value,
+                    width: "Infinity",
+                    cursor: that.editor.getCursorPosition(),
+                    complete: function(v, cursor) {
+                        that.editor.setValue(v, -1);
+                        that.editor.gotoLine(cursor.row + 1, cursor.column, false);
+                        setTimeout(function() { that.editor.focus(); }, 300);
+                    }
+                });
+            });
+
+            setTimeout(function() {
+                var nodeId = that.id;
+
+                function refreshKillBtn() {
+                    $.get("node-queue/" + nodeId + "/status", function(data) {
+                        var executing = parseInt(data.executing, 10) || 0;
+                        $("#node-nq-kill-btn").toggleClass("is-executing", executing > 0);
+                    });
+                }
+                refreshKillBtn();
+                var killBtnInterval = setInterval(refreshKillBtn, 1000);
+
+                $("#node-nq-kill-btn").on("click", function(e) {
+                    e.preventDefault();
+                    e.stopPropagation();
+
+                    function doKill() {
+                        $.post("node-queue/" + nodeId + "/kill");
+                        setTimeout(refreshKillBtn, 300);
+                    }
+
+                    $.get("node-queue/" + nodeId + "/status", function(data) {
+                        var executing = parseInt(data.executing, 10) || 0;
+                        var workers   = parseInt(data.workers,   10) || 0;
+                        console.log("[node.queue kill] click — nodeId:", nodeId, "executing:", executing, "workers:", workers);
+                        if (workers > 0) {
+                            var msg = executing > 0
+                                ? "Kill <strong>" + executing + "</strong> running worker" + (executing > 1 ? "s" : "") + "?"
+                                : "Kill idle workers?";
+                            var $dlg = $("<div>")
+                                .html(msg)
+                                .dialog({
+                                    modal: true,
+                                    title: "Kill running workers",
+                                    closeOnEscape: true,
+                                    width: 320,
+                                    buttons: {
+                                        "Cancel": function() { $(this).dialog("close"); },
+                                        "Kill":   function() { $(this).dialog("close"); doKill(); }
+                                    },
+                                    close: function() { $(this).dialog("destroy").remove(); }
+                                });
+                            $dlg.closest(".ui-dialog").css("z-index", 9999);
+                        } else {
+                            doKill();
+                        }
+                    }).fail(function() { doKill(); });
+                });
+
+                that._killBtnInterval = killBtnInterval;
+            }, 0);
+        },
+        oneditsave: function() {
+            this.currentLine = this.editor.getCursorPosition();
+            $("#node-input-template").val(this.editor.getValue());
+            this.editor.destroy();
+            delete this.editor;
+            if (this._killBtnInterval) { clearInterval(this._killBtnInterval); delete this._killBtnInterval; }
+        },
+        oneditcancel: function() {
+            this.editor.destroy();
+            delete this.editor;
+            if (this._killBtnInterval) { clearInterval(this._killBtnInterval); delete this._killBtnInterval; }
+        },
+        oneditresize: function(size) {
+            var rows   = $("#dialog-form>div:not(.node-text-editor-row)");
+            var height = $("#dialog-form").height();
+            for (var i = 0; i < rows.length; i++) {
+                height -= $(rows[i]).outerHeight(true);
+            }
+            var editorRow = $("#dialog-form>div.node-text-editor-row");
+            height -= (parseInt(editorRow.css("marginTop")) + parseInt(editorRow.css("marginBottom")));
+            $(".node-text-editor").css("height", height + "px");
+            this.editor.resize();
+        }
+    });
+</script>