node-red-contrib-influxdb3 1.0.8 → 1.1.0

package/README.md

@@ -64,6 +64,18 @@ Writes data points to InfluxDB v3.
 - **Name**: Optional node name
 - **Measurement**: Default measurement name (can be overridden by `msg.measurement`)
 - **Database**: Optional database override (uses connection default if not set)
+- **Partial writes**: Accept the valid lines of a batch even if other lines are rejected (InfluxDB 3 Core/Enterprise only)
+- **No sync**: Respond without waiting for WAL persistence — faster writes without durability confirmation (InfluxDB 3 Core/Enterprise only)
+
+#### Partial Writes
+
+By default a batch write is all-or-nothing: one invalid line causes InfluxDB to reject the entire batch. With **Partial writes** enabled, InfluxDB writes the valid lines and reports the rejected ones. The node then:
+
+- shows a yellow `partial write` status instead of an error
+- logs a warning listing each rejected line and the reason
+- forwards the message with the details attached as `msg.partialWriteErrors`, an array of `{ lineNumber, errorMessage, originalLine }` objects
+
+Enabling **Partial writes** or **No sync** routes the write through the InfluxDB v3 API endpoint, which is only available on InfluxDB 3 Core and Enterprise. On other deployments (Cloud Serverless/Dedicated, Clustered) leave both options disabled — writes there use the v2-compatible endpoint, where these options are not supported and would cause writes to fail. When **No sync** is enabled without **Partial writes**, the node keeps the all-or-nothing write semantics.
 
 ## Usage
 
@@ -80,6 +92,8 @@ msg.payload = "temperature,location=room1 value=21.5";
 return msg;
 ```
 
+> **Note:** raw line protocol strings are passed through unmodified (each line is only sanity-checked). When data comes from an untrusted source, prefer the object formats below — the node escapes measurement, tag and field values automatically.
+
 #### 2. Object with Fields and Tags
 
 Send an object with explicit `fields` and `tags` properties:
@@ -102,7 +116,7 @@ return msg;
 
 #### 3. Simplified Object Format
 
-Send an object where all properties (except 'tags' and 'timestamp') are treated as fields:
+Send an object where all properties are treated as fields, except the reserved keys `measurement`, `fields`, `tags`, `timestamp` and `integers`:
 
 ```javascript
 msg.measurement = "environment";
@@ -416,7 +430,7 @@ The node will display error status and log details to the Node-RED debug panel:
 
 ## Requirements
 
-- Node.js v18.0.0 or higher
+- Node.js v24.0.0 or higher
 - Node-RED v3.0.0 or higher
 - InfluxDB v3 instance (Cloud or Edge)
 

package/influxdb3.html

@@ -6,7 +6,14 @@
         category: 'config',
         defaults: {
             name: { value: '' },
-            host: { value: '', required: true },
+            host: {
+                value: '',
+                required: true,
+                validate: function(v) {
+                    // Accept http(s) URLs or Node-RED ${ENV_VAR} substitution
+                    return /^https?:\/\/\S+$/.test(v) || /\$\{[^}]+\}/.test(v);
+                }
+            },
             database: { value: '', required: true },
             tlsRejectUnauthorized: { value: true },
             caCertPath: { value: '' }
@@ -79,7 +86,9 @@
             influxdb: { type: 'influxdb3-config', required: true },
             name: { value: '' },
             measurement: { value: '' },
-            database: { value: '' }
+            database: { value: '' },
+            allowPartialWrites: { value: false },
+            noSync: { value: false }
         },
         inputs: 1,
         outputs: 1,
@@ -110,6 +119,16 @@
         <label for="node-input-database"><i class="fa fa-database"></i> Database</label>
         <input type="text" id="node-input-database" placeholder="Override default database (optional)">
     </div>
+    <div class="form-row">
+        <label for="node-input-allowPartialWrites"><i class="fa fa-tasks"></i> Partial writes</label>
+        <input type="checkbox" id="node-input-allowPartialWrites" style="width:auto;">
+        <span>Allow partial writes (InfluxDB 3 Core/Enterprise only)</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-noSync"><i class="fa fa-bolt"></i> No sync</label>
+        <input type="checkbox" id="node-input-noSync" style="width:auto;">
+        <span>Don't wait for WAL persistence (InfluxDB 3 Core/Enterprise only)</span>
+    </div>
 </script>
 
 <script type="text/html" data-help-name="influxdb3-write">
@@ -130,13 +149,17 @@
         <dt class="optional">database <span class="property-type">string</span></dt>
         <dd>Override the database configured in the node or connection</dd>
         <dt class="optional">timestamp <span class="property-type">Date | number</span></dt>
