node-firebird 2.5.0 → 2.7.0

package/lib/wire/database.js

@@ -189,6 +189,48 @@ class Database extends events_1.default.EventEmitter {
         });
         return self;
     }
+    /**
+     * Bulk-execute `query` once per row via the Firebird 4 batch API
+     * (protocol 16+) with all-or-nothing semantics: the batch runs in its
+     * own transaction, committed only when every record succeeded and
+     * rolled back otherwise. On failure the error of the first failed
+     * record is reported, with the full completion attached as
+     * err.batchCompletion. Use transaction.executeBatch for partial-success
+     * handling.
+     */
+    executeBatch(query, rows, callback, options) {
+        var self = this;
+        self.connection.startTransaction(function (err, transaction) {
+            if (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+            transaction.executeBatch(query, rows, function (err, result) {
+                if (err) {
+                    transaction.rollback(function () {
+                        (0, callback_1.doError)(err, callback);
+                    });
+                    return;
+                }
+                if (!result.success) {
+                    transaction.rollback(function () {
+                        var first = result.errors.length ? result.errors[0] : null;
+                        var batchError = first
+                            ? first.error
+                            : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
+                        batchError.batchCompletion = result;
+                        (0, callback_1.doError)(batchError, callback);
+                    });
+                    return;
+                }
+                transaction.commit(function (err) {
+                    if (callback)
+                        callback(err, result);
+                });
+            }, options);
+        });
+        return self;
+    }
     sequentially(query, params, on, callback, options = {}) {
         if (params instanceof Function) {
             options = callback;
@@ -273,6 +315,21 @@ class Database extends events_1.default.EventEmitter {
     drop(callback) {
         return this.connection.dropDatabase(callback);
     }
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        this.connection.cancelOperation(kind, callback);
+        return this;
+    }
     attachEvent(callback) {
         var self = this;
         const eventid = self.eventid++;
@@ -391,6 +448,10 @@ class Database extends events_1.default.EventEmitter {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.execute(query, params, cb, options); });
     }
+    executeBatchAsync(query, rows, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.executeBatch(query, rows, cb, options); });
+    }
     sequentiallyAsync(query, params, on, options) {
         if (params instanceof Function) {
             options = on;
@@ -423,6 +484,10 @@ class Database extends events_1.default.EventEmitter {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.attachEvent(cb); });
     }
+    cancelAsync(kind) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.cancel(kind, cb); });
+    }
     /**
      * Run `work` inside a transaction: commits when the returned promise
      * resolves, rolls back when it rejects (the original error is rethrown,

package/lib/wire/serialize.d.ts

@@ -42,7 +42,7 @@ export declare class XdrWriter {
     constructor(size?: number);
     ensure(len: number): void;
     addInt(value: number): void;
-    addInt64(value: number): void;
+    addInt64(value: number | bigint): void;
     addInt128(value: number | bigint | string): void;
     addDecFloat16(value: number | string | bigint): void;
     addDecFloat34(value: number | string | bigint): void;
@@ -53,6 +53,7 @@ export declare class XdrWriter {
     addBlr(blr: BlrWriter): void;
     getData(): Buffer;
     addDouble(value: number): void;
+    addFloat(value: number): void;
     addQuad(quad: {
         low: number;
         high: number;

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

@@ -1,8 +1,3 @@
-/***************************************
- *
- *   Transaction
- *
- ***************************************/
 declare class Transaction {
     connection: any;
     db: any;
@@ -13,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

@@ -10,6 +10,36 @@ const const_1 = __importDefault(require("./const"));
  *   Transaction
  *
  ***************************************/
+/** The error delivered when options.signal was already aborted on entry. */
+function abortError(signal) {
+    if (signal && signal.reason instanceof Error)
+        return signal.reason;
+    var err = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    err.code = 'ABORT_ERR';
+    return err;
+}
+/**
+ * Wire an AbortSignal to a running statement: on abort, send an out-of-band
+ * op_cancel so the server fails the executing operation with isc_cancelled
+ * (surfaced through the statement's own callback as err.gdscode ===
+ * GDSCode.CANCELLED). Returns the wrapped callback that detaches the
+ * listener once the operation settles.
+ */
+function hookAbortSignal(connection, signal, callback) {
+    var settled = false;
+    var onAbort = function () {
+        if (!settled)
+            connection.cancelOperation(const_1.default.fb_cancel_raise);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    return function (err, result, meta, isSelect) {
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        if (callback)
+            callback(err, result, meta, isSelect);
+    };
+}
 class Transaction {
     constructor(connection) {
         this.connection = connection;
@@ -32,6 +62,14 @@ class Transaction {
             callback = params;
             params = undefined;
         }
+        var signal = options && options.signal;
+        if (signal) {
+            if (signal.aborted) {
+                (0, callback_1.doError)(abortError(signal), callback);
+                return;
+            }
+            callback = hookAbortSignal(this.connection, signal, callback);
+        }
         var self = this;
         this.newStatement(query, function (err, statement) {
             if (err) {
@@ -162,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.5.0",
+    "version": "2.7.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/types.ts

@@ -75,9 +75,43 @@ 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;
+    /**
+     * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
+     * If the signal is already aborted the query is not sent at all and the
+     * callback/promise fails with an `AbortError`. If it fires mid-flight an
+     * out-of-band op_cancel is sent and the query fails with
+     * `err.gdscode === GDSCode.CANCELLED`. Cancellation is per-attachment:
+     * it cancels whatever is currently executing on the connection.
+     */
+    signal?: AbortSignal;
 }
 
 export interface Database {
@@ -86,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;
@@ -99,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>;
@@ -109,12 +146,22 @@ export interface Database {
     attachEventAsync(): Promise<any>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
+    /**
+     * Cancel the operation currently executing on this connection
+     * (Firebird 2.5+ / protocol 12+). The cancelled operation fails through
+     * its own callback/promise with `err.gdscode === GDSCode.CANCELLED`.
+     */
+    cancel(callback?: SimpleCallback): Database;
+    cancel(kind: number, callback?: SimpleCallback): Database;
+    cancelAsync(kind?: number): Promise<void>;
 }
 
 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;
@@ -124,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>;
@@ -142,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>;