snowpipe-streaming 1.6.1 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snowpipe-streaming",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Snowflake Streaming Ingest SDK for Node.js",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -27,11 +27,11 @@
     "typedoc": "^0.28.19"
   },
   "optionalDependencies": {
-    "snowpipe-streaming-linux-x64-gnu": "1.6.1",
-    "snowpipe-streaming-linux-x64-musl": "1.6.1",
-    "snowpipe-streaming-linux-arm64-gnu": "1.6.1",
-    "snowpipe-streaming-linux-arm64-musl": "1.6.1",
-    "snowpipe-streaming-darwin-arm64": "1.6.1",
-    "snowpipe-streaming-win32-x64-msvc": "1.6.1"
+    "snowpipe-streaming-linux-x64-gnu": "1.7.0",
+    "snowpipe-streaming-linux-x64-musl": "1.7.0",
+    "snowpipe-streaming-linux-arm64-gnu": "1.7.0",
+    "snowpipe-streaming-linux-arm64-musl": "1.7.0",
+    "snowpipe-streaming-darwin-arm64": "1.7.0",
+    "snowpipe-streaming-win32-x64-msvc": "1.7.0"
   }
 }

package/src/channel.js

@@ -17,6 +17,7 @@
 
 const { callFFI, StreamingIngestError } = require("./errors.js");
 const { ChannelStatus } = require("./channel_status.js");
+const { serializeRowsToNdjson } = require("./row_serializer.js");
 
 const WAIT_FOR_COMMIT_CHECK_INTERVAL_MS = 1000;
 
@@ -71,35 +72,6 @@ class StreamingIngestChannel {
     return this._native.binaryInputFormat;
   }
 
-  /**
-   * Convert Buffer/Uint8Array values in a row according to binaryInputFormat.
-   * For HEX, binary values become hex-encoded strings.
-   * For UTF-8, binary values are decoded as UTF-8 strings.
-   * Only top-level values are converted; nested structures are left as-is.
-   * @param {Object} row - Row object
-   * @returns {Object} Row with binary values converted
-   * @private
-   */
-  _convertBytesInRow(row) {
-    const result = {};
-    for (const [key, value] of Object.entries(row)) {
-      if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
-        const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
-        if (this.binaryInputFormat === "HEX") {
-          result[key] = buf.toString("hex");
-        } else if (this.binaryInputFormat === "UTF-8") {
-          result[key] = buf.toString("utf8");
-        } else {
-          // BASE64: convert to base64 string for JSON serialization
-          result[key] = buf.toString("base64");
-        }
-      } else {
-        result[key] = value;
-      }
-    }
-    return result;
-  }
-
   /**
    * Append a single row. Convenience wrapper for appendRows.
    * @param {Object} row - Row data as key-value pairs
@@ -108,6 +80,9 @@ class StreamingIngestChannel {
    * @throws {StreamingIngestError} If the row appending fails
    */
   appendRow(row, offsetToken) {
+    if (row == null) {
+      throw new TypeError("row must not be null");
+    }
     this.appendRows([row], offsetToken, offsetToken);
   }
 
