node-firebird 2.15.1 → 2.16.1

package/README.md

@@ -11,7 +11,7 @@
 - [Installation](#installation)
 - [Usage](#usage) — including [developing the driver](#developing-the-driver)
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
-- [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
+- [Connection types](#connection-types) — connection options, `firebird://` / `inet://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, tagged-template queries (sql), named placeholders, nested result tables (nestTables), row-key transforms (transformKeys), result metadata / affected rows (withMeta), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
 - [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts incl. BLOBs), bulk-insert stream (batchStream), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
@@ -200,6 +200,7 @@ options.dbCryptConfig = undefined; // optional; database encryption key for encr
 options.connectTimeout = 10000; // optional; timeout in ms for a single pool.get() attach operation (default: no timeout)
 options.enableKeepAlive = true; // TCP keepalive probing to detect dead/stale connections (same option names as mysql2); set to false to disable
 options.keepAliveInitialDelay = 60000; // ms a socket must be idle before the first keepalive probe (ignored when enableKeepAlive is false)
+options.ipFamily = 4; // optional; force IPv4 (4) or IPv6 (6) when resolving host — also set by inet4:// / inet6:// URIs
 options.parallelWorkers = undefined; // optional; request multiple thread workers for maintenance/index tasks (FB >= 5)
 options.maxInlineBlobSize = undefined; // optional; threshold size in bytes for inline blob transmission (default 65535, FB >= 5.0.3)
 options.maxNegotiatedProtocols = undefined; // optional; cap how many protocol versions are offered, oldest first (default: all, up to Protocol 20; set to 10 to stop at Protocol 19)
@@ -248,6 +249,20 @@ be passed as query parameters. IPv6 hosts use brackets:
 `firebird://[::1]:3050/employee`. The parser is exported as
 `Firebird.parseConnectionUri(uri)` if you need the resulting options object.
 
+Firebird's own URL-style connection strings (Firebird 3+) are accepted with
+the same rules, so a string that works with isql works here unchanged:
+
+| URI | meaning |
+| :--- | :--- |
+| `inet://host/employee` | same as `firebird://host/employee` |
+| `inet://host:3051//var/fb/prod.fdb` | host, port and an absolute path |
+| `inet4://host/employee` | resolve `host` as IPv4 only (sets `ipFamily: 4`) |
+| `inet6://[::1]/employee` | IPv6 only (sets `ipFamily: 6`) |
+
+`inet://` strings may carry credentials and query options exactly like
+`firebird://` ones. The local-only transports `xnet://` and `wnet://` are
+rejected — this driver speaks TCP only.
+
 ### Traditional connection strings (old style)
 
 The classic Firebird connection string format — the same
@@ -748,16 +763,29 @@ option `numericMode` controls how those result values are exposed:
 
 | Mode | Result policy |
 | :--- | :--- |
-| `Firebird.NUMERIC_MODE_LOSSY` | INT64-backed values are returned as `number`; INT128 uses a mixed `number`/`string` path. Unsafe coefficients may lose precision. |
+| `Firebird.NUMERIC_MODE_LOSSY` | INT64-backed values are returned as `number`, losing precision beyond the safe integer range; INT128 returns a `number` for a safe coefficient and an exact scaled `string` for an unsafe one. |
 | `Firebird.NUMERIC_MODE_SAFE` | Safe coefficients are returned as `number`; unsafe coefficients as exact scaled `string`. |
 | `Firebird.NUMERIC_MODE_STRING` | All values are returned as exact scaled `string`. |
 
-`LOSSY` decodes INT64-backed values through JavaScript `Number`. INT128 uses a
-mixed number/string decoding path. For coefficients outside JavaScript's safe
-integer range, the result type can depend on the Firebird wire type and value,
-and numeric precision is not guaranteed. `LOSSY` remains the default so that
-adding `numericMode` does not silently change result types for applications
-upgrading from earlier node-firebird releases.
+`LOSSY` decodes INT64-backed values through JavaScript `Number`, so a
+coefficient beyond JavaScript's safe integer range loses digits silently.
+INT128 instead takes a mixed path: a coefficient inside the inclusive safe
+range is returned as a scaled `number`, and one outside it — in either
+direction — is returned as an exact scaled `string`, formatted just as
+`STRING` would format it. The result type of an INT128 column therefore
+depends on the value:
+
+```js
+// numericMode: LOSSY, INT128 column
+// coefficient 12345, scale -2   -> 123.45   (number)
+// coefficient -12345, scale -2  -> -123.45  (number)
+// coefficient 2^127-1, scale 0  -> '170141183460469231731687303715884105727'
+// coefficient -2^127, scale 0   -> '-170141183460469231731687303715884105728'
+```
+
+Use `SAFE` or `STRING` when a stable result type matters. `LOSSY` remains the
+default so that adding `numericMode` does not silently change result types for
+applications upgrading from earlier node-firebird releases.
 
 `SAFE` tests the raw integer coefficient against JavaScript's inclusive safe
 range (`Number.MIN_SAFE_INTEGER` through `Number.MAX_SAFE_INTEGER`) before
@@ -774,6 +802,12 @@ const db = await Firebird.attachAsync({
 // DECIMAL coefficient 420000,-4 -> '42.0000'
 ```
 
+Every declared scale is supported in all three modes, including the 18
+fractional digits an INT64-backed `NUMERIC(18,18)` allows and the 38 an INT128
+column can declare. A Firebird coefficient represents `value * 10^scale`, so
+the positive scales that dialect 1 and some legacy metadata still produce
+scale the value up rather than down.
+
 The string literals `'lossy'`, `'safe'`, and `'string'` are accepted too,
 including in connection URIs (`?numericMode=safe`). `NULL` remains `null` in
 every mode. The option does not change `FLOAT`, `DOUBLE`, `DECFLOAT`, or input
@@ -1893,10 +1927,14 @@ in bytes).
 Notes:
 
 - Requires wire protocol 16+ (Firebird 4.0 or newer server).
-- Values are encoded from the statement's own parameter metadata, so
-  NUMERIC/DECIMAL scale, `BIGINT`/`INT128` (pass `BigInt`), `BOOLEAN`,
-  `TIMESTAMP`/`DATE`/`TIME`, `FLOAT`/`DOUBLE` and `DECFLOAT` all round-trip
-  exactly.
+- Values are encoded from the statement's own parameter metadata. Fixed-point
+  `NUMERIC`/`DECIMAL`, `BIGINT`, and `INT128` parameters accept numbers, decimal
+  strings, and `BigInt`. Decimal strings retain their exact digits; finite
+  numbers are interpreted through their canonical decimal representation and
+  rounded to the declared scale with ties away from zero. Use a string (or
+  `BigInt` for whole values) when the input is outside JavaScript's safe integer
+  range. `BOOLEAN`, `TIMESTAMP`/`DATE`/`TIME`, `FLOAT`/`DOUBLE`, and `DECFLOAT`
+  use their corresponding wire types.
 - `BLOB` columns accept Buffers, strings, JSON-able objects, or
   pre-created blob quad ids: values are uploaded as transaction blobs
   first — all initiated back-to-back so the blob ops pipeline on the

package/lib/types.d.ts

@@ -432,6 +432,12 @@ export interface Options {
      * probe is sent (default 60000). Ignored when enableKeepAlive is false.
      */
     keepAliveInitialDelay?: number;
+    /**
+     * Force the TCP socket to IPv4 (4) or IPv6 (6) when resolving `host`.
+     * Unset lets the resolver choose. Set automatically by `inet4://` /
+     * `inet6://` connection URIs.
+     */
+    ipFamily?: 4 | 6;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/lib/uri.d.ts

@@ -5,9 +5,11 @@
  ***************************************/
 import type { Options } from './types';
 /**
- * Parse a firebird:// connection URI into an options object.
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -45,13 +47,15 @@ export declare function parseConnectionUri(uri: string): Options;
  */
 export declare function parseOldStyleConnectionString(str: string): Options;
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 export declare function parseConnectionString(str: string): Options;
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 export declare function normalizeOptions<T>(options: T | string): T;

package/lib/uri.js

@@ -22,7 +22,7 @@ const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay', 'ipFamily',
 ]);
 function coerce(key, value) {
     if (BOOLEAN_KEYS.has(key)) {
@@ -38,9 +38,29 @@ function coerce(key, value) {
     return value;
 }
 /**
- * Parse a firebird:// connection URI into an options object.
+ * URI schemes accepted by parseConnectionUri. `firebird://` is this driver's
+ * own scheme; `inet://`, `inet4://` and `inet6://` are Firebird's native
+ * URL-style connection strings (Firebird 3+), so a string that works with
+ * isql works here too. inet4/inet6 pin the socket's IP family (the
+ * `ipFamily` option); inet and firebird let the resolver pick.
+ */
+const URI_SCHEMES = {
+    'firebird:': undefined,
+    'inet:': undefined,
+    'inet4:': 4,
+    'inet6:': 6,
+};
+/**
+ * Firebird protocols this driver cannot speak: they are local-machine IPC
+ * transports (shared memory / named pipes), not TCP.
+ */
+const LOCAL_SCHEMES = /^(xnet|wnet):$/;
+/**
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -64,11 +84,20 @@ function parseConnectionUri(uri) {
     catch (e) {
         throw new Error('Invalid connection URI: ' + uri);
     }
-    if (url.protocol !== 'firebird:') {
-        throw new Error('Unsupported connection URI scheme "' + url.protocol.replace(/:$/, '') +
-            '" (expected firebird://...)');
+    var scheme = url.protocol.toLowerCase();
+    if (LOCAL_SCHEMES.test(scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (local IPC transports are not available over the wire — use inet:// or firebird://)');
+    }
+    if (!Object.prototype.hasOwnProperty.call(URI_SCHEMES, scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (expected firebird://, inet://, inet4:// or inet6://)');
     }
     var options = {};
+    var ipFamily = URI_SCHEMES[scheme];
+    if (ipFamily !== undefined) {
+        options.ipFamily = ipFamily;
+    }
     if (url.hostname) {
         // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
         options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
@@ -172,8 +201,9 @@ function parseOldStyleConnectionString(str) {
 }
 const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 function parseConnectionString(str) {
     return URI_SCHEME.test(str)
@@ -181,8 +211,9 @@ function parseConnectionString(str) {
         : parseOldStyleConnectionString(str);
 }
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 function normalizeOptions(options) {

package/lib/wire/connection.js

@@ -168,7 +168,7 @@ class Connection {
         this._detachTimeout;
         this._detachCallback;
         this._detachAuto;
-        this._socket = new socket_1.default(port, host, options.enableKeepAlive !== false, options.keepAliveInitialDelay);
+        this._socket = new socket_1.default(port, host, options.enableKeepAlive !== false, options.keepAliveInitialDelay, options.ipFamily);
         this._pending = [];
         this._isOpened = false;
         this._isClosed = false;
@@ -1194,6 +1194,17 @@ class Connection {
                 return;
             }
         }
+        // Validate fixed-point values before the BLOB pre-pass. Blob uploads
+        // write immediately, so deferring numeric validation until message
+        // encoding could leave transaction blob state behind for a batch that
+        // can never be sent.
+        try {
+            validateBatchFixedPointRows(input, rows);
+        }
+        catch (err) {
+            (0, callback_1.doError)(err, callback);
+            return;
+        }
         var self = this;
         // BLOB pre-pass: upload every Buffer/string blob value as a
         // transaction blob and replace it (in a cloned row) with the quad
@@ -3065,6 +3076,46 @@ function scaleOutputLengths(output, options) {
         p.length = Math.min(Math.floor(p.length / colWidth) * connWidth, Math.floor(0xFFFF / connWidth) * connWidth);
     }
 }
+function scaleBatchFixedPoint(value, meta, bits, column) {
+    try {
+        return Xsql.toScaledInteger(value, meta.scale, bits);
+    }
+    catch (err) {
+        var message = err instanceof Error ? err.message : String(err);
+        throw new Error('Invalid fixed-point batch value for column ' + column +
+            ' (' + (meta.field || '?') + '): ' + message);
+    }
+}
+/** Validate values whose batch wire representation is metadata-directed.
+ * This runs before BLOB uploads, which may write to the transaction as soon
+ * as executeBatch starts its asynchronous pre-pass. */
+function validateBatchFixedPointRows(input, rows) {
+    for (var i = 0; i < rows.length; i++) {
+        for (var j = 0; j < input.length; j++) {
+            var value = rows[i][j];
+            if (value === null || value === undefined)
+                continue;
+            var bits = undefined;
+            switch (input[j].type) {
+                case const_1.default.SQL_SHORT:
+                    bits = 16;
+                    break;
+                case const_1.default.SQL_LONG:
+                    bits = 32;
+                    break;
+                case const_1.default.SQL_INT64:
+                    bits = 64;
+                    break;
+                case const_1.default.SQL_INT128:
+                    bits = 128;
+                    break;
+            }
+            if (bits !== undefined) {
+                scaleBatchFixedPoint(value, input[j], bits, j + 1);
+            }
+        }
+    }
+}
 /**
  * Batch support: the engine requires every batch message to use EXACTLY the
  * statement's described input format (unlike op_execute, where the client
@@ -3104,16 +3155,6 @@ function buildBatchEncoders(input, options) {
             return (0, utils_1.parseDate)(v);
         return new Date(v);
     };
-    var scaled = function (v, scale) {
-        var n = typeof v === 'string' ? parseFloat(v) : Number(v);
-        return scale ? Math.round(n * Math.pow(10, -scale)) : n;
-    };
-    var scaledBig = function (v, scale) {
-        if (typeof v === 'bigint') {
-            return scale ? v * (10n ** BigInt(-scale)) : v;
-        }
-        return BigInt(scaled(v, scale));
-    };
     for (var j = 0; j < input.length; j++) {
         var meta = input[j];
         var column = j + 1;
@@ -3144,32 +3185,32 @@ function buildBatchEncoders(input, options) {
                 break;
             case const_1.default.SQL_SHORT:
                 // 2 bytes in the message struct (msglen), 4 on the XDR wire
-                encoders.push((function (m) {
-                    return function (msg, v) { msg.addInt(scaled(v, m.scale)); };
-                })(meta));
+                encoders.push((function (m, col) {
+                    return function (msg, v) { msg.addInt(Number(scaleBatchFixedPoint(v, m, 16, col))); };
+                })(meta, column));
                 align(2);
                 offset += 2;
                 break;
             case const_1.default.SQL_LONG:
-                encoders.push((function (m) {
-                    return function (msg, v) { msg.addInt(scaled(v, m.scale)); };
-                })(meta));
+                encoders.push((function (m, col) {
+                    return function (msg, v) { msg.addInt(Number(scaleBatchFixedPoint(v, m, 32, col))); };
+                })(meta, column));
                 align(4);
                 offset += 4;
                 break;
             case const_1.default.SQL_INT64:
-                encoders.push((function (m) {
+                encoders.push((function (m, col) {
                     return function (msg, v) {
-                        msg.addInt64(typeof v === 'bigint' ? scaledBig(v, m.scale) : scaled(v, m.scale));
+                        msg.addInt64(scaleBatchFixedPoint(v, m, 64, col));
                     };
-                })(meta));
+                })(meta, column));
                 align(8);
                 offset += 8;
                 break;
             case const_1.default.SQL_INT128:
-                encoders.push((function (m) {
-                    return function (msg, v) { msg.addInt128(scaledBig(v, m.scale)); };
-                })(meta));
+                encoders.push((function (m, col) {
+                    return function (msg, v) { msg.addInt128(scaleBatchFixedPoint(v, m, 128, col)); };
+                })(meta, column));
                 align(8);
                 offset += 16;
                 break;

package/lib/wire/serialize.js

@@ -241,7 +241,7 @@ class XdrWriter {
         const bigValue = BigInt(value);
         const high = bigValue >> BigInt(64);
         const low = bigValue & BigInt("0xFFFFFFFFFFFFFFFF");
-        this.buffer.writeBigUInt64BE(high, this.pos);
+        this.buffer.writeBigInt64BE(high, this.pos);
         this.pos += 8;
         this.buffer.writeBigUInt64BE(low, this.pos);
         this.pos += 8;

package/lib/wire/socket.d.ts

@@ -32,7 +32,7 @@ declare class Socket {
     encrypt: boolean;
     encryptCipher: any;
     decryptCipher: any;
-    constructor(port: number, host: string, enableKeepAlive?: boolean, keepAliveInitialDelay?: number);
+    constructor(port: number, host: string, enableKeepAlive?: boolean, keepAliveInitialDelay?: number, ipFamily?: 4 | 6);
     /**
      * Decompress and/or decrypt data when received.
      * Override on data event.

package/lib/wire/socket.js

@@ -82,9 +82,10 @@ class ChaChaCipher {
  */
 class Socket {
     static { this.Arc4 = Arc4; }
-    constructor(port, host, enableKeepAlive = true, keepAliveInitialDelay = 60000) {
+    constructor(port, host, enableKeepAlive = true, keepAliveInitialDelay = 60000, ipFamily) {
         this.compress = false;
-        this._socket = net_1.default.createConnection(port, host);
+        // family: 0 is "either" (Node's default); 4/6 pin the resolver
+        this._socket = net_1.default.createConnection({ port: port, host: host, family: ipFamily || 0 });
         this._socket.setNoDelay(true);
         // TCP keepalive probing detects dead/stale connections; the delay is
         // how long the socket must be idle before the first probe.

package/lib/wire/xsqlvar.d.ts

@@ -273,6 +273,14 @@ export declare class SQLParamInt128 {
     calcBlr(blr: BlrWriter): void;
     encode(data: XdrWriter): void;
 }
+/**
+ * Convert a decimal input to the signed integer coefficient used by a
+ * Firebird fixed-point wire type. Numbers are interpreted through their
+ * canonical decimal string; strings and bigints never pass through Number.
+ * Digits discarded by the target scale are rounded to nearest, ties away
+ * from zero, matching Firebird's conversion of decimal parameter text.
+ */
+export declare function toScaledInteger(value: number | string | bigint, scale: number, bits: 16 | 32 | 64 | 128): bigint;
 export declare class SQLParamDecFloat16 {
     value: any;
     constructor(value: any);

package/lib/wire/xsqlvar.js

@@ -18,6 +18,7 @@ exports.nestCell = nestCell;
 exports.describeField = describeField;
 exports.describeFields = describeFields;
 exports.parseRecordCounts = parseRecordCounts;
+exports.toScaledInteger = toScaledInteger;
 exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
 const serialize_1 = require("./serialize");
@@ -27,11 +28,29 @@ const codepages_1 = require("./codepages");
  *   SQLVar
  *
  ***************************************/
-const ScaleDivisor = [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000, 10000000000, 100000000000, 1000000000000, 10000000000000, 100000000000000, 1000000000000000];
 const DateOffset = 40587, TimeCoeff = 86400000, MsPerMinute = 60000;
 const EMPTY_BUFFER = Buffer.alloc(0);
 const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+/**
+ * Apply a Firebird numeric scale to a value already narrowed to a JS number.
+ *
+ * This replaces the former lookup table of divisors, which only held
+ * 10^0..10^15: any larger scale indexed past its end and yielded NaN. That is
+ * reachable for INT64 (NUMERIC(18,18)) and routine for INT128, where the scale
+ * runs to 38. Math.pow(10, n) returns the identical double for every exponent
+ * the table did cover, so in-range results are unchanged.
+ *
+ * Positive scales multiply, matching decodeExactNumeric and formatScaledBigInt;
+ * the table path divided by them, which was the wrong direction.
+ */
+function applyScale(value, scale) {
+    if (!scale)
+        return value;
+    return scale < 0
+        ? value / Math.pow(10, -scale)
+        : value * Math.pow(10, scale);
+}
 /** Format a signed Firebird integer coefficient without passing through Number. */
 function formatScaledBigInt(value, scale) {
     const negative = value < 0n;
@@ -56,10 +75,16 @@ function decodeExactNumeric(value, scale, mode) {
 }
 /** Decode INT128 using the mixed number/string policy of lossy mode. */
 function decodeLossyInt128(value, scale) {
-    if (value > MAX_SAFE_BIGINT) {
+    // Both bounds matter, as in decodeExactNumeric. While this path read the
+    // coefficient unsigned, every negative arrived as a huge positive and so
+    // always took the exact-string branch, which masked the missing lower
+    // bound. Now that the reader is signed, a large negative would otherwise
+    // fall through to Number() and lose precision while its positive twin
+    // stayed exact.
+    if (value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
         return formatScaledBigInt(value, scale);
     }
-    return Number(value) / ScaleDivisor[Math.abs(scale)];
+    return applyScale(Number(value), scale);
 }
 /**
  * Maps Firebird character-set names (upper-case) to the Node.js Buffer
@@ -487,9 +512,7 @@ exports.SQLVarArray = SQLVarArray;
 class SQLVarInt extends SQLVarBase {
     decode(data, lowerV13) {
         var ret = data.readInt();
-        if (this.scale) {
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
-        }
+        ret = applyScale(ret, this.scale);
         if (!lowerV13 || !data.readInt()) {
             return ret;
         }
@@ -516,8 +539,7 @@ class SQLVarInt64 extends SQLVarBase {
         let ret;
         if (mode === const_1.default.NUMERIC_MODE_LOSSY) {
             ret = data.readInt64();
-            if (this.scale)
-                ret = ret / ScaleDivisor[Math.abs(this.scale)];
+            ret = applyScale(ret, this.scale);
         }
         else {
             ret = decodeExactNumeric(data.readInt64BigInt(), this.scale, mode);
@@ -538,7 +560,7 @@ class SQLVarInt128 extends SQLVarBase {
     decode(data, lowerV13, options) {
         const mode = options?.numericMode || const_1.default.NUMERIC_MODE_LOSSY;
         const ret = mode === const_1.default.NUMERIC_MODE_LOSSY
-            ? decodeLossyInt128(data.readInt128(), this.scale)
+            ? decodeLossyInt128(data.readInt128Signed(), this.scale)
             : decodeExactNumeric(data.readInt128Signed(), this.scale, mode);
         if (!lowerV13 || !data.readInt()) {
             return ret;
@@ -813,6 +835,78 @@ class SQLParamInt128 {
 }
 exports.SQLParamInt128 = SQLParamInt128;
 //------------------------------------------------------
+const FIXED_POINT_RE = /^([+-]?)(?:(\d+)(?:\.(\d*))?|\.(\d+))(?:[eE]([+-]?\d+))?$/;
+/**
+ * Convert a decimal input to the signed integer coefficient used by a
+ * Firebird fixed-point wire type. Numbers are interpreted through their
+ * canonical decimal string; strings and bigints never pass through Number.
+ * Digits discarded by the target scale are rounded to nearest, ties away
+ * from zero, matching Firebird's conversion of decimal parameter text.
+ */
+function toScaledInteger(value, scale, bits) {
+    if (!Number.isSafeInteger(scale)) {
+        throw new TypeError('Fixed-point scale must be an integer');
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new TypeError('Fixed-point value must be finite');
+    }
+    if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'bigint') {
+        throw new TypeError('Fixed-point value must be a number, string, or bigint');
+    }
+    const text = String(value).trim();
+    const match = FIXED_POINT_RE.exec(text);
+    if (!match) {
+        throw new TypeError('Invalid fixed-point value: ' + text);
+    }
+    const negative = match[1] === '-';
+    const integer = match[2] || '0';
+    const fraction = match[3] !== undefined ? match[3] : (match[4] || '');
+    const exponent = match[5] === undefined ? 0 : Number(match[5]);
+    if (!Number.isSafeInteger(exponent)) {
+        throw new RangeError('Fixed-point exponent is outside the supported range: ' + match[5]);
+    }
+    let digits = (integer + fraction).replace(/^0+/, '') || '0';
+    if (digits === '0')
+        return 0n;
+    const shift = exponent - fraction.length - scale;
+    let coefficientDigits;
+    let roundUp = false;
+    if (shift >= 0) {
+        // Every supported destination is at most 39 decimal digits. Avoid
+        // constructing an arbitrarily large BigInt for inputs such as 1e999999.
+        if (digits.length + shift > 40) {
+            throw new RangeError('Fixed-point value is outside the signed ' + bits + '-bit range: ' + text);
+        }
+        coefficientDigits = digits + '0'.repeat(shift);
+    }
+    else {
+        const discarded = -shift;
+        if (discarded < digits.length) {
+            const split = digits.length - discarded;
+            coefficientDigits = digits.slice(0, split);
+            roundUp = digits.charCodeAt(split) >= 0x35;
+        }
+        else {
+            coefficientDigits = '0';
+            // If discarded exceeds the number of significant digits, the
+            // magnitude is below 0.1 coefficient and cannot round to one.
+            roundUp = discarded === digits.length && digits.charCodeAt(0) >= 0x35;
+        }
+    }
+    let coefficient = BigInt(coefficientDigits);
+    if (roundUp)
+        coefficient += 1n;
+    if (negative)
+        coefficient = -coefficient;
+    const width = BigInt(bits);
+    const min = -(1n << (width - 1n));
+    const max = (1n << (width - 1n)) - 1n;
+    if (coefficient < min || coefficient > max) {
+        throw new RangeError('Fixed-point value is outside the signed ' + bits + '-bit range: ' + text);
+    }
+    return coefficient;
+}
+//------------------------------------------------------
 class SQLParamDecFloat16 {
     constructor(value) {
         this.value = value;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.15.1",
+    "version": "2.16.1",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/types.ts

@@ -493,6 +493,12 @@ export interface Options {
      * probe is sent (default 60000). Ignored when enableKeepAlive is false.
      */
     keepAliveInitialDelay?: number;
+    /**
+     * Force the TCP socket to IPv4 (4) or IPv6 (6) when resolving `host`.
+     * Unset lets the resolver choose. Set automatically by `inet4://` /
+     * `inet6://` connection URIs.
+     */
+    ipFamily?: 4 | 6;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/src/uri.ts

@@ -20,7 +20,7 @@ const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay', 'ipFamily',
 ]);
 
 function coerce(key: string, value: string): any {
@@ -38,9 +38,31 @@ function coerce(key: string, value: string): any {
 }
 
 /**
- * Parse a firebird:// connection URI into an options object.
+ * URI schemes accepted by parseConnectionUri. `firebird://` is this driver's
+ * own scheme; `inet://`, `inet4://` and `inet6://` are Firebird's native
+ * URL-style connection strings (Firebird 3+), so a string that works with
+ * isql works here too. inet4/inet6 pin the socket's IP family (the
+ * `ipFamily` option); inet and firebird let the resolver pick.
+ */
+const URI_SCHEMES: Record<string, 4 | 6 | undefined> = {
+    'firebird:': undefined,
+    'inet:': undefined,
+    'inet4:': 4,
+    'inet6:': 6,
+};
+
+/**
+ * Firebird protocols this driver cannot speak: they are local-machine IPC
+ * transports (shared memory / named pipes), not TCP.
+ */
+const LOCAL_SCHEMES = /^(xnet|wnet):$/;
+
+/**
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -64,13 +86,23 @@ export function parseConnectionUri(uri: string): Options {
         throw new Error('Invalid connection URI: ' + uri);
     }
 
-    if (url.protocol !== 'firebird:') {
-        throw new Error('Unsupported connection URI scheme "' + url.protocol.replace(/:$/, '') +
-            '" (expected firebird://...)');
+    var scheme = url.protocol.toLowerCase();
+    if (LOCAL_SCHEMES.test(scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (local IPC transports are not available over the wire — use inet:// or firebird://)');
+    }
+    if (!Object.prototype.hasOwnProperty.call(URI_SCHEMES, scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (expected firebird://, inet://, inet4:// or inet6://)');
     }
 
     var options: any = {};
 
+    var ipFamily = URI_SCHEMES[scheme];
+    if (ipFamily !== undefined) {
+        options.ipFamily = ipFamily;
+    }
+
     if (url.hostname) {
         // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
         options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
@@ -182,8 +214,9 @@ export function parseOldStyleConnectionString(str: string): Options {
 const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 export function parseConnectionString(str: string): Options {
     return URI_SCHEME.test(str)
@@ -192,8 +225,9 @@ export function parseConnectionString(str: string): Options {
 }
 
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 export function normalizeOptions<T>(options: T | string): T {

package/src/wire/connection.ts

@@ -186,7 +186,8 @@ class Connection {
         this._detachAuto;
         this._socket = new Socket(port, host,
             options.enableKeepAlive !== false,
-            options.keepAliveInitialDelay);
+            options.keepAliveInitialDelay,
+            options.ipFamily);
         this._pending = [];
         this._isOpened = false;
         this._isClosed = false;
@@ -1453,6 +1454,17 @@ class Connection {
             }
         }
 
+        // Validate fixed-point values before the BLOB pre-pass. Blob uploads
+        // write immediately, so deferring numeric validation until message
+        // encoding could leave transaction blob state behind for a batch that
+        // can never be sent.
+        try {
+            validateBatchFixedPointRows(input, rows as any[][]);
+        } catch (err) {
+            doError(err, callback);
+            return;
+        }
+
         var self = this;
 
         // BLOB pre-pass: upload every Buffer/string blob value as a
@@ -3537,6 +3549,39 @@ function scaleOutputLengths(output: any[], options: any) {
     }
 }
 
+function scaleBatchFixedPoint(value: any, meta: any, bits: 16 | 32 | 64 | 128, column: number): bigint {
+    try {
+        return Xsql.toScaledInteger(value, meta.scale, bits);
+    } catch (err) {
+        var message = err instanceof Error ? err.message : String(err);
+        throw new Error('Invalid fixed-point batch value for column ' + column +
+            ' (' + (meta.field || '?') + '): ' + message);
+    }
+}
+
+/** Validate values whose batch wire representation is metadata-directed.
+ * This runs before BLOB uploads, which may write to the transaction as soon
+ * as executeBatch starts its asynchronous pre-pass. */
+function validateBatchFixedPointRows(input: any[], rows: any[][]): void {
+    for (var i = 0; i < rows.length; i++) {
+        for (var j = 0; j < input.length; j++) {
+            var value = rows[i][j];
+            if (value === null || value === undefined) continue;
+
+            var bits: 16 | 32 | 64 | 128 | undefined = undefined;
+            switch (input[j].type) {
+                case Const.SQL_SHORT: bits = 16; break;
+                case Const.SQL_LONG: bits = 32; break;
+                case Const.SQL_INT64: bits = 64; break;
+                case Const.SQL_INT128: bits = 128; break;
+            }
+            if (bits !== undefined) {
+                scaleBatchFixedPoint(value, input[j], bits, j + 1);
+            }
+        }
+    }
+}
+
 /**
  * Batch support: the engine requires every batch message to use EXACTLY the
  * statement's described input format (unlike op_execute, where the client
@@ -3572,17 +3617,6 @@ function buildBatchEncoders(input: any[], options: any) {
         if (typeof v === 'string') return parseDate(v);
         return new Date(v);
     };
-    var scaled = function(v: any, scale: number): number {
-        var n = typeof v === 'string' ? parseFloat(v) : Number(v);
-        return scale ? Math.round(n * Math.pow(10, -scale)) : n;
-    };
-    var scaledBig = function(v: any, scale: number): bigint {
-        if (typeof v === 'bigint') {
-            return scale ? v * (10n ** BigInt(-scale)) : v;
-        }
-        return BigInt(scaled(v, scale));
-    };
-
     for (var j = 0; j < input.length; j++) {
         var meta = input[j];
         var column = j + 1;
@@ -3615,32 +3649,32 @@ function buildBatchEncoders(input: any[], options: any) {
 
             case Const.SQL_SHORT:
                 // 2 bytes in the message struct (msglen), 4 on the XDR wire
-                encoders.push((function(m) {
-                    return function(msg: any, v: any) { msg.addInt(scaled(v, m.scale)); };
-                })(meta));
+                encoders.push((function(m, col) {
+                    return function(msg: any, v: any) { msg.addInt(Number(scaleBatchFixedPoint(v, m, 16, col))); };
+                })(meta, column));
                 align(2); offset += 2;
                 break;
 
             case Const.SQL_LONG:
-                encoders.push((function(m) {
-                    return function(msg: any, v: any) { msg.addInt(scaled(v, m.scale)); };
-                })(meta));
+                encoders.push((function(m, col) {
+                    return function(msg: any, v: any) { msg.addInt(Number(scaleBatchFixedPoint(v, m, 32, col))); };
+                })(meta, column));
                 align(4); offset += 4;
                 break;
 
             case Const.SQL_INT64:
-                encoders.push((function(m) {
+                encoders.push((function(m, col) {
                     return function(msg: any, v: any) {
-                        msg.addInt64(typeof v === 'bigint' ? (scaledBig(v, m.scale) as any) : scaled(v, m.scale));
+                        msg.addInt64(scaleBatchFixedPoint(v, m, 64, col));
                     };
-                })(meta));
+                })(meta, column));
                 align(8); offset += 8;
                 break;
 
             case Const.SQL_INT128:
-                encoders.push((function(m) {
-                    return function(msg: any, v: any) { msg.addInt128(scaledBig(v, m.scale)); };
-                })(meta));
+                encoders.push((function(m, col) {
+                    return function(msg: any, v: any) { msg.addInt128(scaleBatchFixedPoint(v, m, 128, col)); };
+                })(meta, column));
                 align(8); offset += 16;
                 break;
 

package/src/wire/serialize.ts

@@ -303,7 +303,7 @@ export class XdrWriter {
         const high = bigValue >> BigInt(64);
         const low = bigValue & BigInt("0xFFFFFFFFFFFFFFFF");
 
-        this.buffer.writeBigUInt64BE(high, this.pos);
+        this.buffer.writeBigInt64BE(high, this.pos);
         this.pos += 8;
         this.buffer.writeBigUInt64BE(low, this.pos);
         this.pos += 8;

package/src/wire/socket.ts

@@ -109,8 +109,9 @@ class Socket {
     encryptCipher: any;
     decryptCipher: any;
 
-    constructor(port: number, host: string, enableKeepAlive = true, keepAliveInitialDelay = 60000) {
-        this._socket = net.createConnection(port, host);
+    constructor(port: number, host: string, enableKeepAlive = true, keepAliveInitialDelay = 60000, ipFamily?: 4 | 6) {
+        // family: 0 is "either" (Node's default); 4/6 pin the resolver
+        this._socket = net.createConnection({ port: port, host: host, family: ipFamily || 0 });
         this._socket.setNoDelay(true);
         // TCP keepalive probing detects dead/stale connections; the delay is
         // how long the socket must be idle before the first probe.

package/src/wire/xsqlvar.ts

@@ -11,8 +11,6 @@ import type { NumericMode, RecordCounts } from '../types';
  *
  ***************************************/
 
-const
-    ScaleDivisor = [1,10,100,1000,10000,100000,1000000,10000000,100000000,1000000000,10000000000, 100000000000,1000000000000,10000000000000,100000000000000,1000000000000000];
 const
     DateOffset = 40587,
     TimeCoeff = 86400000,
@@ -26,6 +24,25 @@ type NumericDecodeOptions = {
     numericMode?: NumericMode;
 };
 
+/**
+ * Apply a Firebird numeric scale to a value already narrowed to a JS number.
+ *
+ * This replaces the former lookup table of divisors, which only held
+ * 10^0..10^15: any larger scale indexed past its end and yielded NaN. That is
+ * reachable for INT64 (NUMERIC(18,18)) and routine for INT128, where the scale
+ * runs to 38. Math.pow(10, n) returns the identical double for every exponent
+ * the table did cover, so in-range results are unchanged.
+ *
+ * Positive scales multiply, matching decodeExactNumeric and formatScaledBigInt;
+ * the table path divided by them, which was the wrong direction.
+ */
+function applyScale(value: number, scale: number): number {
+    if (!scale) return value;
+    return scale < 0
+        ? value / Math.pow(10, -scale)
+        : value * Math.pow(10, scale);
+}
+
 /** Format a signed Firebird integer coefficient without passing through Number. */
 function formatScaledBigInt(value: bigint, scale: number): string {
     const negative = value < 0n;
@@ -51,11 +68,17 @@ function decodeExactNumeric(value: bigint, scale: number, mode: 'safe' | 'string
 
 /** Decode INT128 using the mixed number/string policy of lossy mode. */
 function decodeLossyInt128(value: bigint, scale: number): number | string {
-    if (value > MAX_SAFE_BIGINT) {
+    // Both bounds matter, as in decodeExactNumeric. While this path read the
+    // coefficient unsigned, every negative arrived as a huge positive and so
+    // always took the exact-string branch, which masked the missing lower
+    // bound. Now that the reader is signed, a large negative would otherwise
+    // fall through to Number() and lose precision while its positive twin
+    // stayed exact.
+    if (value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
         return formatScaledBigInt(value, scale);
     }
 
-    return Number(value) / ScaleDivisor[Math.abs(scale)];
+    return applyScale(Number(value), scale);
 }
 
 /**
@@ -564,9 +587,7 @@ export class SQLVarInt extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean) {
         var ret = data.readInt();
 
-        if (this.scale) {
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
-        }
+        ret = applyScale(ret, this.scale);
 
         if (!lowerV13 || !data.readInt()) {
             return ret;
@@ -599,7 +620,7 @@ export class SQLVarInt64 extends SQLVarBase {
 
         if (mode === Const.NUMERIC_MODE_LOSSY) {
             ret = data.readInt64();
-            if (this.scale) ret = ret / ScaleDivisor[Math.abs(this.scale)];
+            ret = applyScale(ret, this.scale);
         } else {
             ret = decodeExactNumeric(data.readInt64BigInt(), this.scale, mode);
         }
@@ -622,7 +643,7 @@ export class SQLVarInt128 extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: NumericDecodeOptions) {
         const mode = options?.numericMode || Const.NUMERIC_MODE_LOSSY;
         const ret = mode === Const.NUMERIC_MODE_LOSSY
-            ? decodeLossyInt128(data.readInt128(), this.scale)
+            ? decodeLossyInt128(data.readInt128Signed(), this.scale)
             : decodeExactNumeric(data.readInt128Signed(), this.scale, mode);
 
         if (!lowerV13 || !data.readInt()) {
@@ -957,6 +978,83 @@ export class SQLParamInt128 {
 
 //------------------------------------------------------
 
+const FIXED_POINT_RE = /^([+-]?)(?:(\d+)(?:\.(\d*))?|\.(\d+))(?:[eE]([+-]?\d+))?$/;
+
+/**
+ * Convert a decimal input to the signed integer coefficient used by a
+ * Firebird fixed-point wire type. Numbers are interpreted through their
+ * canonical decimal string; strings and bigints never pass through Number.
+ * Digits discarded by the target scale are rounded to nearest, ties away
+ * from zero, matching Firebird's conversion of decimal parameter text.
+ */
+export function toScaledInteger(value: number | string | bigint, scale: number, bits: 16 | 32 | 64 | 128): bigint {
+    if (!Number.isSafeInteger(scale)) {
+        throw new TypeError('Fixed-point scale must be an integer');
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new TypeError('Fixed-point value must be finite');
+    }
+    if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'bigint') {
+        throw new TypeError('Fixed-point value must be a number, string, or bigint');
+    }
+
+    const text = String(value).trim();
+    const match = FIXED_POINT_RE.exec(text);
+    if (!match) {
+        throw new TypeError('Invalid fixed-point value: ' + text);
+    }
+
+    const negative = match[1] === '-';
+    const integer = match[2] || '0';
+    const fraction = match[3] !== undefined ? match[3] : (match[4] || '');
+    const exponent = match[5] === undefined ? 0 : Number(match[5]);
+    if (!Number.isSafeInteger(exponent)) {
+        throw new RangeError('Fixed-point exponent is outside the supported range: ' + match[5]);
+    }
+
+    let digits = (integer + fraction).replace(/^0+/, '') || '0';
+    if (digits === '0') return 0n;
+
+    const shift = exponent - fraction.length - scale;
+    let coefficientDigits: string;
+    let roundUp = false;
+
+    if (shift >= 0) {
+        // Every supported destination is at most 39 decimal digits. Avoid
+        // constructing an arbitrarily large BigInt for inputs such as 1e999999.
+        if (digits.length + shift > 40) {
+            throw new RangeError('Fixed-point value is outside the signed ' + bits + '-bit range: ' + text);
+        }
+        coefficientDigits = digits + '0'.repeat(shift);
+    } else {
+        const discarded = -shift;
+        if (discarded < digits.length) {
+            const split = digits.length - discarded;
+            coefficientDigits = digits.slice(0, split);
+            roundUp = digits.charCodeAt(split) >= 0x35;
+        } else {
+            coefficientDigits = '0';
+            // If discarded exceeds the number of significant digits, the
+            // magnitude is below 0.1 coefficient and cannot round to one.
+            roundUp = discarded === digits.length && digits.charCodeAt(0) >= 0x35;
+        }
+    }
+
+    let coefficient = BigInt(coefficientDigits);
+    if (roundUp) coefficient += 1n;
+    if (negative) coefficient = -coefficient;
+
+    const width = BigInt(bits);
+    const min = -(1n << (width - 1n));
+    const max = (1n << (width - 1n)) - 1n;
+    if (coefficient < min || coefficient > max) {
+        throw new RangeError('Fixed-point value is outside the signed ' + bits + '-bit range: ' + text);
+    }
+    return coefficient;
+}
+
+//------------------------------------------------------
+
 export class SQLParamDecFloat16 {
     value: any;