node-firebird 2.11.0 → 2.13.0

package/src/wire/const.ts

@@ -587,6 +587,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
@@ -669,6 +675,12 @@ const DESCRIBE_WITH_SCHEMA = [
     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      */
 /***********************/
@@ -910,6 +922,7 @@ const Const = Object.freeze({
     ...defaultOptions,
     DESCRIBE,
     DESCRIBE_WITH_SCHEMA,
+    RECORDS_INFO,
     ...dpb,
     ...dsql,
     ...fetchOp,

package/src/wire/database.ts

@@ -1,11 +1,13 @@
 import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
-import { escape } from '../utils';
+import { batchResultToError, escape } from '../utils';
 import Const from './const';
-import { computeColumnKeys, nestCell, resolveNestTables } from './xsqlvar';
+import { makeSqlTag, type SqlTag } from '../sql-template';
+import { computeColumnKeys, nestCell, resolveKeyTransform, resolveNestTables } from './xsqlvar';
 import EventConnection from './eventConnection';
 import FbEventManager from './fbEventManager';
 import makeQueryStream from './query-stream';
+import makeBatchStream from './batch-stream';
 import type Connection from './connection';
 import type Transaction from './transaction';
 import type Statement from './statement';
@@ -95,7 +97,7 @@ function readblob(blob: any, callback: Callback): void {
     });
 }
 
-function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined, callback: Callback): void {
+function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined, transform: ((key: string) => string) | undefined, callback: Callback): void {
     if (!row || !meta || !meta.length || !meta.some((m) => m && m.type === Const.SQL_BLOB)) {
         callback(null, row);
         return;
@@ -106,7 +108,7 @@ function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string |
     // 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 : computeColumnKeys(meta, nestTables, lowercaseKeys);
+    const keys = isArrayRow ? null : computeColumnKeys(meta, nestTables, lowercaseKeys, transform);
     const blobCells: { target: any; key: string | number }[] = [];
 
     for (let i = 0; i < meta.length; i++) {
@@ -147,6 +149,7 @@ function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string |
 class Database extends Events.EventEmitter {
     connection: Connection;
     eventid: number;
+    private _sql?: SqlTag;
 
     constructor(connection: Connection) {
         super();
@@ -155,6 +158,17 @@ class Database extends Events.EventEmitter {
         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(): SqlTag {
+        return this._sql || (this._sql = makeSqlTag((text, params, options) =>
+            this.queryAsync(text, params, { ...options, namedPlaceholders: false })));
+    }
+
     escape(value: any): string {
         return escape(value, this.connection.accept.protocolVersion);
     }
@@ -287,12 +301,7 @@ class Database extends Events.EventEmitter {
 
                 if (!result.success) {
                     transaction.rollback(function() {
-                        var first = result.errors.length ? result.errors[0] : null;
-                        var batchError: any = first
-                            ? first.error
-                            : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
-                        batchError.batchCompletion = result;
-                        doError(batchError, callback);
+                        doError(batchResultToError(result), callback);
                     });
                     return;
                 }
@@ -325,6 +334,9 @@ class Database extends Events.EventEmitter {
         }
 
         var self = this;
+        var keyResolutionDone = false;
+        var resolvedNest: boolean | string | undefined;
+        var resolvedTransform: ((key: string) => string) | undefined;
         var _on = function(row: any, i: number, meta: any[], next: (err?: any) => void) {
             var done = false;
             var finish = function(err?: any) {
@@ -335,9 +347,15 @@ class Database extends Events.EventEmitter {
                 next(err);
             };
 
-            // options is read at call time, after the normalization below
-            const nest = resolveNestTables(options as any, self.connection.options);
-            fetchBlobSyncRow(row, meta, nest, self.connection._lowercase_keys, function(blobErr: any) {
+            // 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 = resolveNestTables(options as any, self.connection.options);
+                resolvedTransform = resolveKeyTransform(options as any, self.connection.options);
+                keyResolutionDone = true;
+            }
+            fetchBlobSyncRow(row, meta, resolvedNest, self.connection._lowercase_keys, resolvedTransform, function(blobErr: any) {
                 if (blobErr) {
                     finish(blobErr);
                     return;
@@ -393,6 +411,18 @@ class Database extends Events.EventEmitter {
         return makeQueryStream(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: string, options?: any) {
+        return makeBatchStream(this, query, options, true);
+    }
+
     query(query: string, params?: QueryParams | Callback, callback?: any, options: InternalQueryOptions = {}): this {
         if (params instanceof Function) {
             options = callback || {};
@@ -552,8 +582,9 @@ class Database extends Events.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: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]> {

package/src/wire/serialize.ts

@@ -197,7 +197,11 @@ export class BlrReader {
                 value = this.buffer.readInt16LE(this.pos);
                 break;
             case 4:
-                value = this.buffer.readInt32LE(this.pos)
+                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;
@@ -342,6 +346,17 @@ export class XdrWriter {
         this.pos += alen;
     }
 
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b: Buffer): void {
+        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: string, encoding: BufferEncoding): void {
         var len = Buffer.byteLength(s, encoding);
         var alen = align(len);

package/src/wire/socket.ts

@@ -163,9 +163,15 @@ class Socket {
      * Compress and/or encrypt data before sending to socket.
      */
     write(data: Buffer | Uint8Array, defer = false): void {
+        // 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);
+                data.length, (data as Buffer).toString('hex'), this.encrypt, defer);
         }
         if (defer) {
             // Accumulate deferred packets instead of overwriting.  Multiple
@@ -174,8 +180,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 as Buffer);
             return;
         }
 

package/src/wire/transaction.ts

@@ -2,12 +2,15 @@ import { doCallback, doError, fromCallback, type Callback, type SimpleCallback }
 import { parseNamedPlaceholders } from '../named-params';
 import { noop } from '../utils';
 import Const from './const';
+import { makeSqlTag, type SqlTag } from '../sql-template';
+import { describeFields, parseRecordCounts } from './xsqlvar';
 import makeQueryStream from './query-stream';
+import makeBatchStream from './batch-stream';
 import type Connection from './connection';
 import type Database from './database';
 import type Statement from './statement';
 import type { BatchCb, StatementCb, InternalQueryOptions } from './wire-types';
-import type { BatchOptions, BatchResult, QueryOptions, QueryParams, QueryStreamOptions, SequentialCallback } from '../types';
+import type { BatchOptions, BatchResult, QueryOptions, QueryParams, QueryStreamOptions, RecordCounts, SequentialCallback } from '../types';
 
 /***************************************
  *
@@ -53,11 +56,80 @@ class Transaction {
     // populated externally from the op_transaction response
     handle!: number;
 
+    private _sql?: SqlTag;
+
     constructor(connection: Connection) {
         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(): SqlTag {
+        return this._sql || (this._sql = makeSqlTag((text, params, options) =>
+            this.queryAsync(text, params, { ...options, namedPlaceholders: false })));
+    }
+
+    /** Current savepoint nesting depth (names savepoints, see savepoint()). */
+    private _savepointDepth = 0;
+
+    /**
+     * 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<T>(work: (transaction: this) => Promise<T> | T): Promise<T> {
+        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: T;
+            try {
+                result = await work(this);
+            } catch (err: any) {
+                // 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: any) {
+                    // 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. */
     private namedPlaceholdersEnabled(options?: InternalQueryOptions): boolean {
         if (options && options.namedPlaceholders !== undefined)
@@ -138,6 +210,69 @@ class Transaction {
                     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 as any).withMeta && !(options as any).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: any, isSelect: boolean, plainDml?: boolean) {
+                    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?: RecordCounts) {
+                        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: describeFields(statement!.output),
+                            affectedRows: affectedRows,
+                            recordCounts: counts,
+                            warnings: execWarnings,
+                        }, statement!.output, isSelect);
+                    };
+
+                    var t = statement!.type;
+                    var isDml = t === Const.isc_info_sql_stmt_insert ||
+                        t === Const.isc_info_sql_stmt_update ||
+                        t === Const.isc_info_sql_stmt_delete ||
+                        t === Const.isc_info_sql_stmt_exec_procedure;
+                    if (!isDml) {
+                        finalize();
+                        return;
+                    }
+                    self.connection.statementInfo(statement!, Const.RECORDS_INFO, function(err: any, info: any) {
+                        if (err) {
+                            dropError(err);
+                            return;
+                        }
+                        finalize(parseRecordCounts(info && info.buffer));
+                    });
+                }
+
                 switch (statement.type) {
                     case Const.isc_info_sql_stmt_select:
                         statement.fetchAll(self, function(err: any, r: any) {
@@ -146,34 +281,39 @@ class Transaction {
                                 return;
                             }
 
-                            statement.release();
-
-                            if (callback)
-                                callback(undefined, r, statement.output, true);
-
+                            deliver(r, true);
                         });
 
                         break;
 
                     case Const.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?: any) {
+                                if (blobErr) {
+                                    dropError(blobErr);
+                                    return;
+                                }
+                                deliver(ret.data[0], true);
+                            });
                             break;
                         } else if (statement.output.length) {
-                            statement.fetch(self, 1, function(err: any, ret: any) {
+                            statement.fetch(self, 1, function(err: any, fret: any) {
                                 if (err) {
                                     dropError(err);
                                     return;
                                 }
 
-                                statement.release();
-
-                                if (callback)
-                                    callback(undefined, ret.data[0], statement.output, false);
+                                self.connection.resolveTextBlobs(self, fret, function(blobErr?: any) {
+                                    if (blobErr) {
+                                        dropError(blobErr);
+                                        return;
+                                    }
+                                    deliver(fret.data[0], false);
+                                });
                             });
 
                             break;
@@ -181,9 +321,7 @@ class Transaction {
 
                     // Fall through is normal
                     default:
-                        statement.release();
-                        if (callback)
-                            callback()
+                        deliver(undefined, false, true);
                         break;
                 }
 
@@ -265,6 +403,15 @@ class Transaction {
         return makeQueryStream(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: string, options?: any) {
+        return makeBatchStream(this, query, options, false);
+    }
+
     query(query: string, params?: QueryParams | Callback, callback?: any, options: InternalQueryOptions = {}): void {
         if (params instanceof Function) {
             callback = params;