node-firebird 2.9.0 → 2.11.0

package/src/wire/connection.ts

@@ -3,7 +3,7 @@ import os from 'os';
 import path from 'path';
 
 import { XdrWriter, BlrWriter, XdrReader, BitSet, BlrReader } from './serialize';
-import { doCallback, doError } from '../callback';
+import { doCallback, doError, type Callback, type SimpleCallback } from '../callback';
 import * as srp from '../srp';
 import * as crypt from '../unix-crypt';
 import Const from './const';
@@ -14,6 +14,8 @@ import Statement from './statement';
 import Transaction from './transaction';
 import { lookupMessages, noop, parseDate } from '../utils';
 import Socket from './socket';
+import type { QueueCallback, QueueEntry, WireResponse, InternalOptions, InternalQueryOptions, BatchCb, Quad, AcceptPacket } from './wire-types';
+import type { BatchOptions, BatchResult, QueryParams } from '../types';
 
 function parseValueIfJson(value: any, options: any) {
     if (options && options.jsonAsObject && typeof value === 'string' && (value.startsWith('{') || value.startsWith('['))) {
@@ -26,6 +28,115 @@ function parseValueIfJson(value: any, options: any) {
     return value;
 }
 
+/**
+ * Resolve the prepared-statement cache limit from the connection options:
+ * `statementCacheSize` (new), or the legacy `cacheQuery`/`maxCachedQuery`
+ * pair (which had no eviction; it now gets a bounded LRU). 0 = disabled.
+ */
+/**
+ * Build the isc_dpb_search_path value from the defaultSchema / searchPath
+ * options (Firebird 6.0 / protocol 20+). There is no "default schema" DPB
+ * tag in Firebird: CURRENT_SCHEMA is simply the first existing schema of
+ * the search path, so defaultSchema is implemented by putting it at the
+ * front of the list. When only defaultSchema is given, PUBLIC is kept as a
+ * fallback so unqualified names outside the new schema still resolve (the
+ * server always appends SYSTEM itself). Returns null when neither option
+ * is set.
+ */
+function buildSchemaSearchPath(options: InternalOptions): string | null {
+    var list: string[] = [];
+    if (options.searchPath) {
+        list = Array.isArray(options.searchPath)
+            ? options.searchPath.slice()
+            : String(options.searchPath).split(',').map(function(s: string) { return s.trim(); }).filter(Boolean);
+    }
+    var def = options.defaultSchema;
+    if (def) {
+        if (list.length === 0) {
+            // defaultSchema alone: keep PUBLIC as a fallback after it
+            list = def === 'PUBLIC' ? ['PUBLIC'] : [def, 'PUBLIC'];
+        } else {
+            // explicit searchPath: respect it, just move defaultSchema first
+            list = [def].concat(list.filter(function(s) { return s !== def; }));
+        }
+    }
+    return list.length ? list.join(',') : null;
+}
+
+function statementCacheLimit(options: InternalOptions): number {
+    const size = options && options.statementCacheSize;
+    if (size && size > 0) {
+        return Math.floor(size);
+    }
+    if (options && options.cacheQuery) {
+        const legacy = options.maxCachedQuery;
+        return legacy && legacy > 0 ? Math.floor(legacy) : 100;
+    }
+    return 0;
+}
+
+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',
+};
+
+/**
+ * Run the user's typeCast hook (options.typeCast) for one column value.
+ * The hook receives the column metadata and a next() returning the value
+ * the driver would produce by default (after blobAsText/jsonAsObject);
+ * whatever it returns becomes the value in the row. Rows may be decoded
+ * more than once when a response spans TCP packets, so the hook must be
+ * a pure function of its inputs.
+ */
+function applyTypeCast(options: InternalOptions, meta: Partial<Xsql.SQLVarBase>, defaultValue: any) {
+    const typeCast = options && options.typeCast;
+    if (typeof typeCast !== 'function') {
+        return defaultValue;
+    }
+    const column = {
+        type: meta.type!,
+        typeName: SQL_TYPE_NAMES[meta.type!] || 'UNKNOWN',
+        subType: meta.subType,
+        scale: meta.scale,
+        length: meta.length,
+        field: meta.field,
+        relation: meta.relation,
+        alias: meta.alias,
+    };
+    // A hook exception must never escape into the row-decode loop: there it
+    // would be mistaken for an incomplete packet and desync the response
+    // queue (the same failure mode as issue #341). Fall back to the default
+    // value instead and tell the user.
+    try {
+        return typeCast(column, function () { return defaultValue; });
+    } catch (err: any) {
+        console.warn('[node-firebird] typeCast hook threw for column "%s" (%s): %s — using default value',
+            column.alias || column.field, column.typeName, err && err.message);
+        return defaultValue;
+    }
+}
+
 /***************************************
  *
  *   Connection
@@ -39,10 +150,12 @@ class Connection {
     static parseValueIfJson: typeof parseValueIfJson;
     static describe: typeof describe;
 
-    db: any;
-    svc: any;
-    options: any;
-    accept: any;
+    db: Database;
+    svc: ServiceManager | undefined;
+    options: InternalOptions;
+    /** protocol negotiation result (op_accept / op_cond_accept / op_accept_data);
+     *  populated during the connect/attach handshake */
+    accept!: AcceptPacket;
     error: any;
     dbhandle: number | undefined;
     svchandle: number | undefined;
@@ -51,10 +164,12 @@ class Connection {
 
     _msg: XdrWriter;
     _blr: BlrWriter;
-    _queue: any[];
+    /** response queue: one entry per expected server response (see wire-types) */
+    _queue: QueueEntry[];
     _pending: string[];
-    _socket: any;
-    _xdr: any;
+    _socket: Socket;
+    /** partially received packet buffered between 'data' events */
+    _xdr: XdrReader | undefined;
     _isOpened: boolean;
     _isClosed: boolean;
     _isDetach: boolean;
@@ -66,16 +181,18 @@ class Connection {
     _detachAuto: any;
     _retry_connection_id: any;
     _retry_connection_interval: number;
-    _max_cached_query: number;
-    _cache_query: Record<string, any> | null;
+    _statementCacheSize: number;
+    _statementCache: Map<string, Statement> | null;
     _messageFile: string;
     _authStartTime: number | undefined;
     _pendingAccept: any;
     _inlineBlobs: Map<string, Buffer> | undefined;
 
-    constructor(host: string, port: number, callback: any, options: any, db?: any, svc?: any) {
+    constructor(host: string, port: number, callback: SimpleCallback | undefined, options: InternalOptions, db?: Database, svc?: ServiceManager) {
         var self = this;
-        this.db = db;
+        // db is absent for service-manager connections; the wire core only
+        // touches it on database attachments, where it is always set
+        this.db = db!;
         this.svc = svc
         this._msg = new XdrWriter(32);
         this._blr = new BlrWriter(32);
@@ -83,7 +200,9 @@ class Connection {
         this._detachTimeout;
         this._detachCallback;
         this._detachAuto;
-        this._socket = new Socket(port, host);
+        this._socket = new Socket(port, host,
+            options.enableKeepAlive !== false,
+            options.keepAliveInitialDelay);
         this._pending = [];
         this._isOpened = false;
         this._isClosed = false;
@@ -96,32 +215,66 @@ class Connection {
         // the same values.
         if (options && !options.user) options.user = Const.DEFAULT_USER;
         if (options && !options.password) options.password = Const.DEFAULT_PASSWORD;
-        if (options && options.blobChunkSize > 65535) options.blobChunkSize = 65535;
-        if (options && options.blobReadChunkSize > 65535) options.blobReadChunkSize = 65535;
+        if (options && options.blobChunkSize && options.blobChunkSize > 65535) options.blobChunkSize = 65535;
+        if (options && options.blobReadChunkSize && options.blobReadChunkSize > 65535) options.blobReadChunkSize = 65535;
         this.options = options;
         this._bind_events(host, port, callback);
         this.error;
         this._retry_connection_id;
         this._retry_connection_interval = options.retryConnectionInterval || 1000;
-        this._max_cached_query = options.maxCachedQuery || -1;
-        this._cache_query = options.cacheQuery?{}:null;
+        this._statementCacheSize = statementCacheLimit(options);
+        this._statementCache = this._statementCacheSize > 0 ? new Map() : null;
         this._messageFile = options.messageFile || path.join(__dirname, 'firebird.msg');
     }
 
 
-    _setcachedquery(query, statement) {
-        if (this._cache_query){
-            if (this._max_cached_query === -1 || this._max_cached_query > Object.keys(this._cache_query).length){
-                this._cache_query[query] = statement;
-            }
+    /**
+     * Take an idle prepared statement for `query` out of the cache, or null.
+     * The statement leaves the cache while in use, so concurrent callers of
+     * the same query never share a server-side cursor — they simply prepare
+     * a fresh statement and the spare is dropped when released.
+     */
+    takeCachedStatement(query: string) {
+        const cache = this._statementCache;
+        if (!cache) {
+            return null;
         }
-    
-    
+        const statement = cache.get(query);
+        if (!statement) {
+            return null;
+        }
+        cache.delete(query);
+        return statement;
     }
 
+    /**
+     * Return a statement after use. With the statement cache enabled the
+     * statement goes back into the cache as most-recently-used (closing its
+     * cursor but keeping the prepared handle), evicting the least-recently
+     * used statement over the limit. Failed statements, DDL and spares for
+     * an already-cached query are dropped instead.
+     */
+    releaseStatement(statement: Statement, callback?: QueueCallback) {
+        const cache = this._statementCache;
+        const cacheable = cache &&
+            statement.query &&
+            !statement._failed &&
+            statement.type !== Const.isc_info_sql_stmt_ddl &&
+            !cache.has(statement.query);
+
+        if (!cacheable) {
+            this.dropStatement(statement, callback);
+            return;
+        }
 
-    getCachedQuery(query) {
-        return this._cache_query ? this._cache_query[query] : null;
+        cache!.set(statement.query, statement);
+        while (cache!.size > this._statementCacheSize) {
+            const oldestKey = cache!.keys().next().value!;
+            const oldest = cache!.get(oldestKey)!;
+            cache!.delete(oldestKey);
+            this.dropStatement(oldest, undefined);
+        }
+        this.closeStatement(statement, callback);
     }
 
 
@@ -131,7 +284,7 @@ class Connection {
     // be transparently resumed on a reconnect: a fresh attach() hands out new
     // transaction/statement handles, so nothing the server sends back could
     // ever match a callback queued against the old connection.
-    _rejectPending(err) {
+    _rejectPending(err: any) {
         var queue = this._queue;
         this._queue = [];
         this._pending = [];
@@ -142,7 +295,7 @@ class Connection {
     }
 
 
-    _bind_events(host, port, callback) {
+    _bind_events(host: string, port: number, callback: SimpleCallback | undefined) {
 
         var self = this;
 
@@ -168,17 +321,19 @@ class Connection {
 
             self._retry_connection_id = setTimeout(function() {
                 self._socket.removeAllListeners();
-                self._socket = null;
+                // transiently null while the replacement Connection is built
+                // (restored by the Object.assign(self, ctx) below)
+                self._socket = null!;
 
-                var ctx = new Connection(host, port, function(err) {
-                    ctx.connect(self.options, function(err) {
+                var ctx = new Connection(host, port, function(err: any) {
+                    ctx.connect(self.options, function(err: any) {
 
                         if (err) {
                             self.db.emit('error', err);
                             return;
                         }
 
-                        ctx.attach(self.options, function(err) {
+                        ctx.attach(self.options, function(err: any) {
 
                             if (err) {
                                 self.db.emit('error', err);
@@ -197,7 +352,7 @@ class Connection {
 
         });
     
-        self._socket.on('error', function(e) {
+        self._socket.on('error', function(e: any) {
     
             self.error = e;
     
@@ -216,8 +371,8 @@ class Connection {
                 callback();
         });
     
-        self._socket.on('data', function (data) {
-            var xdr;
+        self._socket.on('data', function (data: any) {
+            var xdr: any;
             var hadSavedBuffer = Boolean(self._xdr);
     
             if (!self._xdr) {
@@ -337,7 +492,7 @@ class Connection {
 
 
 
-    sendOpContAuth(authData, authDataEnc, pluginName) {
+    sendOpContAuth(authData: string, authDataEnc: BufferEncoding, pluginName: string) {
         var msg = this._msg;
         msg.pos = 0;
     
@@ -352,7 +507,7 @@ class Connection {
     }
 
 
-    sendOpCrypt(encryptPlugin) {
+    sendOpCrypt(encryptPlugin: string) {
         var msg = this._msg;
         msg.pos = 0;
 
@@ -364,7 +519,7 @@ class Connection {
     }
 
 
-    sendOpCryptKeyCallback(pluginData) {
+    sendOpCryptKeyCallback(pluginData: BlrWriter) {
         var msg = this._msg;
         msg.pos = 0;
 
@@ -381,7 +536,7 @@ class Connection {
      * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
      * op_cancel packet itself has no response, so nothing is queued here.
      */
-    cancelOperation(kind, callback) {
+    cancelOperation(kind?: number | SimpleCallback, callback?: SimpleCallback) {
         if (typeof kind === 'function') {
             callback = kind;
             kind = undefined;
@@ -408,7 +563,7 @@ class Connection {
 
 
     /** Write a prebuilt packet and queue its response callback. */
-    _queueEventBuffer(buffer, callback) {
+    _queueEventBuffer(buffer: Buffer, callback: QueueCallback | undefined) {
         if (this._isClosed) {
             if (callback)
                 callback(new Error('Connection is closed.'));
@@ -420,7 +575,7 @@ class Connection {
     }
 
 
-    _queueEvent(callback, defer = false) {
+    _queueEvent(callback: QueueCallback | undefined, defer = false) {
         var self = this;
     
         if (self._isClosed) {
@@ -449,7 +604,7 @@ class Connection {
     }
 
 
-    connect(options, callback) {
+    connect(options: InternalOptions, callback: Callback<AcceptPacket> | undefined) {
         var pluginName = options.pluginName || Const.AUTH_PLUGIN_LIST[0];
         var msg = this._msg;
         var blr = this._blr;
@@ -460,7 +615,7 @@ class Connection {
         msg.pos = 0;
         blr.pos = 0;
     
-        blr.addString(Const.CNCT_login, options.user, Const.DEFAULT_ENCODING);
+        blr.addString(Const.CNCT_login, options.user!, Const.DEFAULT_ENCODING);
         blr.addString(Const.CNCT_plugin_name, pluginName, Const.DEFAULT_ENCODING);
         blr.addString(Const.CNCT_plugin_list, Const.AUTH_PLUGIN_LIST.join(','), Const.DEFAULT_ENCODING);
     
@@ -474,7 +629,7 @@ class Connection {
             specificData = this.clientKeys.public.toString(16);
             blr.addMultiblockPart(Const.CNCT_specific_data, specificData, Const.DEFAULT_ENCODING);
         } else if (pluginName === Const.AUTH_PLUGIN_LEGACY) {
-            specificData = crypt.crypt(options.password, Const.LEGACY_AUTH_SALT).substring(2);
+            specificData = crypt.crypt(options.password!, Const.LEGACY_AUTH_SALT).substring(2);
             blr.addMultiblockPart(Const.CNCT_specific_data, specificData, Const.DEFAULT_ENCODING);
         } else {
             doError(new Error('Invalide auth plugin \'' + pluginName + '\''), callback);
@@ -490,10 +645,17 @@ class Connection {
         msg.addInt(Const.CONNECT_VERSION3);
         msg.addInt(Const.ARCHITECTURE_GENERIC);
         msg.addString(options.database || options.filename, Const.DEFAULT_ENCODING);
-        var maxProtocols = options.maxNegotiatedProtocols !== undefined ? options.maxNegotiatedProtocols : 10;
+        // Send the full list by default. Servers parse every entry and ignore
+        // versions they do not know (verified back to Firebird 2.5), so the
+        // list length itself is harmless; the option remains as an escape
+        // hatch to cap negotiation at an older protocol.
+        var maxProtocols = options.maxNegotiatedProtocols !== undefined ? options.maxNegotiatedProtocols : Const.SUPPORTED_PROTOCOL.length;
         var protocolsToSend = Const.SUPPORTED_PROTOCOL;
         if (protocolsToSend.length > maxProtocols) {
-            protocolsToSend = protocolsToSend.slice(-maxProtocols);
+            // keep the FIRST N entries: the list is ordered oldest→newest, so
+            // capping the count caps the newest protocol offered (e.g. 10 =
+            // stop at protocol 19, the documented pre-Firebird-6 behavior)
+            protocolsToSend = protocolsToSend.slice(0, maxProtocols);
         }
 
         msg.addInt(protocolsToSend.length);  // Count of Protocol version understood count.
@@ -512,7 +674,7 @@ class Connection {
         }
     
         var self = this;
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
             if (err) {
                 doError(err, callback);
                 return;
@@ -534,11 +696,11 @@ class Connection {
 
                 var selectedPlugin = 'Arc4';
                 if (ret.keys) {
-                    var serverPlugins = ret.keys.split(',').map(function(s) { return s.trim().toLowerCase(); });
+                    var serverPlugins = ret.keys.split(',').map(function(s: any) { return s.trim().toLowerCase(); });
                     var preferred = ['chacha64', 'chacha', 'arc4'];
                     for (var i = 0; i < preferred.length; i++) {
                         if (serverPlugins.indexOf(preferred[i]) !== -1) {
-                            var mapping = {
+                            var mapping: Record<string, string> = {
                                 chacha64: 'ChaCha64',
                                 chacha: 'ChaCha',
                                 arc4: 'Arc4'
@@ -559,7 +721,7 @@ class Connection {
                 }
 
                 self._pending.push('crypt');
-                self._queue.push(function(cryptErr, response) {
+                self._queue.push(function(cryptErr: any, response: any) {
                     if (cryptErr) {
                         doError(cryptErr, callback);
                         return;
@@ -593,7 +755,7 @@ class Connection {
     }
 
 
-    attach(options: any, callback?: any, db?: any) {
+    attach(options: InternalOptions, callback?: Callback<Database>, db?: Database) {
         this._lowercase_keys = options.lowercase_keys || Const.DEFAULT_LOWERCASE_KEYS;
     
         var database = options.database || options.filename;
@@ -657,31 +819,19 @@ class Connection {
         }
 
         // Firebird 6.0 SQL Schema parameters (Protocol 20+).
-        // These DPB tags configure the session's current schema and the
-        // schema search path for unqualified object name resolution.
         if (this.accept.protocolVersion >= Const.PROTOCOL_VERSION20) {
-            if (options.defaultSchema) {
-                // Sets CURRENT_SCHEMA for the session.  Equivalent to issuing
-                // SET SCHEMA <name> immediately after connecting.
-                blr.addString(Const.isc_dpb_default_schema, options.defaultSchema, Const.DEFAULT_ENCODING);
-            }
-            if (options.searchPath) {
-                // Comma-separated ordered schema name list, like PostgreSQL's
-                // search_path.  Unqualified object references are resolved by
-                // scanning schemas in this order.
-                const sp = Array.isArray(options.searchPath)
-                    ? options.searchPath.join(',')
-                    : String(options.searchPath);
+            const sp = buildSchemaSearchPath(options);
+            if (sp) {
                 blr.addString(Const.isc_dpb_search_path, sp, Const.DEFAULT_ENCODING);
             }
         }
-    
+
         msg.addInt(Const.op_attach);
         msg.addInt(0);  // Database Object ID
         msg.addString(database, Const.DEFAULT_ENCODING);
         msg.addBlr(this._blr);
     
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
             if (err) {
                 doError(err, callback);
                 return;
@@ -708,7 +858,7 @@ class Connection {
     }
 
 
-    detach(callback) {
+    detach(callback: Callback | undefined) {
 
         var self = this;
 
@@ -724,7 +874,7 @@ class Connection {
         msg.addInt(Const.op_detach);
         msg.addInt(0); // Database Object ID
     
-        self._queueEvent(function(err, ret) {
+        self._queueEvent(function(err: any, ret: any) {
             clearTimeout(self._retry_connection_id);
             delete(self.dbhandle);
             if (callback)
@@ -733,7 +883,7 @@ class Connection {
     }
 
 
-    createDatabase(options, callback) {
+    createDatabase(options: InternalOptions, callback: Callback<Database> | undefined) {
         // Mirror attach(): honour the lowercase_keys option so that db.query()
         // called on a freshly-created database returns the expected column case.
         this._lowercase_keys = options.lowercase_keys || Const.DEFAULT_LOWERCASE_KEYS;
@@ -796,16 +946,18 @@ class Connection {
 
         // Firebird 6.0 SQL Schema parameters (Protocol 20+).
         if (this.accept.protocolVersion >= Const.PROTOCOL_VERSION20) {
-            if (options.defaultSchema) {
-                blr.addString(Const.isc_dpb_default_schema, options.defaultSchema, Const.DEFAULT_ENCODING);
-            }
-            if (options.searchPath) {
-                const sp = Array.isArray(options.searchPath)
-                    ? options.searchPath.join(',')
-                    : String(options.searchPath);
+            const sp = buildSchemaSearchPath(options);
+            if (sp) {
                 blr.addString(Const.isc_dpb_search_path, sp, Const.DEFAULT_ENCODING);
             }
         }
+
+        if (options.owner) {
+            // Firebird 6.0+ (issue #7718): create the database owned by a
+            // different user (requires superuser rights). Older servers
+            // ignore unknown DPB tags, so this is safe to always send.
+            blr.addString(Const.isc_dpb_owner, options.owner, Const.DEFAULT_ENCODING);
+        }
     
         blr.addNumeric(Const.isc_dpb_sql_dialect, 3);
         blr.addNumeric(Const.isc_dpb_force_write, 1);
@@ -821,7 +973,7 @@ class Connection {
     
         var self = this;
     
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
     
             if (ret)
                 self.dbhandle = ret.handle;
@@ -838,15 +990,15 @@ class Connection {
     }
 
 
-    dropDatabase(callback) {
+    dropDatabase(callback: SimpleCallback | undefined) {
         var msg = this._msg;
         msg.pos = 0;
     
         msg.addInt(Const.op_drop_database);
-        msg.addInt(this.dbhandle);
+        msg.addInt(this.dbhandle!);
     
         var self = this;
-        this._queueEvent(function(err) {
+        this._queueEvent(function(err: any) {
             self.detach(function() {
                 self.disconnect();
     
@@ -857,7 +1009,7 @@ class Connection {
     }
 
 
-    throwClosed(callback) {
+    throwClosed(callback: ((err: Error, ...args: any[]) => void) | undefined) {
         var err = new Error('Connection is closed.');
         this.db.emit('error', err);
         if (callback)
@@ -866,7 +1018,9 @@ class Connection {
     }
 
 
-    startTransaction(options, callback) {
+    /** `options` is a resolved options object, a bare isolation array, or
+     *  the callback itself when no options are given. */
+    startTransaction(options: any, callback?: any) {
     
         if (typeof(options) === 'function') {
             var tmp = options;
@@ -939,7 +1093,7 @@ class Connection {
         }*/
     
         msg.addInt(Const.op_transaction);
-        msg.addInt(this.dbhandle);
+        msg.addInt(this.dbhandle!);
         msg.addBlr(blr);
         callback.response = new Transaction(this);
     
@@ -948,7 +1102,7 @@ class Connection {
     }
 
 
-    commit(transaction, callback) {
+    commit(transaction: Transaction, callback: QueueCallback | undefined) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -965,7 +1119,7 @@ class Connection {
     }
 
 
-    rollback(transaction, callback) {
+    rollback(transaction: Transaction, callback: QueueCallback | undefined) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -982,7 +1136,7 @@ class Connection {
     }
 
 
-    commitRetaining(transaction, callback) {
+    commitRetaining(transaction: Transaction, callback: QueueCallback | undefined) {
 
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -998,7 +1152,7 @@ class Connection {
     }
 
 
-    rollbackRetaining(transaction, callback) {
+    rollbackRetaining(transaction: Transaction, callback: QueueCallback | undefined) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1014,7 +1168,7 @@ class Connection {
     }
 
 
-    allocateStatement(callback) {
+    allocateStatement(callback: QueueCallback) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1025,13 +1179,13 @@ class Connection {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_allocate_statement);
-        msg.addInt(this.dbhandle);
+        msg.addInt(this.dbhandle!);
         callback.response = new Statement(this);
         this._queueEvent(callback);
     }
 
 
-    dropStatement(statement, callback) {
+    dropStatement(statement: Statement, callback: QueueCallback | undefined) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1049,7 +1203,7 @@ class Connection {
     }
 
 
-    closeStatement(statement, callback) {
+    closeStatement(statement: Statement, callback: QueueCallback | undefined) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1067,16 +1221,15 @@ class Connection {
     }
 
 
-    allocateAndPrepareStatement(transaction, query, plan, callback) {
+    allocateAndPrepareStatement(transaction: Transaction, query: string, plan: boolean, callback: Callback<Statement>) {
         var self = this;
-        var mainCallback: any = function(err: any, ret: any) {
+        var mainCallback: QueueCallback = function(err: any, ret: any) {
             if (!err) {
                 mainCallback.response.handle = ret.handle;
                 describe(ret.buffer, mainCallback.response);
                 mainCallback.response.query = query;
                 self.db.emit('query', query);
                 ret = mainCallback.response;
-                self._setcachedquery(query, ret);
             }
     
             if (callback)
@@ -1093,7 +1246,7 @@ class Connection {
         blr.pos = 0;
     
         msg.addInt(Const.op_allocate_statement);
-        msg.addInt(this.dbhandle);
+        msg.addInt(this.dbhandle!);
         mainCallback.lazy_count = 1;
     
         const describeBytes = this.accept.protocolVersion >= Const.PROTOCOL_VERSION20 ? Const.DESCRIBE_WITH_SCHEMA : Const.DESCRIBE;
@@ -1111,6 +1264,12 @@ class Connection {
         msg.addString(query, Const.DEFAULT_ENCODING);
         msg.addBlr(blr);
         msg.addInt(65535); // buffer_length
+        if (this.accept.protocolVersion >= Const.PROTOCOL_VERSION20) {
+            // p_sqlst_flags (IStatement::PREPARE_* bits, none needed) — the
+            // server blocks reading this field if it is missing, which was
+            // the protocol-20 "prepare hang"
+            msg.addInt(0);
+        }
         mainCallback.lazy_count += 1;
     
         mainCallback.response = new Statement(this);
@@ -1118,13 +1277,13 @@ class Connection {
     }
 
 
-    prepare(transaction, query, plan, callback) {
+    prepare(transaction: Transaction, query: string, plan: boolean, callback: Callback<Statement>) {
         var self = this;
     
         if (this.accept.protocolMinimumType === Const.ptype_lazy_send) { // V11 Statement or higher
             self.allocateAndPrepareStatement(transaction, query, plan, callback);
         } else { // V10 Statement
-            self.allocateStatement(function (err, statement) {
+            self.allocateStatement(function (err: any, statement: Statement) {
                 if (err) {
                     doError(err, callback);
                     return;
@@ -1137,7 +1296,8 @@ class Connection {
 
 
 
-    prepareStatement(transaction, statement, query, plan, callback) {
+    /** `plan` may be the callback itself when no plan flag is given. */
+    prepareStatement(transaction: Transaction, statement: Statement, query: string, plan: boolean | Callback<Statement>, callback?: Callback<Statement>) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1166,16 +1326,18 @@ class Connection {
         msg.addString(query, Const.DEFAULT_ENCODING);
         msg.addBlr(blr);
         msg.addInt(65535); // buffer_length
+        if (this.accept.protocolVersion >= Const.PROTOCOL_VERSION20) {
+            msg.addInt(0); // p_sqlst_flags (see allocateAndPrepareStatement)
+        }
     
         var self = this;
-        this._queueEvent(function(err, ret) {
+        this._queueEvent(function(err: any, ret: any) {
     
             if (!err) {
                 describe(ret.buffer, statement);
                 statement.query = query;
                 self.db.emit('query', query);
                 ret = statement;
-                self._setcachedquery(query, ret);
             }
     
             if (callback)
@@ -1198,7 +1360,7 @@ class Connection {
      * { recordCount, updateCounts, errors: [{recordNumber, error}],
      *   errorRecordNumbers, success }.
      */
-    executeBatch(transaction, statement, rows, callback, options) {
+    executeBatch(transaction: Transaction, statement: Statement, rows: QueryParams[], callback: BatchCb | undefined, options?: BatchOptions) {
         options = options || {};
 
         if (this._isClosed)
@@ -1244,7 +1406,7 @@ class Connection {
 
         var self = this;
         var encoders = built.encoders;
-        var chunkSize = options.chunkSize > 0 ? options.chunkSize : 500;
+        var chunkSize = options.chunkSize && options.chunkSize > 0 ? options.chunkSize : 500;
         var chunkCount = Math.ceil(rows.length / chunkSize);
 
         var failure: any = null;
@@ -1264,7 +1426,7 @@ class Connection {
             }
 
             var detailed = completion ? completion.detailedErrors : [];
-            var errorRecordNumbers = detailed.map(function(e) { return e.recordNumber; })
+            var errorRecordNumbers = detailed.map(function(e: any) { return e.recordNumber; })
                 .concat(completion ? completion.errorRecordNumbers : []);
 
             if (callback) callback(undefined, {
@@ -1312,7 +1474,8 @@ class Connection {
                 msg.addInt(end - start);
 
                 for (var i = start; i < end; i++) {
-                    var row = rows[i];
+                    // validated as an array of input.length values above
+                    var row = rows[i] as any[];
 
                     var nullBits = new BitSet();
                     for (var j = 0; j < input.length; j++) {
@@ -1371,7 +1534,7 @@ class Connection {
         for (var p = 0; p < packets.length; p++) {
             this._pending.push('executeBatch');
             if (p === execIndex) {
-                this._queueEventBuffer(packets[p], function(err, ret) {
+                this._queueEventBuffer(packets[p], function(err: any, ret: any) {
                     if (!err && ret && ret.batchCompletion) {
                         completion = ret.batchCompletion;
                         settle();
@@ -1382,13 +1545,14 @@ class Connection {
             } else if (p === packets.length - 1) {
                 this._queueEventBuffer(packets[p], function() {});
             } else {
-                this._queueEventBuffer(packets[p], function(err) { settle(err); });
+                this._queueEventBuffer(packets[p], function(err: any) { settle(err); });
             }
         }
     }
 
 
-    executeStatement(transaction, statement, params, callback, custom) {
+    /** `params` may be the callback itself when the statement has no parameters. */
+    executeStatement(transaction: Transaction, statement: Statement, params: any, callback?: QueueCallback, custom?: InternalQueryOptions) {
     
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -1412,14 +1576,14 @@ class Connection {
             op = Const.op_execute2;
         }
     
-        function PrepareParams(params, input, callback) {
+        function PrepareParams(params: any[], input: Xsql.SQLVarBase[], callback: (prms: any[]) => void) {
 
             var value, meta;
             var ret = new Array(params.length);
 
-            function putBlobData(index, value, callback) {
+            function putBlobData(index: any, value: any, callback: any) {
     
-                self.createBlob2(transaction, function(err, blob) {
+                self.createBlob2(transaction, function(err: any, blob: any) {
     
                     var b;
                     var isStream = value.readable;
@@ -1447,7 +1611,7 @@ class Connection {
                     var isReading = false;
                     var isEnd = false;
 
-                    value.on('data', function(chunk) {
+                    value.on('data', function(chunk: any) {
                         // Optimization: If chunk is smaller than transfer size, send directly
                         if (chunk.length <= chunkSize) {
                             self.batchSegments(blob, chunk, function () {
@@ -1488,7 +1652,7 @@ class Connection {
                 });
             }
     
-            function step(i) {
+            function step(i: any) {
                 if (i === params.length) {
                     callback(ret);
                     return;
@@ -1605,12 +1769,12 @@ class Connection {
     
             if (!(params instanceof Array)) {
                 if (params !== undefined && typeof params === 'object' && params !== null) {
-                    var mappedParams = [];
+                    var mappedParams: any[] = [];
                     for (var i = 0; i < input.length; i++) {
                         mappedParams.push(undefined);
                     }
                     var matchedCount = 0;
-                    var nameMap = {};
+                    var nameMap: Record<string, number> = {};
                     for (var i = 0; i < input.length; i++) {
                         var name = input[i].alias || input[i].field;
                         if (name) {
@@ -1641,11 +1805,11 @@ class Connection {
     
             if (params.length !== input.length) {
                 self._pending.pop();
-                callback(new Error('Expected parameters: (params=' + params.length + ' vs. expected=' + input.length + ') - ' + statement.query));
+                callback!(new Error('Expected parameters: (params=' + params.length + ' vs. expected=' + input.length + ') - ' + statement.query));
                 return;
             }
     
-            PrepareParams(params, input, function(prms) {
+            PrepareParams(params, input, function(prms: any) {
                 self.sendExecute(op, statement, transaction, callback, prms);
             });
     
@@ -1656,7 +1820,7 @@ class Connection {
     }
 
 
-    sendExecute(op: number, statement: any, transaction: any, callback: any, parameters?: any[]) {
+    sendExecute(op: number, statement: Statement, transaction: Transaction, callback: QueueCallback | undefined, parameters?: any[]) {
         var msg = this._msg;
         var blr = this._blr;
         msg.pos = 0;
@@ -1736,14 +1900,15 @@ class Connection {
             msg.addInt(statement.options?.maxInlineBlobSize !== undefined ? statement.options.maxInlineBlobSize : (this.options?.maxInlineBlobSize || 0)); // p_sqldata_inline_blob_size
         }
     
-        callback.statement = statement;
+        callback!.statement = statement;
         this._queueEvent(callback);
     }
 
 
 
 
-    fetch(statement, transaction, count, callback) {
+    /** `count` may be the callback itself when no fetch size is given. */
+    fetch(statement: Statement, transaction: Transaction, count: any, callback?: QueueCallback) {
     
         var msg = this._msg;
         var blr = this._blr;
@@ -1763,12 +1928,12 @@ class Connection {
         msg.addInt(0); // message number
         msg.addInt(count || Const.DEFAULT_FETCHSIZE); // fetch count
     
-        callback.statement = statement;
+        callback!.statement = statement;
         this._queueEvent(callback);
     }
 
 
-    fetchScroll(statement, transaction, direction, offset, count, callback) {
+    fetchScroll(statement: Statement, transaction: Transaction, direction: string | number, offset: any, count: any, callback?: QueueCallback) {
         if (typeof count === 'function') {
             callback = count;
             count = undefined;
@@ -1814,18 +1979,18 @@ class Connection {
         msg.addInt(dirInt); // fetch operation
         msg.addInt(offsetVal); // fetch position (offset)
     
-        callback.statement = statement;
+        callback!.statement = statement;
         this._queueEvent(callback);
     }
 
 
-    fetchAll(statement, transaction, callback) {
+    fetchAll(statement: Statement, transaction: Transaction, callback: Callback<any[]>) {
         const self = this;
         const custom = statement.options || {};
         const asStream = custom.asStream && custom.on;
-        const data = asStream ? null : [];
+        const data: any[] | null = asStream ? null : [];
         let streamIndex = 0;
-        const loop = (err, ret) => {
+        const loop = (err: any, ret: any) => {
             if (err) {
                 callback(err);
                 return;
@@ -1837,24 +2002,28 @@ class Connection {
                 // which causes a server-side deadlock when many rows contain
                 // BLOBs and blobAsText is true. See issue #387.
                 const arrBlobFns = ret.arrBlob || [];
-                const readBlobsSequentially = (index, results) => {
+                const readBlobsSequentially = (index: any, results: any) => {
                     if (index >= arrBlobFns.length) {
                         return Promise.resolve(results);
                     }
-                    return arrBlobFns[index](transaction).then((v) => {
+                    return arrBlobFns[index](transaction).then((v: any) => {
                         results.push(v);
                         return readBlobsSequentially(index + 1, results);
                     });
                 };
 
-                readBlobsSequentially(0, []).then((arrBlob) => {
+                readBlobsSequentially(0, []).then((arrBlob: any) => {
                     for (let i = 0; i < arrBlob.length; i++) {
                         const blob = arrBlob[i];
-                        ret.data[blob.row][blob.column] = parseValueIfJson(blob.value, statement.connection.options);
+                        // nestTables === true rows: the value lives in the
+                        // per-table sub-object, not on the row itself
+                        Xsql.nestCell(ret.data[blob.row], blob.table)[blob.column] = applyTypeCast(
+                            statement.connection.options, blob.meta || {},
+                            parseValueIfJson(blob.value, statement.connection.options));
                     }
 
                     doSynchronousLoop(ret.data, (row, _i, next) => {
-                        const pos = asStream ? streamIndex++ : (data.push(row) - 1);
+                        const pos = asStream ? streamIndex++ : (data!.push(row) - 1);
                         if (asStream) {
                             executeStreamRow(custom, row, pos, statement.output, next);
                         } else {
@@ -1888,7 +2057,7 @@ class Connection {
 
 
 
-    openBlob(blob, transaction, callback) {
+    openBlob(blob: Quad, transaction: Transaction, callback: QueueCallback) {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_open_blob);
@@ -1898,7 +2067,7 @@ class Connection {
     }
 
 
-    closeBlob(blob, callback, defer = true) {
+    closeBlob(blob: any, callback?: QueueCallback, defer = true) {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_close_blob);
@@ -1907,7 +2076,7 @@ class Connection {
     }
 
 
-    getSegment(blob, callback) {
+    getSegment(blob: any, callback: QueueCallback) {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_get_segment);
@@ -1918,7 +2087,7 @@ class Connection {
     }
 
 
-    createBlob2(transaction, callback) {
+    createBlob2(transaction: Transaction, callback: QueueCallback) {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_create_blob2);
@@ -1930,7 +2099,7 @@ class Connection {
     }
 
 
-    batchSegments(blob, buffer, callback) {
+    batchSegments(blob: any, buffer: Buffer, callback: QueueCallback) {
         var msg = this._msg;
         var blr = this._blr;
         msg.pos = 0;
@@ -1944,7 +2113,7 @@ class Connection {
     }
 
 
-    svcattach(options: any, callback?: any, svc?: any) {
+    svcattach(options: InternalOptions, callback?: Callback<ServiceManager>, svc?: ServiceManager) {
         this._lowercase_keys = options.lowercase_keys || Const.DEFAULT_LOWERCASE_KEYS;
         var database = options.database || options.filename;
         var user = options.user || Const.DEFAULT_USER;
@@ -1979,7 +2148,7 @@ class Connection {
     
         var self = this;
     
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
     
             if (err) {
                 doError(err, callback);
@@ -2005,19 +2174,19 @@ class Connection {
     }
 
 
-    svcstart(spbaction, callback) {
+    svcstart(spbaction: BlrWriter, callback: QueueCallback | undefined) {
         var msg = this._msg;
         var blr = this._blr;
         msg.pos = 0;
         msg.addInt(Const.op_service_start);
-        msg.addInt(this.svchandle);
+        msg.addInt(this.svchandle!);
         msg.addInt(0)
         msg.addBlr(spbaction);
         this._queueEvent(callback);
     }
 
 
-    svcquery(spbquery, resultbuffersize, timeout,callback) {
+    svcquery(spbquery: number[], resultbuffersize: number, timeout: number | undefined, callback: QueueCallback | undefined) {
         if (resultbuffersize > Const.MAX_BUFFER_SIZE) {
             doError(new Error('Buffer is too big'), callback);
             return;
@@ -2030,7 +2199,7 @@ class Connection {
         blr.addByte(Const.isc_spb_current_version);
         //blr.addByteInt32(Const.isc_info_svc_timeout, timeout);
         msg.addInt(Const.op_service_info);
-        msg.addInt(this.svchandle);
+        msg.addInt(this.svchandle!);
         msg.addInt(0);
         msg.addBlr(blr);
         blr.pos = 0
@@ -2041,7 +2210,7 @@ class Connection {
     }
 
 
-    svcdetach(callback) {
+    svcdetach(callback: Callback | undefined) {
         var self = this;
 
         if (self._isClosed) {
@@ -2056,9 +2225,9 @@ class Connection {
     
         msg.pos = 0;
         msg.addInt(Const.op_service_detach);
-        msg.addInt(this.svchandle); // Database Object ID
+        msg.addInt(this.svchandle!); // Database Object ID
     
-        self._queueEvent(function (err, ret) {
+        self._queueEvent(function (err: any, ret: any) {
             delete (self.svchandle);
             if (callback)
                 callback(err, ret);
@@ -2067,7 +2236,7 @@ class Connection {
 
 
 
-    auxConnection(eventid, callback) {
+    auxConnection(eventid: number | Callback, callback?: Callback) {
         if (typeof eventid === 'function') {
             // Preserve the older auxConnection(callback) call shape; plain
             // auxiliary connections historically used event id 0.
@@ -2081,13 +2250,13 @@ class Connection {
         msg.pos = 0;
         msg.addInt(Const.op_connect_request);
         msg.addInt(1); // async
-        msg.addInt(self.dbhandle);
+        msg.addInt(self.dbhandle!);
         msg.addInt(eventid);
         if (process.env.FIREBIRD_DEBUG) {
             console.log('[fb-debug] auxConnection: sending op_connect_request(53) dbhandle=%d eventid=%d queue_before=%d xdr_saved=%s',
                 self.dbhandle, eventid, self._queue.length, Boolean(self._xdr));
         }
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
     
             if (err) {
                 if (process.env.FIREBIRD_DEBUG) {
@@ -2108,13 +2277,13 @@ class Connection {
                     socket_info.family, socket_info.port, socket_info.host, self._queue.length);
             }
     
-            callback(undefined, socket_info);
+            callback!(undefined, socket_info);
         }
         this._queueEvent(cb);
     }
 
 
-    queEvents(events, eventid, callback) {
+    queEvents(events: Record<string, number>, eventid: number, callback: Callback) {
         var self = this;
         if (this._isClosed)
             return this.throwClosed(callback);
@@ -2123,7 +2292,7 @@ class Connection {
         blr.pos = 0;
         msg.pos = 0;
         msg.addInt(Const.op_que_events);
-        msg.addInt(this.dbhandle);
+        msg.addInt(this.dbhandle!);
         // prepare EPB
         blr.addByte(1) // epb_version
         for (var event in events) {
@@ -2137,7 +2306,7 @@ class Connection {
         msg.addInt(0);   // args
         msg.addInt(eventid);
         
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
             if (err) {
                 doError(err, callback);
                 return;
@@ -2150,17 +2319,17 @@ class Connection {
     }
 
 
-    closeEvents(eventid, callback) {
+    closeEvents(eventid: number, callback: Callback) {
         var self = this;
         if (this._isClosed)
             return this.throwClosed(callback);
         var msg = self._msg;
         msg.pos = 0;
         msg.addInt(Const.op_cancel_events);
-        msg.addInt(self.dbhandle);
+        msg.addInt(self.dbhandle!);
         msg.addInt(eventid);
     
-        function cb(err, ret) {
+        function cb(err: any, ret: any) {
             if (err) {
                 doError(err, callback);
                 return;
@@ -2179,7 +2348,7 @@ const opcodeNames = Object.fromEntries(
     Object.entries(Const).filter(([k]) => k.startsWith('op_')).map(([k, v]) => [v, k])
 );
 
-function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any, cb: (err?: any, obj?: any) => void) {
+function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cnx: Connection, lowercase_keys: boolean | undefined, cb: (err?: any, obj?: any) => void) {
     try {
         do {
             var r = data.r || data.readInt();
@@ -2200,7 +2369,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                     cnx._inlineBlobs = new Map();
                 }
                 const cacheKey = `${blob_id.high}:${blob_id.low}`;
-                cnx._inlineBlobs.set(cacheKey, blob_data);
+                cnx._inlineBlobs.set(cacheKey, blob_data!);
                 r = Const.op_dummy; // Continue loop to read next opcode
             }
         } while (r === Const.op_dummy);
@@ -2210,7 +2379,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                 r, opcodeNames[r] || 'unknown', data.pos, data.buffer.length);
         }
 
-        var item, op, response;
+        var item, op, response: any;
 
         switch (r) {
             case Const.op_response:
@@ -2221,7 +2390,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                     response = {};
                 }
 
-                let loop = function (err) {
+                let loop = function (err: any) {
                     if (err) {
                         return cb(err);
                     } else {
@@ -2282,13 +2451,28 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
             }
             case Const.op_fetch_response:
             case Const.op_sql_response:
-                var statement = callback.statement;
+                // fetch/sql_response entries always carry their statement
+                var statement = callback!.statement!;
                 var output = statement.output;
                 var custom = statement.options || {};
                 var isOpFetch = r === Const.op_fetch_response;
                 var _xdrpos;
                 statement.nbrowsfetched = statement.nbrowsfetched || 0;
 
+                // The f* decode state is only meaningful within a single
+                // decode call: incomplete packets are re-decoded from scratch
+                // on a fresh XdrReader (see the 'data' handler). State left by
+                // an earlier packet in the same data event (e.g. fstatus=100 /
+                // fcount=0 from a completed fetch) would make this decode
+                // consume just the opcode and desync every later response.
+                delete data.fstatus;
+                delete data.fcount;
+                delete data.fcolumn;
+                delete data.frow;
+                delete data.frows;
+                delete data.fcols;
+                delete data.ftables;
+
                 if (isOpFetch && data.fop) { // could be set when a packet is not complete
                     data.readBuffer(68); // ??
                     op = data.readInt(); // ??
@@ -2309,56 +2493,74 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                 data.frows = data.frows || [];
 
                 if (custom.asObject && !data.fcols) {
-                    if (lowercase_keys) {
-                        data.fcols = output.map((column) => column.alias.toLowerCase());
-                    } else {
-                        data.fcols = output.map((column) => column.alias);
+                    const nest = Xsql.resolveNestTables(custom, cnx.options);
+                    const columnKeys = Xsql.computeColumnKeys(output, nest, lowercase_keys);
+                    data.fcols = columnKeys.map((k) => k.key);
+                    if (nest === true) {
+                        // computeColumnKeys always sets table when nesting
+                        data.ftables = columnKeys.map((k) => k.table!);
                     }
                 }
 
-                const arrBlob = [];
+                const arrBlob: any[] = [];
                 const lowerV13 = statement.connection.accept.protocolVersion <  Const.PROTOCOL_VERSION13;
 
+                // op_sql_response (op_execute2) is always followed by an
+                // op_response carrying the execute status vector. The row loop
+                // below consumes it after the last row, but with zero rows
+                // (e.g. INSERT ... RETURNING failing on a constraint) it stays
+                // in the buffer, shifting every later response to the wrong
+                // callback and poisoning the connection (issue #341).
+                var sqlResponseTrailerPending = !isOpFetch && !data.fcount;
+
                 while (data.fcount && (data.fstatus !== 100)) {
                     let nullBitSet;
                     if (!lowerV13) {
                         const nullBitsLen = Math.floor((output.length + 7) / 8);
-                        nullBitSet = new BitSet(data.readBuffer(nullBitsLen, false));
+                        nullBitSet = new BitSet(data.readBuffer(nullBitsLen, false)!);
                         data.readBuffer((4 - nullBitsLen) & 3, false); // Skip padding
                     }
 
                     for (let length = output.length; data.fcolumn < length; data.fcolumn++) {
                         item = output[data.fcolumn];
 
-                        if (!lowerV13 && nullBitSet.get(data.fcolumn)) {
-                            if (custom.asObject) {
-                                data.frow[data.fcols[data.fcolumn]] = null;
-                            } else {
-                                data.frow[data.fcolumn] = null;
-                            }
+                        if (!lowerV13 && nullBitSet!.get(data.fcolumn)) {
+                            const nullKey = custom.asObject ? data.fcols![data.fcolumn!] : data.fcolumn;
+                            // ftables is only set when nestTables === true, so
+                            // the default path writes straight into the row
+                            (data.ftables ? Xsql.nestCell(data.frow, data.ftables[data.fcolumn!]) : data.frow)[nullKey] =
+                                applyTypeCast(cnx.options, item, null);
 
                             continue;
                         }
 
                         try {
                             _xdrpos = data.pos;
-                            const key = custom.asObject ? data.fcols[data.fcolumn] : data.fcolumn;
+                            const key = custom.asObject ? data.fcols![data.fcolumn!] : data.fcolumn;
                             const row = data.frows.length;
                             let value = item.decode(data, lowerV13, cnx.options);
+                            // text blobs resolved by blobAsText run through the
+                            // typeCast hook once the text arrives (see fetchAll),
+                            // not here where the value is still a pending fetch
+                            let pendingTextBlob = false;
 
                             if (item.type === Const.SQL_BLOB && value !== null) {
                                 if (item.subType === Const.isc_blob_text && cnx.options.blobAsText) {
-                                    value = fetch_blob_async_transaction(statement, value, key, row);
+                                    value = fetch_blob_async_transaction(statement, value, key, row, item,
+                                        data.ftables && data.ftables[data.fcolumn!]);
                                     arrBlob.push(value);
+                                    pendingTextBlob = true;
                                 } else {
                                     value = fetch_blob_async(statement, value, key, row);
                                 }
                             }
 
-                            data.frow[key] = parseValueIfJson(value, cnx.options);
+                            (data.ftables ? Xsql.nestCell(data.frow, data.ftables[data.fcolumn!]) : data.frow)[key] = pendingTextBlob
+                                ? value
+                                : applyTypeCast(cnx.options, item, parseValueIfJson(value, cnx.options));
                         } catch (e) {
                             // uncomplete packet read
-                            data.pos = _xdrpos;
+                            data.pos = _xdrpos!;
                             data.r = r;
                             return cb(new Error('Packet is not complete'));
                         }
@@ -2403,6 +2605,17 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                     statement.nbrowsfetched++;
                 }
 
+                if (sqlResponseTrailerPending) {
+                    op = data.readInt();
+                    if (op === Const.op_response) {
+                        response = {};
+                        parseOpResponse(data, response);
+                        if (response.status) {
+                            return cb(null, response);
+                        }
+                    }
+                }
+
                 // ToDo: emit "result" with blob subtype string decoded
                 statement.connection.db.emit('result', data.frows, arrBlob);
                 return cb(null, {data: data.frows, fetched: Boolean(!isOpFetch || data.fstatus === 100), arrBlob});
@@ -2427,7 +2640,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                 }
 
                 if (r === Const.op_cond_accept || r === Const.op_accept_data) {
-                    var d = new BlrReader(data.readArray());
+                    var d = new BlrReader(data.readArray()!);
                     accept.pluginName = data.readString(Const.DEFAULT_ENCODING);
                     var is_authenticated = data.readInt();
                     var keys = data.readString(Const.DEFAULT_ENCODING); // keys
@@ -2447,7 +2660,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                         }
 
                         if (Const.AUTH_PLUGIN_SRP_LIST.indexOf(accept.pluginName) !== -1) {
-                            var crypto = {
+                            var crypto: Record<string, string> = {
                                 Srp: 'sha1',
                                 Srp256: 'sha256',
                                 Srp384: 'sha384',
@@ -2458,7 +2671,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                             if (!d.buffer) {
                                 cnx._pendingAccept = accept;
                                 cnx.sendOpContAuth(
-                                    cnx.clientKeys.public.toString(16),
+                                    cnx.clientKeys!.public.toString(16),
                                     Const.DEFAULT_ENCODING,
                                     accept.pluginName
                                 );
@@ -2489,20 +2702,20 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
 
                             if (process.env.FIREBIRD_DEBUG) {
                                 console.log('--- DEBUG SRP Handshake ---');
-                                console.log('salt:', cnx.serverKeys.salt);
-                                console.log('server public key:', cnx.serverKeys.public.toString(16));
-                                console.log('client public key:', cnx.clientKeys.public.toString(16));
+                                console.log('salt:', cnx.serverKeys!.salt);
+                                console.log('server public key:', cnx.serverKeys!.public.toString(16));
+                                console.log('client public key:', cnx.clientKeys!.public.toString(16));
                                 console.log('hashAlgo:', accept.srpAlgo);
                             }
 
                             const _t1 = Date.now();
                             var proof = srp.clientProof(
-                                cnx.options.user.toUpperCase(),
-                                cnx.options.password,
-                                cnx.serverKeys.salt,
-                                cnx.clientKeys.public,
-                                cnx.serverKeys.public,
-                                cnx.clientKeys.private,
+                                cnx.options.user!.toUpperCase(),
+                                cnx.options.password!,
+                                cnx.serverKeys!.salt,
+                                cnx.clientKeys!.public,
+                                cnx.serverKeys!.public,
+                                cnx.clientKeys!.private,
                                 accept.srpAlgo
                             );
 
@@ -2519,7 +2732,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                             accept.authData = proof.authData.toString(16);
                             accept.sessionKey = proof.clientSessionKey;
                         } else if (accept.pluginName === Const.AUTH_PLUGIN_LEGACY) {
-                            accept.authData = crypt.crypt(cnx.options.password, Const.LEGACY_AUTH_SALT).substring(2);
+                            accept.authData = crypt.crypt(cnx.options.password!, Const.LEGACY_AUTH_SALT).substring(2);
                         } else {
                             return cb(new Error('Unknow auth plugin : ' + accept.pluginName));
                         }
@@ -2557,7 +2770,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
 
                 return cb(undefined, accept);
             case Const.op_cont_auth:
-                var d = new BlrReader(data.readArray());
+                var d = new BlrReader(data.readArray()!);
                 var pluginName = data.readString(Const.DEFAULT_ENCODING);
                 data.readString(Const.DEFAULT_ENCODING); // plist
                 data.readString(Const.DEFAULT_ENCODING); // pkey
@@ -2584,7 +2797,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                     // the proof with the new plugin's hash algorithm - rather than
                     // as the server's M2 proof, otherwise the client silently waits
                     // forever for an op_accept the server will never send (#254).
-                    if (!cnx.serverKeys || cnx.serverKeys.pluginName !== pluginName) {
+                    if (!cnx.serverKeys || cnx.serverKeys!.pluginName !== pluginName) {
                         // Check buffer contains salt
                         var saltLen = d.buffer.readUInt16LE(0);
                         if (saltLen > 32 * 2) {
@@ -2607,7 +2820,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                             pluginName: pluginName
                         };
 
-                        var crypto = {
+                        var crypto: Record<string, string> = {
                             Srp: 'sha1',
                             Srp256: 'sha256',
                             Srp384: 'sha384',
@@ -2617,20 +2830,20 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
 
                         if (process.env.FIREBIRD_DEBUG) {
                             console.log('--- DEBUG SRP Handshake ---');
-                            console.log('salt:', cnx.serverKeys.salt);
-                            console.log('server public key:', cnx.serverKeys.public.toString(16));
-                            console.log('client public key:', cnx.clientKeys.public.toString(16));
+                            console.log('salt:', cnx.serverKeys!.salt);
+                            console.log('server public key:', cnx.serverKeys!.public.toString(16));
+                            console.log('client public key:', cnx.clientKeys!.public.toString(16));
                             console.log('hashAlgo:', srpAlgo);
                         }
 
                         const _t1 = Date.now();
                         var proof = srp.clientProof(
-                            cnx.options.user.toUpperCase(),
-                            cnx.options.password,
-                            cnx.serverKeys.salt,
-                            cnx.clientKeys.public,
-                            cnx.serverKeys.public,
-                            cnx.clientKeys.private,
+                            cnx.options.user!.toUpperCase(),
+                            cnx.options.password!,
+                            cnx.serverKeys!.salt,
+                            cnx.clientKeys!.public,
+                            cnx.serverKeys!.public,
+                            cnx.clientKeys!.private,
                             srpAlgo
                         );
 
@@ -2667,7 +2880,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                             cnx._pendingAccept.protocolVersion,
                             cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
                     }
-                    var legacyAuthData = crypt.crypt(cnx.options.password, Const.LEGACY_AUTH_SALT).substring(2);
+                    var legacyAuthData = crypt.crypt(cnx.options.password!, Const.LEGACY_AUTH_SALT).substring(2);
                     cnx.sendOpContAuth(legacyAuthData, Const.DEFAULT_ENCODING, pluginName);
                     return; // wait for op_accept
                 }
@@ -2680,7 +2893,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
 
                     if (pluginName === Const.AUTH_PLUGIN_LEGACY) { // Fallback to LegacyAuth
                         cnx.accept.pluginName = pluginName;
-                        cnx.accept.authData = crypt.crypt(cnx.options.password, Const.LEGACY_AUTH_SALT).substring(2);
+                        cnx.accept.authData = crypt.crypt(cnx.options.password!, Const.LEGACY_AUTH_SALT).substring(2);
 
                         cnx.sendOpContAuth(
                             cnx.accept.authData,
@@ -2773,7 +2986,7 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                 }
                 return cb(new Error('Unexpected:' + r));
         }
-    } catch (err) {
+    } catch (err: any) {
         if (process.env.FIREBIRD_DEBUG) {
             console.warn('[fb-debug] decodeResponse exception: %s (RangeError=%s) pos=%d buflen=%d',
                 err.message, err instanceof RangeError, data.pos, data.buffer.length);
@@ -2789,8 +3002,8 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
  * Read one XDR status vector (as in op_response / op_batch_cs error
  * vectors): a stream of isc_arg_* items terminated by isc_arg_end.
  */
-function readStatusVector(data: any): { status: any[]; sqlcode?: number } {
-    var result: { status: any[]; sqlcode?: number } = { status: [] };
+function readStatusVector(data: XdrReader): { status: any[]; warnings?: any[]; sqlcode?: number } {
+    var result: { status: any[]; warnings?: any[]; sqlcode?: number } = { status: [] };
     var item: any = {};
 
     while (true) {
@@ -2820,13 +3033,24 @@ function readStatusVector(data: any): { status: any[]; sqlcode?: number } {
                     result.sqlcode = n;
                 }
                 break;
+            case Const.isc_arg_warning:
+                // A warning attached to a SUCCESS vector (e.g. "parallel
+                // workers value capped"). Keep it out of `status` so the
+                // operation is not mistaken for a failure; later string/
+                // number items attach to the warning entry.
+                var wnum = data.readInt();
+                item = { gdscode: wnum };
+                if (wnum) {
+                    (result.warnings = result.warnings || []).push(item);
+                }
+                break;
             default:
                 throw new Error('Unexpected status vector item: ' + op);
         }
     }
 }
 
-function parseOpResponse(data: any, response: any, cb?: (err?: any, response?: any) => void) {
+function parseOpResponse(data: XdrReader, response: WireResponse, cb?: (err?: any, response?: any) => void) {
     var handle = data.readInt();
 
     if (!response.handle) {
@@ -2889,18 +3113,31 @@ function parseOpResponse(data: any, response: any, cb?: (err?: any, response?: a
                     response.sqlcode = num;
                 }
 
+                break;
+            case Const.isc_arg_warning:
+                // A warning attached to a SUCCESS response (e.g. Firebird's
+                // "parallel workers value capped" on attach). Keep it out of
+                // `status` so the response is not mistaken for an error;
+                // later string/number items attach to the warning entry.
+                num = data.readInt();
+                item = { gdscode: num };
+                if (num) {
+                    (response.warnings = response.warnings || []).push(item);
+                }
                 break;
             default:
+                // Stop parsing: continuing the loop after an unknown item
+                // re-read the same bytes forever (the caller resets the
+                // reader position when the error is delivered).
                 if (cb) {
-                    cb(new Error('Unexpected: ' + op))
-                } else {
-                    throw new Error('Unexpected: ' + op);
+                    return cb(new Error('Unexpected: ' + op));
                 }
+                throw new Error('Unexpected: ' + op);
         }
     }
 }
 
-function describe(buff: Buffer, statement: any) {
+function describe(buff: Buffer, statement: Statement) {
     var br = new BlrReader(buff);
     var parameters: any = null;
     var type: any, param: any;
@@ -2908,7 +3145,7 @@ function describe(buff: Buffer, statement: any) {
     while (br.pos < br.buffer.length) {
         switch (br.readByteCode()) {
             case Const.isc_info_sql_stmt_type:
-                statement.type = br.readInt();
+                statement.type = br.readInt()!;
                 break;
             case Const.isc_info_sql_get_plan:
                 statement.plan = br.readString(Const.DEFAULT_ENCODING);
@@ -2932,7 +3169,9 @@ function describe(buff: Buffer, statement: any) {
                         case Const.isc_info_sql_describe_end:
                             break;
                         case Const.isc_info_sql_sqlda_seq:
-                            var num = br.readInt();
+                            // describe output always encodes the sequence as a
+                            // 1/2/4-byte int, so readInt cannot return undefined
+                            var num = br.readInt()!;
                             break;
                         case Const.isc_info_sql_type:
                             type = br.readInt();
@@ -2963,7 +3202,9 @@ function describe(buff: Buffer, statement: any) {
                                 default:
                                     throw new Error('Unexpected');
                             }
-                            parameters[num-1] = param;
+                            // isc_info_sql_sqlda_seq always precedes the type
+                            // item in the describe stream, so num is set here
+                            parameters[num!-1] = param;
                             param.type = type;
                             param.nullable = Boolean(param.type & 1);
                             param.type &= ~1;
@@ -3243,10 +3484,10 @@ function CalcBlr(blr: BlrWriter, xsqlda: any[]) {
     blr.addByte(Const.blr_eoc);
 }
 
-function fetch_blob_async_transaction(statement: any, id: any, column: any, row: any) {
-    const infoValue = { row, column, value: '' };
+function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase, table?: string) {
+    const infoValue = { row, column, value: '', meta, table };
 
-    return (transactionArg) => {
+    return (transactionArg: any) => {
         const cacheKey = `${id.high}:${id.low}`;
         if (statement.connection._inlineBlobs && statement.connection._inlineBlobs.has(cacheKey)) {
             const data = statement.connection._inlineBlobs.get(cacheKey);
@@ -3256,10 +3497,10 @@ function fetch_blob_async_transaction(statement: any, id: any, column: any, row:
 
         const singleTransaction = transactionArg === undefined;
 
-        let promiseTransaction;
+        let promiseTransaction: Promise<Transaction>;
         if (singleTransaction) {
             promiseTransaction = new Promise((resolve, reject) => {
-                statement.connection.startTransaction(Const.ISOLATION_READ_UNCOMMITTED, (err, transaction) => {
+                statement.connection.startTransaction(Const.ISOLATION_READ_UNCOMMITTED, (err: any, transaction: Transaction) => {
                     if (err) {
                         return reject(err);
                     }
@@ -3273,7 +3514,7 @@ function fetch_blob_async_transaction(statement: any, id: any, column: any, row:
         return promiseTransaction.then((transaction) => {
             return new Promise((resolve, reject) => {
                 statement.connection._pending.push('openBlob');
-                statement.connection.openBlob(id, transaction, (err, blob) => {
+                statement.connection.openBlob(id, transaction, (err: any, blob: any) => {
 
                     if (err) {
                         reject(err);
@@ -3281,7 +3522,7 @@ function fetch_blob_async_transaction(statement: any, id: any, column: any, row:
                     }
 
                     const read = () => {
-                        statement.connection.getSegment(blob, (err, ret) => {
+                        statement.connection.getSegment(blob, (err: any, ret: any) => {
 
                             if (err) {
                                 if (singleTransaction) {
@@ -3305,7 +3546,7 @@ function fetch_blob_async_transaction(statement: any, id: any, column: any, row:
 
                             statement.connection.closeBlob(blob);
                             if (singleTransaction) {
-                                transaction.commit((err) => {
+                                transaction.commit((err: any) => {
                                     if (err) {
                                         reject(err);
                                     } else {
@@ -3325,14 +3566,14 @@ function fetch_blob_async_transaction(statement: any, id: any, column: any, row:
     };
 }
 
-function fetch_blob_async(statement: any, id: any, name: any, row: any) {
-    const cbTransaction = (transaction, close, callback) => {
+function fetch_blob_async(statement: Statement, id: Quad, name: string | number, row: number) {
+    const cbTransaction = (transaction: Transaction, close: any, callback: any) => {
         statement.connection._pending.push('openBlob');
-        statement.connection.openBlob(id, transaction, (err, blob) => {
+        statement.connection.openBlob(id, transaction, (err: any, blob: any) => {
             let e: any = new Events.EventEmitter();
 
-            e.pipe = (stream) => {
-                e.on('data', (chunk) => {
+            e.pipe = (stream: any) => {
+                e.on('data', (chunk: any) => {
                     stream.write(chunk);
                 });
                 e.on('end', () => {
@@ -3345,7 +3586,7 @@ function fetch_blob_async(statement: any, id: any, name: any, row: any) {
             }
 
             const read = () => {
-                statement.connection.getSegment(blob, (err, ret) => {
+                statement.connection.getSegment(blob, (err: any, ret: any) => {
 
                     if (err) {
                         transaction.rollback(() => {
@@ -3368,7 +3609,7 @@ function fetch_blob_async(statement: any, id: any, name: any, row: any) {
 
                     statement.connection.closeBlob(blob);
                     if (close) {
-                        transaction.commit((err) => {
+                        transaction.commit((err: any) => {
                             if (err) {
                                 e.emit('error', err);
                             } else {
@@ -3388,7 +3629,7 @@ function fetch_blob_async(statement: any, id: any, name: any, row: any) {
         });
     };
 
-    return (transaction, callback) => {
+    return (transaction: Transaction, callback: any) => {
         // callback(error, nameField, eventEmitter, row)
         const singleTransaction = callback === undefined;
         const actualCallback = singleTransaction ? transaction : callback;
@@ -3397,8 +3638,8 @@ function fetch_blob_async(statement: any, id: any, name: any, row: any) {
         if (statement.connection._inlineBlobs && statement.connection._inlineBlobs.has(cacheKey)) {
             const data = statement.connection._inlineBlobs.get(cacheKey);
             let e: any = new Events.EventEmitter();
-            e.pipe = (stream) => {
-                e.on('data', (chunk) => {
+            e.pipe = (stream: any) => {
+                e.on('data', (chunk: any) => {
                     stream.write(chunk);
                 });
                 e.on('end', () => {
@@ -3419,7 +3660,7 @@ function fetch_blob_async(statement: any, id: any, name: any, row: any) {
 
         if (singleTransaction) {
             callback = transaction;
-            statement.connection.startTransaction(Const.ISOLATION_READ_UNCOMMITTED, (err, transaction) => {
+            statement.connection.startTransaction(Const.ISOLATION_READ_UNCOMMITTED, (err: any, transaction: Transaction) => {
                 if (err) {
                     callback(err);
                     return;
@@ -3438,7 +3679,7 @@ function doSynchronousLoop(data: any[], processData: (row: any, index: number, n
         return;
     }
 
-    const loop = (index) => {
+    const loop = (index: any) => {
         processData(data[index], index, (err) => {
             if (err) {
                 done(err);