@rosepetal/node-red-contrib-async-function 1.0.0

package/nodes/async-function.html

@@ -0,0 +1,600 @@
+<!-- Async Function Node - Node-RED Editor Configuration -->
+
+<script type="text/javascript">
+    RED.nodes.registerType('async-function', {
+        category: 'function',
+        color: '#d7d9dc',
+        defaults: {
+            name: { value: '' },
+            func: {
+                value: '// Write your async code here\n// The code runs in a worker thread\n// Available: msg, return, async/await, require()\n// Not available: context, flow, global, node\n\nreturn msg;'
+            },
+            outputs: { value: 1, validate: RED.validators.number() },
+            timeout: { value: 30000, validate: RED.validators.number() },
+            numWorkers: { value: 3, validate: RED.validators.number() },
+            maxQueueSize: { value: 100, validate: RED.validators.number() },
+            libs: { value: [] },
+            noerr: { value: 0 }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'function.svg',
+        label: function() {
+            return this.name || 'async function';
+        },
+        labelStyle: function() {
+            return this.name ? 'node_label_italic' : '';
+        },
+        oneditprepare: function() {
+            const node = this;
+
+            // Create tabs system
+            const tabs = RED.tabs.create({
+                id: "async-func-tabs",
+                onchange: function(tab) {
+                    // Hide all tabs
+                    $("#async-func-tabs-content").children().hide();
+                    // Show selected tab
+                    $("#" + tab.id).show();
+
+                    // Handle editor focus for Function tab
+                    if (tab.id === "async-func-tab-function") {
+                        const editor = $("#" + tab.id).find('.node-text-editor').first();
+                        if (editor.length && node.editor) {
+                            RED.tray.resize();
+                            node.editor.focus();
+                        }
+                    }
+                }
+            });
+
+            // Add tabs
+            tabs.addTab({
+                id: "async-func-tab-setup",
+                iconClass: "fa fa-cog",
+                label: "Setup"
+            });
+
+            tabs.addTab({
+                id: "async-func-tab-function",
+                label: "Function"
+            });
+
+            // Activate Function tab by default
+            tabs.activateTab("async-func-tab-function");
+
+            // Build extraLibs for Monaco editor (format: [{var, module}])
+            var extraLibs = (this.libs || []).map(function(lib) {
+                return { var: lib.var, module: lib.module };
+            });
+
+            // Setup editor with extraLibs for Monaco IntelliSense
+            this.editor = RED.editor.createEditor({
+                id: 'node-input-func-editor',
+                mode: 'ace/mode/nrjavascript',
+                value: $('#node-input-func').val(),
+                globals: {
+                    msg: true,
+                    require: true,
+                    console: true,
+                    setTimeout: true,
+                    clearTimeout: true,
+                    setInterval: true,
+                    clearInterval: true,
+                    Buffer: true,
+                    process: true
+                },
+                extraLibs: extraLibs
+            });
+
+            // Refresh Monaco module libs after editor is ready
+            var that = this;
+            if (extraLibs.length > 0) {
+                setTimeout(function() {
+                    if (that.editor && that.editor.nodered && that.editor.nodered.refreshModuleLibs) {
+                        that.editor.nodered.refreshModuleLibs(extraLibs);
+                    }
+                }, 200);
+            }
+
+            // Setup outputs spinner
+            $('#node-input-outputs').spinner({
+                min: 0,
+                max: 10
+            });
+
+            // Setup timeout input
+            $('#node-input-timeout').spinner({
+                min: 1000,
+                max: 300000,
+                step: 1000
+            });
+
+            // Setup worker pool spinners
+            $('#node-input-numWorkers').spinner({ min: 1, max: 16 });
+            $('#node-input-maxQueueSize').spinner({ min: 10, max: 1000, step: 10 });
+
+            // Setup modules editable list
+            $('#node-input-libs-container').css('min-height','120px').editableList({
+                addButton: true,
+                removable: true,
+                sortable: false,
+                header: $('<div class="async-func-libs-header"><div>Module</div><div>Import as</div></div>'),
+                addItem: function(container, i, opt) {
+                    var row = $('<div class="async-func-libs-entry"/>').appendTo(container);
+                    $('<input/>', {
+                        class: 'node-input-libs-module',
+                        type: 'text',
+                        placeholder: 'e.g. lodash'
+                    }).val(opt.module || '').appendTo(row);
+                    $('<input/>', {
+                        class: 'node-input-libs-var',
+                        type: 'text',
+                        placeholder: 'e.g. _'
+                    }).val(opt.var || '').appendTo(row);
+
+                    // Auto-generate variable name from module name
+                    row.find('.node-input-libs-module').on('change keyup', function() {
+                        var varInput = row.find('.node-input-libs-var');
+                        if (!varInput.val()) {
+                            var moduleName = $(this).val().trim();
+                            // Generate variable name: strip scope, replace dashes/dots with camelCase
+                            var varName = moduleName
+                                .replace(/^@[^/]+\//, '')  // Remove npm scope
+                                .replace(/[-_.]/g, ' ')
+                                .replace(/\s+(.)/g, function(m, c) { return c.toUpperCase(); })
+                                .replace(/\s/g, '');
+                            varInput.val(varName);
+                            varInput.trigger('change');
+                        }
+                    }).on('change', function() {
+                        // Update editor modules when module name changes
+                        if (typeof updateEditorModules === 'function') {
+                            updateEditorModules();
+                        }
+                    });
+
+                    // Validate variable name is a valid JS identifier and update editor
+                    row.find('.node-input-libs-var').on('change keyup', function() {
+                        var val = $(this).val().trim();
+                        var isValid = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(val);
+                        var reserved = ['msg', 'require', 'console', 'setTimeout', 'setInterval',
+                                       'clearTimeout', 'clearInterval', 'Buffer', 'process'];
+                        if (reserved.indexOf(val) !== -1) {
+                            isValid = false;
+                        }
+                        if (val && !isValid) {
+                            $(this).addClass('input-error');
+                        } else {
+                            $(this).removeClass('input-error');
+                        }
+                    }).on('change', function() {
+                        // Update editor modules when variable name changes
+                        if (typeof updateEditorModules === 'function') {
+                            updateEditorModules();
+                        }
+                    });
+                }
+            });
+
+            // Populate existing libs
+            if (this.libs && this.libs.length > 0) {
+                var libsList = this.libs;
+                for (var i = 0; i < libsList.length; i++) {
+                    $('#node-input-libs-container').editableList('addItem', libsList[i]);
+                }
+            }
+
+            // Get current libs list from editableList
+            function getLibsList() {
+                var libs = [];
+                $('#node-input-libs-container').editableList('items').each(function() {
+                    var moduleName = $(this).find('.node-input-libs-module').val().trim();
+                    var varName = $(this).find('.node-input-libs-var').val().trim();
+                    if (moduleName && varName) {
+                        libs.push({ var: varName, module: moduleName });
+                    }
+                });
+                return libs;
+            }
+
+            // Update editor when modules change (supports both Monaco and ACE)
+            function updateEditorModules() {
+                if (node.editor) {
+                    var libs = getLibsList();
+
+                    // For Monaco editor: use refreshModuleLibs
+                    if (node.editor.nodered && node.editor.nodered.refreshModuleLibs) {
+                        node.editor.nodered.refreshModuleLibs(libs);
+                    }
+
+                    // For ACE editor: update globals
+                    if (node.editor.session && node.editor.session.$worker) {
+                        var globals = {
+                            msg: true,
+                            require: true,
+                            console: true,
+                            setTimeout: true,
+                            clearTimeout: true,
+                            setInterval: true,
+                            clearInterval: true,
+                            Buffer: true,
+                            process: true
+                        };
+                        libs.forEach(function(lib) {
+                            if (lib.var) {
+                                globals[lib.var] = true;
+                            }
+                        });
+                        node.editor.session.$worker.send("setOptions", [{
+                            globals: globals,
+                            maxerr: 1000
+                        }]);
+                    }
+                }
+            }
+
+            // Hook into editableList add/remove events and variable name changes
+            $('#node-input-libs-container').on('editablelistitemadd editablelistitemremove', updateEditorModules);
+            // Ensure configured module vars are registered in the editor on load
+            updateEditorModules();
+
+            // Resize editor on dialog resize
+            $('#dialog-form').on('dialogresize', function() {
+                const rows = $('#dialog-form>div:not(#async-func-tabs-content)');
+                let height = $('#dialog-form').height();
+                for (let i = 0; i < rows.length; i++) {
+                    height -= $(rows[i]).outerHeight(true);
+                }
+                height -= 20; // Tab container margin adjustment
+
+                // Calculate editor height (only in Function tab)
+                const editorRow = $('#async-func-tab-function .node-text-editor-row');
+                const editorMargins = parseInt(editorRow.css('marginTop')) +
+                                     parseInt(editorRow.css('marginBottom'));
+
+                // Subtract Function tab's non-editor rows
+                const functionTabRows = $('#async-func-tab-function>div:not(.node-text-editor-row)');
+                let editorHeight = height;
+                for (let i = 0; i < functionTabRows.length; i++) {
+                    editorHeight -= $(functionTabRows[i]).outerHeight(true);
+                }
+                editorHeight -= editorMargins;
+
+                $('.node-text-editor').css('height', editorHeight + 'px');
+                node.editor.resize();
+            });
+        },
+        oneditsave: function() {
+            // Save editor content
+            $('#node-input-func').val(this.editor.getValue());
+            this.editor.destroy();
+            delete this.editor;
+
+            // Save libs
+            var libs = [];
+            $('#node-input-libs-container').editableList('items').each(function() {
+                var module = $(this).find('.node-input-libs-module').val().trim();
+                var varName = $(this).find('.node-input-libs-var').val().trim();
+                if (module && varName) {
+                    libs.push({ module: module, var: varName });
+                }
+            });
+            this.libs = libs;
+        },
+        oneditcancel: function() {
+            this.editor.destroy();
+            delete this.editor;
+        },
+        oneditresize: function(size) {
+            // Calculate available height excluding non-tab rows
+            const rows = $('#dialog-form>div:not(#async-func-tabs-content)');
+            let height = size.height;
+
+            for (let i = 0; i < rows.length; i++) {
+                height -= $(rows[i]).outerHeight(true);
+            }
+
+            height -= 20; // Tab container margin adjustment
+
+            // Calculate editor height (only in Function tab)
+            const editorRow = $('#async-func-tab-function .node-text-editor-row');
+            const editorMargins = parseInt(editorRow.css('marginTop')) +
+                                 parseInt(editorRow.css('marginBottom'));
+
+            // Subtract Function tab's non-editor rows
+            const functionTabRows = $('#async-func-tab-function>div:not(.node-text-editor-row)');
+            let editorHeight = height;
+            for (let i = 0; i < functionTabRows.length; i++) {
+                editorHeight -= $(functionTabRows[i]).outerHeight(true);
+            }
+            editorHeight -= editorMargins;
+
+            $('.node-text-editor').css('height', editorHeight + 'px');
+
+            if (this.editor) {
+                this.editor.resize();
+            }
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="async-function">
+    <style>
+        .async-func-tabs-row {
+            margin-bottom: 0;
+        }
+        .async-func-section {
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            padding: 10px 15px;
+            margin-bottom: 15px;
+            background: #fafafa;
+        }
+        .async-func-section-header {
+            font-weight: 500;
+            margin-bottom: 10px;
+            color: #333;
+            border-bottom: 1px solid #eee;
+            padding-bottom: 5px;
+        }
+        .async-func-section .form-row {
+            margin-bottom: 8px;
+        }
+        .async-func-section .form-row:last-child {
+            margin-bottom: 0;
+        }
+        /* Modules editableList styles */
+        #node-input-libs-container {
+            min-height: 120px;
+        }
+        #node-input-libs-container .red-ui-editableList-header,
+        .async-func-libs-header {
+            display: flex;
+            gap: 10px;
+            padding: 6px 8px;
+            font-weight: 500;
+            color: #666;
+            background: var(--red-ui-tertiary-background, #f7f7f7);
+            border-bottom: 1px solid #ddd;
+            padding-right: 35px; /* Space for delete button column */
+        }
+        #node-input-libs-container .red-ui-editableList-header > div,
+        .async-func-libs-header > div {
+            flex: 1;
+        }
+        #node-input-libs-container .red-ui-editableList-container {
+            padding: 0;
+        }
+        #node-input-libs-container .red-ui-editableList-item-content {
+            padding: 4px 0;
+        }
+        .async-func-libs-entry {
+            display: flex;
+            gap: 10px;
+            align-items: center;
+        }
+        .async-func-libs-entry input {
+            flex: 1;
+        }
+        .async-func-libs-entry input.input-error {
+            border-color: #d9534f;
+            background-color: #fff5f5;
+        }
+    </style>
+
+    <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>
+
+    <!-- Tab Navigation Row -->
+    <div class="form-row async-func-tabs-row">
+        <ul style="min-width: 600px; margin-bottom: 20px;" id="async-func-tabs"></ul>
+    </div>
+
+    <!-- Tab Content Container -->
+    <div id="async-func-tabs-content" style="min-height: calc(100% - 95px);">
+
+        <!-- Setup Tab -->
+        <div id="async-func-tab-setup" style="display:none">
+            <!-- Behavior Section -->
+            <div class="async-func-section">
+                <div class="async-func-section-header">
+                    <i class="fa fa-sliders"></i> Behavior
+                </div>
+                <div class="form-row">
+                    <label for="node-input-outputs"><i class="fa fa-random"></i> Outputs</label>
+                    <input id="node-input-outputs" style="width:60px;" value="1">
+                </div>
+                <div class="form-row">
+                    <label for="node-input-timeout"><i class="fa fa-clock-o"></i> Timeout</label>
+                    <input id="node-input-timeout" style="width:120px;" value="30000">
+                    <span style="margin-left:5px;">ms</span>
+                </div>
+            </div>
+
+            <!-- Worker Pool Section -->
+            <div class="async-func-section">
+                <div class="async-func-section-header">
+                    <i class="fa fa-cogs"></i> Worker Pool
+                </div>
+                <div class="form-row">
+                    <label for="node-input-numWorkers">Workers</label>
+                    <input type="number" id="node-input-numWorkers" style="width: 80px;" min="1" max="16" value="3">
+                    <span style="margin-left: 10px; color: #999;">Fixed worker count (1-16)</span>
+                </div>
+                <div class="form-row">
+                    <label for="node-input-maxQueueSize">Queue Size</label>
+                    <input type="number" id="node-input-maxQueueSize" style="width: 80px;" min="10" max="1000" step="10" value="100">
+                    <span style="margin-left: 10px; color: #999;">Max queued messages</span>
+                </div>
+            </div>
+
+            <!-- Modules Section -->
+            <div class="async-func-section">
+                <div class="async-func-section-header">
+                    <i class="fa fa-cubes"></i> Modules
+                </div>
+                <div class="form-row" style="margin-bottom: 0;">
+                    <ol id="node-input-libs-container"></ol>
+                </div>
+            </div>
+        </div>
+
+        <!-- Function Tab -->
+        <div id="async-func-tab-function" style="display:none">
+            <div class="form-row" style="margin-bottom:0;">
+                <label for="node-input-func"><i class="fa fa-wrench"></i> Function</label>
+                <input type="hidden" id="node-input-func">
+            </div>
+
+            <div class="form-row node-text-editor-row">
+                <div style="height:250px; min-height:150px;" class="node-text-editor" id="node-input-func-editor"></div>
+            </div>
+
+            <div class="form-tips">
+                <b>Tips:</b>
+                <ul style="margin-top:5px; margin-bottom:0;">
+                    <li>Code runs in a worker thread to prevent blocking</li>
+                    <li>Available: <code>msg</code>, <code>return</code>, <code>async/await</code>, <code>require()</code></li>
+                    <li>Not available: <code>context</code>, <code>flow</code>, <code>global</code>, <code>node</code></li>
+                    <li>Return <code>msg</code> for single output, or <code>[msg1, msg2]</code> for multiple outputs</li>
+                    <li>Return <code>null</code> to stop the flow</li>
+                </ul>
+            </div>
+        </div>
+
+    </div>
+</script>
+
+<script type="text/html" data-help-name="async-function">
+    <p>Execute custom JavaScript code in a worker thread to prevent event loop blocking.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt>
+        <dd>The message payload to process</dd>
+        <dt class="optional">topic <span class="property-type">string</span></dt>
+        <dd>The message topic</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt>
+        <dd>The processed message payload</dd>
+    </dl>
+
+    <h3>Details</h3>
+    <p>This node executes JavaScript code in a worker thread, preventing CPU-intensive operations
+    from blocking the Node-RED event loop.</p>
+
+    <h4>Available in Code</h4>
+    <ul>
+        <li><code>msg</code> - The incoming message object</li>
+        <li><code>return</code> - Return modified message or array of messages</li>
+        <li><code>async/await</code> - Use async operations</li>
+        <li><code>require()</code> - Import Node.js modules</li>
+        <li><code>console</code> - Logging functions</li>
+        <li><code>setTimeout</code>, <code>setInterval</code> - Timers</li>
+    </ul>
+
+    <h4>Not Available</h4>
+    <ul>
+        <li><code>context</code>, <code>flow</code>, <code>global</code> - Context storage (v2.0 feature)</li>
+        <li><code>node</code> - Node instance methods</li>
+        <li>Non-serializable objects in <code>msg</code></li>
+    </ul>
+
+    <h4>Example: Simple Transformation</h4>
+    <pre>msg.payload = msg.payload * 2;
+return msg;</pre>
+
+    <h4>Example: Async Operation</h4>
+    <pre>const crypto = require('crypto');
+
+msg.hash = crypto.createHash('sha256')
+    .update(msg.payload)
+    .digest('hex');
+
+return msg;</pre>
+
+    <h4>Example: Multiple Outputs</h4>
+    <pre>if (msg.payload > 100) {
+    return [msg, null];  // Send to first output
+} else {
+    return [null, msg];  // Send to second output
+}</pre>
+
+    <h4>Example: CPU-Intensive Task</h4>
+    <pre>// Calculate prime numbers (won't block Node-RED!)
+function isPrime(n) {
+    if (n <= 1) return false;
+    for (let i = 2; i * i <= n; i++) {
+        if (n % i === 0) return false;
+    }
+    return true;
+}
+
+const limit = msg.payload;
+const primes = [];
+
+for (let i = 2; i <= limit; i++) {
+    if (isPrime(i)) {
+        primes.push(i);
+    }
+}
+
+msg.payload = primes;
+return msg;</pre>
+
+    <h3>Configuration</h3>
+    <dl class="message-properties">
+        <dt>Outputs</dt>
+        <dd>Number of output ports (0-10). Use array return for multiple outputs.</dd>
+        <dt>Timeout</dt>
+        <dd>Maximum execution time in milliseconds (1000-300000). Worker is terminated if exceeded. Default: 30000 (30s).</dd>
+        <dt>Workers</dt>
+        <dd>Fixed number of worker threads (1-16). Each node maintains exactly this many workers. Default: 3.</dd>
+        <dt>Queue Size</dt>
+        <dd>Maximum number of messages queued when all workers are busy (10-1000). Default: 100.</dd>
+        <dt>Buffers</dt>
+        <dd>All Buffers are transferred via shared memory when possible (falls back to base64 if needed).</dd>
+    </dl>
+
+    <h3>Status Display</h3>
+    <p>The node status shows real-time worker pool statistics:</p>
+    <ul>
+        <li><b>Active: X/Y</b> - X workers currently processing out of Y total workers</li>
+        <li><b>Queue: Z</b> - Z messages waiting in queue</li>
+        <li><b>SHM: N</b> - N shared memory files active (shown only when >0, indicates large buffers being processed)</li>
+        <li><b>Green dot</b> - Normal operation</li>
+        <li><b>Yellow dot</b> - Queue getting full (>50 messages)</li>
+        <li><b>Red dot</b> - Queue almost full (>90%) or error</li>
+        <li><b>Ring</b> - All workers busy with queued messages</li>
+    </ul>
+
+    <h3>Error Handling</h3>
+    <p>Errors in your code will be caught and sent to a Catch node if configured:</p>
+    <pre>if (!msg.payload) {
+    throw new Error('Payload is required');
+}</pre>
+
+    <h3>Performance Notes</h3>
+    <ul>
+        <li>Worker threads add ~5-10ms overhead per message</li>
+        <li>Best for CPU-intensive operations (>10ms execution time)</li>
+        <li>For simple operations, use the standard function node</li>
+        <li>Workers are pooled and reused for efficiency</li>
+        <li><b>Buffer Transfer:</b> Buffers are streamed through shared memory (base64 fallback)</li>
+        <li>Event loop never blocks, even when processing multi-MB binary data (images, files, etc.)</li>
+        <li>Message transfer is optimized by copying only referenced <code>msg.*</code> keys when possible</li>
+        <li>Timing is recorded on <code>msg.performance</code> under the node label</li>
+    </ul>
+
+    <h3>References</h3>
+    <ul>
+        <li><a href="https://nodejs.org/api/worker_threads.html" target="_blank">Node.js Worker Threads</a></li>
+        <li><a href="https://nodered.org/docs/user-guide/writing-functions" target="_blank">Node-RED Function Nodes</a></li>
+    </ul>
+</script>