@@ -122,17 +97,15 @@ class StreamingIngestChannel {
    * @throws {StreamingIngestError} If the rows appending fails
    */
   appendRows(rows, startOffsetToken, endOffsetToken) {
+    if (rows == null) {
+      throw new TypeError("rows must not be null");
+    }
     if (!Array.isArray(rows)) {
       throw new TypeError("rows must be an array");
     }
     // Empty arrays are handled by the Rust core, which returns a proper InvalidRequest error.
     const buffer =
-      rows.length === 0
-        ? Buffer.alloc(0)
-        : Buffer.from(
-            rows.map((r) => JSON.stringify(this._convertBytesInRow(r))).join("\n"),
-            "utf8",
-          );
+      rows.length === 0 ? Buffer.alloc(0) : serializeRowsToNdjson(rows, this.binaryInputFormat);
     try {
       this._native.appendRows(buffer, rows.length, startOffsetToken, endOffsetToken);
     } catch (e) {

package/src/client.js

@@ -18,6 +18,8 @@
 const { callFFI, StreamingIngestError } = require("./errors.js");
 const { ChannelStatus } = require("./channel_status.js");
 const { StreamingIngestChannel } = require("./channel.js");
+const { StreamingIngestElasticChannel } = require("./elastic_channel.js");
+const { ElasticChannelAckState } = require("./mark_complete_callback.js");
 
 /**
  * Streaming ingest client for creating channels to ingest data into Snowflake.
@@ -45,6 +47,8 @@ class StreamingIngestClient {
   /** @param {object} nativeClient - Internal JsClient from FFI */
   constructor(nativeClient) {
     this._native = nativeClient;
+    /** @type {Promise<StreamingIngestElasticChannel>|null} Cached elastic-channel promise (singleton). */
+    this._elasticChannelPromise = null;
   }
 
   /** @returns {string} The client name */
@@ -108,6 +112,37 @@ class StreamingIngestClient {
     };
   }
 
+  /**
+   * Get the elastic channel for this client. Elastic channels have no offset
+   * tokens and their lifecycle is tied to the client (no close method). The same
+   * instance is returned on repeated calls (singleton).
+   *
+   * @returns {Promise<StreamingIngestElasticChannel>}
+   */
+  async getElasticChannel() {
+    if (!this._elasticChannelPromise) {
+      // Cache the in-flight promise so concurrent callers share one open and one
+      // instance. The pending-futures map is shared between the FFI callbacks and
+      // the channel wrapper (the JS side owns per-message-ack promise resolution).
+      this._elasticChannelPromise = (async () => {
+        const pendingFutures = new Map();
+        const ackState = new ElasticChannelAckState(pendingFutures);
+        const nativeChannel = await callFFI(() =>
+          this._native.getElasticChannel(ackState.markComplete, ackState.invalidateAll),
+        );
+        // Plug the native handle in before exposing the channel so the ack
+        // state can drive `invalidateChannel` from JS on detected anomalies.
+        ackState.setNativeChannel(nativeChannel);
+        return new StreamingIngestElasticChannel(nativeChannel, pendingFutures);
+      })().catch((e) => {
+        // Don't cache failures (e.g. closed client, transient open error) so a retry can re-open.
+        this._elasticChannelPromise = null;
+        throw e;
+      });
+    }
+    return this._elasticChannelPromise;
+  }
+
   /**
    * Drop a channel by name (server-side removal).
    * @param {string} channelName
@@ -175,15 +210,16 @@ class StreamingIngestClient {
 }
 
 /**
- * Create a new streaming ingest client.
- *
- * @param {object} native - The native addon instance (provided by index.js)
- * @param {{clientName: string, dbName: string, schemaName: string, pipeName: string, profilePath?: string, properties?: Object.<string, string>}} options
+ * Shared client construction: coerce property values to strings, apply the
+ * Windows workaround, call the native factory, and wrap the result.
+ * @param {object} native - The native addon instance
+ * @param {{clientName: string, dbName: string, schemaName: string, pipeName: string, profilePath?: string, properties?: Object.<string, string>, isTableMode: boolean}} args
  * @returns {Promise<StreamingIngestClient>}
+ * @private
  */
-async function createClient(native, options) {
+async function _createNativeClient(native, args) {
   // Coerce property values to strings (matching Python)
-  let properties = options.properties;
+  let properties = args.properties;
   if (properties) {
     properties = Object.fromEntries(Object.entries(properties).map(([k, v]) => [k, String(v)]));
   }
@@ -198,19 +234,60 @@ async function createClient(native, options) {
 
   const nativeClient = await callFFI(() =>
     native.createClient({
-      clientName: options.clientName,
-      dbName: options.dbName,
-      schemaName: options.schemaName,
-      pipeName: options.pipeName,
-      profilePath: options.profilePath,
+      clientName: args.clientName,
+      dbName: args.dbName,
+      schemaName: args.schemaName,
+      pipeName: args.pipeName,
+      profilePath: args.profilePath,
       properties,
+      isTableMode: args.isTableMode,
     }),
   );
 
   return new StreamingIngestClient(nativeClient);
 }
 
+/**
+ * Create a new streaming ingest client.
+ *
+ * @param {object} native - The native addon instance (provided by index.js)
+ * @param {{clientName: string, dbName: string, schemaName: string, pipeName: string, profilePath?: string, properties?: Object.<string, string>}} options
+ * @returns {Promise<StreamingIngestClient>}
+ */
+async function createClient(native, options) {
+  return _createNativeClient(native, {
+    clientName: options.clientName,
+    dbName: options.dbName,
+    schemaName: options.schemaName,
+    pipeName: options.pipeName,
+    profilePath: options.profilePath,
+    properties: options.properties,
+    isTableMode: false,
+  });
+}
+
+/**
+ * Create a new streaming ingest client in table mode. The pipe name is derived
+ * from the table name by appending "-STREAMING".
+ *
+ * @param {object} native - The native addon instance (provided by index.js)
+ * @param {{clientName: string, dbName: string, schemaName: string, tableName: string, profilePath?: string, properties?: Object.<string, string>}} options
+ * @returns {Promise<StreamingIngestClient>}
+ */
+async function createTableClient(native, options) {
+  return _createNativeClient(native, {
+    clientName: options.clientName,
+    dbName: options.dbName,
+    schemaName: options.schemaName,
+    pipeName: `${options.tableName}-STREAMING`,
+    profilePath: options.profilePath,
+    properties: options.properties,
+    isTableMode: true,
+  });
+}
+
 module.exports = {
   StreamingIngestClient,
   createClient,
+  createTableClient,
 };

package/src/elastic_channel.js

@@ -0,0 +1,175 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+const { callFFI, StreamingIngestError } = require("./errors.js");
+const { ChannelStatus } = require("./channel_status.js");
+const { serializeRowsToNdjson } = require("./row_serializer.js");
+
+/**
+ * Elastic channel for streaming data into a Snowflake table.
+ *
+ * Unlike a regular channel, an elastic channel has no offset tokens and its
+ * lifecycle is tied to the client (no close method). appendRow/appendRows return
+ * a Promise that resolves when Snowflake acknowledges the rows.
+ *
+ * Created via {@link StreamingIngestClient#getElasticChannel}, not directly.
+ */
+class StreamingIngestElasticChannel {
+  /**
+   * @param {object} nativeChannel - Internal JsElasticChannel from FFI
+   * @param {Map<number, {resolve: Function, reject: Function}>} pendingFutures
+   *   Pending-promise map shared with the mark-complete callback wired into FFI.
+   */
+  constructor(nativeChannel, pendingFutures) {
+    if (!(nativeChannel && typeof nativeChannel === "object")) {
+      throw new TypeError(
+        "StreamingIngestElasticChannel cannot be instantiated directly. " +
+          "Use client.getElasticChannel() instead.",
+      );
+    }
+    this._native = nativeChannel;
+    this._pendingFutures = pendingFutures;
+  }
+
+  /** @returns {string} The channel name (always "ELASTIC") */
+  get channelName() {
+    return this._native.channelName;
+  }
+
+  /** @returns {string} The database name */
+  get dbName() {
+    return this._native.dbName;
+  }
+
+  /** @returns {string} The schema name */
+  get schemaName() {
+    return this._native.schemaName;
+  }
+
+  /** @returns {string} The pipe name */
+  get pipeName() {
+    return this._native.pipeName;
+  }
+
+  /** @returns {boolean} True if the channel is closed (because the client was closed) */
+  get isClosed() {
+    return this._native.isClosed;
+  }
+
+  /**
+   * Get the binary input format for this channel.
+   * @returns {string} One of: "BASE64", "HEX", "UTF-8"
+   */
+  get binaryInputFormat() {
+    return this._native.binaryInputFormat;
+  }
+
+  /**
+   * Append a single row into the elastic channel.
+   * @param {Object} row - Row data as column-name to value pairs
+   * @returns {Promise<void>} Resolves when Snowflake acknowledges the row
+   */
+  async appendRow(row) {
+    if (row == null) {
+      throw new TypeError("row must not be null");
+    }
+    return this.appendRows([row]);
+  }
+
+  /**
+   * Append multiple rows into the elastic channel.
+   *
+   * The native call is synchronous: it buffers the rows and returns a future id,
+   * which is registered in the shared pending map before returning to the event
+   * loop. The Promise resolves later when the mark-complete callback fires with
+   * the server acknowledgement (or rejects on error / channel invalidation).
+   *
+   * @param {Object[]} rows - Array of row objects
+   * @returns {Promise<void>} Resolves when Snowflake acknowledges the batch
+   */
+  async appendRows(rows) {
+    if (rows == null) {
+      throw new TypeError("rows must not be null");
+    }
+    if (!Array.isArray(rows)) {
+      throw new TypeError("rows must be an array");
+    }
+    // Empty arrays are validated by the Rust core, which throws a proper error.
+    const buffer =
+      rows.length === 0 ? Buffer.alloc(0) : serializeRowsToNdjson(rows, this.binaryInputFormat);
+    let futureId;
+    try {
+      futureId = Number(this._native.appendRows(buffer, rows.length));
+    } catch (e) {
+      throw StreamingIngestError.from(e);
+    }
+
+    // Build the promise out-of-line so we can stash {resolve, reject} into the
+    // shared map synchronously — the single-threaded event loop guarantees this
+    // happens-before any queued threadsafe-function callback runs. Map and
+    // resolve are then visible to mark_complete_callback.js (the JS owner of
+    // resolution) and the invalidate-all path on channel teardown.
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+      resolveFn = resolve;
+      rejectFn = reject;
+    });
+    const previous = this._pendingFutures.get(futureId);
+    this._pendingFutures.set(futureId, { resolve: resolveFn, reject: rejectFn });
+    if (previous !== undefined) {
+      // Mirrors Java/Python: a duplicate future id from Rust means the SDK
+      // and the core have drifted, which is fatal. Reject the displaced
+      // promise, invalidate the channel, and throw to the caller so the
+      // new promise we just stashed isn't left hanging either.
+      const errMsg = `Duplicate future_id=${futureId} in pendingFutures`;
+      const err = new StreamingIngestError("Fatal", errMsg, 500, "Internal Server Error");
+      previous.reject(err);
+      try {
+        this._native.invalidateChannel(errMsg);
+      } catch (invErr) {
+        // eslint-disable-next-line no-console
+        console.error("Elastic channel invalidate_channel FFI call failed:", invErr);
+      }
+      throw err;
+    }
+    return promise;
+  }
+
+  /**
+   * Trigger a flush of this channel (non-blocking).
+   * @throws {StreamingIngestError} If the flush cannot be initiated
+   */
+  initiateFlush() {
+    try {
+      this._native.initiateFlush();
+    } catch (e) {
+      throw StreamingIngestError.from(e);
+    }
+  }
+
+  /**
+   * Get the current status of this channel.
+   * @returns {Promise<ChannelStatus>}
+   */
+  async getChannelStatus() {
+    const raw = await callFFI(() => this._native.getChannelStatus());
+    return new ChannelStatus(raw);
+  }
+}
+
+module.exports = { StreamingIngestElasticChannel };

package/src/index.d.ts

@@ -55,6 +55,32 @@ export function createClient(options: {
   properties?: Record<string, string>;
 }): Promise<StreamingIngestClient>;
 
+/**
+ * Create a new streaming ingest client in table mode. The pipe name is derived
+ * from the table name by appending "-STREAMING". Each client is tied to a single
+ * database, schema, and (derived) pipe.
+ *
+ * Either `profilePath` or `properties` must be provided for authentication.
+ * If both are provided, `properties` takes precedence for conflicting keys.
+ *
+ * @param options - Client configuration
+ * @throws StreamingIngestError If client creation fails
+ */
+export function createTableClient(options: {
+  /** A unique name to identify this client instance, used for tracking and debugging purposes. */
+  clientName: string;
+  /** The name of the Snowflake database where data will be ingested. */
+  dbName: string;
+  /** The name of the schema within the database. */
+  schemaName: string;
+  /** The table name. The pipe name is derived as `${tableName}-STREAMING`. */
+  tableName: string;
+  /** Path to a JSON file containing connection properties and authentication information. */
+  profilePath?: string;
+  /** Connection properties and authentication information. */
+  properties?: Record<string, string>;
+}): Promise<StreamingIngestClient>;
+
 /**
  * A client that is the starting point for using the Streaming Ingest client APIs.
  *
@@ -116,6 +142,15 @@ export class StreamingIngestClient {
     status: ChannelStatus | null;
   }>;
 
+  /**
+   * Get the elastic channel for this client. Elastic channels have no offset
+   * tokens and their lifecycle is tied to the client (there is no close method).
+   * The same instance is returned on repeated calls (singleton).
+   *
+   * @throws StreamingIngestError If the client is closed or the channel cannot be opened
+   */
+  getElasticChannel(): Promise<StreamingIngestElasticChannel>;
+
   /**
    * Drop a channel by name (server-side removal).
    *
@@ -292,6 +327,67 @@ export class StreamingIngestChannel {
   }): Promise<void>;
 }
 
+/**
+ * An elastic channel for streaming data into a Snowflake table.
+ *
+ * Unlike a regular channel, an elastic channel has no offset tokens and its
+ * lifecycle is tied to the client — there is no close method, and the same
+ * instance is returned on repeated calls to `client.getElasticChannel()`.
+ * `appendRow`/`appendRows` resolve when Snowflake acknowledges the rows.
+ *
+ * Create instances using `client.getElasticChannel()`.
+ */
+export class StreamingIngestElasticChannel {
+  private constructor();
+
+  /** The channel name (always "ELASTIC"). */
+  readonly channelName: string;
+  /** The database name. */
+  readonly dbName: string;
+  /** The schema name. */
+  readonly schemaName: string;
+  /** The pipe name. */
+  readonly pipeName: string;
+  /** Whether the channel is closed (because the client was closed). */
+  readonly isClosed: boolean;
+  /** The binary input format. One of: "BASE64", "HEX", "UTF-8". */
+  readonly binaryInputFormat: string;
+
+  /**
+   * Append a single row into the elastic channel. The returned promise resolves
+   * when Snowflake acknowledges the row.
+   *
+   * @param row - Row data as column-name to value pairs
+   * @throws StreamingIngestError If the row appending fails
+   */
+  appendRow(row: Record<string, any>): Promise<void>;
+
+  /**
+   * Append multiple rows into the elastic channel. The returned promise resolves
+   * when Snowflake acknowledges the batch.
+   *
+   * @param rows - Array of row objects (column-name to value pairs)
+   * @throws TypeError If rows is not an array
+   * @throws StreamingIngestError If the rows appending fails
+   */
+  appendRows(rows: Record<string, any>[]): Promise<void>;
+
+  /**
+   * Initiate a flush of all buffered data for this channel but do not wait for
+   * the flush to complete.
+   *
+   * @throws StreamingIngestError If the flush cannot be initiated
+   */
+  initiateFlush(): void;
+
+  /**
+   * Get the current status of this channel.
+   *
+   * @throws StreamingIngestError If getting the channel status fails
+   */
+  getChannelStatus(): Promise<ChannelStatus>;
+}
+
 /**
  * Status information for a streaming ingest channel.
  *
@@ -344,6 +440,8 @@ export class ChannelStatus {
 export class StreamingIngestError extends Error {
   /** The error code (for example, "ConfigError", "ChannelNotFound"). */
   readonly errorCode: string;
+  /** The error message. Inherited from `Error`; redeclared for autodoc visibility. */
+  readonly message: string;
   /** HTTP status code indicating error category. */
   readonly httpStatusCode: number;
   /** HTTP status name (for example, "Bad Request"). */

package/src/index.js

@@ -20,8 +20,13 @@
 const { loadNativeAddon } = require("./loader.js");
 const { StreamingIngestError } = require("./errors.js");
 const { ChannelStatus } = require("./channel_status.js");
-const { StreamingIngestClient, createClient: _createClient } = require("./client.js");
+const {
+  StreamingIngestClient,
+  createClient: _createClient,
+  createTableClient: _createTableClient,
+} = require("./client.js");
 const { StreamingIngestChannel } = require("./channel.js");
+const { StreamingIngestElasticChannel } = require("./elastic_channel.js");
 
 // Load native addon and bootstrap the Rust runtime
 const native = loadNativeAddon();
@@ -41,8 +46,10 @@ const StreamingIngestErrorCode = Object.freeze(
 
 module.exports = {
   createClient: (options) => _createClient(native, options),
+  createTableClient: (options) => _createTableClient(native, options),
   StreamingIngestClient,
   StreamingIngestChannel,
+  StreamingIngestElasticChannel,
   StreamingIngestError,
   StreamingIngestErrorCode,
   ChannelStatus,

package/src/mark_complete_callback.js

@@ -0,0 +1,157 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+// Per-elastic-channel acknowledgement bridge. Port of Python's
+// _mark_complete_callback.py and Java's MarkCompleteCallback. The Rust
+// threadsafe-function callbacks fire into `markComplete` (one call per
+// server-ack batch) and `invalidateAll` (once on channel teardown); the JS
+// side owns the pending-promise map keyed by future id and resolves or
+// rejects accordingly.
+//
+// Java/Python express the same protocol slightly differently: their
+// markComplete *throws* on a missing future id or an odd-length range, and
+// the host (JNI/PyO3) propagates that exception back to Rust which then
+// invalidates the channel. The napi threadsafe-function bridge is
+// NonBlocking and has no return channel, so we can't ride the exception
+// back. Instead the JS side detects the inconsistency, rejects every
+// in-flight promise, and calls `invalidateChannel` on the native handle
+// directly — same end state, driven from JS.
+
+const { StreamingIngestError } = require("./errors.js");
+
+function buildError(success, errorCode, message, httpStatusCode, httpStatusName) {
+  if (success) {
+    return null;
+  }
+  return new StreamingIngestError(
+    errorCode || "Fatal",
+    message || "Unknown error",
+    httpStatusCode != null ? Number(httpStatusCode) : 409,
+    httpStatusName || "Conflict",
+  );
+}
+
+/**
+ * Acknowledgement state for one elastic channel. Owns the pending-futures map
+ * shared with `StreamingIngestElasticChannel.appendRows`, the `invalidated`
+ * gate that mirrors Java/Python's flag, and a reference to the native channel
+ * for JS-driven invalidation. The native reference is plugged in after the
+ * channel is opened (chicken-and-egg: these callbacks are passed *into* the
+ * open call, so they exist before the native handle does).
+ */
+class ElasticChannelAckState {
+  constructor(pendingFutures) {
+    this._pendingFutures = pendingFutures;
+    this._invalidated = false;
+    this._nativeChannel = null;
+    this.markComplete = this._markComplete.bind(this);
+    this.invalidateAll = this._invalidateAll.bind(this);
+  }
+
+  /** Plug in the native channel after `getElasticChannel` resolves. */
+  setNativeChannel(nativeChannel) {
+    this._nativeChannel = nativeChannel;
+  }
+
+  _markComplete(payload) {
+    const { futureIdRanges, success, errorCode, message, httpStatusCode, httpStatusName } = payload;
+
+    if (futureIdRanges.length % 2 !== 0) {
+      const errMsg = `future_id_ranges has odd length ${futureIdRanges.length}, expected even (flattened [min, max] pairs)`;
+      this._invalidateLocally(
+        new StreamingIngestError("Fatal", errMsg, 500, "Internal Server Error"),
+      );
+      return;
+    }
+
+    const error = buildError(success, errorCode, message, httpStatusCode, httpStatusName);
+
+    const missingIds = [];
+    for (let i = 0; i < futureIdRanges.length; i += 2) {
+      const min = Number(futureIdRanges[i]);
+      const max = Number(futureIdRanges[i + 1]);
+      for (let fid = min; fid <= max; fid++) {
+        const pending = this._pendingFutures.get(fid);
+        if (pending === undefined) {
+          missingIds.push(fid);
+          continue;
+        }
+        this._pendingFutures.delete(fid);
+        if (error) {
+          pending.reject(error);
+        } else {
+          pending.resolve();
+        }
+      }
+    }
+
+    // `_invalidated` gate matches Java/Python: after invalidateAll has run,
+    // the map is empty and further mark-complete callbacks for in-flight
+    // batches are expected to find nothing — don't escalate that to fatal.
+    if (missingIds.length > 0 && !this._invalidated) {
+      const errMsg = `Future ids [${missingIds.join(", ")}] not found in pending futures`;
+      this._invalidateLocally(
+        new StreamingIngestError("Fatal", errMsg, 500, "Internal Server Error"),
+      );
+    }
+  }
+
+  _invalidateAll(payload) {
+    this._invalidated = true;
+    const error =
+      buildError(
+        payload.success,
+        payload.errorCode,
+        payload.message,
+        payload.httpStatusCode,
+        payload.httpStatusName,
+      ) || new StreamingIngestError("Fatal", "Elastic channel invalidated", 409, "Conflict");
+    for (const pending of this._pendingFutures.values()) {
+      pending.reject(error);
+    }
+    this._pendingFutures.clear();
+  }
+
+  /**
+   * JS-driven invalidation when we detect state Rust isn't aware of yet
+   * (odd-length range, missing future id, duplicate future id). Idempotent
+   * via `_invalidated`. Promises are rejected first so the user observation
+   * doesn't depend on the FFI call succeeding; the native invalidate is
+   * best-effort — Rust will fire `invalidateAll` on its next informer
+   * tick, which finds an empty map and is a no-op.
+   */
+  _invalidateLocally(error) {
+    if (this._invalidated) {
+      return;
+    }
+    this._invalidated = true;
+    for (const pending of this._pendingFutures.values()) {
+      pending.reject(error);
+    }
+    this._pendingFutures.clear();
+    if (this._nativeChannel) {
+      try {
+        this._nativeChannel.invalidateChannel(error.message);
+      } catch (invErr) {
+        // eslint-disable-next-line no-console
+        console.error("Elastic channel invalidate_channel FFI call failed:", invErr);
+      }
+    }
+  }
+}
+
+module.exports = { ElasticChannelAckState };

package/src/row_serializer.js

@@ -0,0 +1,62 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+// Shared row serialization for regular and elastic channels. Kept in one place
+// because the NDJSON byte-count behavior is a cross-language gotcha (Rust appends
+// a trailing newline unconditionally) and the two channel classes must not drift.
+
+/**
+ * Convert Buffer/Uint8Array values in a row according to binaryInputFormat.
+ * For HEX, binary values become hex-encoded strings. For UTF-8, decoded as UTF-8.
+ * For BASE64 (the default), base64-encoded for JSON serialization. Only top-level
+ * values are converted; nested structures are left as-is.
+ * @param {Object} row - Row object
+ * @param {string} binaryInputFormat - One of "BASE64", "HEX", "UTF-8"
+ * @returns {Object} Row with binary values converted
+ */
+function convertBytesInRow(row, binaryInputFormat) {
+  // Resolve the format-specific encoder once per row instead of branching per cell
+  // — appendRows is the hot path and rows are dominated by columns, not formats.
+  const encoding =
+    binaryInputFormat === "HEX" ? "hex" : binaryInputFormat === "UTF-8" ? "utf8" : "base64";
+  const result = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (Buffer.isBuffer(value)) {
+      result[key] = value.toString(encoding);
+    } else if (value instanceof Uint8Array) {
+      result[key] = Buffer.from(value).toString(encoding);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Serialize rows to an NDJSON Buffer, converting binary column values per binaryInputFormat.
+ * @param {Object[]} rows - Array of row objects
+ * @param {string} binaryInputFormat - One of "BASE64", "HEX", "UTF-8"
+ * @returns {Buffer} UTF-8 NDJSON buffer (no trailing newline; Rust appends one per row)
+ */
+function serializeRowsToNdjson(rows, binaryInputFormat) {
+  const ndjson = rows
+    .map((r) => JSON.stringify(convertBytesInRow(r, binaryInputFormat)))
+    .join("\n");
+  return Buffer.from(ndjson, "utf8");
+}
+
+module.exports = { convertBytesInRow, serializeRowsToNdjson };