node-firebird 2.6.0 → 2.8.0

package/lib/wire/serialize.js

@@ -226,10 +226,10 @@ class XdrWriter {
     }
     addInt64(value) {
         this.ensure(8);
-        // Note: precision is limited to Number.MAX_SAFE_INTEGER (±2^53-1).
-        // Values outside this range lose precision, which matches the previous
-        // Long.fromNumber() behaviour.
-        this.buffer.writeBigInt64BE(BigInt(Math.trunc(value)), this.pos);
+        // Note: for numbers, precision is limited to Number.MAX_SAFE_INTEGER
+        // (±2^53-1); values outside this range lose precision, which matches
+        // the previous Long.fromNumber() behaviour. BigInts keep full precision.
+        this.buffer.writeBigInt64BE(typeof value === 'bigint' ? value : BigInt(Math.trunc(value)), this.pos);
         this.pos += 8;
     }
     addInt128(value) {
@@ -306,6 +306,11 @@ class XdrWriter {
         this.buffer.writeDoubleBE(value, this.pos);
         this.pos += 8;
     }
+    addFloat(value) {
+        this.ensure(4);
+        this.buffer.writeFloatBE(value, this.pos);
+        this.pos += 4;
+    }
     addQuad(quad) {
         this.ensure(8);
         var b = this.buffer;

package/lib/wire/statement.d.ts

@@ -21,7 +21,13 @@ declare class Statement {
     fetch(transaction: any, count: number | string, callback: (err: any, result?: any) => void): void;
     fetchScroll(transaction: any, direction: string | number, offset?: any, count?: any, callback?: any): void;
     fetchAll(transaction: any, callback: (err: any, result?: any) => void): void;
+    /**
+     * Execute this statement once per row via the Firebird 4 batch API
+     * (protocol 16+). `rows` is an array of parameter arrays.
+     */
+    executeBatch(transaction: any, rows: any[][], callback?: any, options?: any): void;
     executeAsync(transaction: any, params?: any, options?: any): Promise<any>;
+    executeBatchAsync(transaction: any, rows: any[][], options?: any): Promise<any>;
     fetchAsync(transaction: any, count: number | string): Promise<any>;
     fetchScrollAsync(transaction: any, direction: string | number, offset?: any, count?: any): Promise<any>;
     fetchAllAsync(transaction: any): Promise<any>;

package/lib/wire/statement.js

@@ -49,11 +49,22 @@ class Statement {
     fetchAll(transaction, callback) {
         this.connection.fetchAll(this, transaction, callback);
     }
+    /**
+     * Execute this statement once per row via the Firebird 4 batch API
+     * (protocol 16+). `rows` is an array of parameter arrays.
+     */
+    executeBatch(transaction, rows, callback, options) {
+        this.connection.executeBatch(transaction, this, rows, callback, options);
+    }
     /* Promise / async-await API — wrappers over the callback methods above. */
     executeAsync(transaction, params, options) {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.execute(transaction, params, cb, options); });
     }
+    executeBatchAsync(transaction, rows, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.executeBatch(transaction, rows, cb, options); });
+    }
     fetchAsync(transaction, count) {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.fetch(transaction, count, cb); });

package/lib/wire/transaction.d.ts

@@ -8,6 +8,17 @@ declare class Transaction {
     execute(query: string, params?: any, callback?: any, options?: any): void;
     sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
     query(query: string, params?: any, callback?: any, options?: any): void;
+    /**
+     * Execute `query` once per row in `rows` using the Firebird 4 batch API
+     * (protocol 16+, single network flush). The callback receives a
+     * completion object: { recordCount, updateCounts, errors:
+     * [{recordNumber, error}], errorRecordNumbers, success }. Per-record
+     * failures do NOT roll anything back here — inspect the completion and
+     * commit or roll back yourself (or use db.executeBatch for
+     * all-or-nothing semantics).
+     */
+    executeBatch(query: string, rows: any[][], callback?: any, options?: any): void;
+    executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any>;
     commit(callback?: (err?: any) => void): void;
     rollback(callback?: (err?: any) => void): void;
     commitRetaining(callback?: (err?: any) => void): void;

package/lib/wire/transaction.js

@@ -200,6 +200,33 @@ class Transaction {
         };
         this.execute(query, params, callback, options);
     }
