@rosepetal/node-red-contrib-utils 1.1.1

package/docs/nodes/util/clean-debug.md

@@ -0,0 +1,58 @@
+# Clean Debug Node
+
+## Purpose & Use Cases
+
+The `clean-debug` node is a drop-in replacement for the core Debug node that keeps the editor sidebar responsive by sanitizing heavy payloads (buffers, images, base64 strings) before display.
+
+**Typical scenarios:**
+- Inspecting image or binary flows without freezing the sidebar
+- Logging large messages safely during development
+- Keeping debug output readable in production flows
+
+## Input/Output Specification
+
+### Inputs
+- **Incoming Message**: Any Node-RED message.
+
+### Outputs
+- **No message output**: The node publishes to the debug sidebar and/or console only.
+
+## Configuration Options
+
+### Output
+- **Type**: Typed input (msg/flow/global/env/jsonata/etc.)
+- **Default**: `msg.payload`
+- **Purpose**: Selects the value to display. Choose the full message object if needed.
+
+### Send to debug sidebar
+- **Type**: Boolean
+- **Default**: Enabled
+- **Purpose**: Shows the sanitized value in the editor sidebar.
+
+### Also log to console
+- **Type**: Boolean
+- **Default**: Disabled
+- **Purpose**: Logs the value to the Node-RED runtime log.
+
+### Clean heavy payloads
+- **Type**: Boolean
+- **Default**: Enabled
+- **Purpose**: Replaces large buffers, typed arrays, data URLs, and long base64 strings with short placeholders.
+
+### Enabled
+- **Type**: Boolean (button toggle)
+- **Purpose**: Temporarily disable the node without removing it from the flow.
+
+## Behavior Notes
+
+- Cleaning only affects what is displayed; the original message is not modified.
+- When cleaning is disabled, the node behaves like the standard Debug node.
+- Large arrays/objects are truncated for safety; circular references are handled gracefully.
+
+## Example
+
+```
+[Image-In] -> [clean-debug: Output=msg.payload, Clean=on]
+```
+
+Use clean mode to inspect image payloads without dumping full binary data.

package/lib/node-utils.js

