node-firebird 2.9.0 → 2.11.0

package/lib/wire/database.d.ts

@@ -1,14 +1,27 @@
 import Events from 'events';
+import { type Callback, type SimpleCallback } from '../callback';
+import FbEventManager from './fbEventManager';
+import type Connection from './connection';
+import type Transaction from './transaction';
+import type Statement from './statement';
+import type { BatchCb, StatementCb, InternalQueryOptions } from './wire-types';
+import type { BatchOptions, BatchResult, Isolation, QueryParams, QueryStreamOptions, TransactionCallback, TransactionOptions } from '../types';
+/** Callback for startTransaction: the internal optional-args shape, or the
+ *  public TransactionCallback (non-optional transaction) from types.ts. */
+type TransactionCb = Callback<Transaction> | TransactionCallback;
+/** startTransaction options: resolved options object, a bare isolation
+ *  array, or omitted entirely (callback in the options position). */
+type TransactionArg = TransactionOptions | Isolation | TransactionCb | undefined;
 declare class Database extends Events.EventEmitter {
-    connection: any;
+    connection: Connection;
     eventid: number;
-    constructor(connection: any);
+    constructor(connection: Connection);
     escape(value: any): string;
-    detach(callback?: (err?: any, obj?: any) => void, force?: boolean): this;
-    transaction(options: any, callback?: (err: any, transaction?: any) => void): this;
-    startTransaction(options: any, callback?: (err: any, transaction?: any) => void): this;
-    newStatement(query: string, callback: (err: any, statement?: any) => void): this;
-    execute(query: string, params?: any, callback?: any, options?: any): this;
+    detach(callback?: Callback, force?: boolean): this;
+    transaction(options: TransactionArg, callback?: TransactionCb): this;
+    startTransaction(options: TransactionArg, callback?: TransactionCb): this;
+    newStatement(query: string, callback: StatementCb): this;
+    execute(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): this;
     /**
      * Bulk-execute `query` once per row via the Firebird 4 batch API
      * (protocol 16+) with all-or-nothing semantics: the batch runs in its
@@ -18,10 +31,20 @@ declare class Database extends Events.EventEmitter {
      * err.batchCompletion. Use transaction.executeBatch for partial-success
      * handling.
      */
-    executeBatch(query: string, rows: any[][], callback?: any, options?: any): this;
-    sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
-    query(query: string, params?: any, callback?: any, options?: any): this;
-    drop(callback?: (err?: any) => void): void;
+    executeBatch(query: string, rows: QueryParams[], callback?: BatchCb, options?: BatchOptions): this;
+    sequentially(query: string, params?: any, on?: any, callback?: any, options?: InternalQueryOptions | boolean): this;
+    /**
+     * Run `query` and return an object-mode Readable emitting one row per
+     * chunk (what pg-query-stream / mysql2 .stream() return), with real
+     * backpressure: fetching pauses while the stream buffer is full. Runs
+     * in its own transaction, like db.query. Destroying the stream early
+     * (e.g. a pipeline() teardown) aborts the fetch and releases the
+     * statement. Rows go through the regular decode path, so typeCast,
+     * blobAsText and jsonAsObject all apply.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): this;
+    drop(callback?: SimpleCallback): void;
     /**
      * Cancel the operation currently executing on this connection by sending
      * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
@@ -29,8 +52,8 @@ declare class Database extends Events.EventEmitter {
      * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
      * per-attachment, not per-statement.
      */
-    cancel(kind?: number | ((err?: any) => void), callback?: (err?: any) => void): this;
-    attachEvent(callback: (err: any, evt?: any) => void): this;
+    cancel(kind?: number | SimpleCallback, callback?: SimpleCallback): this;
+    attachEvent(callback: Callback<FbEventManager>): this;
     /**
      * Create a physical tablespace.
      * Supported in Firebird 6.0+ (Protocol 20+).
@@ -40,7 +63,7 @@ declare class Database extends Events.EventEmitter {
      * @param {function} [callback] - Asynchronous completion callback.
      * @returns {Database}
      */
-    createTablespace(name: string, filePath: string, callback?: any): this;
+    createTablespace(name: string, filePath: string, callback?: Callback): this;
     /**
      * Alter an existing tablespace physical location.
      * Supported in Firebird 6.0+ (Protocol 20+).
@@ -50,7 +73,7 @@ declare class Database extends Events.EventEmitter {
      * @param {function} [callback] - Asynchronous completion callback.
      * @returns {Database}
      */
-    alterTablespace(name: string, filePath: string, callback?: any): this;
+    alterTablespace(name: string, filePath: string, callback?: Callback): this;
     /**
      * Drop a tablespace.
      * Supported in Firebird 6.0+ (Protocol 20+).
@@ -59,7 +82,7 @@ declare class Database extends Events.EventEmitter {
      * @param {function} [callback] - Asynchronous completion callback.
      * @returns {Database}
      */
-    dropTablespace(name: string, callback?: any): this;
+    dropTablespace(name: string, callback?: Callback): this;
     /**
      * Create a schema/namespace. Can optionally partition/map the namespace
      * to a physical tablespace.
@@ -70,23 +93,25 @@ declare class Database extends Events.EventEmitter {
      * @param {function} [callback] - Asynchronous completion callback.
      * @returns {Database}
      */
-    createSchema(schemaName: string, tablespaceName?: string | ((err?: any) => void), callback?: any): this;
-    queryAsync(query: string, params?: any, options?: any): Promise<any[]>;
-    executeAsync(query: string, params?: any, options?: any): Promise<any[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any>;
-    sequentiallyAsync(query: string, params?: any, on?: any, options?: any): Promise<void>;
-    transactionAsync(options?: any): Promise<any>;
-    startTransactionAsync(options?: any): Promise<any>;
-    newStatementAsync(query: string): Promise<any>;
+    createSchema(schemaName: string, tablespaceName?: string | Callback, callback?: Callback): this;
+    queryAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]>;
+    executeAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]>;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
+    /** `on` may hold the options when the params argument is the row callback
+     *  (public overload: sequentiallyAsync(query, rowCallback, options)). */
+    sequentiallyAsync(query: string, params?: any, on?: any, options?: InternalQueryOptions | boolean): Promise<void>;
+    transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
+    startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
+    newStatementAsync(query: string): Promise<Statement>;
     detachAsync(force?: boolean): Promise<void>;
     dropAsync(): Promise<void>;