+    /**
+     * Execute `query` once per row in `rows` using the Firebird 4 batch API
+     * (protocol 16+, single network flush). The callback receives a
+     * completion object: { recordCount, updateCounts, errors:
+     * [{recordNumber, error}], errorRecordNumbers, success }. Per-record
+     * failures do NOT roll anything back here — inspect the completion and
+     * commit or roll back yourself (or use db.executeBatch for
+     * all-or-nothing semantics).
+     */
+    executeBatch(query, rows, callback, options) {
+        var self = this;
+        this.newStatement(query, function (err, statement) {
+            if (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+            statement.executeBatch(self, rows, function (err, result) {
+                statement.release();
+                if (callback)
+                    callback(err, result);
+            }, options);
+        });
+    }
+    executeBatchAsync(query, rows, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.executeBatch(query, rows, cb, options); });
+    }
     commit(callback) {
         this.connection.commit(this, callback);
     }

package/lib/wire/xsqlvar.d.ts

@@ -155,6 +155,15 @@ export declare class SQLParamBuffer {
     encode(data: XdrWriter): void;
     calcBlr(blr: BlrWriter): void;
 }
+/**
+ * Split a JS Date into the Firebird wire representation used by
+ * TIMESTAMP/DATE/TIME columns: `date` is the modified-Julian day number and
+ * `time` the count of 100-microsecond units since midnight (local time).
+ */
+export declare function encodeDateTimeParts(value: Date): {
+    date: number;
+    time: number;
+};
 export declare class SQLParamQuad {
     value: any;
     constructor(value: any);

package/lib/wire/xsqlvar.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQLVarBase = void 0;
+exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
 /***************************************
  *
@@ -593,6 +594,24 @@ class SQLParamBuffer {
 }
 exports.SQLParamBuffer = SQLParamBuffer;
 //------------------------------------------------------
+/**
+ * Split a JS Date into the Firebird wire representation used by
+ * TIMESTAMP/DATE/TIME columns: `date` is the modified-Julian day number and
+ * `time` the count of 100-microsecond units since midnight (local time).
+ */
+function encodeDateTimeParts(value) {
+    var ms = value.getTime() - value.getTimezoneOffset() * MsPerMinute;
+    var time = ms % TimeCoeff;
+    var date = (ms - time) / TimeCoeff + DateOffset;
+    time *= 10;
+    // check overflow (dates before the epoch)
+    if (time < 0) {
+        date--;
+        time = TimeCoeff * 10 + time;
+    }
+    return { date: date, time: time };
+}
+//------------------------------------------------------
 class SQLParamQuad {
     constructor(value) {
         this.value = value;
@@ -621,17 +640,9 @@ class SQLParamDate {
     }
     encode(data) {
         if (this.value != null) {
-            var value = this.value.getTime() - this.value.getTimezoneOffset() * MsPerMinute;
-            var time = value % TimeCoeff;
-            var date = (value - time) / TimeCoeff + DateOffset;
-            time *= 10;
-            // check overflow
-            if (time < 0) {
-                date--;
-                time = TimeCoeff * 10 + time;
-            }
-            data.addInt(date);
-            data.addUInt(time);
+            var parts = encodeDateTimeParts(this.value);
+            data.addInt(parts.date);
+            data.addUInt(parts.time);
         }
         else {
             data.addInt(0);

package/package.json

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

package/src/pool.ts

@@ -4,32 +4,140 @@
  *
  ***************************************/
 
+import Events from 'events';
 import { fromCallback } from './callback';
 import type { Callback } from './callback';
 
 type AttachFn = (options: any, callback: Callback) => void;
 
-class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+class Pool extends Events.EventEmitter {
     attach: AttachFn;
     internaldb: any[];
     pooldb: any[];
     dbinuse: number;
     _creating: number;
     max: number;
+    min: number;
+    idleTimeoutMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
+    _reaper: NodeJS.Timeout | null;
 
     constructor(attach: AttachFn, max: number, options: any) {
+        super();
         this.attach    = attach;
         this.internaldb = []; // connections created by the pool (for destroy)
         this.pooldb    = []; // connections available in the pool (idle)
         this.dbinuse   = 0;  // connections currently handed out to callers
         this._creating = 0;  // connections currently being created (attach in flight)
         this.max       = max || 4;
+        this.min       = (options && options.min > 0) ? Math.min(options.min, this.max) : 0;
+        this.idleTimeoutMillis = (options && options.idleTimeoutMillis > 0) ? options.idleTimeoutMillis : 0;
         this.pending   = []; // callbacks waiting for a free slot
         this.options   = options;
         this._destroyed = false; // true after destroy() — prevents further use
+        this._reaper   = null;
+
+        if (this.idleTimeoutMillis) {
+            var self = this;
+            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // the timer from holding the process open.
+            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            this._reaper = setInterval(function() { self._reap(); }, interval);
+            if (this._reaper.unref) this._reaper.unref();
+        }
+    }
+
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount(): number {
+        return this.internaldb.length;
+    }
+
+    /** Connections sitting idle in the pool. */
+    get idleCount(): number {
+        return this.pooldb.length;
+    }
+
+    /** Connections currently handed out to callers. */
+    get activeCount(): number {
+        return this.dbinuse;
+    }
+
+    /** get() requests queued for a free slot. */
+    get waitingCount(): number {
+        return this.pending.length;
+    }
+
+    /** True when the connection can no longer be used. */
+    _isDead(db: any): boolean {
+        return !db.connection || db.connection._isClosed || db.connection._isDetach ||
+            !db.connection._socket || db.connection._socket.destroyed;
+    }
+
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db: any): void {
+        var idx = this.internaldb.indexOf(db);
+        if (idx !== -1) this.internaldb.splice(idx, 1);
+        idx = this.pooldb.indexOf(db);
+        if (idx !== -1) this.pooldb.splice(idx, 1);
+        this.emit('remove', db);
+    }
+
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err: any, db?: any): void {
+        if (this.listenerCount('error') > 0) this.emit('error', err, db);
+    }
+
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap(): void {
+        if (this._destroyed) return;
+        var self = this;
+        var now = Date.now();
+
+        // iterate over a copy — we splice from pooldb while walking
+        this.pooldb.slice().forEach(function(db) {
+            if (self._isDead(db)) {
+                self._forget(db);
+                return;
+            }
+            if (self.internaldb.length <= self.min) return;
+            var idleSince = typeof db.__poolIdleSince === 'number' ? db.__poolIdleSince : now;
+            if (now - idleSince < self.idleTimeoutMillis) return;
+
+            self._forget(db);
+            db.connection._pooled = false;
+            try {
+                db.detach(function(err?: any) {
+                    if (err) self._emitError(err, db);
+                });
+            } catch (e) {
+                self._emitError(e, db);
+            }
+        });
     }
 
     get(callback: Callback): this {
@@ -59,15 +167,15 @@ class Pool {
         if (self.pooldb.length) {
             var db = self.pooldb.shift();
             // Discard connections that have been closed or destroyed while idle
-            if (db.connection && (db.connection._isClosed || db.connection._isDetach || !db.connection._socket || db.connection._socket.destroyed)) {
-                var idx = self.internaldb.indexOf(db);
-                if (idx !== -1) self.internaldb.splice(idx, 1);
+            if (self._isDead(db)) {
+                self._forget(db);
                 self.pending.unshift(cb);
                 setImmediate(function () { self.check(); });
                 return self;
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            self.emit('acquire', db);
             cb(null, db);
         } else {
             // No idle connection — create a new one via attach().
@@ -133,14 +241,20 @@ class Pool {
                         if (self.pooldb.indexOf(db) !== -1 || self.internaldb.indexOf(db) === -1)
                             return;
                         // if not usable don't put it back in the pool
-                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false)
+                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
-                        else
+                            self.emit('remove', db);
+                        } else {
+                            db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);
+                            self.emit('release', db);
+                        }
 
                         self.dbinuse--;
                         self.check();
                     });
+                    self.emit('connect', db);
+                    self.emit('acquire', db);
                 }
 
                 cb(err, db);
@@ -157,6 +271,11 @@ class Pool {
         var self = this;
         self._destroyed = true;
 
+        if (self._reaper) {
+            clearInterval(self._reaper);
+            self._reaper = null;
+        }
+
         // [Fix 4] Drain pending callbacks so callers are not left hanging.
         // This is critical when destroy() is called as a recovery measure after
         // a timeout: without draining, every concurrent pool.get() that had not
@@ -197,6 +316,7 @@ class Pool {
                 self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
                 db.detach(detachCallback);
+                self.emit('remove', db);
             } else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).
                 // The caller is responsible for releasing it via detach().

package/src/types.ts

@@ -75,6 +75,31 @@ export type TransactionOptions = {
     waitTimeout?: number;
 };
 
+/** Result of an executeBatch call (Firebird 4 batch API, protocol 16+). */
+export interface BatchResult {
+    /** Total number of records processed by the server. */
+    recordCount: number;
+    /** Per-record update counts (in record order). */
+    updateCounts: number[];
+    /** Per-record failures with full status vectors (capped by `detailedErrors`). */
+    errors: Array<{ recordNumber: number; error: Error }>;
+    /** Record numbers of ALL failed records (detailed + status-less). */
+    errorRecordNumbers: number[];
+    /** True when every record executed without error. */
+    success: boolean;
+}
+
+export type BatchOptions = {
+    /** Continue past per-record errors and report them all (default true). */
+    multiError?: boolean;
+    /** Server-side batch buffer limit in bytes (BATCH_TAG_BUFFER_BYTES_SIZE). */
+    bufferSize?: number;
+    /** Max number of detailed per-record status vectors returned (server default 64). */
+    detailedErrors?: number;
+    /** Rows per op_batch_msg packet (default 500). */
+    chunkSize?: number;
+};
+
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
@@ -95,6 +120,8 @@ export interface Database {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
@@ -108,6 +135,7 @@ export interface Database {
     // Result metadata is only available through the callback API.
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -132,6 +160,8 @@ export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
@@ -141,6 +171,7 @@ export interface Transaction {
     // Promise / async-await API
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
@@ -159,8 +190,12 @@ export interface Statement {
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
 
+    /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
+    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
+
     // Promise / async-await API
     executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;
@@ -246,6 +281,19 @@ export interface Options {
      * expected Firebird server response time under load.
      */
     connectTimeout?: number;
+    /**
+     * Pool only: minimum number of physical connections the idle reaper
+     * keeps alive. Only meaningful together with `idleTimeoutMillis`.
+     * Default 0 (the pool may shrink to no connections).
+     */
+    min?: number;
+    /**
+     * Pool only: close connections that have been idle in the pool for this
+     * many milliseconds, never shrinking below `min`. Dead idle connections
+     * (server restarts, dropped sockets) are evicted on the same sweep.
+     * Default 0 (idle connections are kept forever).
+     */
+    idleTimeoutMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -289,10 +337,30 @@ export interface SvcMgrOptions extends Options {
     manager: true; // Attach to ServiceManager
 }
 
+export type PoolEvent = 'connect' | 'acquire' | 'release' | 'remove' | 'error';
+
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
 
+    // Metrics (live counters, pg.Pool-style)
+    /** Physical connections owned by the pool (idle + in use). */
+    readonly totalCount: number;
+    /** Connections sitting idle in the pool. */
+    readonly idleCount: number;
+    /** Connections currently handed out to callers. */
+    readonly activeCount: number;
+    /** get() requests queued for a free slot. */
+    readonly waitingCount: number;
+
+    // Events
+    on(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    on(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    once(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    once(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    off(event: PoolEvent, listener: (...args: any[]) => void): this;
+    removeListener(event: PoolEvent, listener: (...args: any[]) => void): this;
+
     // Promise / async-await API
     getAsync(): Promise<Database>;
     destroyAsync(): Promise<void>;