-        <dd>Timestamp for the data point (if not in payload)</dd>
+        <dd>Timestamp for the data point (if not in payload). Numbers are interpreted as <b>milliseconds</b> since the epoch</dd>
     </dl>
 
     <h3>Outputs</h3>
     <dl class="message-properties">
         <dt>payload <span class="property-type">object</span></dt>
         <dd>The original payload is passed through</dd>
+        <dt class="optional">partialWriteErrors <span class="property-type">array</span></dt>
+        <dd>Only set when a partial write occurred (see <b>Partial writes</b> below).
+            An array of <code>{ lineNumber, errorMessage, originalLine }</code> objects
+            describing the lines InfluxDB rejected</dd>
     </dl>
 
     <h3>Details</h3>
@@ -145,6 +168,9 @@
     <h4>Line Protocol Format</h4>
     <p>Send a string in line protocol format:</p>
     <pre>msg.payload = "temperature,location=room1 value=21.5";</pre>
+    <p><b>Note:</b> raw line protocol strings are passed through unmodified. When data comes from
+    an untrusted source, prefer the object format below — the node escapes measurement, tag and
+    field values automatically.</p>
     
     <h4>Object Format</h4>
     <p>Send an object with fields and optionally tags:</p>
@@ -161,7 +187,8 @@
 }</pre>
 
     <h4>Simplified Object Format</h4>