-    attachEventAsync(): Promise<any>;
+    attachEventAsync(): Promise<FbEventManager>;
     cancelAsync(kind?: number): Promise<void>;
     /**
      * Run `work` inside a transaction: commits when the returned promise
      * resolves, rolls back when it rejects (the original error is rethrown,
      * even if the rollback itself fails).
      */
-    withTransaction<T>(work: (transaction: any) => Promise<T> | T, options?: any): Promise<T>;
+    withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
 }
 export = Database;

package/lib/wire/database.js

@@ -6,8 +6,10 @@ const events_1 = __importDefault(require("events"));
 const callback_1 = require("../callback");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
+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"));
 /***************************************
  *
  *   Database
@@ -74,30 +76,42 @@ function readblob(blob, callback) {
         });
     });
 }
-function fetchBlobSyncRow(row, meta, callback) {
-    if (!row || !meta || !meta.length) {
+function fetchBlobSyncRow(row, meta, nestTables, lowercaseKeys, 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);
+    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);
@@ -128,7 +142,7 @@ class Database extends events_1.default.EventEmitter {
                 self.emit('detach', false);
                 if (callback)
                     callback(err, obj);
-            }, force);
+            });
         }
         else {
             self.emit('detach', false);
@@ -145,18 +159,21 @@ class Database extends events_1.default.EventEmitter {
         return this;
     }
     newStatement(query, callback) {
+        // the public strict callback shape and the internal optional-args
+        // shape only differ in optionality; treat it as the internal one
+        const cb = callback;
         this.startTransaction(function (err, transaction) {
-            if (err) {
-                callback(err);
+            if (err || !transaction) {
+                cb(err);
                 return;
             }
             transaction.newStatement(query, function (err, statement) {
                 if (err) {
-                    callback(err);
+                    cb(err);
                     return;
                 }
                 transaction.commit(function (err) {
-                    callback(err, statement);
+                    cb(err, statement);
                 });
             });
         });
@@ -170,7 +187,7 @@ class Database extends events_1.default.EventEmitter {
         }
         var self = this;
         self.connection.startTransaction(function (err, transaction) {
-            if (err) {
+            if (err || !transaction) {
                 (0, callback_1.doError)(err, callback);
                 return;
             }
@@ -201,12 +218,12 @@ class Database extends events_1.default.EventEmitter {
     executeBatch(query, rows, callback, options) {
         var self = this;
         self.connection.startTransaction(function (err, transaction) {
-            if (err) {
+            if (err || !transaction) {
                 (0, callback_1.doError)(err, callback);
                 return;
             }
             transaction.executeBatch(query, rows, function (err, result) {
-                if (err) {
+                if (err || !result) {
                     transaction.rollback(function () {
                         (0, callback_1.doError)(err, callback);
                     });
@@ -255,7 +272,9 @@ 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
+            const nest = (0, xsqlvar_1.resolveNestTables)(options, self.connection.options);
+            fetchBlobSyncRow(row, meta, nest, self.connection._lowercase_keys, function (blobErr) {
                 if (blobErr) {
                     finish(blobErr);
                     return;
@@ -297,6 +316,18 @@ class Database extends events_1.default.EventEmitter {
         self.execute(query, params, callback, options);
         return self;
     }
+    /**
+     * Run `query` and return an object-mode Readable emitting one row per
+     * chunk (what pg-query-stream / mysql2 .stream() return), with real
+     * backpressure: fetching pauses while the stream buffer is full. Runs
+     * in its own transaction, like db.query. Destroying the stream early
+     * (e.g. a pipeline() teardown) aborts the fetch and releases the
+     * statement. Rows go through the regular decode path, so typeCast,
+     * blobAsText and jsonAsObject all apply.
+     */
+    queryStream(query, params, options) {
+        return (0, query_stream_1.default)(this, query, params, options);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             options = callback || {};
@@ -452,6 +483,8 @@ class Database extends events_1.default.EventEmitter {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.executeBatch(query, rows, cb, options); });
     }
