node-firebird 2.9.0 → 2.10.0

package/src/wire/const.ts

@@ -269,7 +269,8 @@ const SUPPORTED_PROTOCOL = [
     [protocol.PROTOCOL_VERSION16, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 7],
     [protocol.PROTOCOL_VERSION17, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 8],
     [protocol.PROTOCOL_VERSION18, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 9],
-    [protocol.PROTOCOL_VERSION19, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 10]
+    [protocol.PROTOCOL_VERSION19, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 10],
+    [protocol.PROTOCOL_VERSION20, connect.ARCHITECTURE_GENERIC, acceptType.ptype_lazy_send, acceptType.ptype_lazy_send, 11]
 ];
 
 const authPlugin = {
@@ -472,16 +473,27 @@ const dpb = {
     isc_dpb_reset_icu 				: 89,
     isc_dpb_map_attach 				: 90,
     isc_dpb_session_time_zone 		: 91,
-    isc_dpb_parallel_workers        : 92,
-    isc_dpb_max_inline_blob_size    : 93,
-    // Firebird 6.0 SQL Schema parameters
+    // Firebird 4.0
+    isc_dpb_set_db_replica          : 92,
+    isc_dpb_set_bind                : 93,
+    isc_dpb_decfloat_round          : 94,
+    isc_dpb_decfloat_traps          : 95,
+    isc_dpb_clear_map               : 96,
+    // Firebird 5.0
+    isc_dpb_upgrade_db              : 97,
+    isc_dpb_parallel_workers        : 100,
+    isc_dpb_worker_attach           : 101,
+    // Firebird 6.0
+    // isc_dpb_owner sets the owner of a newly created database to a user
+    // other than the connecting one (create only; requires superuser).
+    isc_dpb_owner                   : 102,
+    isc_dpb_max_blob_cache_size     : 103,
+    isc_dpb_max_inline_blob_size    : 104, // Firebird 5.0.3+
     // isc_dpb_search_path sets the comma-separated ordered list of schema
     // names to search for unqualified object names (similar to PostgreSQL
-    // search_path).  Available on Protocol 20+ (Firebird 6.0).
-    isc_dpb_search_path             : 94,
-    // isc_dpb_default_schema overrides the session's current schema
-    // (CURRENT_SCHEMA) at connection time.  Available on Protocol 20+.
-    isc_dpb_default_schema          : 95,
+    // search_path). CURRENT_SCHEMA is the first existing schema of the list.
+    // Available on Protocol 20+ (Firebird 6.0).
+    isc_dpb_search_path             : 105,
 };
 
 const cnct = {

package/src/wire/database.ts

@@ -1,9 +1,23 @@
 import Events from 'events';
-import { doError, fromCallback } from '../callback';
+import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
 import { escape } from '../utils';
 import Const from './const';
 import EventConnection from './eventConnection';
 import FbEventManager from './fbEventManager';
+import makeQueryStream from './query-stream';
+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;
 
 /***************************************
  *
@@ -40,7 +54,7 @@ import FbEventManager from './fbEventManager';
  *
  ***************************************/
 
-function readblob(blob: any, callback: (err: any, data?: any) => void): void {
+function readblob(blob: any, callback: Callback): void {
     if (blob === undefined || blob === null) {
         callback(null, blob);
         return;
@@ -80,7 +94,7 @@ function readblob(blob: any, callback: (err: any, data?: any) => void): void {
     });
 }
 
-function fetchBlobSyncRow(row: any, meta: any[], callback: (err: any, row?: any) => void): void {
+function fetchBlobSyncRow(row: any, meta: any[], callback: Callback): void {
     if (!row || !meta || !meta.length) {
         callback(null, row);
         return;
@@ -118,10 +132,10 @@ function fetchBlobSyncRow(row: any, meta: any[], callback: (err: any, row?: any)
 }
 
 class Database extends Events.EventEmitter {
-    connection: any;
+    connection: Connection;
     eventid: number;
 
-    constructor(connection: any) {
+    constructor(connection: Connection) {
         super();
         this.connection = connection;
         connection.db = this;
@@ -132,7 +146,7 @@ class Database extends Events.EventEmitter {
         return escape(value, this.connection.accept.protocolVersion);
     }
 
-    detach(callback?: (err?: any, obj?: any) => void, force?: boolean): this {
+    detach(callback?: Callback, force?: boolean): this {
         var self = this;
 
         if (!force && self.connection._pending.length > 0) {
@@ -150,7 +164,7 @@ class Database extends Events.EventEmitter {
                 if (callback)
                     callback(err, obj);
 
-            }, force);
+            });
         } else {
             self.emit('detach', false);
             if (callback)
@@ -160,32 +174,35 @@ class Database extends Events.EventEmitter {
         return self;
     }
 
-    transaction(options: any, callback?: (err: any, transaction?: any) => void): this {
+    transaction(options: TransactionArg, callback?: TransactionCb): this {
         return this.startTransaction(options, callback);
     }
 
-    startTransaction(options: any, callback?: (err: any, transaction?: any) => void): this {
+    startTransaction(options: TransactionArg, callback?: TransactionCb): this {
         this.connection.startTransaction(options, callback);
         return this;
     }
 
-    newStatement(query: string, callback: (err: any, statement?: any) => void): this {
-        this.startTransaction(function(err: any, transaction: any) {
+    newStatement(query: string, callback: StatementCb): this {
+        // the public strict callback shape and the internal optional-args
+        // shape only differ in optionality; treat it as the internal one
+        const cb = callback as Callback<Statement>;
+        this.startTransaction(function(err: any, transaction?: Transaction) {
 
-            if (err) {
-                callback(err);
+            if (err || !transaction) {
+                cb(err);
                 return;
             }
 
-            transaction.newStatement(query, function(err: any, statement: any) {
+            transaction.newStatement(query, function(err: any, statement?: Statement) {
 
                 if (err) {
-                    callback(err);
+                    cb(err);
                     return;
                 }
 
                 transaction.commit(function(err: any) {
-                    callback(err, statement);
+                    cb(err, statement);
                 });
             });
         });
@@ -193,7 +210,7 @@ class Database extends Events.EventEmitter {
         return this;
     }
 
-    execute(query: string, params?: any, callback?: any, options?: any): this {
+    execute(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): this {
         if (params instanceof Function) {
             options = callback;
             callback = params;
@@ -202,9 +219,9 @@ class Database extends Events.EventEmitter {
 
         var self = this;
 
-        self.connection.startTransaction(function(err: any, transaction: any) {
+        self.connection.startTransaction(function(err: any, transaction?: Transaction) {
 
-            if (err) {
+            if (err || !transaction) {
                 doError(err, callback);
                 return;
             }
@@ -238,17 +255,17 @@ class Database extends Events.EventEmitter {
      * err.batchCompletion. Use transaction.executeBatch for partial-success
      * handling.
      */
-    executeBatch(query: string, rows: any[][], callback?: any, options?: any): this {
+    executeBatch(query: string, rows: QueryParams[], callback?: BatchCb, options?: BatchOptions): this {
         var self = this;
 
-        self.connection.startTransaction(function(err: any, transaction: any) {
-            if (err) {
+        self.connection.startTransaction(function(err: any, transaction?: Transaction) {
+            if (err || !transaction) {
                 doError(err, callback);
                 return;
             }
 
-            transaction.executeBatch(query, rows, function(err: any, result: any) {
-                if (err) {
+            transaction.executeBatch(query, rows, function(err: any, result?: BatchResult) {
+                if (err || !result) {
                     transaction.rollback(function() {
                         doError(err, callback);
                     });
@@ -277,7 +294,7 @@ class Database extends Events.EventEmitter {
         return self;
     }
 
-    sequentially(query: string, params?: any, on?: any, callback?: any, options: any = {}): this {
+    sequentially(query: string, params?: any, on?: any, callback?: any, options: InternalQueryOptions | boolean = {}): this {
         if (params instanceof Function) {
             options = callback;
             callback = on;
@@ -295,7 +312,7 @@ class Database extends Events.EventEmitter {
         }
 
         var self = this;
-        var _on = function(row: any, i: number, meta: any, next: (err?: any) => void) {
+        var _on = function(row: any, i: number, meta: any[], next: (err?: any) => void) {
             var done = false;
             var finish = function(err?: any) {
                 if (done) {
@@ -348,7 +365,20 @@ class Database extends Events.EventEmitter {
         return self;
     }
 
-    query(query: string, params?: any, callback?: any, options: any = {}): 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) {
+        return makeQueryStream(this, query, params, options);
+    }
+
+    query(query: string, params?: QueryParams | Callback, callback?: any, options: InternalQueryOptions = {}): this {
         if (params instanceof Function) {
             options = callback || {};
             callback = params;
@@ -366,7 +396,7 @@ class Database extends Events.EventEmitter {
         return self;
     }
 
-    drop(callback?: (err?: any) => void): void {
+    drop(callback?: SimpleCallback): void {
         return this.connection.dropDatabase(callback);
     }
 
@@ -377,7 +407,7 @@ 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 {
+    cancel(kind?: number | SimpleCallback, callback?: SimpleCallback): this {
         if (typeof kind === 'function') {
             callback = kind;
             kind = undefined;
@@ -386,7 +416,7 @@ class Database extends Events.EventEmitter {
         return this;
     }
 
-    attachEvent(callback: (err: any, evt?: any) => void): this {
+    attachEvent(callback: Callback<FbEventManager>): this {
         var self = this;
         const eventid = self.eventid++;
         if (process.env.FIREBIRD_DEBUG) {
@@ -450,7 +480,7 @@ 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 {
         const sql = `CREATE TABLESPACE ${name} FILE '${filePath}'`;
         return this.execute(sql, [], callback);
     }
@@ -464,7 +494,7 @@ 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 {
         const sql = `ALTER TABLESPACE ${name} SET FILE TO '${filePath}'`;
         return this.execute(sql, [], callback);
     }
@@ -477,7 +507,7 @@ 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 {
         const sql = `DROP TABLESPACE ${name}`;
         return this.execute(sql, [], callback);
     }
@@ -492,7 +522,7 @@ class Database extends Events.EventEmitter {
      * @param {function} [callback] - Asynchronous completion callback.
      * @returns {Database}
      */
-    createSchema(schemaName: string, tablespaceName?: string | ((err?: any) => void), callback?: any): this {
+    createSchema(schemaName: string, tablespaceName?: string | Callback, callback?: Callback): this {
         if (typeof tablespaceName === 'function') {
             callback = tablespaceName;
             tablespaceName = undefined;
@@ -511,22 +541,24 @@ class Database extends Events.EventEmitter {
      * callback API — the promises resolve with the rows alone.
      */
 
-    queryAsync(query: string, params?: any, options?: any): Promise<any[]> {
+    queryAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]> {
         var self = this;
         return fromCallback(function(cb) { self.query(query, params, cb, options); });
     }
 
-    executeAsync(query: string, params?: any, options?: any): Promise<any[]> {
+    executeAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]> {
         var self = this;
         return fromCallback(function(cb) { self.execute(query, params, cb, options); });
     }
 
-    executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any> {
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult> {
         var self = this;
         return fromCallback(function(cb) { self.executeBatch(query, rows, cb, options); });
     }
 
-    sequentiallyAsync(query: string, params?: any, on?: any, options?: any): Promise<void> {
+    /** `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> {
         if (params instanceof Function) {
             options = on;
             on = params;
@@ -536,16 +568,16 @@ class Database extends Events.EventEmitter {
         return fromCallback(function(cb) { self.sequentially(query, params, on, cb, options); });
     }
 
-    transactionAsync(options?: any): Promise<any> {
+    transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction> {
         var self = this;
         return fromCallback(function(cb) { self.startTransaction(options, cb); });
     }
 
-    startTransactionAsync(options?: any): Promise<any> {
+    startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction> {
         return this.transactionAsync(options);
     }
 
-    newStatementAsync(query: string): Promise<any> {
+    newStatementAsync(query: string): Promise<Statement> {
         var self = this;
         return fromCallback(function(cb) { self.newStatement(query, cb); });
     }
@@ -560,7 +592,7 @@ class Database extends Events.EventEmitter {
         return fromCallback(function(cb) { self.drop(cb); });
     }
 
-    attachEventAsync(): Promise<any> {
+    attachEventAsync(): Promise<FbEventManager> {
         var self = this;
         return fromCallback(function(cb) { self.attachEvent(cb); });
     }
@@ -575,7 +607,7 @@ class Database extends Events.EventEmitter {
      * resolves, rolls back when it rejects (the original error is rethrown,
      * even if the rollback itself fails).
      */
-    async withTransaction<T>(work: (transaction: any) => Promise<T> | T, options?: any): Promise<T> {
+    async withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T> {
         const transaction = await this.transactionAsync(options);
         try {
             const result = await work(transaction);

package/src/wire/eventConnection.ts

@@ -22,8 +22,8 @@ class EventConnection {
         this._isOpened = false;
         this._socket = net.createConnection(port, host);
         this._bind_events(host, port, callback);
-        this.error;
-        this.eventcallback;
+        this.error = null;
+        this.eventcallback = null;
     }
 
     _bind_events(host: string, port: number, callback?: () => void): void {
@@ -60,9 +60,10 @@ class EventConnection {
                 xdr.buffer = buf;
             }
 
+            var op_pos = xdr.pos;
+
             try {
 
-                var op_pos = xdr.pos;
                 var tmp_event: Record<string, number>;
                 while (xdr.pos < xdr.buffer.length) {
                     do {
@@ -72,10 +73,12 @@ class EventConnection {
                     switch (r) {
                         case Const.op_event:
                             xdr.readInt(); // db handle
-                            buf = xdr.readArray();
+                            // 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 = {};
-                            var lst_event = [];
+                            var lst_event: { name: string; count: number }[] = [];
                             var eventname = '';
                             var eventcount = 0;
                             var pos = 1;

package/src/wire/query-stream.ts

@@ -0,0 +1,80 @@
+/***************************************
+ *
+ *   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.
+ */
+function makeQueryStream(target: any, query: string, params?: any, options?: any): Readable {
+    options = options || {};
+
+    const streamOptions: any = { 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: ((err?: any) => void) | null = null;
+    const resume = (err?: any) => {
+        if (pendingNext) {
+            const next = pendingNext;
+            pendingNext = null;
+            next(err);
+        }
+    };
+
+    const stream = new Readable({
+        ...streamOptions,
+        read() {
+            resume();
+        },
+        destroy(err: any, cb: (err?: any) => void) {
+            // 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: any, _index: number, next: (err?: any) => void) {
+        if (stream.destroyed) {
+            next(abortError);
+            return;
+        }
+        if (stream.push(row)) {
+            next();
+        } else {
+            pendingNext = next;
+        }
+    }, function (err: any) {
+        if (err && err !== abortError) {
+            stream.destroy(err);
+        } else if (!stream.destroyed) {
+            stream.push(null);
+        }
+    }, queryOptions);
+
+    return stream;
+}
+
+export = makeQueryStream;

package/src/wire/serialize.ts

@@ -421,6 +421,28 @@ export class XdrReader {
     buffer: Buffer;
     pos: number;
 
+    // Row-decode scratch state used by decodeResponse (connection.ts) while
+    // decoding op_fetch_response / op_sql_response. Only meaningful within a
+    // single decode call: incomplete packets are re-decoded from scratch on
+    // a fresh XdrReader, and decodeResponse clears these at branch entry so
+    // nothing leaks between packets sharing a data event (issue #341).
+    /** 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) */
+    fcols?: string[];
+
     constructor(buffer: Buffer) {
         this.buffer = buffer;
         this.pos = 0;
@@ -506,6 +528,13 @@ export 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;