node-firebird 2.11.0 → 2.13.0

package/lib/wire/const.js

@@ -540,6 +540,12 @@ const sqlInfo = {
     isc_info_sql_stmt_type: 21,
     isc_info_sql_get_plan: 22,
     isc_info_sql_records: 23,
+    // per-verb row counts nested inside an isc_info_sql_records cluster
+    // (inf_pub.h isc_info_req_*)
+    isc_info_req_select_count: 13,
+    isc_info_req_insert_count: 14,
+    isc_info_req_update_count: 15,
+    isc_info_req_delete_count: 16,
     isc_info_sql_batch_fetch: 24,
     isc_info_sql_relation_alias: 25, // >: 2.0
     isc_info_sql_explain_plan: 26, // >= 3.0
@@ -618,6 +624,11 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_length,
     sqlInfo.isc_info_sql_describe_end
 ];
+// op_info_sql request for the per-verb DML row counts of an executed
+// statement (withMeta / affectedRows).
+const RECORDS_INFO = [
+    sqlInfo.isc_info_sql_records,
+];
 /***********************/
 /*   ISC Services      */
 /***********************/
@@ -843,6 +854,7 @@ const Const = Object.freeze({
     ...defaultOptions,
     DESCRIBE,
     DESCRIBE_WITH_SCHEMA,
+    RECORDS_INFO,
     ...dpb,
     ...dsql,
     ...fetchOp,

package/lib/wire/database.d.ts

@@ -1,5 +1,6 @@
 import Events from 'events';
 import { type Callback, type SimpleCallback } from '../callback';
+import { type SqlTag } from '../sql-template';
 import FbEventManager from './fbEventManager';
 import type Connection from './connection';
 import type Transaction from './transaction';
@@ -15,7 +16,15 @@ type TransactionArg = TransactionOptions | Isolation | TransactionCb | undefined
 declare class Database extends Events.EventEmitter {
     connection: Connection;
     eventid: number;
+    private _sql?;
     constructor(connection: Connection);
+    /**
+     * Tagged-template query API: db.sql`SELECT ... ${value}` (see README).
+     * Built lazily on first access; the compiled text is positional-only,
+     * so the namedPlaceholders rewriter is disabled — any `:token` in the
+     * template is PSQL (EXECUTE BLOCK), not a placeholder.
+     */
+    get sql(): SqlTag;
     escape(value: any): string;
     detach(callback?: Callback, force?: boolean): this;
     transaction(options: TransactionArg, callback?: TransactionCb): this;
@@ -43,6 +52,15 @@ declare class Database extends Events.EventEmitter {
      * blobAsText and jsonAsObject all apply.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    /**
+     * Bulk-insert Writable (the COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows, they are flushed in chunks through the batch
+     * API on one prepared statement. Runs its own transaction — committed
+     * on finish, rolled back on error/destroy (all-or-nothing for the
+     * whole stream). BLOB columns accept Buffers/strings. After 'finish',
+     * stream.recordCount / stream.affectedRows carry the totals.
+     */
+    batchStream(query: string, options?: any): import("node:stream").Writable;
     query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): this;
     drop(callback?: SimpleCallback): void;
     /**

package/lib/wire/database.js

@@ -6,10 +6,12 @@ const events_1 = __importDefault(require("events"));
 const callback_1 = require("../callback");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
+const sql_template_1 = require("../sql-template");
 const xsqlvar_1 = require("./xsqlvar");
 const eventConnection_1 = __importDefault(require("./eventConnection"));
 const fbEventManager_1 = __importDefault(require("./fbEventManager"));
 const query_stream_1 = __importDefault(require("./query-stream"));
+const batch_stream_1 = __importDefault(require("./batch-stream"));
 /***************************************
  *
  *   Database
@@ -76,7 +78,7 @@ function readblob(blob, callback) {
         });
     });
 }
-function fetchBlobSyncRow(row, meta, nestTables, lowercaseKeys, callback) {
+function fetchBlobSyncRow(row, meta, nestTables, lowercaseKeys, transform, callback) {
     if (!row || !meta || !meta.length || !meta.some((m) => m && m.type === const_1.default.SQL_BLOB)) {
         callback(null, row);
         return;
@@ -86,7 +88,7 @@ function fetchBlobSyncRow(row, meta, nestTables, lowercaseKeys, callback) {
     // duplicate JOIN column names (and nested rows) break that alignment.
     // Array rows (sequentially's legacy boolean form) are keyed by index.
     const isArrayRow = Array.isArray(row);
-    const keys = isArrayRow ? null : (0, xsqlvar_1.computeColumnKeys)(meta, nestTables, lowercaseKeys);
+    const keys = isArrayRow ? null : (0, xsqlvar_1.computeColumnKeys)(meta, nestTables, lowercaseKeys, transform);
     const blobCells = [];
     for (let i = 0; i < meta.length; i++) {
         if (!meta[i] || meta[i].type !== const_1.default.SQL_BLOB) {
@@ -126,6 +128,15 @@ class Database extends events_1.default.EventEmitter {
         connection.db = this;
         this.eventid = 1;
     }
+    /**
+     * Tagged-template query API: db.sql`SELECT ... ${value}` (see README).
+     * Built lazily on first access; the compiled text is positional-only,
+     * so the namedPlaceholders rewriter is disabled — any `:token` in the
+     * template is PSQL (EXECUTE BLOCK), not a placeholder.
+     */
+    get sql() {
+        return this._sql || (this._sql = (0, sql_template_1.makeSqlTag)((text, params, options) => this.queryAsync(text, params, { ...options, namedPlaceholders: false })));
+    }
     escape(value) {
         return (0, utils_1.escape)(value, this.connection.accept.protocolVersion);
     }
@@ -231,12 +242,7 @@ class Database extends events_1.default.EventEmitter {
                 }
                 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);
+                        (0, callback_1.doError)((0, utils_1.batchResultToError)(result), callback);
                     });
                     return;
                 }
