@bldgblocks/node-red-contrib-control 0.1.4

package/nodes/memory-block.html

@@ -0,0 +1,90 @@
+<!-- UI Template Section -->
+<script type="text/html" data-template-name="memory-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-writePeriod" title="Delay in milliseconds before writing to file (non-negative number from msg, flow, global, or static value). Ignored if Write On Update is enabled."><i class="fa fa-clock-o"></i> File Write Period (ms)</label>
+        <input type="text" id="node-input-writePeriod" placeholder="60000">
+        <input type="hidden" id="node-input-writePeriodType">
+    </div>
+    <div class="form-row">
+        <label for="node-input-transferProperty" title="Property to transfer from stored message to output message"><i class="fa fa-exchange"></i> Transfer Property</label>
+        <input type="text" id="node-input-transferProperty" placeholder="payload">
+    </div>
+    <div class="form-row">
+        <label for="node-input-writeOnUpdate" title="If checked, updates write directly to file without storing in memory. Execute reads from file."><i class="fa fa-save"></i> Write On Update</label>
+        <input type="checkbox" id="node-input-writeOnUpdate" style="width: auto;">
+    </div>
+</script>
+
+<!-- JavaScript Section -->
+<script type="text/javascript">
+    RED.nodes.registerType("memory-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            writePeriod: { value: "60000", validate: function(v) { return RED.validators.number(true)(v) && parseFloat(v) >= 0; } },
+            writePeriodType: { value: "num" },
+            transferProperty: { value: "payload", required: true, validate: RED.validators.regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/) },
+            writeOnUpdate: { value: false }
+        },
+        inputs: 1,
+        outputs: 2,
+        inputLabels: ["input"],
+        outputLabels: ["query", "value"],
+        icon: "font-awesome/fa-database",
+        paletteLabel: "memory",
+        label: function() {
+            return this.name || "memory";
+        },
+        oneditprepare: function() {
+            const periodInput = $("#node-input-writePeriod").typedInput({
+                default: "num",
+                types: ["num", "msg", "flow", "global"],
+                typeField: "#node-input-writePeriodType"
+            });
+            
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="memory-block">
+Stores a message property persistently across reboots and redeployments, with configurable property transfer and optional direct file writes.
+
+### Inputs
+: context (string) : Action (`"update"` to store message property, `"execute"` to output stored property, `"executeWithFallback"` to output stored property or store and output fallback, `"query"` to check stored value existence).
+: [transferProperty] (any) : Property to store (`"update"`, `"executeWithFallback"`) or pass through (no `context`).
+
+### Outputs
+: query : For `context = "query"`; `{ payload; boolean }` (`true` if stored value exists, `false` if none).
+: value : For no `context`; Input `msg` unchanged. For `context = "execute"`; Input `msg` with `transferProperty` from stored message, or `{ payload; null }` if none. For `context = "executeWithFallback"`; Input `msg` with `transferProperty` from stored message, or stores and outputs `msg[transferProperty]`. For `context = "update"`; No output.
+
+### Properties
+: writePeriod (string) : Delay in milliseconds before writing to file (non-negative, from `msg`, `flow`, `global`, or static). Ignored if Write On Update is enabled.
+: writePeriodType (string) : Source of `writePeriod` (`"num"`, `"msg"`, `"flow"`, `"global"`).
+: transferProperty (string) : Property to transfer from stored message to output message (valid JavaScript property name).
+: writeOnUpdate (boolean) : If true, `update` writes directly to file without in-memory storage; `execute` and `executeWithFallback` read from file.
+
+### Details
+Stores a single message property persistently in a JSON file, surviving Node-RED reboots and redeployments. Actions;
+- `msg.context = "update"` Stores `msg[transferProperty]`. If Write On Update is enabled, writes directly to file without in-memory storage; otherwise, stores in memory and context, schedules file write after `writePeriod` (ms, default 60000). No output.
+- `msg.context = "execute"` Outputs input `msg` with `transferProperty` from stored message to Output 2 if available, or `{ payload; null }` if none. Reads from file if Write On Update is enabled, else uses in-memory value. No file write.
+- `msg.context = "executeWithFallback"` Outputs input `msg` with `transferProperty` from stored message to Output 2 if available; if none, stores `msg[transferProperty]`, schedules file write (or writes directly if Write On Update is enabled), and outputs `msg[transferProperty]`.
+- `msg.context = "query"` Outputs `{ payload; true }` to Output 1 if a stored value exists, `{ payload; false }` if none. Checks file existence if Write On Update is enabled. No file write or Output 2 message.
+- No `msg.context` Passes input `msg` unchanged to Output 2, no effect on stored message or file.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/memory-block.js

@@ -0,0 +1,241 @@
+const fs = require("fs").promises;
+const path = require("path");
+const fsSync = require("fs");
+
+module.exports = function(RED) {
+    function MemoryBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            writePeriod: config.writePeriod,
+            writePeriodType: config.writePeriodType,
+            transferProperty: config.transferProperty,
+            writeOnUpdate: config.writeOnUpdate === true,
+            storedMsg: null
+        };
+
+        // File path for persistent storage
+        const filePath = path.join(RED.settings.userDir, `memory-${node.id}.json`);
+
+        let writeTimeout = null;
+        let lastUpdateMsg = null;
+
+        // Load stored message from file
+        async function loadStoredMessage() {
+            try {
+                const data = await fs.readFile(filePath, "utf8");
+                node.runtime.storedMsg = JSON.parse(data);
+                const payloadStr = node.runtime.storedMsg[node.runtime.transferProperty] != null ? String(node.runtime.storedMsg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                node.status({ fill: "green", shape: "dot", text: `loaded: ${payloadStr}` });
+            } catch (err) {
+                if (err.code !== "ENOENT") {
+                    node.status({ fill: "red", shape: "ring", text: "file error" });
+                }
+            }
+        }
+
+        // Read message from file synchronously (for execute and executeWithFallback when writeOnUpdate is true)
+        function readStoredMessageSync() {
+            try {
+                if (fsSync.existsSync(filePath)) {
+                    const data = fsSync.readFileSync(filePath, "utf8");
+                    return JSON.parse(data);
+                }
+                return null;
+            } catch (err) {
+                node.status({ fill: "red", shape: "ring", text: "file read error" });
+                node.error("Failed to read stored message: " + err.message);
+                return null;
+            }
+        }
+
+        // Save message to file
+        async function saveMessage() {
+            if (lastUpdateMsg === null) return;
+            try {
+                await fs.writeFile(filePath, JSON.stringify(lastUpdateMsg));
+                lastUpdateMsg = null;
+            } catch (err) {
+                node.status({ fill: "red", shape: "ring", text: "file error" });
+                node.error("Failed to save message: " + err.message);
+            }
+        }
+
+        // Initialize (load only if writeOnUpdate is false)
+        if (!node.runtime.writeOnUpdate) {
+            loadStoredMessage().catch(err => {
+                node.error("Failed to load stored message: " + err.message);
+            });
+        }
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Resolve typed inputs
+            node.runtime.writePeriod = RED.util.evaluateNodeProperty(
+                config.writePeriod, config.writePeriodType, node, msg
+            );
+            node.runtime.writePeriod = parseFloat(node.runtime.writePeriod);
+
+            // Initialize output array: [Output 1, Output 2]
+            const output = [null, null];
+
+            // Handle context
+            if (!msg.hasOwnProperty("context") || !msg.context || typeof msg.context !== "string") {
+                // Pass-through message to Output 2
+                const payloadStr = msg[node.runtime.transferProperty] != null ? String(msg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                node.status({ fill: "blue", shape: "dot", text: `in: ${payloadStr}, out2: ${payloadStr}` });
+                output[1] = msg;
+                send(output);
+                if (done) done();
+                return;
+            }
+
+            if (msg.context === "update") {
+                if (!msg.hasOwnProperty(node.runtime.transferProperty)) {
+                    node.status({ fill: "red", shape: "ring", text: `missing ${node.runtime.transferProperty}` });
+                    if (done) done();
+                    return;
+                }
+                const payloadStr = msg[node.runtime.transferProperty] != null ? String(msg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                if (node.runtime.writeOnUpdate) {
+                    // Write directly to file, do not store in memory
+                    try {
+                        fs.writeFile(filePath, JSON.stringify(msg)).catch(err => {
+                            node.status({ fill: "red", shape: "ring", text: "file error" });
+                            node.error("Failed to save message: " + err.message);
+                        });
+                        node.status({ fill: "green", shape: "dot", text: `updated: ${payloadStr}` });
+                    } catch (err) {
+                        node.status({ fill: "red", shape: "ring", text: "file error" });
+                        node.error("Failed to save message: " + err.message);
+                    }
+                } else {
+                    // Original behavior: store in memory and context, delay write
+                    node.runtime.storedMsg = RED.util.cloneMessage(msg);
+                    node.context().set("storedMsg", node.runtime.storedMsg);
+                    lastUpdateMsg = node.runtime.storedMsg;
+                    node.status({ fill: "green", shape: "dot", text: `updated: ${payloadStr}` });
+                    if (writeTimeout) clearTimeout(writeTimeout);
+                    writeTimeout = setTimeout(() => {
+                        saveMessage();
+                    }, writePeriod);
+                }
+                if (done) done();
+                return;
+            }
+
+            if (msg.context === "execute") {
+                let storedMsg = node.runtime.writeOnUpdate ? readStoredMessageSync() : node.runtime.storedMsg;
+                if (storedMsg !== null) {
+                    const outMsg = RED.util.cloneMessage(msg);
+                    outMsg[node.runtime.transferProperty] = storedMsg[node.runtime.transferProperty];
+                    const payloadStr = outMsg[node.runtime.transferProperty] != null ? String(outMsg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                    node.status({ fill: "blue", shape: "dot", text: `in: execute, out2: ${payloadStr}` });
+                    output[1] = outMsg;
+                } else {
+                    node.status({ fill: "blue", shape: "ring", text: `in: execute, out2: null` });
+                    output[1] = { payload: null };
+                }
+                send(output);
+                if (done) done();
+                return;
+            }
+
+            if (msg.context === "executeWithFallback") {
+                let storedMsg = node.runtime.writeOnUpdate ? readStoredMessageSync() : node.runtime.storedMsg;
+                if (storedMsg !== null) {
+                    const outMsg = RED.util.cloneMessage(msg);
+                    outMsg[node.runtime.transferProperty] = storedMsg[node.runtime.transferProperty];
+                    const payloadStr = outMsg[node.runtime.transferProperty] != null ? String(outMsg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                    node.status({ fill: "blue", shape: "dot", text: `in: executeWithFallback, out2: ${payloadStr}` });
+                    output[1] = outMsg;
+                } else {
+                    let value;
+                    if (msg.hasOwnProperty(node.runtime.transferProperty)) {
+                        value = msg[node.runtime.transferProperty];
+                    }
+                    else if (msg.hasOwnProperty("fallback")) {
+                        value = msg.fallback;
+                    } else {
+                        node.status({ fill: "red", shape: "ring", text: `missing ${node.runtime.transferProperty}` });
+                        if (done) done();
+                        return;
+                    }
+                    
+                    if (node.runtime.writeOnUpdate) {
+                        // Write directly to file
+                        try {
+                            fs.writeFile(filePath, JSON.stringify({ [node.runtime.transferProperty]: value })).catch(err => {
+                                node.status({ fill: "red", shape: "ring", text: "file error" });
+                                node.error("Failed to save message: " + err.message);
+                            });
+                        } catch (err) {
+                            node.status({ fill: "red", shape: "ring", text: "file error" });
+                            node.error("Failed to save message: " + err.message);
+                        }
+                    } else {
+                        // Store in memory and context
+                        node.runtime.storedMsg = { [node.runtime.transferProperty]: value };
+                        node.context().set("storedMsg", node.runtime.storedMsg);
+                        lastUpdateMsg = node.runtime.storedMsg;
+                        if (writeTimeout) clearTimeout(writeTimeout);
+                        writeTimeout = setTimeout(() => {
+                            saveMessage();
+                        }, writePeriod);
+                    }
+                    const outMsg = RED.util.cloneMessage(msg);
+                    outMsg[node.runtime.transferProperty] = value;
+                    const payloadStr = msg[node.runtime.transferProperty] != null ? String(msg[node.runtime.transferProperty]).substring(0, 20) : "null";
+                    node.status({ fill: "blue", shape: "dot", text: `in: executeWithFallback, out2: ${payloadStr}` });
+                    output[1] = outMsg;
+                }
+                send(output);
+                if (done) done();
+                return;
+            }
+
+            if (msg.context === "query") {
+                const hasValue = node.runtime.writeOnUpdate ? fsSync.existsSync(filePath) : node.runtime.storedMsg !== null;
+                node.status({ fill: "blue", shape: "dot", text: `in: query, out1: ${hasValue}` });
+                output[0] = { payload: hasValue };
+                send(output);
+                if (done) done();
+                return;
+            }
+
+            node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+            if (done) done("Unknown context");
+        });
+
+        node.on("close", function(done) {
+            if (writeTimeout) clearTimeout(writeTimeout);
+            if (!node.runtime.writeOnUpdate && lastUpdateMsg) {
+                saveMessage()
+                    .then(() => {
+                        node.status({});
+                        done();
+                    })
+                    .catch(err => {
+                        node.error("Failed to save message on close: " + err.message);
+                        node.status({});
+                        done();
+                    });
+            } else {
+                done();
+            }
+        });
+    }
+
+    RED.nodes.registerType("memory-block", MemoryBlockNode);
+};

package/nodes/min-block.html

@@ -0,0 +1,77 @@
+<!-- UI Template Section: Defines the edit dialog -->
+<script type="text/html" data-template-name="min-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-min" title="Minimum value for capping the input number"><i class="fa fa-arrow-down"></i> Min</label>
+        <input type="text" id="node-input-min" placeholder="50" min="0" step="any">
+        <input type="hidden" id="node-input-minType">
+    </div>
+</script>
+
+<!-- JavaScript Section: Registers the node and handles editor logic -->
+<script type="text/javascript">
+    RED.nodes.registerType("min-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            min: { value: 50, required: true },
+            minType: { value: "num" },
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["output"],
+        icon: "font-awesome/fa-arrow-circle-down",
+        paletteLabel: "min",
+        label: function() {
+            return this.name || "min";
+        },
+        oneditprepare: function() {
+            const node = this;
+            
+            // Initialize typed inputs
+            $("#node-input-min").typedInput({
+                default: "num",
+                types: ["num", "msg", "flow", "global"],
+                typeField: "#node-input-minType"
+            }).typedInput("type", node.minType || "num").typedInput("value", node.min);
+            
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="min-block">
+Ensures a numeric input is at least a configurable minimum value.
+
+### Inputs
+: context (string) : Configures minimum value (`"min"`, `"setpoint"`). Unmatched values trigger warning.
+: payload (number) : Input number to cap or new minimum value with `msg.context`.
+
+### Outputs
+: payload (number) : Input number capped at the minimum value.
+: *other* (any) : All input properties preserved, including `msg.context`.
+
+### Properties
+: min (number) : Minimum value for capping.
+
+### Details
+Ensures `msg.payload` (a number) is at least the minimum value, forwarding the input message with updated `msg.payload`. 
+
+Outputs on every valid input, with status indicating whether the output changed.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/min-block.js

@@ -0,0 +1,106 @@
+module.exports = function(RED) {
+    function MinBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+        };
+
+        // Store last output value for status
+        let lastOutput = null;
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Evaluate typed-inputs
+            try {
+                node.runtime.min = RED.util.evaluateNodeProperty(
+                    config.min, config.minType, node, msg
+                );
+                
+                // Validate values
+                if (isNaN(node.runtime.min)) {
+                    node.status({ fill: "red", shape: "ring", text: "invalid evaluated values" });
+                    if (done) done();
+                    return;
+                }
+            } catch(err) {
+                node.status({ fill: "red", shape: "ring", text: "error evaluating properties" });
+                if (done) done(err);
+                return;
+            }
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Handle context updates
+            if (msg.hasOwnProperty("context")) {
+                if (!msg.hasOwnProperty("payload")) {
+                    node.status({ fill: "red", shape: "ring", text: "missing payload for min" });
+                    if (done) done();
+                    return;
+                }
+                if (msg.context === "min" || msg.context === "setpoint") {
+                    const minValue = parseFloat(msg.payload);
+                    if (!isNaN(minValue) && minValue >= 0) {
+                        node.runtime.min = minValue;
+                        node.status({
+                            fill: "green",
+                            shape: "dot",
+                            text: `min: ${minValue}`
+                        });
+                    } else {
+                        node.status({ fill: "red", shape: "ring", text: "invalid min" });
+                    }
+                    if (done) done();
+                    return;
+                } else {
+                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    if (done) done();
+                    return;
+                }
+            }
+
+            // Validate input payload
+            if (!msg.hasOwnProperty("payload")) {
+                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                if (done) done();
+                return;
+            }
+
+            const inputValue = parseFloat(msg.payload);
+            if (isNaN(inputValue)) {
+                node.status({ fill: "red", shape: "ring", text: "invalid payload" });
+                if (done) done();
+                return;
+            }
+
+            // Cap input at min
+            const outputValue = Math.max(inputValue, node.runtime.min);
+
+            // Update status and send output
+            msg.payload = outputValue;
+            node.status({
+                fill: "blue",
+                shape: lastOutput === outputValue ? "ring" : "dot",
+                text: `in: ${inputValue.toFixed(2)}, out: ${outputValue.toFixed(2)}`
+            });
+            lastOutput = outputValue;
+            send(msg);
+
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+
+    RED.nodes.registerType("min-block", MinBlockNode);
+};

package/nodes/minmax-block.html

@@ -0,0 +1,89 @@
+<!-- UI Template Section: Defines the edit dialog -->
+<script type="text/html" data-template-name="minmax-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-min" title="Minimum value for clamping the input number"><i class="fa fa-arrow-down"></i> Min</label>
+        <input type="text" id="node-input-min" placeholder="0" min="0" step="any">
+        <input type="hidden" id="node-input-minType">
+    </div>
+    <div class="form-row">
+        <label for="node-input-max" title="Maximum value for clamping the input number"><i class="fa fa-arrow-up"></i> Max</label>
+        <input type="text" id="node-input-max" placeholder="100" min="0" step="any">
+        <input type="hidden" id="node-input-maxType">
+    </div>
+</script>
+
+<!-- JavaScript Section: Registers the node and handles editor logic -->
+<script type="text/javascript">
+    RED.nodes.registerType("minmax-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            min: { value: 0, required: true },
+            max: { value: 100, required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["output"],
+        icon: "font-awesome/fa-arrows-v",
+        paletteLabel: "minmax",
+        label: function() {
+            return this.name || "minmax";
+        },
+        oneditprepare: function() {
+            const node = this;
+            
+            // Initialize typed inputs
+            $("#node-input-min").typedInput({
+                default: "num",
+                types: ["num", "msg", "flow", "global"],
+                typeField: "#node-input-minType"
+            }).typedInput("type", node.minType || "num").typedInput("value", node.min);
+
+            $("#node-input-max").typedInput({
+                default: "num",
+                types: ["num", "msg", "flow", "global"],
+                typeField: "#node-input-maxType"
+            }).typedInput("type", node.maxType || "num").typedInput("value", node.max);
+
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="minmax-block">
+Clamps a numeric input to a configurable range.
+
+### Inputs
+: context (string) : Configures range (`"min"`, `"max"`). Unmatched values trigger warning.
+: payload (number) : Input number to clamp or new min/max value with `msg.context`.
+
+### Outputs
+: payload (number) : Input number clamped to `[min, max]`.
+: *other* (any) : All input properties preserved, including `msg.context`.
+
+### Properties
+: min (number) : Minimum value for clamping (≥ 0).
+: max (number) : Maximum value for clamping (≥ 0, ≥ min)..
+
+### Details
+Clamps `msg.payload` (a number) to the range `[min, max]`, forwarding the input message with updated `msg.payload`. 
+
+Ensures `min ≤ max` by adjusting the other value if needed (e.g., setting `min > max` sets `max = min`). 
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>