node-firebird 2.14.4 → 2.15.0

package/README.md

@@ -210,6 +210,7 @@ options.jsonAsObject = false; // optional; automatically stringify parameters an
 options.namedPlaceholders = false; // set to true to allow :name placeholders in SQL with a { name: value } params object (see Named placeholders)
 options.nestTables = false; // true nests object rows by source table (row[table][column]); a string separator flattens to 'table<sep>column' keys — see Nested result tables (nestTables). Overridable per query
 options.transformKeys = undefined; // 'camel' (FIRST_NAME → firstName) or a (key) => key mapper for object-row keys — see Transforming row keys (transformKeys). Overridable per query
+options.numericMode = Firebird.NUMERIC_MODE_LOSSY; // INT64/INT128 result policy: LOSSY (default), SAFE, or STRING
 options.typeCast = undefined; // optional; custom type parser called for every result column value (see Custom type parsers)
 options.statementCacheSize = 0; // optional; per-connection LRU cache of prepared statements, 0 = disabled (see Prepared-statement cache)
 ```
@@ -738,6 +739,48 @@ on databases and transactions alike. It is ignored by the streaming APIs
 PROCEDURE`, `affectedRows` reflects DML the procedure performed — a
 procedure that only returns values reports 0 alongside its row.
 
+### Fixed-point numeric results (numericMode)
+
+Firebird sends `BIGINT`, `INT128`, and the `NUMERIC`/`DECIMAL` types backed by
+them as signed integer coefficients plus a decimal scale. JavaScript numbers
+cannot represent every INT64 or INT128 coefficient exactly. The connection
+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_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.
+
+`SAFE` tests the raw integer coefficient against JavaScript's inclusive safe
+range (`Number.MIN_SAFE_INTEGER` through `Number.MAX_SAFE_INTEGER`) before
+applying its scale. `STRING` provides a stable result type and retains zeroes
+implied by the declared scale:
+
+```js
+const db = await Firebird.attachAsync({
+    ...options,
+    numericMode: Firebird.NUMERIC_MODE_STRING,
+});
+
+// BIGINT 42                     -> '42'
+// DECIMAL coefficient 420000,-4 -> '42.0000'
+```
+
+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
+parameter encoding. A `SAFE` result returned as a number still has the normal
+IEEE-754 behavior of JavaScript fractional numbers; use `STRING` when the
+decimal representation itself must remain exact.
+
 ### Custom type parsers (typeCast)
 
 The `typeCast` connection option lets you override how column values are
@@ -758,10 +801,6 @@ Firebird.attach({
             const v = next();
             return v === null ? null : v.toISOString().slice(0, 10);
         }
-        // BIGINT columns as strings
-        if (column.type === Firebird.SQL_TYPES.SQL_INT64 && !column.scale) {
-            return String(next());
-        }
         return next(); // everything else: default decoding
     },
 }, (err, db) => { /* ... */ });