@@ -263,6 +269,9 @@ class Database extends events_1.default.EventEmitter {
             callback = undefined;
         }
         var self = this;
+        var keyResolutionDone = false;
+        var resolvedNest;
+        var resolvedTransform;
         var _on = function (row, i, meta, next) {
             var done = false;
             var finish = function (err) {
@@ -272,9 +281,15 @@ class Database extends events_1.default.EventEmitter {
                 done = true;
                 next(err);
             };
-            // options is read at call time, after the normalization below
-            const nest = (0, xsqlvar_1.resolveNestTables)(options, self.connection.options);
-            fetchBlobSyncRow(row, meta, nest, self.connection._lowercase_keys, function (blobErr) {
+            // options is read at call time, after the normalization below;
+            // both values are query-invariant, so resolve them once on the
+            // first row instead of allocating per row
+            if (!keyResolutionDone) {
+                resolvedNest = (0, xsqlvar_1.resolveNestTables)(options, self.connection.options);
+                resolvedTransform = (0, xsqlvar_1.resolveKeyTransform)(options, self.connection.options);
+                keyResolutionDone = true;
+            }
+            fetchBlobSyncRow(row, meta, resolvedNest, self.connection._lowercase_keys, resolvedTransform, function (blobErr) {
                 if (blobErr) {
                     finish(blobErr);
                     return;
@@ -328,6 +343,17 @@ class Database extends events_1.default.EventEmitter {
     queryStream(query, params, options) {
         return (0, query_stream_1.default)(this, query, params, options);
     }
+    /**
+     * Bulk-insert Writable (the COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows, they are flushed in chunks through the batch
+     * API on one prepared statement. Runs its own transaction — committed
+     * on finish, rolled back on error/destroy (all-or-nothing for the
+     * whole stream). BLOB columns accept Buffers/strings. After 'finish',
+     * stream.recordCount / stream.affectedRows carry the totals.
+     */
+    batchStream(query, options) {
+        return (0, batch_stream_1.default)(this, query, options, true);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             options = callback || {};
@@ -468,8 +494,9 @@ class Database extends events_1.default.EventEmitter {
     /*
      * Promise / async-await API.
      * Each *Async method wraps its callback counterpart; the callback API
-     * stays untouched. Result metadata is only available through the
-     * callback API — the promises resolve with the rows alone.
+     * stays untouched. The promises resolve with the rows alone unless
+     * { withMeta: true } is passed, which resolves the full
+     * { rows, fields, affectedRows, recordCounts, warnings } result.
      */
     queryAsync(query, params, options) {
         var self = this;

package/lib/wire/serialize.d.ts

@@ -48,6 +48,8 @@ export declare class XdrWriter {
     addDecFloat34(value: number | string | bigint): void;
     addUInt(value: number): void;
     addString(s: string, encoding: BufferEncoding): void;
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b: Buffer): void;
     addText(s: string, encoding: BufferEncoding): void;
     addParamBuffer(b: Buffer): void;
     addBlr(blr: BlrWriter): void;

package/lib/wire/serialize.js

@@ -160,6 +160,10 @@ class BlrReader {
                 break;
             case 4:
                 value = this.buffer.readInt32LE(this.pos);
+                break;
+            case 8:
+                // e.g. record counts above 2^31 (isc_info_sql_records)
+                value = Number(this.buffer.readBigInt64LE(this.pos));
         }
         this.pos += len;
         return value;
@@ -273,6 +277,16 @@ class XdrWriter {
         this.buffer.fill(0, this.pos + len, this.pos + alen);
         this.pos += alen;
     }
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b) {
+        var alen = align(b.length);
+        this.ensure(alen + 4);
+        this.buffer.writeInt32BE(b.length, this.pos);
+        this.pos += 4;
+        b.copy(this.buffer, this.pos);
+        this.buffer.fill(0, this.pos + b.length, this.pos + alen);
+        this.pos += alen;
+    }
     addText(s, encoding) {
         var len = Buffer.byteLength(s, encoding);
         var alen = align(len);

package/lib/wire/socket.js

@@ -132,8 +132,14 @@ class Socket {
      * Compress and/or encrypt data before sending to socket.
      */
     write(data, defer = false) {
+        // Callers pass views of the connection's shared _msg buffer, and both
+        // net.Socket (when it cannot flush immediately) and zlib keep a
+        // REFERENCE to the chunk — a later sender rebuilding _msg would then
+        // corrupt this queued packet (intermittent, load-dependent). Own the
+        // bytes at the send boundary, once.
+        data = Buffer.from(data);
         if (process.env.FIREBIRD_DEBUG) {
-            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, Buffer.from(data).toString('hex'), this.encrypt, defer);
+            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, data.toString('hex'), this.encrypt, defer);
         }
         if (defer) {
             // Accumulate deferred packets instead of overwriting.  Multiple
@@ -142,8 +148,8 @@ class Socket {
             // overwriting the buffer silently drops packets and desynchronises
             // the request/response queue, causing the connection to hang.
             this.buffer = this.buffer
-                ? Buffer.concat([this.buffer, Buffer.from(data)])
-                : Buffer.from(data);
+                ? Buffer.concat([this.buffer, data])
+                : data;
             return;
         }
         if (!defer && this.buffer) {

package/lib/wire/transaction.d.ts

@@ -1,4 +1,5 @@
 import { type Callback, type SimpleCallback } from '../callback';
+import { type SqlTag } from '../sql-template';
 import type Connection from './connection';
 import type Database from './database';
 import type Statement from './statement';
@@ -8,7 +9,33 @@ declare class Transaction {
     connection: Connection;
     db: Database;
     handle: number;
+    private _sql?;
     constructor(connection: Connection);
+    /**
+     * Tagged-template query API: tx.sql`SELECT ... ${value}` (see README).
+     * Built lazily — transactions are created per-query internally, and
+     * those throwaway instances must not pay for the tag. The compiled text
+     * is positional-only, so the namedPlaceholders rewriter is disabled:
+     * any `:token` in the template is PSQL (EXECUTE BLOCK), not a
+     * placeholder.
+     */
+    get sql(): SqlTag;
+    /** Current savepoint nesting depth (names savepoints, see savepoint()). */
+    private _savepointDepth;
+    /**
+     * Run `work` inside a savepoint (Firebird 1.5+): on resolve the
+     * savepoint is released, on reject the transaction rolls back TO the
+     * savepoint — undoing only work's changes — and the error is rethrown,
+     * leaving the transaction itself usable. Nestable (each call generates
+     * a fresh NF_SP_n name), mirroring db.withTransaction's style and
+     * Postgres.js's sql.savepoint().
+     *
+     * Do NOT run sibling savepoints concurrently on one transaction
+     * (Promise.all): Firebird's RELEASE SAVEPOINT also releases every
+     * savepoint created after it, so interleaved siblings release each
+     * other. Nested (awaited) savepoints are fine.
+     */
+    savepoint<T>(work: (transaction: this) => Promise<T> | T): Promise<T>;
     /** Per-call options.namedPlaceholders overrides the connection option. */
     private namedPlaceholdersEnabled;
     newStatement(query: string, callback: StatementCb, options?: InternalQueryOptions): void;
@@ -21,6 +48,12 @@ declare class Transaction {
      * stream ends — commit or roll back yourself.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    /**
+     * Bulk-insert Writable running inside this transaction (see
+     * Database.batchStream). The transaction is NOT committed or rolled
+     * back by the stream — settle it yourself after 'finish'/'error'.
+     */
+    batchStream(query: string, options?: any): import("node:stream").Writable;
     query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void;
     /**
      * Execute `query` once per row in `rows` using the Firebird 4 batch API

package/lib/wire/transaction.js

@@ -6,7 +6,10 @@ const callback_1 = require("../callback");
 const named_params_1 = require("../named-params");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
+const sql_template_1 = require("../sql-template");
+const xsqlvar_1 = require("./xsqlvar");
 const query_stream_1 = __importDefault(require("./query-stream"));
+const batch_stream_1 = __importDefault(require("./batch-stream"));
 /***************************************
  *
  *   Transaction
@@ -44,9 +47,73 @@ function hookAbortSignal(connection, signal, callback) {
 }
 class Transaction {
     constructor(connection) {
+        /** Current savepoint nesting depth (names savepoints, see savepoint()). */
+        this._savepointDepth = 0;
         this.connection = connection;
         this.db = connection.db;
     }
+    /**
+     * Tagged-template query API: tx.sql`SELECT ... ${value}` (see README).
+     * Built lazily — transactions are created per-query internally, and
+     * those throwaway instances must not pay for the tag. The compiled text
+     * is positional-only, so the namedPlaceholders rewriter is disabled:
+     * any `:token` in the template is PSQL (EXECUTE BLOCK), not a
+     * placeholder.
+     */
+    get sql() {
+        return this._sql || (this._sql = (0, sql_template_1.makeSqlTag)((text, params, options) => this.queryAsync(text, params, { ...options, namedPlaceholders: false })));
+    }
+    /**
+     * Run `work` inside a savepoint (Firebird 1.5+): on resolve the
+     * savepoint is released, on reject the transaction rolls back TO the
+     * savepoint — undoing only work's changes — and the error is rethrown,
+     * leaving the transaction itself usable. Nestable (each call generates
+     * a fresh NF_SP_n name), mirroring db.withTransaction's style and
+     * Postgres.js's sql.savepoint().
+     *
+     * Do NOT run sibling savepoints concurrently on one transaction
+     * (Promise.all): Firebird's RELEASE SAVEPOINT also releases every
+     * savepoint created after it, so interleaved siblings release each
+     * other. Nested (awaited) savepoints are fine.
+     */
+    async savepoint(work) {
+        if (typeof work !== 'function') {
+            throw new Error('savepoint(work) expects a function');
+        }
+        // named by nesting depth, not a global counter: sequential
+        // savepoints at the same depth reuse the same three SQL strings, so
+        // the statement cache serves them instead of accumulating
+        // single-use entries (redefining a released savepoint name is legal)
+        const name = 'NF_SP_' + (++this._savepointDepth);
+        try {
+            await this.queryAsync('SAVEPOINT ' + name);
+            let result;
+            try {
+                result = await work(this);
+            }
+            catch (err) {
+                // only a work() failure rolls back to the savepoint — a
+                // RELEASE failure below must NOT undo work's successful
+                // changes
+                try {
+                    await this.queryAsync('ROLLBACK TO SAVEPOINT ' + name);
+                }
+                catch (rollbackErr) {
+                    // the original failure matters more; keep the rollback
+                    // failure attached for diagnosis
+                    if (err && typeof err === 'object') {
+                        err.savepointRollbackError = rollbackErr;
+                    }
+                }
+                throw err;
+            }
+            await this.queryAsync('RELEASE SAVEPOINT ' + name);
+            return result;
+        }
+        finally {
+            this._savepointDepth--;
+        }
+    }
     /** Per-call options.namedPlaceholders overrides the connection option. */
     namedPlaceholdersEnabled(options) {
         if (options && options.namedPlaceholders !== undefined)
@@ -116,6 +183,66 @@ class Transaction {
                     dropError(err);
                     return;
                 }
+                // withMeta applies to query/execute only: in streaming mode
+                // (sequentially/queryStream, which spread user options) rows
+                // bypass fetchAll's array, so a result object here would
+                // carry rows: [] and a meaningless affectedRows
+                var withMeta = Boolean(options && typeof options === 'object' &&
+                    options.withMeta && !options.asStream);
+                // Deliver the historic result shape, or — when options.withMeta
+                // is set — request the per-verb DML row counts while the
+                // statement handle is still open and wrap everything in a
+                // { rows, fields, affectedRows, recordCounts, warnings } object.
+                function deliver(rows, isSelect, plainDml) {
+                    if (!withMeta) {
+                        statement.release();
+                        if (callback) {
+                            if (plainDml) {
+                                // plain DML historically calls back with no args
+                                callback();
+                            }
+                            else {
+                                callback(undefined, rows, statement.output, isSelect);
+                            }
+                        }
+                        return;
+                    }
+                    var execWarnings = (ret && ret.warnings) || [];
+                    var finalize = function (counts) {
+                        statement.release();
+                        if (!callback) {
+                            return;
+                        }
+                        // DML: what the server actually changed; SELECT: rows
+                        // returned (pg's rowCount convention)
+                        var affectedRows = counts
+                            ? counts.insertCount + counts.updateCount + counts.deleteCount
+                            : (Array.isArray(rows) ? rows.length : (rows !== undefined ? 1 : 0));
+                        callback(undefined, {
+                            rows: rows,
+                            fields: (0, xsqlvar_1.describeFields)(statement.output),
+                            affectedRows: affectedRows,
+                            recordCounts: counts,
+                            warnings: execWarnings,
+                        }, statement.output, isSelect);
+                    };
+                    var t = statement.type;
+                    var isDml = t === const_1.default.isc_info_sql_stmt_insert ||
+                        t === const_1.default.isc_info_sql_stmt_update ||
+                        t === const_1.default.isc_info_sql_stmt_delete ||
+                        t === const_1.default.isc_info_sql_stmt_exec_procedure;
+                    if (!isDml) {
+                        finalize();
+                        return;
+                    }
+                    self.connection.statementInfo(statement, const_1.default.RECORDS_INFO, function (err, info) {
+                        if (err) {
+                            dropError(err);
+                            return;
+                        }
+                        finalize((0, xsqlvar_1.parseRecordCounts)(info && info.buffer));
+                    });
+                }
                 switch (statement.type) {
                     case const_1.default.isc_info_sql_stmt_select:
                         statement.fetchAll(self, function (err, r) {
@@ -123,35 +250,43 @@ class Transaction {
                                 dropError(err);
                                 return;
                             }
-                            statement.release();
-                            if (callback)
-                                callback(undefined, r, statement.output, true);
+                            deliver(r, true);
                         });
                         break;
                     case const_1.default.isc_info_sql_stmt_exec_procedure:
                         if (ret && ret.data && ret.data.length > 0) {
-                            statement.release();
-                            if (callback)
-                                callback(undefined, ret.data[0], statement.output, true);
+                            // singleton op_execute2 rows never pass through
+                            // fetchAll, so their blobAsText fetches must be
+                            // resolved here (issue #305: EXECUTE PROCEDURE
+                            // returned text blobs as unresolved functions)
+                            self.connection.resolveTextBlobs(self, ret, function (blobErr) {
+                                if (blobErr) {
+                                    dropError(blobErr);
+                                    return;
+                                }
+                                deliver(ret.data[0], true);
+                            });
                             break;
                         }
                         else if (statement.output.length) {
-                            statement.fetch(self, 1, function (err, ret) {
+                            statement.fetch(self, 1, function (err, fret) {
                                 if (err) {
                                     dropError(err);
                                     return;
                                 }
-                                statement.release();
-                                if (callback)
-                                    callback(undefined, ret.data[0], statement.output, false);
+                                self.connection.resolveTextBlobs(self, fret, function (blobErr) {
+                                    if (blobErr) {
+                                        dropError(blobErr);
+                                        return;
+                                    }
+                                    deliver(fret.data[0], false);
+                                });
                             });
                             break;
                         }
                     // Fall through is normal
                     default:
-                        statement.release();
-                        if (callback)
-                            callback();
+                        deliver(undefined, false, true);
                         break;
                 }
             }, options);
@@ -226,6 +361,14 @@ class Transaction {
     queryStream(query, params, options) {
         return (0, query_stream_1.default)(this, query, params, options);
     }
+    /**
+     * Bulk-insert Writable running inside this transaction (see
+     * Database.batchStream). The transaction is NOT committed or rolled
+     * back by the stream — settle it yourself after 'finish'/'error'.
+     */
+    batchStream(query, options) {
+        return (0, batch_stream_1.default)(this, query, options, false);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             callback = params;