node-firebird 2.11.0 → 2.12.0

package/src/wire/database.ts

@@ -2,7 +2,8 @@ import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
 import { 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';
@@ -95,7 +96,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 +107,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 +148,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 +157,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);
     }
@@ -325,6 +338,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 +351,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;
@@ -552,8 +574,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;

package/src/wire/transaction.ts

@@ -2,12 +2,14 @@ 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 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 +55,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 +209,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 +280,23 @@ 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);
-
+                            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);
+                                deliver(fret.data[0], false);
                             });
 
                             break;
@@ -181,9 +304,7 @@ class Transaction {
 
                     // Fall through is normal
                     default:
-                        statement.release();
-                        if (callback)
-                            callback()
+                        deliver(undefined, false, true);
                         break;
                 }
 

package/src/wire/xsqlvar.ts

@@ -1,5 +1,7 @@
 import Const from './const';
+import { BlrReader } from './serialize';
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
+import type { RecordCounts } from '../types';
 
 /***************************************
  *
@@ -117,13 +119,17 @@ export interface ColumnKey {
 export function computeColumnKeys(
     output: SQLVarBase[],
     nestTables: boolean | string | undefined,
-    lowercaseKeys: boolean | undefined
+    lowercaseKeys: boolean | undefined,
+    transform?: (key: string) => string
 ): ColumnKey[] {
     return output.map((column) => {
         let key = column.alias || '';
         if (lowercaseKeys) {
             key = key.toLowerCase();
         }
+        if (transform) {
+            key = transform(key);
+        }
         if (nestTables !== true && typeof nestTables !== 'string') {
             return { key };
         }
@@ -131,6 +137,9 @@ export function computeColumnKeys(
         if (lowercaseKeys) {
             table = table.toLowerCase();
         }
+        if (transform) {
+            table = transform(table);
+        }
         if (nestTables === true) {
             return { table, key };
         }
@@ -138,6 +147,67 @@ export function computeColumnKeys(
     });
 }
 
+/** 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 function camelizeKey(key: string): string {
+    const parts = String(key).toLowerCase().split('_');
+    let out = parts[0] || '';
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part) {
+            out += part.charAt(0).toUpperCase() + part.slice(1);
+        }
+    }
+    return out;
+}
+
+/**
+ * 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 function resolveKeyTransform(
+    queryOptions: { transformKeys?: KeyTransform } | undefined,
+    connectionOptions: { transformKeys?: KeyTransform } | undefined
+): ((key: string) => string) | undefined {
+    const value = resolveQueryOption<KeyTransform>('transformKeys', queryOptions, connectionOptions);
+    if (value === 'camel') {
+        return camelizeKey;
+    }
+    if (typeof value !== 'function') {
+        return undefined;
+    }
+    return (key: string) => {
+        try {
+            return String(value(key));
+        } catch (err: any) {
+            console.warn('[node-firebird] transformKeys mapper threw for key "%s": %s — using the untransformed key',
+                key, err && err.message);
+            return key;
+        }
+    };
+}
+
+/**
+ * Shared precedence rule for per-query-overridable connection options:
+ * the per-query value wins whenever it is present (even if falsy), the
+ * connection option applies otherwise.
+ */
+function resolveQueryOption<T>(
+    name: string,
+    queryOptions: Record<string, any> | undefined,
+    connectionOptions: Record<string, any> | undefined
+): T | undefined {
+    if (queryOptions && queryOptions[name] !== undefined) {
+        return queryOptions[name];
+    }
+    return connectionOptions ? connectionOptions[name] : undefined;
+}
+
 /**
  * Resolve the effective nestTables value: the per-query option wins over
  * the connection option. The decoder and fetchBlobSyncRow both use this —
@@ -148,10 +218,7 @@ export function resolveNestTables(
     queryOptions: { nestTables?: boolean | string } | undefined,
     connectionOptions: { nestTables?: boolean | string } | undefined
 ): boolean | string | undefined {
-    if (queryOptions && queryOptions.nestTables !== undefined) {
-        return queryOptions.nestTables;
-    }
-    return connectionOptions && connectionOptions.nestTables;
+    return resolveQueryOption('nestTables', queryOptions, connectionOptions);
 }
 
 /**
@@ -169,6 +236,104 @@ export function nestCell(row: any, table: string | undefined) {
 
 //------------------------------------------------------
 
+/** Human-readable names for the SQL_* wire type codes. */
+export const SQL_TYPE_NAMES: Record<number, string> = {
+    [Const.SQL_TEXT]: 'TEXT',
+    [Const.SQL_VARYING]: 'VARYING',
+    [Const.SQL_SHORT]: 'SHORT',
+    [Const.SQL_LONG]: 'LONG',
+    [Const.SQL_FLOAT]: 'FLOAT',
+    [Const.SQL_DOUBLE]: 'DOUBLE',
+    [Const.SQL_D_FLOAT]: 'D_FLOAT',
+    [Const.SQL_TIMESTAMP]: 'TIMESTAMP',
+    [Const.SQL_BLOB]: 'BLOB',
+    [Const.SQL_ARRAY]: 'ARRAY',
+    [Const.SQL_QUAD]: 'QUAD',
+    [Const.SQL_TYPE_TIME]: 'TIME',
+    [Const.SQL_TYPE_DATE]: 'DATE',
+    [Const.SQL_INT64]: 'INT64',
+    [Const.SQL_INT128]: 'INT128',
+    [Const.SQL_TIMESTAMP_TZ]: 'TIMESTAMP_TZ',
+    [Const.SQL_TIMESTAMP_TZ_EX]: 'TIMESTAMP_TZ_EX',
+    [Const.SQL_TIME_TZ]: 'TIME_TZ',
+    [Const.SQL_TIME_TZ_EX]: 'TIME_TZ_EX',
+    [Const.SQL_DEC16]: 'DEC16',
+    [Const.SQL_DEC34]: 'DEC34',
+    [Const.SQL_BOOLEAN]: 'BOOLEAN',
+    [Const.SQL_NULL]: 'NULL',
+};
+
+/**
+ * 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 function describeField(meta: Partial<SQLVarBase>) {
+    return {
+        type: meta.type!,
+        typeName: SQL_TYPE_NAMES[meta.type!] || 'UNKNOWN',
+        subType: meta.subType,
+        scale: meta.scale,
+        length: meta.length,
+        nullable: meta.nullable,
+        field: meta.field,
+        relation: meta.relation,
+        relationAlias: meta.relationAlias,
+        relationSchema: meta.relationSchema,
+        alias: meta.alias,
+    };
+}
+
+/**
+ * Map a statement's output descriptors to the column-metadata array
+ * delivered in withMeta results ({ rows, fields, ... }).
+ */
+export function describeFields(output: SQLVarBase[]) {
+    return (output || []).map(describeField);
+}
+
+/**
+ * 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 function parseRecordCounts(buffer: Buffer | undefined): RecordCounts {
+    const counts = { selectCount: 0, insertCount: 0, updateCount: 0, deleteCount: 0 };
+    if (!buffer || !buffer.length) {
+        return counts;
+    }
+    // this runs inside a response callback — a malformed/truncated buffer
+    // must yield partial counts, never a throw
+    try {
+        const br = new BlrReader(buffer);
+        while (br.pos < br.buffer.length) {
+            const item = br.readByteCode();
+            if (item === Const.isc_info_end || item === Const.isc_info_truncated) {
+                break;
+            }
+            if (item === Const.isc_info_sql_records) {
+                br.pos += 2; // skip the cluster's total length; nested items follow
+                continue;
+            }
+            switch (item) {
+                case Const.isc_info_req_select_count: counts.selectCount = br.readInt() || 0; break;
+                case Const.isc_info_req_insert_count: counts.insertCount = br.readInt() || 0; break;
+                case Const.isc_info_req_update_count: counts.updateCount = br.readInt() || 0; break;
+                case Const.isc_info_req_delete_count: counts.deleteCount = br.readInt() || 0; break;
+                default:
+                    // unknown item: its 2-byte length prefix tells us how far to skip
+                    br.pos += 2 + br.buffer.readUInt16LE(br.pos);
+            }
+        }
+    } catch (e) {
+        // fall through with whatever was parsed so far
+    }
+    return counts;
+}
+
+//------------------------------------------------------
+
 export class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any) {
         let ret;