@rosepetal/node-red-contrib-utils 1.1.1

package/nodes/io/save-file.html

@@ -0,0 +1,243 @@
+<script type="text/javascript">
+    RED.nodes.registerType('rp-save-file', {
+        category: 'RP Utils',
+        color: '#87CEEB',
+        defaults: {
+            name: { value: "" },
+            inputPath: { value: "payload" },
+            inputPathType: { value: "msg" },
+            folderPath: { value: "", required: true },
+            folderPathType: { value: "str" },
+            filename: { value: "" },
+            filenameType: { value: "str" },
+            fileType: { value: "auto" },
+            imageFormat: { value: "jpg" },
+            imageQuality: { value: 90 },
+            pngOptimize: { value: false },
+            jsonIndent: { value: 2 },
+            overwriteProtection: { value: "true" },
+            outputPath: { value: "savedFile" },
+            outputPathType: { value: "msg" }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-save",
+        label: function () {
+            return this.name || "Save File";
+        },
+        oneditprepare: function () {
+            const jsonataTypeOption = {
+                value: 'jsonata',
+                label: 'JSONata',
+                icon: 'red/images/typedInput/expr.svg'
+            };
+
+            $("#node-input-inputPath").typedInput({
+                default: 'msg',
+                types: ['msg', 'flow', 'global'],
+                typeField: "#node-input-inputPathType"
+            });
+
+            $("#node-input-folderPath").typedInput({
+                default: 'str',
+                types: ['str', 'env', 'msg', 'flow', 'global'],
+                typeField: "#node-input-folderPathType"
+            });
+
+            const filenameTypes = ['str', 'msg', 'flow', 'global', jsonataTypeOption];
+
+            $("#node-input-filename").typedInput({
+                default: 'str',
+                types: filenameTypes,
+                typeField: "#node-input-filenameType"
+            });
+
+            $("#node-input-outputPath").typedInput({
+                default: 'msg',
+                types: ['msg', 'flow', 'global'],
+                typeField: "#node-input-outputPathType"
+            });
+
+            const fileTypeField = $("#node-input-fileType");
+            const imageFormatField = $("#node-input-imageFormat");
+            const imageFields = $(".savefile-image-options");
+            const jsonFields = $(".savefile-json-options");
+            const pngOnlyFields = $(".savefile-png-only");
+            const qualityFields = $(".savefile-quality");
+            const imageSeparators = $(".savefile-image-separator");
+            const jsonSeparators = $(".savefile-json-separator");
+            const autoSeparators = $(".savefile-auto-separator");
+
+            function toggleFields() {
+                const current = fileTypeField.val();
+                imageFields.toggle(current === 'image' || current === 'auto');
+                jsonFields.toggle(current === 'json' || current === 'auto');
+                toggleImageFormatFields();
+                toggleSeparators();
+            }
+
+            function toggleImageFormatFields() {
+                const fmt = imageFormatField.val();
+                const showImage = fileTypeField.val() === 'image' || fileTypeField.val() === 'auto';
+                pngOnlyFields.toggle(showImage && fmt === 'png');
+                qualityFields.toggle(showImage && fmt !== 'png');
+            }
+
+            function toggleSeparators() {
+                const ft = fileTypeField.val();
+                const showImageSep = ft === 'image';
+                const showJsonSep = ft === 'json';
+                const showAutoSep = ft === 'auto';
+                imageSeparators.toggle(showImageSep);
+                jsonSeparators.toggle(showJsonSep);
+                autoSeparators.toggle(showAutoSep);
+            }
+
+            fileTypeField.on("change", toggleFields);
+            imageFormatField.on("change", toggleImageFormatFields);
+            toggleFields();
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="rp-save-file">
+    <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>
+
+    <div class="form-row">
+        <label for="node-input-inputPath"><i class="fa fa-sign-in"></i> Input</label>
+        <input type="text" id="node-input-inputPath" style="width: 70%;">
+        <input type="hidden" id="node-input-inputPathType">
+    </div>
+    <div class="form-tips">
+        <b>Input:</b> Location of the data to save. Defaults to <code>msg.payload</code>.
+    </div>
+
+    <hr>
+
+    <div class="form-row">
+        <label for="node-input-folderPath"><i class="fa fa-folder-open"></i> Folder</label>
+        <input type="text" id="node-input-folderPath" style="width: 70%;" placeholder="/tmp/output">
+        <input type="hidden" id="node-input-folderPathType">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-filename"><i class="fa fa-file-text-o"></i> Filename</label>
+        <input type="text" id="node-input-filename" style="width: 70%;" placeholder="optional (auto timestamp)">
+        <input type="hidden" id="node-input-filenameType">
+    </div>
+    <div class="form-tips">
+        <b>Filename:</b> Leave blank to auto-generate; omit slashes. Extension is added automatically unless you provide one.
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-fileType"><i class="fa fa-list"></i> File Type</label>
+        <select id="node-input-fileType">
+            <option value="auto">Auto-detect</option>
+            <option value="image">Image</option>
+            <option value="json">JSON</option>
+            <option value="text">Text</option>
+            <option value="binary">Binary</option>
+        </select>
+    </div>
+
+    <div class="form-row savefile-auto-separator">
+        <hr>
+    </div>
+
+    <div class="form-row savefile-image-options savefile-separator savefile-image-separator">
+        <hr>
+    </div>
+    <div class="form-row savefile-image-options">
+        <label for="node-input-imageFormat"><i class="fa fa-picture-o"></i> Image Format</label>
+        <select id="node-input-imageFormat">
+            <option value="jpg">JPG</option>
+            <option value="png">PNG</option>
+            <option value="webp">WebP</option>
+        </select>
+    </div>
+
+    <div class="form-row savefile-image-options savefile-quality">
+        <label for="node-input-imageQuality"><i class="fa fa-sliders"></i> Quality</label>
+        <input type="number" id="node-input-imageQuality" min="1" max="100" step="1" style="width: 30%;" placeholder="90">
+    </div>
+    <div class="form-row savefile-image-options savefile-png-only">
+        <label for="node-input-pngOptimize"><i class="fa fa-leaf"></i> PNG Options</label>
+        <label style="margin-left: 0; width: auto;">
+            <input type="checkbox" id="node-input-pngOptimize" style="margin-right: 5px;"> Optimize PNG
+        </label>
+    </div>
+    <div class="form-row savefile-image-options savefile-separator savefile-image-separator">
+        <hr>
+    </div>
+
+    <div class="form-row savefile-json-options savefile-separator savefile-json-separator">
+        <hr>
+    </div>
+    <div class="form-row savefile-json-options">
+        <label for="node-input-jsonIndent"><i class="fa fa-indent"></i> JSON Indent</label>
+        <input type="number" id="node-input-jsonIndent" min="0" max="8" step="1" style="width: 30%;" placeholder="2">
+    </div>
+    <div class="form-row savefile-json-options savefile-separator savefile-json-separator">
+        <hr>
+    </div>
+
+    <div class="form-row savefile-auto-separator">
+        <hr>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-overwriteProtection"><i class="fa fa-shield"></i> Overwrite</label>
+        <select id="node-input-overwriteProtection">
+            <option value="true">Avoid overwriting (add suffix)</option>
+            <option value="false">Allow overwrite</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-outputPath"><i class="fa fa-sign-out"></i> Result to</label>
+        <input type="text" id="node-input-outputPath" style="width: 70%;">
+        <input type="hidden" id="node-input-outputPathType">
+    </div>
+    <div class="form-tips">
+        <b>Result:</b> Stores <code>{path, filename, type, extension, sizeBytes[, format]}</code> for downstream nodes. Defaults to <code>msg.savedFile</code>.
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="rp-save-file">
+    <p>Writes incoming data to the local filesystem. Supports raw image objects, encoded image buffers, JSON values, plain text, or arbitrary binary content.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload (default) <span class="property-type">any</span></dt>
+        <dd>Data to write. Auto-detection treats raw image objects and encoded image buffers as images; objects/arrays as JSON; strings as text; buffers as binary.</dd>
+    </dl>
+
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Folder <span class="property-type">string | env | msg | flow | global</span></dt>
+        <dd>Destination directory. Created automatically if missing.</dd>
+        <dt>Filename <span class="property-type">string | msg | flow | global</span></dt>
+        <dd>Optional name without slashes. When blank, a timestamped name is generated. If you include an extension here it is used.</dd>
+        <dt>File Type <span class="property-type">enum</span></dt>
+        <dd>Force saving as image, JSON, text, or binary, or let the node auto-detect from data/extension.</dd>
+        <dt>Image Format / Quality / Optimize PNG <span class="property-type">enum/number/bool</span></dt>
+        <dd>Applies when saving images. Raw image objects are validated and encoded with Sharp.</dd>
+        <dt>JSON Indent <span class="property-type">number</span></dt>
+        <dd>Spacing for pretty-printed JSON output.</dd>
+        <dt>Overwrite <span class="property-type">enum</span></dt>
+        <dd>By default the node avoids overwriting existing files, appending a numeric suffix when needed.</dd>
+        <dt>Result to <span class="property-type">msg | flow | global</span></dt>
+        <dd>Where to store a summary of the saved file: <code>{ path, filename, type, extension, sizeBytes, format? }</code>.</dd>
+    </dl>
+
+    <h3>Behavior</h3>
+    <ul>
+        <li>Auto-detect looks at configured extension, raw image structure, or Sharp metadata for buffers.</li>
+        <li>Image inputs accept encoded buffers or raw objects {data, width, height, channels, colorSpace}.</li>
+        <li>JSON inputs are pretty-printed; JSON strings are preserved if already valid.</li>
+        <li>When overwrite protection is enabled, a numeric suffix is appended if the target file exists.</li>
+    </ul>
+</script>

package/nodes/io/save-file.js

@@ -0,0 +1,440 @@
+/**
+ * @file Generic filesystem sink that can write JSON, images, text, or binary data.
+ * Designed to accept raw image objects, encoded buffers, or plain JS values.
+ */
+const fs = require('fs').promises;
+const path = require('path');
+const sharp = require('sharp');
+const JSON_WARN_BYTES = 5 * 1024 * 1024; // warn when JSON output is larger than 5MB
+
+module.exports = function (RED) {
+  const NodeUtils = require('../../lib/node-utils.js')(RED);
+
+  function SaveFileNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const diskWarnState = { logged: false };
+
+    node.on('input', async (msg, send, done) => {
+      const started = Date.now();
+      node.status({ fill: 'blue', shape: 'dot', text: 'saving...' });
+
+      try {
+        const evaluateProperty = (value, type, fallback = 'str') =>
+          new Promise((resolve, reject) => {
+            const actualType = type || fallback;
+            try {
+              RED.util.evaluateNodeProperty(value, actualType, node, msg, (err, res) => {
+                if (err) reject(err);
+                else resolve(res);
+              });
+            } catch (err) {
+              reject(err);
+            }
+          });
+
+        // Resolve paths and inputs
+        const folderPathType = config.folderPathType || 'str';
+        const folderPathValue = await evaluateProperty(config.folderPath, folderPathType);
+        const folderPath = String(folderPathValue ?? '').trim();
+        if (!folderPath) {
+          throw new Error('Folder path is not configured or resolved.');
+        }
+        await fs.mkdir(folderPath, { recursive: true });
+
+        const inputPath = config.inputPath || 'payload';
+        const inputPathType = config.inputPathType || 'msg';
+        let incoming;
+        if (inputPathType === 'msg') {
+          incoming = RED.util.getMessageProperty(msg, inputPath);
+        } else if (inputPathType === 'flow') {
+          incoming = node.context().flow.get(inputPath);
+        } else if (inputPathType === 'global') {
+          incoming = node.context().global.get(inputPath);
+        }
+        if (incoming === undefined) {
+          throw new Error('No data found at configured input path.');
+        }
+
+        // Resolve file name
+        const filenameType = config.filenameType || 'str';
+        const filenameValue = await evaluateProperty(config.filename, filenameType);
+        const filenameRaw = filenameValue !== undefined && filenameValue !== null
+          ? String(filenameValue).trim()
+          : '';
+        if (/[\\/]/.test(filenameRaw)) {
+          throw new Error('Filename must not contain path separators.');
+        }
+        const parsedName = path.parse(filenameRaw);
+        let baseName = parsedName.name || '';
+        let extFromName = parsedName.ext ? parsedName.ext.replace(/^\./, '') : '';
+
+        // Determine file type and format
+        const configType = String(config.fileType || 'auto').toLowerCase();
+        let imageFormat = String(config.imageFormat || 'jpg').toLowerCase();
+        const extInfo = mapExtension(extFromName);
+
+        let fileType = configType;
+        if (fileType === 'auto' && extInfo?.type) {
+          fileType = extInfo.type;
+          if (extInfo.format) {
+            imageFormat = extInfo.format;
+          }
+        }
+
+        const inferred = fileType === 'auto'
+          ? await inferFileType(incoming, extInfo)
+          : { type: fileType, format: imageFormat };
+
+        fileType = inferred.type;
+        if (fileType === 'image' && inferred.format) {
+          imageFormat = inferred.format;
+        }
+        if (fileType === 'image' && extInfo?.format) {
+          imageFormat = extInfo.format;
+        }
+
+        if (!['image', 'json', 'text', 'binary'].includes(fileType)) {
+          throw new Error(`Unsupported file type: ${fileType}`);
+        }
+
+        // Finalize extension and name
+        let extension = extFromName || defaultExtension(fileType, imageFormat);
+        if (!extension) {
+          throw new Error('Unable to determine file extension.');
+        }
+        if (!baseName) {
+          baseName = defaultBaseName(fileType);
+        }
+        let filename = `${baseName}.${extension}`;
+        const originalFilename = filename;
+        let filePath = path.join(folderPath, filename);
+
+        const overwriteEnabled = String(config.overwriteProtection) !== 'false';
+        if (overwriteEnabled) {
+          let counter = 2;
+          while (await fileExists(filePath)) {
+            filename = `${baseName}_${counter}.${extension}`;
+            filePath = path.join(folderPath, filename);
+            counter += 1;
+            if (counter > 1000) {
+              throw new Error('Too many file variations exist in target folder.');
+            }
+          }
+        }
+
+        // Check disk space (skip if 90%+ used)
+        const diskInfo = await getDiskUsageInfo(folderPath, node, diskWarnState);
+        if (diskInfo && diskInfo.usedRatio >= 0.9) {
+          const usedPercent = (diskInfo.usedRatio * 100).toFixed(1);
+          node.warn(`Storage at "${folderPath}" is ${usedPercent}% full. Skipping save to avoid exhausting disk space.`);
+          node.status({ fill: 'yellow', shape: 'ring', text: `disk ${usedPercent}% full` });
+          done && done();
+          return;
+        }
+
+        // Prepare data to write
+        const quality = parseInt(config.imageQuality, 10) || 90;
+        const pngOptimize = config.pngOptimize === true || config.pngOptimize === 'true';
+        const jsonIndent = Number.isInteger(parseInt(config.jsonIndent, 10))
+          ? parseInt(config.jsonIndent, 10)
+          : 2;
+
+        let payloadToWrite;
+        let isText = false;
+
+        if (fileType === 'image') {
+          payloadToWrite = await toImageBuffer(incoming, imageFormat, quality, pngOptimize, NodeUtils, node);
+        } else if (fileType === 'json') {
+          if (typeof incoming === 'string') {
+            try {
+              // Keep valid JSON strings as-is
+              JSON.parse(incoming);
+              payloadToWrite = incoming;
+            } catch {
+              payloadToWrite = JSON.stringify(incoming, null, jsonIndent);
+            }
+          } else {
+            payloadToWrite = JSON.stringify(incoming, null, jsonIndent);
+          }
+          isText = true;
+        } else if (fileType === 'text') {
+          payloadToWrite = incoming === undefined || incoming === null ? '' : String(incoming);
+          isText = true;
+        } else {
+          payloadToWrite = await toBinary(incoming);
+        }
+
+        if (isText) {
+          await fs.writeFile(filePath, payloadToWrite, 'utf8');
+        } else {
+          await fs.writeFile(filePath, payloadToWrite);
+        }
+
+        const sizeBytes = isText
+          ? Buffer.byteLength(payloadToWrite, 'utf8')
+          : payloadToWrite.length;
+
+        if (fileType === 'json' && sizeBytes >= JSON_WARN_BYTES) {
+          const sizeMB = (sizeBytes / (1024 * 1024)).toFixed(1);
+          node.warn(`JSON output is large (${sizeMB} MB); this may impact the event loop and memory usage.`);
+        }
+
+        const resultInfo = {
+          path: filePath,
+          filename,
+          type: fileType,
+          extension,
+          sizeBytes
+        };
+        if (fileType === 'image') {
+          resultInfo.format = imageFormat;
+        }
+
+        // Optionally attach result info for downstream nodes
+        const outputPath = config.outputPath || 'savedFile';
+        const outputPathType = config.outputPathType || 'msg';
+        try {
+          if (outputPathType === 'msg') {
+            RED.util.setMessageProperty(msg, outputPath, resultInfo, true);
+          } else if (outputPathType === 'flow') {
+            node.context().flow.set(outputPath, resultInfo);
+          } else if (outputPathType === 'global') {
+            node.context().global.set(outputPath, resultInfo);
+          }
+        } catch (setErr) {
+          node.warn(`Unable to store output metadata: ${setErr.message}`);
+        }
+
+        const elapsed = Date.now() - started;
+        const renameOccurred = overwriteEnabled && filename !== originalFilename;
+        const statusSuffix = renameOccurred ? ' (avoided overwrite)' : '';
+        node.status({
+          fill: 'green',
+          shape: 'dot',
+          text: `saved ${filename}${statusSuffix} (${elapsed}ms)`
+        });
+
+        // Record basic performance metric for consistency across nodes
+        NodeUtils.recordPerformanceMetrics(node, msg, { taskMs: elapsed }, elapsed);
+
+        send(msg);
+        done && done();
+      } catch (err) {
+        node.status({ fill: 'red', shape: 'ring', text: 'Error' });
+        node.error(err.message, msg);
+        done && done(err);
+      }
+    });
+  }
+
+  RED.nodes.registerType('rp-save-file', SaveFileNode);
+};
+
+// Helpers
+function mapExtension(ext) {
+  if (!ext) return null;
+  const lower = ext.toLowerCase();
+  if (lower === 'jpg' || lower === 'jpeg') return { type: 'image', format: 'jpg' };
+  if (lower === 'png') return { type: 'image', format: 'png' };
+  if (lower === 'webp') return { type: 'image', format: 'webp' };
+  if (lower === 'json') return { type: 'json' };
+  if (lower === 'txt') return { type: 'text' };
+  if (lower === 'bin' || lower === 'dat') return { type: 'binary' };
+  return null;
+}
+
+function defaultExtension(type, imageFormat) {
+  if (type === 'image') return imageFormat || 'jpg';
+  if (type === 'json') return 'json';
+  if (type === 'text') return 'txt';
+  if (type === 'binary') return 'bin';
+  return '';
+}
+
+function defaultBaseName(type) {
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}Z$/, 'Z')
+    .replace('T', '_');
+  switch (type) {
+    case 'image': return `image_${timestamp}`;
+    case 'json': return `data_${timestamp}`;
+    case 'text': return `text_${timestamp}`;
+    default: return `file_${timestamp}`;
+  }
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function inferFileType(value, extInfo) {
+  if (extInfo?.type) {
+    return { type: extInfo.type, format: extInfo.format };
+  }
+
+  if (value && typeof value === 'object') {
+    if (Buffer.isBuffer(value)) {
+      try {
+        const meta = await sharp(value).metadata();
+        if (meta?.format) {
+          const fmt = normalizeSharpFormat(meta.format);
+          if (fmt) return { type: 'image', format: fmt };
+        }
+      } catch {
+        // Not an image buffer
+      }
+      return { type: 'binary' };
+    }
+
+    if (isRawImageLike(value)) {
+      return { type: 'image' };
+    }
+
+    return { type: 'json' };
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      return { type: 'json' };
+    }
+    return { type: 'text' };
+  }
+
+  return { type: 'binary' };
+}
+
+function normalizeSharpFormat(fmt) {
+  if (!fmt) return null;
+  if (fmt === 'jpeg' || fmt === 'jpg') return 'jpg';
+  if (fmt === 'png') return 'png';
+  if (fmt === 'webp') return 'webp';
+  return null;
+}
+
+function isRawImageLike(obj) {
+  return obj &&
+    typeof obj === 'object' &&
+    !Buffer.isBuffer(obj) &&
+    Object.prototype.hasOwnProperty.call(obj, 'data') &&
+    Object.prototype.hasOwnProperty.call(obj, 'width') &&
+    Object.prototype.hasOwnProperty.call(obj, 'height');
+}
+
+async function toBinary(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value && typeof value === 'object' && Buffer.isBuffer(value.data)) {
+    return Buffer.from(value.data);
+  }
+  if (typeof value === 'string') {
+    return Buffer.from(value, 'utf8');
+  }
+  return Buffer.from(JSON.stringify(value ?? ''), 'utf8');
+}
+
+async function toImageBuffer(imageValue, format, quality, pngOptimize, NodeUtils, node) {
+  // Encoded buffer path
+  if (Buffer.isBuffer(imageValue) && !(imageValue.width && imageValue.height)) {
+    let inputFormat;
+    try {
+      const metadata = await sharp(imageValue).metadata();
+      inputFormat = metadata.format;
+    } catch {
+      inputFormat = null;
+    }
+
+    if (inputFormat && (normalizeSharpFormat(inputFormat) === format)) {
+      return imageValue;
+    }
+
+    const sharpInstance = sharp(imageValue);
+    return encodeSharp(sharpInstance, format, quality, pngOptimize);
+  }
+
+  // Raw image path (uses validator for clear errors)
+  const validated = NodeUtils.validateImageStructure(imageValue, node);
+  if (!validated) {
+    throw new Error('Invalid image structure.');
+  }
+
+  const colorSpace = validated.colorSpace;
+  const channels = validated.channels;
+  let data = validated.data;
+
+  if (colorSpace === 'BGR' || colorSpace === 'BGRA') {
+    data = Buffer.from(data);
+    for (let i = 0; i < data.length; i += channels) {
+      const t = data[i];
+      data[i] = data[i + 2];
+      data[i + 2] = t;
+    }
+  }
+
+  let sharpInstance = sharp(data, {
+    raw: {
+      width: validated.width,
+      height: validated.height,
+      channels: channels
+    }
+  });
+
+  if (colorSpace === 'GRAY') {
+    sharpInstance = sharpInstance.toColourspace('b-w');
+  }
+
+  return encodeSharp(sharpInstance, format, quality, pngOptimize);
+}
+
+function encodeSharp(sharpInstance, format, quality, pngOptimize) {
+  if (format === 'png') {
+    const pngOptions = pngOptimize
+      ? { compressionLevel: 9, palette: true }
+      : { compressionLevel: 6 };
+    return sharpInstance.png(pngOptions).toBuffer();
+  }
+  if (format === 'webp') {
+    return sharpInstance.webp({ quality }).toBuffer();
+  }
+  return sharpInstance.jpeg({ quality }).toBuffer();
+}
+
+async function getDiskUsageInfo(targetPath, node, warnState) {
+  try {
+    const stats = await fs.statfs(targetPath);
+    const blockSize = Number(stats.bsize) || 0;
+    const totalBlocks = Number(stats.blocks) || 0;
+    const availableBlocks = Number(
+      stats.bavail !== undefined ? stats.bavail :
+      stats.bfree !== undefined ? stats.bfree : 0
+    );
+
+    const totalBytes = totalBlocks * blockSize;
+    const availableBytes = availableBlocks * blockSize;
+
+    if (totalBytes <= 0) {
+      return null;
+    }
+
+    const usedRatio = 1 - (availableBytes / totalBytes);
+    return {
+      totalBytes,
+      availableBytes,
+      usedRatio
+    };
+  } catch (err) {
+    if (!warnState.logged) {
+      node.warn(`Disk usage check failed for "${targetPath}": ${err.message}`);
+      warnState.logged = true;
+    }
+    return null;
+  }
+}