node-firebird 2.10.0 → 2.12.0

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';
 
 /***************************************
  *
@@ -93,6 +95,245 @@ export abstract class SQLVarBase {
 
 //------------------------------------------------------
 
+/** 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 function computeColumnKeys(
+    output: SQLVarBase[],
+    nestTables: boolean | string | 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 };
+        }
+        let table = column.relationAlias || column.relation || '';
+        if (lowercaseKeys) {
+            table = table.toLowerCase();
+        }
+        if (transform) {
+            table = transform(table);
+        }
+        if (nestTables === true) {
+            return { table, key };
+        }
+        return { key: table + nestTables + key };
+    });
+}
+
+/** 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 —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+export function resolveNestTables(
+    queryOptions: { nestTables?: boolean | string } | undefined,
+    connectionOptions: { nestTables?: boolean | string } | undefined
+): boolean | string | undefined {
+    return resolveQueryOption('nestTables', queryOptions, connectionOptions);
+}
+
+/**
+ * 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 function nestCell(row: any, table: string | undefined) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
+
+//------------------------------------------------------
+
+/** 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;