-    <p>Send an object where all properties (except 'tags' and 'timestamp') are treated as fields:</p>
+    <p>Send an object where all properties are treated as fields, except the reserved keys
+    <code>measurement</code>, <code>fields</code>, <code>tags</code>, <code>timestamp</code> and <code>integers</code>:</p>
     <pre>{
   "temperature": 21.5,
   "humidity": 65,
@@ -202,8 +229,26 @@
         <dd>The measurement name to use. Can be overridden by <code>msg.measurement</code></dd>
         <dt>Database</dt>
         <dd>Optional database override. If not set, uses the database from the connection config</dd>
+        <dt>Partial writes</dt>
+        <dd>When enabled, InfluxDB accepts the valid lines of a batch even if other lines
+            are rejected (InfluxDB 3 Core/Enterprise only)</dd>
+        <dt>No sync</dt>
+        <dd>When enabled, InfluxDB responds without waiting for WAL persistence — faster
+            writes but no durability confirmation (InfluxDB 3 Core/Enterprise only)</dd>
     </dl>
 
+    <h3>Partial writes</h3>
+    <p>By default a batch write is all-or-nothing: one invalid line causes InfluxDB to
+    reject the entire batch. With <b>Partial writes</b> enabled, the valid lines are
+    written and the rejected lines are reported: the node shows a yellow
+    <i>partial write</i> status, logs a warning with the per-line errors, and forwards
+    the message with the details in <code>msg.partialWriteErrors</code>.</p>
+    <p>Enabling <b>Partial writes</b> or <b>No sync</b> sends the write through the
+    InfluxDB v3 API endpoint, which is only available on InfluxDB 3 Core and
+    Enterprise. On other deployments (Cloud Serverless/Dedicated, Clustered) leave
+    both options disabled — writes there use the v2-compatible endpoint, where these
+    options are not supported.</p>
+
     <h3>Examples</h3>
     <h4>Example 1: Simple temperature reading</h4>
     <pre>msg.measurement = "temperature";

package/influxdb3.js

@@ -12,10 +12,15 @@ module.exports = function(RED) {
     //   Point.setTag(name, value)
     //   Point.setTimestamp(date)
     //   Point.toLineProtocol()
-    const { InfluxDBClient, Point } = require('@influxdata/influxdb3-client');
+    const { InfluxDBClient, Point, PartialWriteError } = require('@influxdata/influxdb3-client');
     const fs = require('fs');
     const { validateLineProtocol } = require('./lib/line-protocol');
 
+    // Heuristic bounds for plausible millisecond timestamps. Values outside this
+    // range usually mean the source supplied seconds or nanoseconds instead.
+    const MS_TIMESTAMP_PLAUSIBLE_MIN = Date.UTC(2000, 0, 1);
+    const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
     /**
      * Normalize host URL to ensure it has trailing slash
      * @param {string} host
@@ -150,6 +155,10 @@ module.exports = function(RED) {
         this.influxdb = RED.nodes.getNode(config.influxdb);
         this.measurement = config.measurement;
         this.database = config.database;
+        /** @type {boolean} */
+        this.allowPartialWrites = config.allowPartialWrites === true;
+        /** @type {boolean} */
+        this.noSync = config.noSync === true;
 
         const node = this;
         let statusTimeout = null;
@@ -220,7 +229,14 @@ module.exports = function(RED) {
             if (typeof value === 'string') {
                 // Check for integer suffix e.g. "42i"
                 if (/^-?\d+i$/.test(value)) {
-                    point.setIntegerField(key, parseInt(value.slice(0, -1), 10));
+                    const parsed = parseInt(value.slice(0, -1), 10);
+                    if (!Number.isSafeInteger(parsed)) {
+                        node.warn(
+                            `Field '${key}': integer value '${value}' exceeds JavaScript's safe integer ` +
+                            `range and loses precision (stored as ${parsed})${context}.`
+                        );
+                    }
+                    point.setIntegerField(key, parsed);
                     return true;
                 }
                 point.setStringField(key, value);
@@ -337,8 +353,19 @@ module.exports = function(RED) {
                     }
                 }
             } else {
-                // Simplified format: treat all non-reserved properties as fields
-                const reservedKeys = new Set(['tags', 'timestamp', 'integers', 'fields']);
+                if (msg.payload.fields !== null && msg.payload.fields !== undefined) {
+                    const typeName = Array.isArray(msg.payload.fields)
+                        ? 'Array'
+                        : typeof msg.payload.fields;
+                    node.warn(
+                        `'fields' is present but is not a plain object (${typeName}) (measurement: '${measurement}'). ` +
+                        `It will be ignored and the other payload properties will be treated as fields.`
+                    );
+                }
+                // Simplified format: treat all non-reserved properties as fields.
+                // 'measurement' is reserved too so that array items like
+                // { measurement: 'temp', value: 1 } don't write it as a string field.
+                const reservedKeys = new Set(['measurement', 'tags', 'timestamp', 'integers', 'fields']);
                 for (const [key, value] of Object.entries(msg.payload)) {
                     if (!reservedKeys.has(key)) {
                         if (addFieldToPoint(point, key, value, integerFields, measurement)) {
@@ -363,7 +390,27 @@ module.exports = function(RED) {
                 if (ts instanceof Date && !isNaN(ts.getTime())) {
                     point.setTimestamp(ts);
                 } else if (typeof ts === 'number' && isFinite(ts) && ts >= 0) {
-                    point.setTimestamp(new Date(ts));
+                    const date = new Date(ts);
+                    if (isNaN(date.getTime())) {
+                        // Beyond the representable Date range (±8.64e15 ms) — almost
+                        // always a nanosecond timestamp passed where ms are expected.
+                        node.warn(
+                            `Invalid timestamp: ${ts} is outside the representable date range. ` +
+                            `Numeric timestamps are interpreted as milliseconds - if the source ` +
+                            `supplies nanoseconds, convert to milliseconds first. The timestamp ` +
+                            `was ignored; InfluxDB will assign the write time.`
+                        );
+                    } else {
+                        // 0 is deliberately allowed without a warning (explicit epoch).
+                        if (ts !== 0 && (ts < MS_TIMESTAMP_PLAUSIBLE_MIN || ts > Date.now() + ONE_DAY_MS)) {
+                            node.warn(
+                                `Numeric timestamp ${ts} resolves to ${date.toISOString()}. ` +
+                                `Numeric timestamps are interpreted as milliseconds - if the source ` +
+                                `supplies seconds or nanoseconds, convert to milliseconds first.`
+                            );
+                        }
+                        point.setTimestamp(date);
+                    }
                 } else if (typeof ts === 'string' && ts.trim() !== '') {
                     const parsed = new Date(ts);
                     if (!isNaN(parsed.getTime())) {
@@ -385,14 +432,7 @@ module.exports = function(RED) {
             return { lineProtocol: lp };
         }
 
-        // Process incoming messages
         node.on('input', async function(msg, send, done) {
-            // For Node-RED 0.x compatibility
-            send = send || function(m) { node.send(m); };
-            done = done || function(err) {
-                if (err) { node.error(err, msg); }
-            };
-
             try {
                 const client = node.influxdb.getClient();
 
@@ -480,8 +520,29 @@ module.exports = function(RED) {
                     );
                 }
 
+                // Both acceptPartial and noSync exist only on the V3 API endpoint,
+                // so opting into either selects it. With neither enabled, no write
+                // options are passed and the client default (V2 endpoint) is used,
+                // preserving previous behaviour.
+                let writeOptions = null;
+                if (node.allowPartialWrites || node.noSync) {
+                    writeOptions = { useV2Api: false };
+                    if (node.noSync) {
+                        writeOptions.noSync = true;
+                    }
+                    if (!node.allowPartialWrites) {
+                        // noSync without partial writes: keep the all-or-nothing
+                        // semantics the V2 endpoint would have provided.
+                        writeOptions.acceptPartial = false;
+                    }
+                }
+
                 // Write to InfluxDB
-                await client.write(lineProtocol, targetDatabase);
+                if (writeOptions) {
+                    await client.write(lineProtocol, targetDatabase, undefined, writeOptions);
+                } else {
+                    await client.write(lineProtocol, targetDatabase);
+                }
 
                 setStatus({ fill: 'green', shape: 'dot', text: 'written' }, 3000);
 
@@ -489,6 +550,33 @@ module.exports = function(RED) {
                 done();
 
             } catch (error) {
+                // The client raises PartialWriteError both when the server accepted
+                // the valid lines (partial write occurred) and when it rejected the
+                // whole batch (acceptPartial=false). Only the former is a partial
+                // success; the server signals it with this specific error text.
+                if (node.allowPartialWrites &&
+                    error instanceof PartialWriteError &&
+                    typeof error.message === 'string' &&
+                    error.message.toLowerCase().includes('partial write')) {
+                    const lineErrors = error.lineErrors || [];
+                    const detail = lineErrors
+                        .map((le) => `line ${le.lineNumber}: ${le.errorMessage}`)
+                        .join('; ');
+                    node.warn(
+                        `Partial write: InfluxDB rejected ${lineErrors.length} line(s), ` +
+                        `the remaining lines were written. ${detail}`
+                    );
+                    msg.partialWriteErrors = lineErrors;
+                    setStatus({
+                        fill: 'yellow',
+                        shape: 'dot',
+                        text: `partial write: ${lineErrors.length} line(s) rejected`
+                    });
+                    send(msg);
+                    done();
+                    return;
+                }
+
                 const shortMsg = error.message
                     ? (error.message.length > 80 ? error.message.substring(0, 80) + '...' : error.message)
                     : 'unknown error';

package/lib/line-protocol.js

@@ -6,33 +6,52 @@
 
 'use strict';
 
+/**
+ * Truncate a string for use in error messages.
+ * @param {string} str
+ * @returns {string}
+ */
+function preview(str) {
+    return str.length > 100 ? str.substring(0, 100) + '...' : str;
+}
+
 /**
  * Validate that a string looks like InfluxDB line protocol.
+ * Multi-line strings (multiple points separated by newlines) are validated
+ * line by line; blank lines are allowed and skipped.
  * Returns null if valid, or an error message string if invalid.
  * @param {string} lp - Trimmed line protocol string
  * @returns {string|null}
  */
 function validateLineProtocol(lp) {
-    // Detect JSON-like strings (both valid JSON and JS object notation)
+    // Detect JSON-like strings (both valid JSON and JS object notation).
+    // Checked against the whole string first, because pretty-printed JSON
+    // spans multiple lines.
     if (/^\{[\s\S]*}$/.test(lp) || /^\[[\s\S]*]$/.test(lp)) {
-        const preview = lp.length > 100 ? lp.substring(0, 100) + '...' : lp;
         return (
             'The payload appears to be a JSON/object string, not line protocol. ' +
             'If you are sending JSON, ensure msg.payload is a parsed object (not a string). ' +
             'Use a JSON parse node before this node to convert the string to an object. ' +
-            `Received string: ${preview}`
+            `Received string: ${preview(lp)}`
         );
     }
 
-    // Line protocol must have at least: measurement field=value
+    // Each line must have at least: measurement field=value
     // i.e. at least one space and one '=' in the field set
-    if (!lp.includes(' ') || !lp.includes('=')) {
-        const preview = lp.length > 100 ? lp.substring(0, 100) + '...' : lp;
-        return (
-            'The payload string does not appear to be valid line protocol. ' +
-            'Expected format: measurement[,tag=val] field=val[,field=val] [timestamp]. ' +
-            `Received: ${preview}`
-        );
+    const lines = lp.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line) {
+            continue;
+        }
+        if (!line.includes(' ') || !line.includes('=')) {
+            const where = lines.length > 1 ? `Line ${i + 1} of the payload` : 'The payload string';
+            return (
+                `${where} does not appear to be valid line protocol. ` +
+                'Expected format: measurement[,tag=val] field=val[,field=val] [timestamp]. ' +
+                `Received: ${preview(line)}`
+            );
+        }
     }
 
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-influxdb3",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Node-RED nodes for InfluxDB v3 integration",
   "main": "influxdb3.js",
   "files": [
@@ -25,7 +25,7 @@
   "author": "Stuart B",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0"
   },
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
     }
   },
   "dependencies": {
-    "@influxdata/influxdb3-client": "^2.2.0"
+    "@influxdata/influxdb3-client": "^2.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",