node-firebird 2.10.0 → 2.11.0

package/README.md

@@ -13,7 +13,7 @@
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
 - [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
-- [Examples](#examples) — parametrized queries, named placeholders, custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
+- [Examples](#examples) — parametrized queries, named placeholders, nested result tables (nestTables), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
 - [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
@@ -185,6 +185,7 @@ options.searchPath = undefined; // optional; ordered list/array of schemas to re
 options.owner = undefined; // optional; owner of a newly created database — lets a superuser create a database for another user (create only, FB >= 6.0)
 options.jsonAsObject = false; // optional; automatically stringify parameters and parse query results that contain JSON (FB >= 6.0)
 options.namedPlaceholders = false; // set to true to allow :name placeholders in SQL with a { name: value } params object (see Named placeholders)
+options.nestTables = false; // true nests object rows by source table (row[table][column]); a string separator flattens to 'table<sep>column' keys — see Nested result tables (nestTables). Overridable per query
 options.typeCast = undefined; // optional; custom type parser called for every result column value (see Custom type parsers)
 options.statementCacheSize = 0; // optional; per-connection LRU cache of prepared statements, 0 = disabled (see Prepared-statement cache)
 ```
@@ -492,6 +493,50 @@ the per-query option:
 await db.queryAsync(execBlockSql, [], { namedPlaceholders: false });
 ```
 
+### Nested result tables (nestTables)
+
+In a `JOIN`, columns sharing a name overwrite each other in object rows —
+`SELECT EMP.ID, DEPT.ID ...` leaves only one `ID` key. The `nestTables`
+option (same as mysql2's) qualifies row keys by source table instead. It is
+accepted at connection level and per query; the per-query value wins.
+
+With `nestTables: true` each row nests one sub-object per table:
+
+```js
+const rows = await db.queryAsync(
+  'SELECT EMP.ID, EMP.NAME, DEPT.ID, DEPT.NAME FROM EMP JOIN DEPT ON DEPT.ID = EMP.DEPT_ID',
+  [], { nestTables: true });
+// rows[0] = { EMP: { ID: 10, NAME: 'Ada' }, DEPT: { ID: 1, NAME: 'Engineering' } }
+```
+
+With a string separator the keys stay flat but qualified:
+
+```js
+const rows = await db.queryAsync(sql, [], { nestTables: '_' });
+// rows[0] = { EMP_ID: 10, EMP_NAME: 'Ada', DEPT_ID: 1, DEPT_NAME: 'Engineering' }
+```
+
+The table qualifier is the query's relation alias when one is used, the
+table name otherwise — so self-joins nest cleanly:
+
+```js
+const rows = await db.queryAsync(
+  'SELECT E.NAME, B.NAME FROM EMP E LEFT JOIN EMP B ON B.ID = E.BOSS_ID',
+  [], { nestTables: true });
+// rows[0] = { E: { NAME: 'Grace' }, B: { NAME: 'Ada' } }
+```
+
+Expression columns (no source table) qualify as `''`, exactly like mysql2:
+they land under the `''` key when nesting (`row[''].ANSWER`) and get the
+bare separator prefix in separator mode (`row._ANSWER`) — always prefixing
+keeps qualified keys collision-free (a bare expression alias could
+otherwise collide with a real `table<sep>column` key). Keys honour
+`lowercase_keys`, and the option composes with
+`typeCast`, `blobAsText` and `queryStream`. Object rows only: `db.execute`
+array rows are positional and need no qualification. Works on every
+supported Firebird version (the source-table metadata comes from the
+statement describe, available since Firebird 2.0).
+
 ### Custom type parsers (typeCast)
 
 The `typeCast` connection option lets you override how column values are

package/lib/types.d.ts

@@ -115,6 +115,18 @@ export type QueryOptions = {
      * it cancels whatever is currently executing on the connection.
      */
     signal?: AbortSignal;
+    /**
+     * Per-query override of the `nestTables` connection option (mysql2
+     * semantics). `true` nests each object row by source table:
+     * `row[table][column]` — the table key is the query's relation alias
+     * when one is used (`FROM emp e` → `row.E`), the table name otherwise,
+     * and `''` for expression columns. A string separator flattens keys
+     * instead: `nestTables: '_'` → `row.EMP_NAME`; expression columns get
+     * the bare separator prefix (`row._ANSWER`, as in mysql2). Keys honour
+     * `lowercase_keys`. Object rows only — `db.execute` array rows are
+     * unaffected.
+     */
+    nestTables?: boolean | string;
 };
 export type QueryStreamOptions = QueryOptions & {
     /**
@@ -254,6 +266,16 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Qualify object-row keys by source table (same option as mysql2), so
+     * JOINed columns with the same name stop overwriting each other:
+     * `true` nests each row as `row[table][column]`; a string separator
+     * flattens to `row['table' + sep + 'column']`. See
+     * `QueryOptions.nestTables` for the exact key rules. Applies wherever
+     * object rows are produced (query / sequentially / queryStream);
+     * array rows (execute) are unaffected. Overridable per query.
+     */
+    nestTables?: boolean | string;
     /**
      * TCP keepalive probing to detect dead/stale connections (same option
      * names as mysql2). On by default; set false to disable.

package/lib/wire/connection.d.ts

@@ -150,6 +150,6 @@ declare function decodeResponse(data: XdrReader, callback: QueueCallback | undef
     error: Error;
 };
 declare function describe(buff: Buffer, statement: Statement): void;
-declare function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase): (transactionArg: any) => Promise<unknown>;
+declare function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase, table?: string): (transactionArg: any) => Promise<unknown>;
 declare function fetch_blob_async(statement: Statement, id: Quad, name: string | number, row: number): (transaction: Transaction, callback: any) => void;
 export = Connection;

package/lib/wire/connection.js

@@ -1699,7 +1699,9 @@ class Connection {
                 readBlobsSequentially(0, []).then((arrBlob) => {
                     for (let i = 0; i < arrBlob.length; i++) {
                         const blob = arrBlob[i];
-                        ret.data[blob.row][blob.column] = applyTypeCast(statement.connection.options, blob.meta || {}, 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);
@@ -2085,6 +2087,7 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                 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(); // ??
@@ -2102,11 +2105,12 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                 data.frow = data.frow || (custom.asObject ? {} : new Array(output.length));
                 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 = [];
@@ -2129,7 +2133,10 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                         item = output[data.fcolumn];
                         if (!lowerV13 && nullBitSet.get(data.fcolumn)) {
                             const nullKey = custom.asObject ? data.fcols[data.fcolumn] : data.fcolumn;
-                            data.frow[nullKey] = applyTypeCast(cnx.options, item, null);
+                            // 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 {
@@ -2143,7 +2150,7 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                             let pendingTextBlob = false;
                             if (item.type === const_1.default.SQL_BLOB && value !== null) {
                                 if (item.subType === const_1.default.isc_blob_text && cnx.options.blobAsText) {
-                                    value = fetch_blob_async_transaction(statement, value, key, row, item);
+                                    value = fetch_blob_async_transaction(statement, value, key, row, item, data.ftables && data.ftables[data.fcolumn]);
                                     arrBlob.push(value);
                                     pendingTextBlob = true;
                                 }
@@ -2151,7 +2158,7 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                                     value = fetch_blob_async(statement, value, key, row);
                                 }
                             }
-                            data.frow[key] = pendingTextBlob
+                            (data.ftables ? Xsql.nestCell(data.frow, data.ftables[data.fcolumn]) : data.frow)[key] = pendingTextBlob
                                 ? value
                                 : applyTypeCast(cnx.options, item, parseValueIfJson(value, cnx.options));
                         }
@@ -3019,8 +3026,8 @@ function CalcBlr(blr, xsqlda) {
     blr.addByte(const_1.default.blr_end);
     blr.addByte(const_1.default.blr_eoc);
 }
-function fetch_blob_async_transaction(statement, id, column, row, meta) {
-    const infoValue = { row, column, value: '', meta };
+function fetch_blob_async_transaction(statement, id, column, row, meta, table) {
+    const infoValue = { row, column, value: '', meta, table };
     return (transactionArg) => {
         const cacheKey = `${id.high}:${id.low}`;
         if (statement.connection._inlineBlobs && statement.connection._inlineBlobs.has(cacheKey)) {

package/lib/wire/const.js

@@ -577,6 +577,7 @@ const DESCRIBE = [
     sqlInfo.isc_info_sql_length,
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
+    sqlInfo.isc_info_sql_relation_alias, // FB 2.0+: query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -604,6 +605,7 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
     sqlInfo.isc_info_sql_relation_schema, // FB 6.0: schema of source relation
+    sqlInfo.isc_info_sql_relation_alias, // query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,

package/lib/wire/database.js

@@ -6,6 +6,7 @@ const events_1 = __importDefault(require("events"));
 const callback_1 = require("../callback");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
+const xsqlvar_1 = require("./xsqlvar");
 const eventConnection_1 = __importDefault(require("./eventConnection"));
 const fbEventManager_1 = __importDefault(require("./fbEventManager"));
 const query_stream_1 = __importDefault(require("./query-stream"));
@@ -75,30 +76,42 @@ function readblob(blob, callback) {
         });
     });
 }
-function fetchBlobSyncRow(row, meta, callback) {
-    if (!row || !meta || !meta.length) {
+function fetchBlobSyncRow(row, meta, nestTables, lowercaseKeys, callback) {
+    if (!row || !meta || !meta.length || !meta.some((m) => m && m.type === const_1.default.SQL_BLOB)) {
         callback(null, row);
         return;
     }
-    const rowKeys = Object.keys(row);
-    const blobColumns = [];
+    // locate blob cells by the same key computation the fetch decoder used,
+    // rather than assuming Object.keys(row) is index-aligned with meta —
+    // duplicate JOIN column names (and nested rows) break that alignment.
+    // Array rows (sequentially's legacy boolean form) are keyed by index.
+    const isArrayRow = Array.isArray(row);
+    const keys = isArrayRow ? null : (0, xsqlvar_1.computeColumnKeys)(meta, nestTables, lowercaseKeys);
+    const blobCells = [];
     for (let i = 0; i < meta.length; i++) {
-        if (meta[i] && meta[i].type === const_1.default.SQL_BLOB && rowKeys[i] !== undefined) {
-            blobColumns.push(rowKeys[i]);
+        if (!meta[i] || meta[i].type !== const_1.default.SQL_BLOB) {
+            continue;
+        }
+        const target = keys ? (0, xsqlvar_1.nestCell)(row, keys[i].table) : row;
+        const key = keys ? keys[i].key : i;
+        // duplicate aliases collapse onto one cell — read it only once
+        if (typeof target[key] === 'function' &&
+            !blobCells.some((cell) => cell.target === target && cell.key === key)) {
+            blobCells.push({ target, key });
         }
     }
-    if (!blobColumns.length) {
+    if (!blobCells.length) {
         callback(null, row);
         return;
     }
-    let pending = blobColumns.length;
+    let pending = blobCells.length;
     let blobErr;
-    blobColumns.forEach(function (columnName) {
-        readblob(row[columnName], function (err, data) {
+    blobCells.forEach(function (cell) {
+        readblob(cell.target[cell.key], function (err, data) {
             if (err && !blobErr) {
                 blobErr = err;
             }
-            row[columnName] = data;
+            cell.target[cell.key] = data;
             pending--;
             if (pending === 0) {
                 callback(blobErr, row);
@@ -259,7 +272,9 @@ class Database extends events_1.default.EventEmitter {
                 done = true;
                 next(err);
             };
-            fetchBlobSyncRow(row, meta, function (blobErr) {
+            // options is read at call time, after the normalization below
+            const nest = (0, xsqlvar_1.resolveNestTables)(options, self.connection.options);
+            fetchBlobSyncRow(row, meta, nest, self.connection._lowercase_keys, function (blobErr) {
                 if (blobErr) {
                     finish(blobErr);
                     return;

package/lib/wire/serialize.d.ts

@@ -83,8 +83,10 @@ export declare class XdrReader {
     frow?: any;
     /** rows decoded so far in this call */
     frows?: any[];
-    /** cached object-row keys (column aliases) */
+    /** cached object-row keys (column aliases, qualified when nestTables is set) */
     fcols?: string[];
+    /** cached per-column table keys when nestTables === true */
+    ftables?: string[];
     constructor(buffer: Buffer);
     readInt(): number;
     readUInt(): number;

package/lib/wire/xsqlvar.d.ts

@@ -21,6 +21,45 @@ export declare abstract class SQLVarBase {
     abstract decode(data: XdrReader, lowerV13: boolean, options?: any): any;
     abstract calcBlr(blr: BlrWriter): void;
 }
+/** Effective object-row key(s) of one output column (see computeColumnKeys). */
+export interface ColumnKey {
+    /** Top-level table key when nestTables === true; undefined otherwise. */
+    table?: string;
+    /** Property key: the column alias, or 'table<sep>alias' in separator mode. */
+    key: string;
+}
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+export declare function computeColumnKeys(output: SQLVarBase[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined): ColumnKey[];
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+export declare function resolveNestTables(queryOptions: {
+    nestTables?: boolean | string;
+} | undefined, connectionOptions: {
+    nestTables?: boolean | string;
+} | undefined): boolean | string | undefined;
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+export declare function nestCell(row: any, table: string | undefined): any;
 export declare class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any): string | Buffer<ArrayBufferLike> | null | undefined;
     calcBlr(blr: BlrWriter): void;

package/lib/wire/xsqlvar.js

@@ -4,6 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQLVarBase = void 0;
+exports.computeColumnKeys = computeColumnKeys;
+exports.resolveNestTables = resolveNestTables;
+exports.nestCell = nestCell;
 exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
 /***************************************
@@ -68,6 +71,62 @@ function resolveTextEncoding(options) {
 class SQLVarBase {
 }
 exports.SQLVarBase = SQLVarBase;
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+function computeColumnKeys(output, nestTables, lowercaseKeys) {
+    return output.map((column) => {
+        let key = column.alias || '';
+        if (lowercaseKeys) {
+            key = key.toLowerCase();
+        }
+        if (nestTables !== true && typeof nestTables !== 'string') {
+            return { key };
+        }
+        let table = column.relationAlias || column.relation || '';
+        if (lowercaseKeys) {
+            table = table.toLowerCase();
+        }
+        if (nestTables === true) {
+            return { table, key };
+        }
+        return { key: table + nestTables + key };
+    });
+}
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+function resolveNestTables(queryOptions, connectionOptions) {
+    if (queryOptions && queryOptions.nestTables !== undefined) {
+        return queryOptions.nestTables;
+    }
+    return connectionOptions && connectionOptions.nestTables;
+}
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+function nestCell(row, table) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
 //------------------------------------------------------
 class SQLVarText extends SQLVarBase {
     decode(data, lowerV13, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.10.0",
+    "version": "2.11.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/types.ts

@@ -127,6 +127,18 @@ export type QueryOptions = {
      * it cancels whatever is currently executing on the connection.
      */
     signal?: AbortSignal;
+    /**
+     * Per-query override of the `nestTables` connection option (mysql2
+     * semantics). `true` nests each object row by source table:
+     * `row[table][column]` — the table key is the query's relation alias
+     * when one is used (`FROM emp e` → `row.E`), the table name otherwise,
+     * and `''` for expression columns. A string separator flattens keys
+     * instead: `nestTables: '_'` → `row.EMP_NAME`; expression columns get
+     * the bare separator prefix (`row._ANSWER`, as in mysql2). Keys honour
+     * `lowercase_keys`. Object rows only — `db.execute` array rows are
+     * unaffected.
+     */
+    nestTables?: boolean | string;
 }
 
 export type QueryStreamOptions = QueryOptions & {
@@ -314,6 +326,16 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Qualify object-row keys by source table (same option as mysql2), so
+     * JOINed columns with the same name stop overwriting each other:
+     * `true` nests each row as `row[table][column]`; a string separator
+     * flattens to `row['table' + sep + 'column']`. See
+     * `QueryOptions.nestTables` for the exact key rules. Applies wherever
+     * object rows are produced (query / sequentially / queryStream);
+     * array rows (execute) are unaffected. Overridable per query.
+     */
+    nestTables?: boolean | string;
     /**
      * TCP keepalive probing to detect dead/stale connections (same option
      * names as mysql2). On by default; set false to disable.

package/src/wire/connection.ts

@@ -2015,7 +2015,9 @@ class Connection {
                 readBlobsSequentially(0, []).then((arrBlob: any) => {
                     for (let i = 0; i < arrBlob.length; i++) {
                         const blob = arrBlob[i];
-                        ret.data[blob.row][blob.column] = applyTypeCast(
+                        // 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));
                     }
@@ -2469,6 +2471,7 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                 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); // ??
@@ -2490,10 +2493,12 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                 data.frows = data.frows || [];
 
                 if (custom.asObject && !data.fcols) {
-                    if (lowercase_keys) {
-                        data.fcols = output.map((column: any) => column.alias.toLowerCase());
-                    } else {
-                        data.fcols = output.map((column: any) => 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!);
                     }
                 }
 
@@ -2521,7 +2526,10 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
 
                         if (!lowerV13 && nullBitSet!.get(data.fcolumn)) {
                             const nullKey = custom.asObject ? data.fcols![data.fcolumn!] : data.fcolumn;
-                            data.frow[nullKey] = applyTypeCast(cnx.options, item, null);
+                            // 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;
                         }
@@ -2538,7 +2546,8 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
 
                             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, item);
+                                    value = fetch_blob_async_transaction(statement, value, key, row, item,
+                                        data.ftables && data.ftables[data.fcolumn!]);
                                     arrBlob.push(value);
                                     pendingTextBlob = true;
                                 } else {
@@ -2546,7 +2555,7 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                                 }
                             }
 
-                            data.frow[key] = pendingTextBlob
+                            (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) {
@@ -3475,8 +3484,8 @@ function CalcBlr(blr: BlrWriter, xsqlda: any[]) {
     blr.addByte(Const.blr_eoc);
 }
 
-function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase) {
-    const infoValue = { row, column, value: '', meta };
+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: any) => {
         const cacheKey = `${id.high}:${id.low}`;

package/src/wire/const.ts

@@ -626,6 +626,7 @@ const DESCRIBE = [
     sqlInfo.isc_info_sql_length,
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
+    sqlInfo.isc_info_sql_relation_alias, // FB 2.0+: query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -654,6 +655,7 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
     sqlInfo.isc_info_sql_relation_schema, // FB 6.0: schema of source relation
+    sqlInfo.isc_info_sql_relation_alias, // query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,

package/src/wire/database.ts

@@ -2,6 +2,7 @@ import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
 import { escape } from '../utils';
 import Const from './const';
+import { computeColumnKeys, nestCell, resolveNestTables } from './xsqlvar';
 import EventConnection from './eventConnection';
 import FbEventManager from './fbEventManager';
 import makeQueryStream from './query-stream';
@@ -94,35 +95,47 @@ function readblob(blob: any, callback: Callback): void {
     });
 }
 
-function fetchBlobSyncRow(row: any, meta: any[], callback: Callback): void {
-    if (!row || !meta || !meta.length) {
+function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined, callback: Callback): void {
+    if (!row || !meta || !meta.length || !meta.some((m) => m && m.type === Const.SQL_BLOB)) {
         callback(null, row);
         return;
     }
 
-    const rowKeys = Object.keys(row);
-    const blobColumns: string[] = [];
+    // locate blob cells by the same key computation the fetch decoder used,
+    // rather than assuming Object.keys(row) is index-aligned with meta —
+    // duplicate JOIN column names (and nested rows) break that alignment.
+    // Array rows (sequentially's legacy boolean form) are keyed by index.
+    const isArrayRow = Array.isArray(row);
+    const keys = isArrayRow ? null : computeColumnKeys(meta, nestTables, lowercaseKeys);
+    const blobCells: { target: any; key: string | number }[] = [];
 
     for (let i = 0; i < meta.length; i++) {
-        if (meta[i] && meta[i].type === Const.SQL_BLOB && rowKeys[i] !== undefined) {
-            blobColumns.push(rowKeys[i]);
+        if (!meta[i] || meta[i].type !== Const.SQL_BLOB) {
+            continue;
+        }
+        const target = keys ? nestCell(row, keys[i].table) : row;
+        const key = keys ? keys[i].key : i;
+        // duplicate aliases collapse onto one cell — read it only once
+        if (typeof target[key] === 'function' &&
+            !blobCells.some((cell) => cell.target === target && cell.key === key)) {
+            blobCells.push({ target, key });
         }
     }
 
-    if (!blobColumns.length) {
+    if (!blobCells.length) {
         callback(null, row);
         return;
     }
 
-    let pending = blobColumns.length;
+    let pending = blobCells.length;
     let blobErr: any;
 
-    blobColumns.forEach(function(columnName) {
-        readblob(row[columnName], function(err: any, data: any) {
+    blobCells.forEach(function(cell) {
+        readblob(cell.target[cell.key], function(err: any, data: any) {
             if (err && !blobErr) {
                 blobErr = err;
             }
-            row[columnName] = data;
+            cell.target[cell.key] = data;
             pending--;
             if (pending === 0) {
                 callback(blobErr, row);
@@ -322,7 +335,9 @@ class Database extends Events.EventEmitter {
                 next(err);
             };
 
-            fetchBlobSyncRow(row, meta, function(blobErr: any) {
+            // options is read at call time, after the normalization below
+            const nest = resolveNestTables(options as any, self.connection.options);
+            fetchBlobSyncRow(row, meta, nest, self.connection._lowercase_keys, function(blobErr: any) {
                 if (blobErr) {
                     finish(blobErr);
                     return;

package/src/wire/serialize.ts

@@ -440,8 +440,10 @@ export class XdrReader {
     frow?: any;
     /** rows decoded so far in this call */
     frows?: any[];
-    /** cached object-row keys (column aliases) */
+    /** cached object-row keys (column aliases, qualified when nestTables is set) */
     fcols?: string[];
+    /** cached per-column table keys when nestTables === true */
+    ftables?: string[];
 
     constructor(buffer: Buffer) {
         this.buffer = buffer;

package/src/wire/xsqlvar.ts

@@ -93,6 +93,82 @@ export abstract class SQLVarBase {
 
 //------------------------------------------------------
 
+/** Effective object-row key(s) of one output column (see computeColumnKeys). */
+export interface ColumnKey {
+    /** Top-level table key when nestTables === true; undefined otherwise. */
+    table?: string;
+    /** Property key: the column alias, or 'table<sep>alias' in separator mode. */
+    key: string;
+}
+
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+export function computeColumnKeys(
+    output: SQLVarBase[],
+    nestTables: boolean | string | undefined,
+    lowercaseKeys: boolean | undefined
+): ColumnKey[] {
+    return output.map((column) => {
+        let key = column.alias || '';
+        if (lowercaseKeys) {
+            key = key.toLowerCase();
+        }
+        if (nestTables !== true && typeof nestTables !== 'string') {
+            return { key };
+        }
+        let table = column.relationAlias || column.relation || '';
+        if (lowercaseKeys) {
+            table = table.toLowerCase();
+        }
+        if (nestTables === true) {
+            return { table, key };
+        }
+        return { key: table + nestTables + key };
+    });
+}
+
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+export function resolveNestTables(
+    queryOptions: { nestTables?: boolean | string } | undefined,
+    connectionOptions: { nestTables?: boolean | string } | undefined
+): boolean | string | undefined {
+    if (queryOptions && queryOptions.nestTables !== undefined) {
+        return queryOptions.nestTables;
+    }
+    return connectionOptions && connectionOptions.nestTables;
+}
+
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+export function nestCell(row: any, table: string | undefined) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
+
+//------------------------------------------------------
+
 export class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any) {
         let ret;