node-firebird 2.10.0 → 2.12.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
@@ -577,6 +583,7 @@ const DESCRIBE = [
     sqlInfo.isc_info_sql_length,
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
+    sqlInfo.isc_info_sql_relation_alias, // FB 2.0+: query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -604,6 +611,7 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
     sqlInfo.isc_info_sql_relation_schema, // FB 6.0: schema of source relation
+    sqlInfo.isc_info_sql_relation_alias, // query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -616,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      */
 /***********************/
@@ -841,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;

package/lib/wire/database.js

@@ -6,6 +6,8 @@ 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"));
@@ -75,30 +77,42 @@ function readblob(blob, callback) {
         });
     });
 }
-function fetchBlobSyncRow(row, meta, callback) {
-    if (!row || !meta || !meta.length) {
+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;
     }
-    const rowKeys = Object.keys(row);
-    const blobColumns = [];
+    // locate blob cells by the same key computation the fetch decoder used,
+    // rather than assuming Object.keys(row) is index-aligned with meta —
+    // 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, transform);
+    const blobCells = [];
     for (let i = 0; i < meta.length; i++) {
-        if (meta[i] && meta[i].type === const_1.default.SQL_BLOB && rowKeys[i] !== undefined) {
-            blobColumns.push(rowKeys[i]);
+        if (!meta[i] || meta[i].type !== const_1.default.SQL_BLOB) {
+            continue;
+        }
+        const target = keys ? (0, xsqlvar_1.nestCell)(row, keys[i].table) : row;
+        const key = keys ? keys[i].key : i;
+        // duplicate aliases collapse onto one cell — read it only once
+        if (typeof target[key] === 'function' &&
+            !blobCells.some((cell) => cell.target === target && cell.key === key)) {
+            blobCells.push({ target, key });
         }
     }
-    if (!blobColumns.length) {
+    if (!blobCells.length) {
         callback(null, row);
         return;
     }
-    let pending = blobColumns.length;
+    let pending = blobCells.length;
     let blobErr;
-    blobColumns.forEach(function (columnName) {
-        readblob(row[columnName], function (err, data) {
+    blobCells.forEach(function (cell) {
+        readblob(cell.target[cell.key], function (err, data) {
             if (err && !blobErr) {
                 blobErr = err;
             }
-            row[columnName] = data;
+            cell.target[cell.key] = data;
             pending--;
             if (pending === 0) {
                 callback(blobErr, row);
@@ -113,6 +127,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);
     }
@@ -250,6 +273,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) {
@@ -259,7 +285,15 @@ class Database extends events_1.default.EventEmitter {
                 done = true;
                 next(err);
             };
-            fetchBlobSyncRow(row, meta, 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;
@@ -453,8 +487,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

@@ -83,8 +83,10 @@ export declare class XdrReader {
     frow?: any;
     /** rows decoded so far in this call */
     frows?: any[];
-    /** cached object-row keys (column aliases) */
+    /** cached object-row keys (column aliases, qualified when nestTables is set) */
     fcols?: string[];
+    /** cached per-column table keys when nestTables === true */
+    ftables?: string[];
     constructor(buffer: Buffer);
     readInt(): number;
     readUInt(): number;

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;

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;

package/lib/wire/transaction.js

@@ -6,6 +6,8 @@ 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"));
 /***************************************
  *
@@ -44,9 +46,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 +182,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 +249,27 @@ 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);
+                            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);
+                                deliver(fret.data[0], false);
                             });
                             break;
                         }
                     // Fall through is normal
                     default:
-                        statement.release();
-                        if (callback)
-                            callback();
+                        deliver(undefined, false, true);
                         break;
                 }
             }, options);

package/lib/wire/xsqlvar.d.ts

@@ -1,4 +1,5 @@
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
+import type { RecordCounts } from '../types';
 /**
  * Common shape of all SQLVar descriptor objects.  The metadata properties
  * are populated externally (in connection.ts) from the op_prepare_statement
@@ -21,6 +22,105 @@ export declare abstract class SQLVarBase {
     abstract decode(data: XdrReader, lowerV13: boolean, options?: any): any;
     abstract calcBlr(blr: BlrWriter): void;
 }
+/** Effective object-row key(s) of one output column (see computeColumnKeys). */
+export interface ColumnKey {
+    /** Top-level table key when nestTables === true; undefined otherwise. */
+    table?: string;
+    /** Property key: the column alias, or 'table<sep>alias' in separator mode. */
+    key: string;
+}
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+export declare function computeColumnKeys(output: SQLVarBase[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined, transform?: (key: string) => string): ColumnKey[];
+/** transformKeys option value: the built-in 'camel', or a custom mapper. */
+export type KeyTransform = 'camel' | ((key: string) => string);
+/** FIRST_NAME → firstName (the transformKeys: 'camel' built-in). */
+export declare function camelizeKey(key: string): string;
+/**
+ * Resolve the effective transformKeys value (per-query wins over the
+ * connection option) into a callable mapper, or undefined when off.
+ * A custom mapper is guarded like the typeCast hook: a throw inside the
+ * row-decode loop would be mistaken for an incomplete packet and desync
+ * the response queue, so failures fall back to the untransformed key.
+ */
+export declare function resolveKeyTransform(queryOptions: {
+    transformKeys?: KeyTransform;
+} | undefined, connectionOptions: {
+    transformKeys?: KeyTransform;
+} | undefined): ((key: string) => string) | undefined;
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+export declare function resolveNestTables(queryOptions: {
+    nestTables?: boolean | string;
+} | undefined, connectionOptions: {
+    nestTables?: boolean | string;
+} | undefined): boolean | string | undefined;
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+export declare function nestCell(row: any, table: string | undefined): any;
+/** Human-readable names for the SQL_* wire type codes. */
+export declare const SQL_TYPE_NAMES: Record<number, string>;
+/**
+ * Public column-metadata shape for one output descriptor: the vocabulary
+ * both the typeCast hook and withMeta `fields` deliver. Keep the two in
+ * lockstep by building both through here.
+ */
+export declare function describeField(meta: Partial<SQLVarBase>): {
+    type: number;
+    typeName: string;
+    subType: number | undefined;
+    scale: number | undefined;
+    length: number | undefined;
+    nullable: boolean | undefined;
+    field: string | undefined;
+    relation: string | undefined;
+    relationAlias: string | undefined;
+    relationSchema: string | undefined;
+    alias: string | undefined;
+};
+/**
+ * Map a statement's output descriptors to the column-metadata array
+ * delivered in withMeta results ({ rows, fields, ... }).
+ */
+export declare function describeFields(output: SQLVarBase[]): {
+    type: number;
+    typeName: string;
+    subType: number | undefined;
+    scale: number | undefined;
+    length: number | undefined;
+    nullable: boolean | undefined;
+    field: string | undefined;
+    relation: string | undefined;
+    relationAlias: string | undefined;
+    relationSchema: string | undefined;
+    alias: string | undefined;
+}[];
+/**
+ * Parse the op_info_sql response buffer of a Const.RECORDS_INFO request
+ * into per-verb row counts. The buffer holds an isc_info_sql_records
+ * cluster (2-byte total length, then nested isc_info_req_*_count items,
+ * each 2-byte length + little-endian integer) terminated by isc_info_end.
+ */
+export declare function parseRecordCounts(buffer: Buffer | undefined): RecordCounts;
 export declare class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any): string | Buffer<ArrayBufferLike> | null | undefined;
     calcBlr(blr: BlrWriter): void;