+    /** `on` may hold the options when the params argument is the row callback
+     *  (public overload: sequentiallyAsync(query, rowCallback, options)). */
     sequentiallyAsync(query, params, on, options) {
         if (params instanceof Function) {
             options = on;

package/lib/wire/eventConnection.js

@@ -15,8 +15,8 @@ class EventConnection {
         this._isOpened = false;
         this._socket = net_1.default.createConnection(port, host);
         this._bind_events(host, port, callback);
-        this.error;
-        this.eventcallback;
+        this.error = null;
+        this.eventcallback = null;
     }
     _bind_events(host, port, callback) {
         var self = this;
@@ -45,8 +45,8 @@ class EventConnection {
                 data.copy(buf, xdr.buffer.length);
                 xdr.buffer = buf;
             }
+            var op_pos = xdr.pos;
             try {
-                var op_pos = xdr.pos;
                 var tmp_event;
                 while (xdr.pos < xdr.buffer.length) {
                     do {
@@ -55,6 +55,8 @@ class EventConnection {
                     switch (r) {
                         case const_1.default.op_event:
                             xdr.readInt(); // db handle
+                            // op_event always carries a payload; readArray only
+                            // returns undefined for zero-length arrays
                             buf = xdr.readArray();
                             // first byte is always set to 1
                             tmp_event = {};

package/lib/wire/query-stream.d.ts

@@ -0,0 +1,18 @@
+/***************************************
+ *
+ *   queryStream — object-mode Readable over sequentially()
+ *
+ ***************************************/
+import { Readable } from 'stream';
+/**
+ * Build an object-mode Readable that emits one row per chunk, implemented
+ * on top of `target.sequentially()`'s next()-based backpressure: fetching
+ * pauses whenever the stream's internal buffer is full and resumes when
+ * the consumer drains it. Shared by Database.queryStream and
+ * Transaction.queryStream.
+ *
+ * Destroying the stream early (including a pipeline() teardown) aborts the
+ * row loop, which releases the statement server-side.
+ */
+declare function makeQueryStream(target: any, query: string, params?: any, options?: any): Readable;
+export = makeQueryStream;

package/lib/wire/query-stream.js

@@ -0,0 +1,73 @@
+"use strict";
+/***************************************
+ *
+ *   queryStream — object-mode Readable over sequentially()
+ *
+ ***************************************/
+const stream_1 = require("stream");
+/**
+ * Build an object-mode Readable that emits one row per chunk, implemented
+ * on top of `target.sequentially()`'s next()-based backpressure: fetching
+ * pauses whenever the stream's internal buffer is full and resumes when
+ * the consumer drains it. Shared by Database.queryStream and
+ * Transaction.queryStream.
+ *
+ * Destroying the stream early (including a pipeline() teardown) aborts the
+ * row loop, which releases the statement server-side.
+ */
+function makeQueryStream(target, query, params, options) {
+    options = options || {};
+    const streamOptions = { objectMode: true };
+    if (options.highWaterMark !== undefined) {
+        streamOptions.highWaterMark = options.highWaterMark;
+    }
+    // forwarded to sequentially(); these keys would break its plumbing
+    const queryOptions = { ...options };
+    delete queryOptions.on;
+    delete queryOptions.asStream;
+    delete queryOptions.highWaterMark;
+    // sentinel used to stop the row loop on early destroy; recognized by
+    // identity in the completion callback and never surfaced to the user
+    const abortError = new Error('queryStream destroyed');
+    let pendingNext = null;
+    const resume = (err) => {
+        if (pendingNext) {
+            const next = pendingNext;
+            pendingNext = null;
+            next(err);
+        }
+    };
+    const stream = new stream_1.Readable({
+        ...streamOptions,
+        read() {
+            resume();
+        },
+        destroy(err, cb) {
+            // if the row loop is paused waiting for us, abort it so the
+            // statement is released instead of leaking mid-fetch
+            resume(abortError);
+            cb(err);
+        },
+    });
+    target.sequentially(query, params, function (row, _index, next) {
+        if (stream.destroyed) {
+            next(abortError);
+            return;
+        }
+        if (stream.push(row)) {
+            next();
+        }
+        else {
+            pendingNext = next;
+        }
+    }, function (err) {
+        if (err && err !== abortError) {
+            stream.destroy(err);
+        }
+        else if (!stream.destroyed) {
+            stream.push(null);
+        }
+    }, queryOptions);
+    return stream;
+}
+module.exports = makeQueryStream;

package/lib/wire/serialize.d.ts

@@ -27,7 +27,7 @@ export declare class BlrReader {
     constructor(buffer: Buffer);
     readByteCode(): number;
     readInt32(): number;
-    readInt(): any;
+    readInt(): number | undefined;
     readString(encoding?: BufferEncoding): string;
     readSegment(): Buffer;
 }
@@ -69,6 +69,24 @@ export declare class XdrWriter {
 export declare class XdrReader {
     buffer: Buffer;
     pos: number;
+    /** opcode carried over for a resumed decode (vestigial, see connection.ts) */
+    r?: number | null;
+    /** partial fetch-op flag (vestigial) */
+    fop?: boolean;
+    /** fetch status of the current row batch (100 = end of cursor) */
+    fstatus?: number;
+    /** rows remaining in the current packet */
+    fcount?: number;
+    /** column index the row decode stopped at */
+    fcolumn?: number;
+    /** row currently being decoded (object or array) */
+    frow?: any;
+    /** rows decoded so far in this call */
+    frows?: any[];
+    /** 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;
@@ -83,7 +101,7 @@ export declare class XdrReader {
     };
     readFloat(): number;
     readDouble(): number;
-    readArray(): Buffer<ArrayBuffer>;
+    readArray(): Buffer<ArrayBuffer> | undefined;
     readBuffer(len?: number, toAlign?: boolean): Buffer | undefined;
     readString(encoding: BufferEncoding): string;
     readText(len: number, encoding: BufferEncoding): string;

package/lib/wire/serialize.js

@@ -408,6 +408,13 @@ class XdrReader {
         var len = this.readInt();
         if (!len)
             return;
+        // Firebird 2.5 sign-extends XDR opaque lengths above 32767: a
+        // 32768-byte array arrives as length 0xFFFF8000. A negative length
+        // is never valid, so recover the real length from the low 16 bits
+        // instead of corrupting the read position (issue #312 — hang when
+        // preparing a statement with very many parameters on FB 2.5).
+        if (len < 0)
+            len &= 0xFFFF;
         var r = this.buffer.slice(this.pos, this.pos + len);
         this.pos += align(len);
         return r;

package/lib/wire/service.d.ts

@@ -62,5 +62,47 @@ declare class ServiceManager extends Events.EventEmitter {
     hasRunningAction(options: any, callback: any): void;
     readusers(options: any, callback: any): void;
     readlimbo(options: any, callback: any): void;
+    detachAsync(force?: boolean): Promise<void>;
+    backupAsync(options: any): Promise<stream.Readable>;
+    nbackupAsync(options: any): Promise<stream.Readable>;
+    restoreAsync(options: any): Promise<stream.Readable>;
+    nrestoreAsync(options: any): Promise<stream.Readable>;
+    setDialectAsync(db: string, dialect: number): Promise<any>;
+    setSweepintervalAsync(db: string, sweepinterval: number): Promise<any>;
+    setCachebufferAsync(db: string, nbpages: number): Promise<any>;
+    BringOnlineAsync(db: string): Promise<any>;
+    ShutdownAsync(db: string, kind: number, delay: number, mode?: any): Promise<any>;
+    setShadowAsync(db: string, val: boolean): Promise<any>;
+    setForcewriteAsync(db: string, val: boolean): Promise<any>;
+    setReservespaceAsync(db: string, val: boolean): Promise<any>;
+    setReadonlyModeAsync(db: string): Promise<any>;
+    setReadwriteModeAsync(db: string): Promise<any>;
+    validateAsync(options: any): Promise<stream.Readable>;
+    commitAsync(db: string, transactid: number): Promise<any>;
+    rollbackAsync(db: string, transactid: number): Promise<any>;
+    recoverAsync(db: string, transactid: number): Promise<any>;
+    getStatsAsync(options: any): Promise<stream.Readable>;
+    getLogAsync(options: any): Promise<stream.Readable>;
+    getUsersAsync(username?: string | null): Promise<any>;
+    addUserAsync(username: string, password: string, options?: any): Promise<any>;
+    editUserAsync(username: string, options: any): Promise<any>;
+    removeUserAsync(username: string, rolename?: string | null): Promise<any>;
+    getFbserverInfosAsync(infos?: any, options?: any): Promise<any>;
+    startTraceAsync(options: any): Promise<stream.Readable>;
+    suspendTraceAsync(options: any): Promise<stream.Readable>;
+    resumeTraceAsync(options: any): Promise<stream.Readable>;
+    stopTraceAsync(options: any): Promise<stream.Readable>;
+    getTraceListAsync(options?: any): Promise<stream.Readable>;
+    readlineAsync(options?: any): Promise<{
+        result: number;
+        line: string;
+    }>;
+    readeofAsync(options?: any): Promise<{
+        result: number;
+        line: string;
+    }>;
+    hasRunningActionAsync(options?: any): Promise<any>;
+    readusersAsync(options?: any): Promise<any>;
+    readlimboAsync(options?: any): Promise<any>;
 }
 export = ServiceManager;