@@ -0,0 +1,429 @@
+/**
+ * @file Contains generic helper functions for the Node-RED nodes.
+ * This module is pure JavaScript and has no dependency on the RED object.
+ * @author Rosepetal
+ */
+
+const sharp = require('sharp'); // Ensure sharp is installed in your project
+
+
+module.exports = function(RED) {
+  const utils = {};
+
+  // Configuration constants
+  const CONSTANTS = {
+    DEFAULT_JPEG_QUALITY: 90,
+    DEFAULT_ARRAY_POSITION: 0,
+    SUPPORTED_DTYPES: ['uint8'],
+    SUPPORTED_COLOR_SPACES: ['GRAY', 'RGB', 'RGBA', 'BGR', 'BGRA'],
+    CHANNEL_MAP: { 'GRAY': 1, 'RGB': 3, 'RGBA': 4, 'BGR': 3, 'BGRA': 4 }
+  };
+
+  /**
+   * Validates and normalizes an image structure
+   * Supports structure: {data, width, height, channels, colorSpace, dtype}
+   */
+  utils.validateImageStructure = function(image, node) {
+    if (!image) {
+      node.warn("Input is null or undefined");
+      return null;
+    }
+
+    switch (true) {
+      // New Rosepetal bitmap structure
+      case (image.hasOwnProperty('width') &&
+            image.hasOwnProperty('height') &&
+            image.hasOwnProperty('data')):
+
+        // Validate dtype (only uint8 supported for now)
+        if (image.dtype && !CONSTANTS.SUPPORTED_DTYPES.includes(image.dtype)) {
+          node.warn(`Unsupported dtype: ${image.dtype}. Supported values: ${CONSTANTS.SUPPORTED_DTYPES.join(', ')}`);
+          return null;
+        }
+
+        // Infer channels if not provided
+        let channels = image.channels;
+        if (!channels) {
+          const calculatedChannels = image.data.length / (image.width * image.height);
+          if (!Number.isInteger(calculatedChannels)) {
+            node.warn(`Cannot infer channels: data.length (${image.data.length}) is not divisible by width*height (${image.width * image.height})`);
+            return null;
+          }
+          channels = calculatedChannels;
+        }
+
+        // Validate channels is a number
+        if (typeof channels !== 'number') {
+          node.warn(`Channels must be a number, got: ${typeof channels}`);
+          return null;
+        }
+
+        // Validate data length matches dimensions
+        if (image.width * image.height * channels !== image.data.length) {
+          node.warn(`Data length mismatch: expected ${image.width * image.height * channels} bytes (${image.width}x${image.height}x${channels}), got ${image.data.length} bytes`);
+          return null;
+        }
+
+        // Handle colorSpace with defaults
+        let colorSpace = image.colorSpace;
+        if (!colorSpace) {
+          // Default based on channel count
+          switch (channels) {
+            case 1: colorSpace = "GRAY"; break;
+            case 3: colorSpace = "RGB"; break;
+            case 4: colorSpace = "RGBA"; break;
+            default:
+              node.warn(`Cannot determine default colorSpace for ${channels} channels`);
+              return null;
+          }
+        }
+
+        // Validate colorSpace matches channel count
+        if (!CONSTANTS.CHANNEL_MAP.hasOwnProperty(colorSpace)) {
+          node.warn(`Unsupported colorSpace: ${colorSpace}. Supported values: ${CONSTANTS.SUPPORTED_COLOR_SPACES.join(', ')}`);
+          return null;
+        }
+
+        if (CONSTANTS.CHANNEL_MAP[colorSpace] !== channels) {
+          node.warn(`ColorSpace mismatch: ${colorSpace} expects ${CONSTANTS.CHANNEL_MAP[colorSpace]} channels, got ${channels} channels`);
+          return null;
+        }
+
+        // Return normalized structure
+        return {
+          data: image.data,
+          width: image.width,
+          height: image.height,
+          channels: channels,
+          colorSpace: colorSpace,
+          dtype: image.dtype || 'uint8'
+        };
+
+      default:
+        // Not our format? Pass to C++ and let OpenCV handle it
+        return image;
+    }
+  }
+
+  utils.validateSingleImage = function(image, node) {
+    const normalized = utils.validateImageStructure(image, node);
+    return normalized !== null;
+  }
+
+  utils.validateListImage = function(list, node) {
+    if (!list || !Array.isArray(list) || list.length === 0) {
+      node.warn("Input is not a valid image list. Expected a non-empty Array.");
+      return false;
+    }
+    // Validate each item in the list
+    for (const image of list) {
+      if (!utils.validateSingleImage(image, node)) {
+        // The warning message is already sent by validateSingleImage
+        return false;
+      }
+    }
+    return true;
+  }
+
+  utils.resolveDimension = function(node, type, value, msg) {
+    if (!value || String(value).trim() === '') return null;
+    let resolvedValue;
+    if (type === 'msg' || type === 'flow' || type === 'global') {
+        resolvedValue = RED.util.evaluateNodeProperty(value, type, node, msg);
+    } else {
+        resolvedValue = value;
+    }
+    const numericValue = parseFloat(resolvedValue);
+    if (numericValue === undefined || isNaN(numericValue)) {
+        throw new Error(`Value "${resolvedValue}" from property "${value}" is not a valid number.`);
+    }
+    return numericValue;
+  }
+
+  /**
+   * Resolves array position value from various sources (msg, flow, global, or direct value)
+   * @param {Object} node - The Node-RED node instance
+   * @param {string} type - The type of source ('msg', 'flow', 'global', or 'num')
+   * @param {*} value - The value or property path to resolve
+   * @param {Object} msg - The message object for msg property resolution
+   * @returns {number} The resolved array position as a non-negative integer
+   * @throws {Error} If the resolved value is not a valid non-negative integer
+   */
+  utils.resolveArrayPosition = function(node, type, value, msg) {
+    if (value === null || value === undefined || String(value).trim() === '') {
+      return CONSTANTS.DEFAULT_ARRAY_POSITION;
+    }
+    
+    let resolvedValue;
+    if (type === 'msg' || type === 'flow' || type === 'global') {
+      resolvedValue = RED.util.evaluateNodeProperty(value, type, node, msg);
+    } else {
+      resolvedValue = value;
+    }
+    
+    const numericValue = parseInt(resolvedValue);
+    if (numericValue === undefined || isNaN(numericValue) || numericValue < 0) {
+      throw new Error(`Array position "${resolvedValue}" from property "${value}" must be a non-negative integer.`);
+    }
+    
+    return numericValue;
+  }
+
+  utils.rawToJpeg = async function (image, quality = CONSTANTS.DEFAULT_JPEG_QUALITY) {
+    const normalized = utils.validateImageStructure(image, { warn: () => {} });
+    if (!normalized)
+      throw new Error('Invalid raw image object supplied to rawToJpeg');
+
+    const colorSpace = normalized.colorSpace;
+    const channels = normalized.channels;
+    let data = normalized.data;
+
+    // BGR/BGRA → RGB/RGBA for Sharp
+    if (colorSpace === 'BGR' || colorSpace === 'BGRA') {
+      data = Buffer.from(data); // copy so we don't mutate shared memory
+      for (let i = 0; i < data.length; i += channels) {
+        const t = data[i];
+        data[i] = data[i + 2];
+        data[i + 2] = t;
+      }
+    }
+
+    const sh = sharp(data, {
+      raw: { width: normalized.width, height: normalized.height, channels }
+    });
+
+    if (colorSpace === 'GRAY') sh.toColourspace('b-w');
+
+    return sh.jpeg({ quality }).toBuffer();
+  }
+
+  /**
+   * Standardized error handling for all nodes
+   * @param {object} node - Node-RED node instance
+   * @param {Error} error - The error that occurred
+   * @param {object} msg - The message object
+   * @param {function} done - The done callback
+   * @param {string} operation - Optional operation name for context
+   */
+  utils.handleNodeError = function(node, error, msg, done, operation = 'processing') {
+    const errorMessage = error.message || `Unknown error during ${operation}.`;
+    node.error(errorMessage, msg);
+    node.status({ fill: "red", shape: "ring", text: "Error" });
+    if (done) {
+      done(error);
+    }
+  }
+
+  /**
+   * Standardized success status formatting
+   * @param {object} node - Node-RED node instance  
+   * @param {number} count - Number of items processed
+   * @param {number} totalTime - Total processing time in ms
+   * @param {object} timing - Timing breakdown object
+   */
+  utils.setSuccessStatus = function(node, count, totalTime, timing = {}) {
+    const { convertMs = 0, taskMs = 0, encodeMs = 0 } = timing;
+    node.status({
+      fill: 'green',
+      shape: 'dot',
+      text: `OK: ${count} img in ${totalTime.toFixed(2)} ms ` +
+            `(conv ${(convertMs + encodeMs).toFixed(2)} ms | ` +
+            `task ${taskMs.toFixed(2)} ms)`
+    });
+  }
+
+  /**
+   * Debug image display utility for inline node debugging
+   * Converts images to displayable format and returns data URL with format message
+   * @param {object|Buffer} image - Image data (raw image object or encoded buffer)
+   * @param {string} outputFormat - The output format selected ('raw', 'jpg', 'png', 'webp')
+   * @param {number} quality - JPEG quality for raw conversion (default: 90)
+   * @param {object} node - Node-RED node instance for error reporting
+   * @param {boolean} debugEnabled - Whether debugging is enabled
+   * @param {number} debugWidth - Desired width for debug image display (default: 200)
+   * @returns {Promise<object|null>} Debug result object with dataUrl and formatMessage, or null if disabled
+   */
+  utils.debugImageDisplay = async function(image, outputFormat, quality, node, debugEnabled, debugWidth) {
+    if (!debugEnabled) return null;
+    
+    // Validate and set default debug width
+    debugWidth = Math.max(1, parseInt(debugWidth) || 200);
+    
+    try {
+      let imageBuffer, formatMessage;
+      
+      if (outputFormat === 'raw') {
+        // Convert raw image to JPG for display using existing utility
+        imageBuffer = await utils.rawToJpeg(image, quality || CONSTANTS.DEFAULT_JPEG_QUALITY);
+        formatMessage = 'jpg default';
+      } else {
+        // Reuse existing converted buffer
+        imageBuffer = Buffer.isBuffer(image) ? image : image.data;
+        formatMessage = outputFormat; // 'jpg', 'png', 'webp'
+      }
+      
+      if (!Buffer.isBuffer(imageBuffer)) {
+        node.warn('Debug display: Invalid image buffer format');
+        return null;
+      }
+      
+      // Resize image for debug display using Sharp
+      let actualWidth = debugWidth;
+      let actualHeight = debugWidth; // Default fallback
+      try {
+        let sharpInstance = sharp(imageBuffer)
+          .resize(debugWidth, null, {
+            withoutEnlargement: false,
+            fit: 'inside'
+          });
+        
+        // Only convert format if output is raw, otherwise preserve the existing format
+        if (outputFormat === 'raw') {
+          // For raw format, convert to JPEG for display
+          sharpInstance = sharpInstance.jpeg({ quality: quality || 90 });
+          formatMessage = 'jpg default';
+        } else {
+          // For other formats (jpg, png, webp), just resize without format conversion
+          // The C++ backend has already converted to the desired format
+          formatMessage = outputFormat + ' resized';
+        }
+        
+        imageBuffer = await sharpInstance.toBuffer();
+        
+        // Get actual dimensions of resized image
+        const metadata = await sharp(imageBuffer).metadata();
+        actualWidth = metadata.width || debugWidth;
+        actualHeight = metadata.height || debugWidth;
+        
+      } catch (resizeError) {
+        node.warn(`Debug image resize error: ${resizeError.message}`);
+        // Continue with original image if resize fails
+        // Try to get original dimensions as fallback
+        try {
+          const originalMetadata = await sharp(imageBuffer).metadata();
+          actualWidth = originalMetadata.width || debugWidth;
+          actualHeight = originalMetadata.height || debugWidth;
+        } catch (metadataError) {
+          // Use debug width as fallback
+          actualWidth = debugWidth;
+          actualHeight = debugWidth;
+        }
+      }
+      
+      // Convert to base64 for WebSocket transmission
+      const base64 = imageBuffer.toString('base64');
+      const mimeType = formatMessage.replace(' default', '').replace(' resized', '');
+      const dataUrl = `data:image/${mimeType};base64,${base64}`;
+      
+      // Send image to frontend via WebSocket for inline display
+      try {
+        RED.comms.publish("debug-image", {
+          id: node.id,
+          data: base64,
+          format: formatMessage,
+          mimeType: mimeType,
+          size: imageBuffer.length,
+          debugWidth: actualWidth,
+          debugHeight: actualHeight
+        });
+      } catch (wsError) {
+        node.warn(`Debug WebSocket error: ${wsError.message}`);
+        // Continue anyway - status display will still work
+      }
+      
+      return {
+        dataUrl: dataUrl,
+        formatMessage: formatMessage,
+        size: imageBuffer.length
+      };
+      
+    } catch (error) {
+      node.warn(`Debug display error: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Enhanced success status formatting with debug information
+   * @param {object} node - Node-RED node instance  
+   * @param {number} count - Number of items processed
+   * @param {number} totalTime - Total processing time in ms
+   * @param {object} timing - Timing breakdown object
+   * @param {string} debugFormat - Optional debug format message to include in status
+   */
+  utils.setSuccessStatusWithDebug = function(node, count, totalTime, timing = {}, debugFormat = null) {
+    const { convertMs = 0, taskMs = 0, encodeMs = 0 } = timing;
+    let statusText = `OK: ${count} img in ${totalTime.toFixed(2)} ms ` +
+                    `(conv ${(convertMs + encodeMs).toFixed(2)} ms | ` +
+                    `task ${taskMs.toFixed(2)} ms)`;
+    
+    if (debugFormat) {
+      statusText += ` | ${debugFormat}`;
+    }
+    
+    node.status({
+      fill: 'green',
+      shape: 'dot',
+      text: statusText
+    });
+  }
+
+  /**
+   * Normalizes the performance metric key based on the node's display name.
+   * Falls back to the node type when the custom name is missing.
+   * @param {object} node - Node-RED node instance
+   * @returns {string} sanitized key
+   */
+  utils.getPerformanceKey = function(node) {
+    const base = (node && node.name && String(node.name).trim()) ||
+                 (node && node.type) ||
+                 'node';
+    return String(base)
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '') || 'node';
+  }
+
+  /**
+   * Records performance metrics on the outgoing message under
+   * msg.performance.rpimage.{nodeNameKey}.
+   * @param {object} node - Node-RED node instance
+   * @param {object} msg - The message object being emitted
+   * @param {object} timings - Timing breakdown { convertMs, encodeMs, taskMs, conversion, task }
+   * @param {number|null} totalTime - Total processing time in ms
+   */
+  utils.recordPerformanceMetrics = function(node, msg, timings = {}, totalTime = null) {
+    if (!msg || !node) {
+      return;
+    }
+    
+    const key = utils.getPerformanceKey(node);
+    const path = `performance.rpimage.${key}`;
+
+    const convertMs = typeof timings.conversion === 'number'
+      ? timings.conversion
+      : (typeof timings.convertMs === 'number' ? timings.convertMs : 0) +
+        (typeof timings.encodeMs === 'number' ? timings.encodeMs : 0);
+    const taskMs = typeof timings.task === 'number'
+      ? timings.task
+      : (typeof timings.taskMs === 'number' ? timings.taskMs : null);
+    const totalMs = typeof totalTime === 'number'
+      ? totalTime
+      : (typeof timings.total === 'number' ? timings.total : null);
+
+    const payload = {
+      conversion: Number.isFinite(convertMs) ? convertMs : null,
+      task: Number.isFinite(taskMs) ? taskMs : null,
+      total: Number.isFinite(totalMs) ? totalMs : null
+    };
+
+    try {
+      RED.util.setMessageProperty(msg, path, payload, true);
+    } catch (err) {
+      node.warn(`Failed to record performance metrics: ${err.message}`);
+    }
+  }
+
+  return utils;
+}

package/nodes/io/array-in.html

@@ -0,0 +1,110 @@
+<script type="text/javascript">
+    RED.nodes.registerType('rp-array-in', {
+        category: 'RP Utils',
+        color: '#87CEEB',
+        defaults: {
+            name: { value: "" },
+            inputPath: { value: "payload" },
+            inputPathType: { value: "msg" },
+            arrayPositionType: { value: "num" },
+            arrayPositionValue: { value: 0 }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-sign-in",
+        label: function() {
+            if (this.name) return this.name;
+            
+            const posDisplay = this.arrayPositionType === 'num' 
+              ? this.arrayPositionValue 
+              : `${this.arrayPositionType}.${this.arrayPositionValue}`;
+            return `Array In [${posDisplay}]`;
+        },
+        oneditprepare: function() {
+            // Set up TypedInput for input path
+            $("#node-input-inputPath").typedInput({
+                default: 'msg',
+                types: ['msg', 'flow', 'global'],
+                typeField: "#node-input-inputPathType"
+            });
+            
+            // Set up TypedInput for array position
+            $("#node-input-arrayPositionValue").typedInput({
+                default: 'num',
+                types: ['num', 'msg', 'flow', 'global'],
+                typeField: "#node-input-arrayPositionType"
+            });
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="rp-array-in">
+    <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>
+    
+    <hr>
+    
+    <div class="form-row">
+        <label for="node-input-inputPath"><i class="fa fa-sign-in"></i> Input from</label>
+        <input type="text" id="node-input-inputPath" style="width: 70%;">
+        <input type="hidden" id="node-input-inputPathType">
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-arrayPositionValue"><i class="fa fa-sort-numeric-asc"></i> Array Position</label>
+        <input type="text" id="node-input-arrayPositionValue" style="width: 70%;" placeholder="0">
+        <input type="hidden" id="node-input-arrayPositionType">
+    </div>
+    
+    <div class="form-tips">
+        <b>Tip:</b> Array position can be a fixed number (starting from 0) or dynamically resolved from msg, flow, or global context. This determines where this data will be placed in the output array.
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="rp-array-in">
+    <p>Collects data from a specified input path and tags it for ordered array assembly with a position index.</p>
+    
+    <h3>Details</h3>
+    <p>This node is designed to work with the rp-array-out node to create ordered arrays from multiple data sources. It extracts data from the specified input path and tags it with a position index, allowing multiple rp-array-in nodes to feed into a single rp-array-out node for ordered collection.</p>
+    
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Input from <span class="property-type">string</span></dt>
+        <dd>The location to read data from. You can select between <code>msg</code>, <code>flow</code>, or <code>global</code> context. Defaults to <code>msg.payload</code>.</dd>
+        <dt>Array Position <span class="property-type">number | msg | flow | global</span></dt>
+        <dd>The index position (0, 1, 2...) where this data should be placed in the final array. Can be a fixed number or dynamically resolved from message properties, flow context, or global context. Must resolve to a non-negative integer.</dd>
+    </dl>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt>
+        <dd>Input message containing the data to be extracted. The actual data location is determined by the "Input from" property. The payload is only replaced when the input is set to <code>msg.payload</code>; otherwise it is left untouched.</dd>
+    </dl>
+    
+    <h3>Outputs</h3>
+    <p>The node passes through the original message with added metadata for array assembly. When the input path is <code>msg.payload</code> the payload is mirrored; for all other inputs the existing payload is preserved and only the metadata is updated.</p>
+    <dl class="message-properties">
+        <dt>meta.arrayPosition <span class="property-type">number</span></dt>
+        <dd>The configured array position index.</dd>
+        <dt>meta.arrayData <span class="property-type">any</span></dt>
+        <dd>The data extracted from the specified input path.</dd>
+    </dl>
+
+    <h3>Examples</h3>
+    <ul>
+        <li><strong>Basic Array Assembly:</strong> Three rp-array-in nodes with positions 0, 1, 2 feeding into an rp-array-out will create: <code>[data0, data1, data2]</code></li>
+        <li><strong>Dynamic Positioning:</strong> Set array position from <code>msg.index</code> to dynamically determine where data should be placed based on message content</li>
+        <li><strong>Image Collection:</strong> Multiple image-in nodes → rp-array-in nodes (positions 0, 1, 2...) → rp-array-out → transform nodes that support arrays</li>
+        <li><strong>Mixed Data Sources:</strong> Combine data from different context levels (msg, flow, global) into a single ordered array</li>
+        <li><strong>Conditional Assembly:</strong> Use flow variables to set positions based on processing conditions or user preferences</li>
+    </ul>
+
+    <h3>Node Interactions</h3>
+    <p><strong>Works with:</strong> Must be used with rp-array-out node for array assembly. Can receive data from any node that outputs to the specified input path.</p>
+    <p><strong>Best Practice:</strong> Use sequential positions starting from 0, ensure each rp-array-in node connected to the same rp-array-out has a unique position.</p>
+
+    <h3>Error Handling</h3>
+    <p>If the input path contains no data or is invalid, the node will set <code>meta.arrayData</code> to <code>null</code> and display a warning.</p>
+</script>