@@ -782,6 +821,9 @@ Firebird.attach({
 
 Notes:
 
+- The hook runs after [`numericMode`](#fixed-point-numeric-results-numericmode).
+  Calling `String(next())` cannot recover digits already lost by lossy
+  numeric decoding; select `SAFE` or `STRING` when exact coefficients matter.
 - Non-text BLOB columns reach the hook as the usual asynchronous fetch
   function; text BLOBs with `blobAsText: true` reach it as the resolved
   string.

package/lib/index.d.ts

@@ -13,6 +13,12 @@ export declare const AUTH_PLUGIN_SRP384: string;
 export declare const AUTH_PLUGIN_SRP512: string;
 export declare const WIRE_CRYPT_DISABLE: number;
 export declare const WIRE_CRYPT_ENABLE: number;
+/** Decode through JavaScript Number where applicable; unsafe coefficients may lose precision. */
+export declare const NUMERIC_MODE_LOSSY: "lossy";
+/** Return safe INT64/INT128 coefficients as numbers and unsafe ones as exact strings. */
+export declare const NUMERIC_MODE_SAFE: "safe";
+/** Return every INT64/INT128-backed fixed-point value as an exact string. */
+export declare const NUMERIC_MODE_STRING: "string";
 /** A transaction sees changes done by uncommitted transactions. */
 export declare const ISOLATION_READ_UNCOMMITTED: number[];
 /** A transaction sees only data committed before the statement has been executed. */

package/lib/index.js

@@ -17,9 +17,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isc_dpb_old_num_files = exports.isc_dpb_old_file_size = exports.isc_dpb_online_dump = exports.isc_dpb_interp = exports.isc_dpb_sys_user_name_enc = exports.isc_dpb_password_enc = exports.isc_dpb_password = exports.isc_dpb_user_name = exports.isc_dpb_no_reserve = exports.isc_dpb_quit_log = exports.isc_dpb_begin_log = exports.isc_dpb_force_write = exports.isc_dpb_delete_shadow = exports.isc_dpb_sweep_interval = exports.isc_dpb_activate_shadow = exports.isc_dpb_encrypt_key = exports.isc_dpb_sys_user_name = exports.isc_dpb_license = exports.isc_dpb_damaged = exports.isc_dpb_no_garbage_collect = exports.isc_dpb_trace = exports.isc_dpb_number_of_users = exports.isc_dpb_dbkey_scope = exports.isc_dpb_disable_journal = exports.isc_dpb_enable_journal = exports.isc_dpb_sweep = exports.isc_dpb_verify = exports.isc_dpb_garbage_collect = exports.isc_dpb_debug = exports.isc_dpb_buffer_length = exports.isc_dpb_num_buffers = exports.isc_dpb_page_size = exports.isc_dpb_journal = exports.isc_dpb_allocation = exports.isc_dpb_cdd_pathname = exports.isc_dpb_version2 = exports.isc_dpb_version1 = exports.ISOLATION_READ_COMMITTED_READ_ONLY = exports.ISOLATION_SERIALIZABLE = exports.ISOLATION_REPEATABLE_READ = exports.ISOLATION_READ_COMMITTED = exports.ISOLATION_READ_UNCOMMITTED = exports.WIRE_CRYPT_ENABLE = exports.WIRE_CRYPT_DISABLE = exports.AUTH_PLUGIN_SRP512 = exports.AUTH_PLUGIN_SRP384 = exports.AUTH_PLUGIN_SRP256 = exports.AUTH_PLUGIN_SRP = exports.AUTH_PLUGIN_LEGACY = exports.GDSCode = void 0;
-exports.isc_dpb_set_db_replica = exports.isc_dpb_session_time_zone = exports.isc_dpb_map_attach = exports.isc_dpb_reset_icu = exports.isc_dpb_nolinger = exports.isc_dpb_config = exports.isc_dpb_auth_plugin_name = exports.isc_dpb_auth_plugin_list = exports.isc_dpb_specific_auth_data = exports.isc_dpb_os_user = exports.isc_dpb_host_name = exports.isc_dpb_remote_protocol = exports.isc_dpb_client_version = exports.isc_dpb_auth_block = exports.isc_dpb_ext_call_depth = exports.isc_dpb_utf8_filename = exports.isc_dpb_org_filename = exports.isc_dpb_trusted_role = exports.isc_dpb_process_name = exports.isc_dpb_trusted_auth = exports.isc_dpb_no_db_triggers = exports.isc_dpb_process_id = exports.isc_dpb_address_path = exports.isc_dpb_gsec_attach = exports.isc_dpb_set_db_charset = exports.isc_dpb_gstat_attach = exports.isc_dpb_gfix_attach = exports.isc_dpb_set_db_sql_dialect = exports.isc_dpb_set_db_readonly = exports.isc_dpb_sql_dialect = exports.isc_dpb_working_directory = exports.isc_dpb_set_page_buffers = exports.isc_dpb_sql_role_name = exports.isc_dpb_gbak_attach = exports.isc_dpb_dummy_packet_interval = exports.isc_dpb_connect_timeout = exports.isc_dpb_sec_attach = exports.isc_dpb_overwrite = exports.isc_dpb_reserved = exports.isc_dpb_shutdown_delay = exports.isc_dpb_online = exports.isc_dpb_shutdown = exports.isc_dpb_cache_manager = exports.isc_dpb_lc_ctype = exports.isc_dpb_lc_messages = exports.isc_dpb_old_dump_id = exports.isc_dpb_old_start_file = exports.isc_dpb_old_start_seqno = exports.isc_dpb_old_start_page = exports.isc_dpb_old_file = void 0;
-exports.parseNamedPlaceholders = exports.parseConnectionString = exports.parseConnectionUri = exports.connection = exports.SQL_TYPES = exports.escape = exports.isc_dpb_search_path = exports.isc_dpb_max_inline_blob_size = exports.isc_dpb_max_blob_cache_size = exports.isc_dpb_owner = exports.isc_dpb_worker_attach = exports.isc_dpb_parallel_workers = exports.isc_dpb_upgrade_db = exports.isc_dpb_clear_map = exports.isc_dpb_decfloat_traps = exports.isc_dpb_decfloat_round = exports.isc_dpb_set_bind = void 0;
+exports.isc_dpb_interp = exports.isc_dpb_sys_user_name_enc = exports.isc_dpb_password_enc = exports.isc_dpb_password = exports.isc_dpb_user_name = exports.isc_dpb_no_reserve = exports.isc_dpb_quit_log = exports.isc_dpb_begin_log = exports.isc_dpb_force_write = exports.isc_dpb_delete_shadow = exports.isc_dpb_sweep_interval = exports.isc_dpb_activate_shadow = exports.isc_dpb_encrypt_key = exports.isc_dpb_sys_user_name = exports.isc_dpb_license = exports.isc_dpb_damaged = exports.isc_dpb_no_garbage_collect = exports.isc_dpb_trace = exports.isc_dpb_number_of_users = exports.isc_dpb_dbkey_scope = exports.isc_dpb_disable_journal = exports.isc_dpb_enable_journal = exports.isc_dpb_sweep = exports.isc_dpb_verify = exports.isc_dpb_garbage_collect = exports.isc_dpb_debug = exports.isc_dpb_buffer_length = exports.isc_dpb_num_buffers = exports.isc_dpb_page_size = exports.isc_dpb_journal = exports.isc_dpb_allocation = exports.isc_dpb_cdd_pathname = exports.isc_dpb_version2 = exports.isc_dpb_version1 = exports.ISOLATION_READ_COMMITTED_READ_ONLY = exports.ISOLATION_SERIALIZABLE = exports.ISOLATION_REPEATABLE_READ = exports.ISOLATION_READ_COMMITTED = exports.ISOLATION_READ_UNCOMMITTED = exports.NUMERIC_MODE_STRING = exports.NUMERIC_MODE_SAFE = exports.NUMERIC_MODE_LOSSY = exports.WIRE_CRYPT_ENABLE = exports.WIRE_CRYPT_DISABLE = exports.AUTH_PLUGIN_SRP512 = exports.AUTH_PLUGIN_SRP384 = exports.AUTH_PLUGIN_SRP256 = exports.AUTH_PLUGIN_SRP = exports.AUTH_PLUGIN_LEGACY = exports.GDSCode = void 0;
+exports.isc_dpb_reset_icu = exports.isc_dpb_nolinger = exports.isc_dpb_config = exports.isc_dpb_auth_plugin_name = exports.isc_dpb_auth_plugin_list = exports.isc_dpb_specific_auth_data = exports.isc_dpb_os_user = exports.isc_dpb_host_name = exports.isc_dpb_remote_protocol = exports.isc_dpb_client_version = exports.isc_dpb_auth_block = exports.isc_dpb_ext_call_depth = exports.isc_dpb_utf8_filename = exports.isc_dpb_org_filename = exports.isc_dpb_trusted_role = exports.isc_dpb_process_name = exports.isc_dpb_trusted_auth = exports.isc_dpb_no_db_triggers = exports.isc_dpb_process_id = exports.isc_dpb_address_path = exports.isc_dpb_gsec_attach = exports.isc_dpb_set_db_charset = exports.isc_dpb_gstat_attach = exports.isc_dpb_gfix_attach = exports.isc_dpb_set_db_sql_dialect = exports.isc_dpb_set_db_readonly = exports.isc_dpb_sql_dialect = exports.isc_dpb_working_directory = exports.isc_dpb_set_page_buffers = exports.isc_dpb_sql_role_name = exports.isc_dpb_gbak_attach = exports.isc_dpb_dummy_packet_interval = exports.isc_dpb_connect_timeout = exports.isc_dpb_sec_attach = exports.isc_dpb_overwrite = exports.isc_dpb_reserved = exports.isc_dpb_shutdown_delay = exports.isc_dpb_online = exports.isc_dpb_shutdown = exports.isc_dpb_cache_manager = exports.isc_dpb_lc_ctype = exports.isc_dpb_lc_messages = exports.isc_dpb_old_dump_id = exports.isc_dpb_old_start_file = exports.isc_dpb_old_start_seqno = exports.isc_dpb_old_start_page = exports.isc_dpb_old_file = exports.isc_dpb_old_num_files = exports.isc_dpb_old_file_size = exports.isc_dpb_online_dump = void 0;
+exports.parseNamedPlaceholders = exports.parseConnectionString = exports.parseConnectionUri = exports.connection = exports.SQL_TYPES = exports.escape = exports.isc_dpb_search_path = exports.isc_dpb_max_inline_blob_size = exports.isc_dpb_max_blob_cache_size = exports.isc_dpb_owner = exports.isc_dpb_worker_attach = exports.isc_dpb_parallel_workers = exports.isc_dpb_upgrade_db = exports.isc_dpb_clear_map = exports.isc_dpb_decfloat_traps = exports.isc_dpb_decfloat_round = exports.isc_dpb_set_bind = exports.isc_dpb_set_db_replica = exports.isc_dpb_session_time_zone = exports.isc_dpb_map_attach = void 0;
 exports.attach = attach;
 exports.drop = drop;
 exports.create = create;
@@ -54,6 +54,12 @@ exports.AUTH_PLUGIN_SRP384 = const_1.default.AUTH_PLUGIN_SRP384;
 exports.AUTH_PLUGIN_SRP512 = const_1.default.AUTH_PLUGIN_SRP512;
 exports.WIRE_CRYPT_DISABLE = const_1.default.WIRE_CRYPT_DISABLE;
 exports.WIRE_CRYPT_ENABLE = const_1.default.WIRE_CRYPT_ENABLE;
+/** Decode through JavaScript Number where applicable; unsafe coefficients may lose precision. */
+exports.NUMERIC_MODE_LOSSY = const_1.default.NUMERIC_MODE_LOSSY;
+/** Return safe INT64/INT128 coefficients as numbers and unsafe ones as exact strings. */
+exports.NUMERIC_MODE_SAFE = const_1.default.NUMERIC_MODE_SAFE;
+/** Return every INT64/INT128-backed fixed-point value as an exact string. */
+exports.NUMERIC_MODE_STRING = const_1.default.NUMERIC_MODE_STRING;
 /** A transaction sees changes done by uncommitted transactions. */
 exports.ISOLATION_READ_UNCOMMITTED = const_1.default.ISOLATION_READ_UNCOMMITTED;
 /** A transaction sees only data committed before the statement has been executed. */

package/lib/types.d.ts

@@ -58,6 +58,8 @@ export interface ColumnMetadata {
     collationId?: number;
 }
 export type Isolation = number[];
+/** Result conversion policy for INT64/INT128-backed fixed-point values. */
+export type NumericMode = 'lossy' | 'safe' | 'string';
 export type TransactionOptions = {
     autoCommit?: boolean;
     autoUndo?: boolean;
@@ -373,6 +375,17 @@ export interface Options {
      */
     blobReadChunkSize?: number;
     wireCrypt?: number;
+    /**
+     * Result conversion policy for BIGINT/INT128 and fixed-point
+     * NUMERIC/DECIMAL values backed by them.
+     *
+     * - `lossy` (default) decodes through JavaScript `Number` where
+     *   applicable; unsafe coefficients may lose precision.
+     * - `safe` returns a number when the raw integer coefficient is within
+     *   JavaScript's safe range, otherwise an exact scaled string.
+     * - `string` always returns an exact scaled string.
+     */
+    numericMode?: NumericMode;
     wireCompression?: boolean;
     /**
      * Enable named placeholders: SQL may use `:name` markers and params may

package/lib/uri.js

@@ -189,7 +189,14 @@ function normalizeOptions(options) {
     if (typeof options === 'string') {
         options = parseConnectionString(options);
     }
-    return applyEnvDefaults(options);
+    const normalized = applyEnvDefaults(options);
+    const numericMode = normalized && normalized.numericMode;
+    if (numericMode !== undefined && numericMode !== 'lossy' &&
+        numericMode !== 'safe' && numericMode !== 'string') {
+        throw new Error('Invalid numericMode option: ' + numericMode +
+            ' (expected "lossy", "safe", or "string")');
+    }
+    return normalized;
 }
 /**
  * Fall back to environment variables for connection settings the caller

package/lib/wire/const.d.ts

@@ -16,6 +16,9 @@ declare const Const: Readonly<{
     MAX_BUFFER_SIZE: number;
     MAX_INT: number;
     MIN_INT: number;
+    NUMERIC_MODE_LOSSY: 'lossy';
+    NUMERIC_MODE_SAFE: 'safe';
+    NUMERIC_MODE_STRING: 'string';
     op_void: number;
     op_connect: number;
     op_exit: number;

package/lib/wire/const.js

@@ -22,6 +22,11 @@ const int = {
     MAX_INT: Math.pow(2, 31) - 1,
     MIN_INT: -Math.pow(2, 31),
 };
+const numericMode = {
+    NUMERIC_MODE_LOSSY: 'lossy',
+    NUMERIC_MODE_SAFE: 'safe',
+    NUMERIC_MODE_STRING: 'string',
+};
 const op = {
     op_void: 0, // Packet has been voided
     op_connect: 1, // Connect to remote server
@@ -861,6 +866,7 @@ const Const = Object.freeze({
     ...int,
     ...iscAction,
     ...iscError,
+    ...numericMode,
     ...op,
     ...protocol,
     ...service,

package/lib/wire/serialize.d.ts

@@ -93,7 +93,9 @@ export declare class XdrReader {
     readInt(): number;
     readUInt(): number;
     readInt64(): number;
+    readInt64BigInt(): bigint;
     readInt128(): bigint;
+    readInt128Signed(): bigint;
     readDecFloat16(): string | number;
     readDecFloat34(): string | number;
     readShort(): number;

package/lib/wire/serialize.js

@@ -370,7 +370,10 @@ class XdrReader {
         // Note: precision is limited to Number.MAX_SAFE_INTEGER (±2^53-1).
         // Values outside this range lose precision, which matches the previous
         // Long(low, high).toNumber() behaviour.
-        const result = Number(this.buffer.readBigInt64BE(this.pos));
+        return Number(this.readInt64BigInt());
+    }
+    readInt64BigInt() {
+        const result = this.buffer.readBigInt64BE(this.pos);
         this.pos += 8;
         return result;
     }
@@ -381,6 +384,13 @@ class XdrReader {
         this.pos += 8;
         return (BigInt(high) << BigInt(64)) + BigInt(low);
     }
+    readInt128Signed() {
+        var high = this.buffer.readBigInt64BE(this.pos);
+        this.pos += 8;
+        var low = this.buffer.readBigUInt64BE(this.pos);
+        this.pos += 8;
+        return (BigInt(high) << BigInt(64)) + BigInt(low);
+    }
     readDecFloat16() {
         // DECFLOAT(16) - IEEE 754 Decimal64 - 8 bytes
         // Full IEEE 754-2008 Decimal64 implementation

package/lib/wire/xsqlvar.d.ts

@@ -1,6 +1,9 @@
 import type { TextCodec } from './codepages';
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
-import type { RecordCounts } from '../types';
+import type { NumericMode, RecordCounts } from '../types';
+type NumericDecodeOptions = {
+    numericMode?: NumericMode;
+};
 export declare function getFirebirdCharsetWidth(charset?: string): number;
 /**
  * Resolve the Node.js Buffer encoding to use when decoding text from a
@@ -197,11 +200,11 @@ export declare class SQLVarShort extends SQLVarInt {
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarInt64 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): number | null;
+    decode(data: XdrReader, lowerV13: boolean, options?: NumericDecodeOptions): string | number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarInt128 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): string | number | null;
+    decode(data: XdrReader, lowerV13: boolean, options?: NumericDecodeOptions): string | number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarDecFloat16 extends SQLVarBase {

package/lib/wire/xsqlvar.js

@@ -30,6 +30,37 @@ const codepages_1 = require("./codepages");
 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);
+/** Format a signed Firebird integer coefficient without passing through Number. */
+function formatScaledBigInt(value, scale) {
+    const negative = value < 0n;
+    let digits = (negative ? -value : value).toString();
+    const sign = negative ? '-' : '';
+    if (scale === 0)
+        return sign + digits;
+    if (scale > 0)
+        return sign + digits + '0'.repeat(scale);
+    const places = -scale;
+    if (digits.length <= places)
+        digits = digits.padStart(places + 1, '0');
+    return sign + digits.slice(0, -places) + '.' + digits.slice(-places);
+}
+function decodeExactNumeric(value, scale, mode) {
+    if (mode === 'string' || value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
+        return formatScaledBigInt(value, scale);
+    }
+    return scale < 0
+        ? Number(value) / Math.pow(10, -scale)
+        : Number(value) * Math.pow(10, scale);
+}
+/** Decode INT128 using the mixed number/string policy of lossy mode. */
+function decodeLossyInt128(value, scale) {
+    if (value > MAX_SAFE_BIGINT) {
+        return formatScaledBigInt(value, scale);
+    }
+    return Number(value) / ScaleDivisor[Math.abs(scale)];
+}
 /**
  * Maps Firebird character-set names (upper-case) to the Node.js Buffer
  * encoding string used by Buffer.toString() / Buffer.from().
@@ -480,10 +511,16 @@ class SQLVarShort extends SQLVarInt {
 exports.SQLVarShort = SQLVarShort;
 //------------------------------------------------------
 class SQLVarInt64 extends SQLVarBase {
-    decode(data, lowerV13) {
-        var ret = data.readInt64();
-        if (this.scale) {
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
+    decode(data, lowerV13, options) {
+        const mode = options?.numericMode || const_1.default.NUMERIC_MODE_LOSSY;
+        let ret;
+        if (mode === const_1.default.NUMERIC_MODE_LOSSY) {
+            ret = data.readInt64();
+            if (this.scale)
+                ret = ret / ScaleDivisor[Math.abs(this.scale)];
+        }
+        else {
+            ret = decodeExactNumeric(data.readInt64BigInt(), this.scale, mode);
         }
         if (!lowerV13 || !data.readInt()) {
             return ret;
@@ -498,21 +535,11 @@ class SQLVarInt64 extends SQLVarBase {
 exports.SQLVarInt64 = SQLVarInt64;
 //------------------------------------------------------
 class SQLVarInt128 extends SQLVarBase {
-    decode(data, lowerV13) {
-        var retBigInt = BigInt(data.readInt128());
-        let ret;
-        if (retBigInt > BigInt(Number.MAX_SAFE_INTEGER)) {
-            ret = retBigInt.toString();
-            var integerPart = ret.slice(0, Math.abs(this.scale) * -1);
-            var decimalPart = ret.slice(Math.abs(this.scale) * -1);
-            if (integerPart === '')
-                integerPart = '0';
-            ret = `${integerPart}.${decimalPart}`;
-        }
-        else {
-            ret = Number(retBigInt);
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
-        }
+    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)
+            : decodeExactNumeric(data.readInt128Signed(), this.scale, mode);
         if (!lowerV13 || !data.readInt()) {
             return ret;
         }

package/package.json

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

package/src/index.ts

@@ -35,6 +35,13 @@ export const AUTH_PLUGIN_SRP512: string = Const.AUTH_PLUGIN_SRP512;
 export const WIRE_CRYPT_DISABLE: number = Const.WIRE_CRYPT_DISABLE;
 export const WIRE_CRYPT_ENABLE: number = Const.WIRE_CRYPT_ENABLE;
 
+/** Decode through JavaScript Number where applicable; unsafe coefficients may lose precision. */
+export const NUMERIC_MODE_LOSSY = Const.NUMERIC_MODE_LOSSY;
+/** Return safe INT64/INT128 coefficients as numbers and unsafe ones as exact strings. */
+export const NUMERIC_MODE_SAFE = Const.NUMERIC_MODE_SAFE;
+/** Return every INT64/INT128-backed fixed-point value as an exact string. */
+export const NUMERIC_MODE_STRING = Const.NUMERIC_MODE_STRING;
+
 /** A transaction sees changes done by uncommitted transactions. */
 export const ISOLATION_READ_UNCOMMITTED: number[] = Const.ISOLATION_READ_UNCOMMITTED;
 /** A transaction sees only data committed before the statement has been executed. */

package/src/types.ts

@@ -70,6 +70,9 @@ export interface ColumnMetadata {
 
 export type Isolation = number[];
 
+/** Result conversion policy for INT64/INT128-backed fixed-point values. */
+export type NumericMode = 'lossy' | 'safe' | 'string';
+
 export type TransactionOptions = {
     autoCommit?: boolean;
     autoUndo?: boolean;
@@ -433,6 +436,17 @@ export interface Options {
      */
     blobReadChunkSize?: number;
     wireCrypt?: number; // WIRE_CRYPT_DISABLE or WIRE_CRYPT_ENABLE
+    /**
+     * Result conversion policy for BIGINT/INT128 and fixed-point
+     * NUMERIC/DECIMAL values backed by them.
+     *
+     * - `lossy` (default) decodes through JavaScript `Number` where
+     *   applicable; unsafe coefficients may lose precision.
+     * - `safe` returns a number when the raw integer coefficient is within
+     *   JavaScript's safe range, otherwise an exact scaled string.
+     * - `string` always returns an exact scaled string.
+     */
+    numericMode?: NumericMode;
     wireCompression?: boolean;
     /**
      * Enable named placeholders: SQL may use `:name` markers and params may

package/src/uri.ts

@@ -200,7 +200,14 @@ export function normalizeOptions<T>(options: T | string): T {
     if (typeof options === 'string') {
         options = parseConnectionString(options) as T;
     }
-    return applyEnvDefaults(options as any);
+    const normalized = applyEnvDefaults(options as any);
+    const numericMode = normalized && normalized.numericMode;
+    if (numericMode !== undefined && numericMode !== 'lossy' &&
+        numericMode !== 'safe' && numericMode !== 'string') {
+        throw new Error('Invalid numericMode option: ' + numericMode +
+            ' (expected "lossy", "safe", or "string")');
+    }
+    return normalized;
 }
 
 /**

package/src/wire/const.ts

@@ -25,6 +25,12 @@ const int = {
     MIN_INT : -Math.pow(2, 31),
 };
 
+const numericMode = {
+    NUMERIC_MODE_LOSSY : 'lossy',
+    NUMERIC_MODE_SAFE : 'safe',
+    NUMERIC_MODE_STRING : 'string',
+} as const;
+
 const op = {
     op_void                   : 0,  // Packet has been voided
     op_connect                : 1,  // Connect to remote server
@@ -929,6 +935,7 @@ const Const = Object.freeze({
     ...int,
     ...iscAction,
     ...iscError,
+    ...numericMode,
     ...op,
     ...protocol,
     ...service,

package/src/wire/serialize.ts

@@ -481,12 +481,16 @@ export class XdrReader {
         // Note: precision is limited to Number.MAX_SAFE_INTEGER (±2^53-1).
         // Values outside this range lose precision, which matches the previous
         // Long(low, high).toNumber() behaviour.
-        const result = Number(this.buffer.readBigInt64BE(this.pos));
+        return Number(this.readInt64BigInt());
+    }
+
+    readInt64BigInt(): bigint {
+        const result = this.buffer.readBigInt64BE(this.pos);
         this.pos += 8;
         return result;
     }
 
-    readInt128() {
+    readInt128(): bigint {
         var high = this.buffer.readBigUInt64BE(this.pos)
         this.pos += 8
 
@@ -496,6 +500,16 @@ export class XdrReader {
         return (BigInt(high) << BigInt(64)) + BigInt(low)
     }
 
+    readInt128Signed(): bigint {
+        var high = this.buffer.readBigInt64BE(this.pos)
+        this.pos += 8
+
+        var low = this.buffer.readBigUInt64BE(this.pos)
+        this.pos += 8
+
+        return (BigInt(high) << BigInt(64)) + BigInt(low)
+    }
+
     readDecFloat16() {
         // DECFLOAT(16) - IEEE 754 Decimal64 - 8 bytes
         // Full IEEE 754-2008 Decimal64 implementation

package/src/wire/xsqlvar.ts

@@ -3,7 +3,7 @@ import { BlrReader } from './serialize';
 import { getCodec } from './codepages';
 import type { TextCodec } from './codepages';
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
-import type { RecordCounts } from '../types';
+import type { NumericMode, RecordCounts } from '../types';
 
 /***************************************
  *
@@ -19,6 +19,44 @@ const
     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);
+
+type NumericDecodeOptions = {
+    numericMode?: NumericMode;
+};
+
+/** Format a signed Firebird integer coefficient without passing through Number. */
+function formatScaledBigInt(value: bigint, scale: number): string {
+    const negative = value < 0n;
+    let digits = (negative ? -value : value).toString();
+    const sign = negative ? '-' : '';
+
+    if (scale === 0) return sign + digits;
+    if (scale > 0) return sign + digits + '0'.repeat(scale);
+
+    const places = -scale;
+    if (digits.length <= places) digits = digits.padStart(places + 1, '0');
+    return sign + digits.slice(0, -places) + '.' + digits.slice(-places);
+}
+
+function decodeExactNumeric(value: bigint, scale: number, mode: 'safe' | 'string'): number | string {
+    if (mode === 'string' || value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
+        return formatScaledBigInt(value, scale);
+    }
+    return scale < 0
+        ? Number(value) / Math.pow(10, -scale)
+        : Number(value) * Math.pow(10, scale);
+}
+
+/** Decode INT128 using the mixed number/string policy of lossy mode. */
+function decodeLossyInt128(value: bigint, scale: number): number | string {
+    if (value > MAX_SAFE_BIGINT) {
+        return formatScaledBigInt(value, scale);
+    }
+
+    return Number(value) / ScaleDivisor[Math.abs(scale)];
+}
 
 /**
  * Maps Firebird character-set names (upper-case) to the Node.js Buffer
@@ -555,11 +593,15 @@ export class SQLVarShort extends SQLVarInt {
 //------------------------------------------------------
 
 export class SQLVarInt64 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean) {
-        var ret = data.readInt64();
+    decode(data: XdrReader, lowerV13: boolean, options?: NumericDecodeOptions) {
+        const mode = options?.numericMode || Const.NUMERIC_MODE_LOSSY;
+        let ret: number | string;
 
-        if (this.scale) {
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
+        if (mode === Const.NUMERIC_MODE_LOSSY) {
+            ret = data.readInt64();
+            if (this.scale) ret = ret / ScaleDivisor[Math.abs(this.scale)];
+        } else {
+            ret = decodeExactNumeric(data.readInt64BigInt(), this.scale, mode);
         }
 
         if (!lowerV13 || !data.readInt()) {
@@ -577,23 +619,11 @@ export class SQLVarInt64 extends SQLVarBase {
 //------------------------------------------------------
 
 export class SQLVarInt128 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean) {
-        var retBigInt = BigInt(data.readInt128())
-        let ret: string | number;
-
-        if (retBigInt > BigInt(Number.MAX_SAFE_INTEGER)) {
-            ret = retBigInt.toString();
-
-            var integerPart = ret.slice(0, Math.abs(this.scale) * -1)
-            var decimalPart = ret.slice(Math.abs(this.scale) * -1)
-
-            if (integerPart === '') integerPart = '0'
-
-            ret = `${integerPart}.${decimalPart}`
-        } else {
-            ret = Number(retBigInt);
-            ret = ret / ScaleDivisor[Math.abs(this.scale)];
-        }
+    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)
+            : decodeExactNumeric(data.readInt128Signed(), this.scale, mode);
 
         if (!lowerV13 || !data.readInt()) {
             return ret;