linkgress-orm 0.1.5 → 0.1.6

package/dist/query/query-builder.js

@@ -6,11 +6,28 @@ exports.getRelationEntriesForSchema = getRelationEntriesForSchema;
 exports.getTargetSchemaForRelation = getTargetSchemaForRelation;
 exports.createNestedFieldRefProxy = createNestedFieldRefProxy;
 const conditions_1 = require("./conditions");
+const db_context_1 = require("../entity/db-context");
 const query_utils_1 = require("./query-utils");
 const subquery_1 = require("./subquery");
 const grouped_query_1 = require("./grouped-query");
 const cte_builder_1 = require("./cte-builder");
 const collection_strategy_factory_1 = require("./collection-strategy.factory");
+/**
+ * Field type categories for optimized result transformation
+ * const enum is inlined at compile time for zero runtime overhead
+ */
+var FieldType;
+(function (FieldType) {
+    FieldType[FieldType["NAVIGATION"] = 0] = "NAVIGATION";
+    FieldType[FieldType["COLLECTION_SCALAR"] = 1] = "COLLECTION_SCALAR";
+    FieldType[FieldType["COLLECTION_ARRAY"] = 2] = "COLLECTION_ARRAY";
+    FieldType[FieldType["COLLECTION_JSON"] = 3] = "COLLECTION_JSON";
+    FieldType[FieldType["CTE_AGGREGATION"] = 4] = "CTE_AGGREGATION";
+    FieldType[FieldType["SQL_FRAGMENT_MAPPER"] = 5] = "SQL_FRAGMENT_MAPPER";
+    FieldType[FieldType["FIELD_REF_MAPPER"] = 6] = "FIELD_REF_MAPPER";
+    FieldType[FieldType["FIELD_REF_NO_MAPPER"] = 7] = "FIELD_REF_NO_MAPPER";
+    FieldType[FieldType["SIMPLE"] = 8] = "SIMPLE";
+})(FieldType || (FieldType = {}));
 /**
  * Performance utility: Get column name map from schema, using cached version if available
  */
@@ -184,16 +201,25 @@ class QueryBuilder {
             return this._cachedMockRow;
         }
         const mock = {};
+        const tableAlias = this.schema.name;
         // Performance: Use pre-computed column name map if available
         const columnNameMap = getColumnNameMapForSchema(this.schema);
+        // Performance: Lazy-cache FieldRef objects - only create when first accessed
+        const fieldRefCache = {};
         // Add columns as FieldRef objects - type-safe with property name and database column name
         for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
-                get: () => ({
-                    __fieldName: colName,
-                    __dbColumnName: dbColumnName,
-                    __tableAlias: this.schema.name,
-                }),
+                get() {
+                    let cached = fieldRefCache[colName];
+                    if (!cached) {
+                        cached = fieldRefCache[colName] = {
+                            __fieldName: colName,
+                            __dbColumnName: dbColumnName,
+                            __tableAlias: tableAlias,
+                        };
+                    }
+                    return cached;
+                },
                 enumerable: true,
                 configurable: true,
             });
@@ -339,14 +365,22 @@ class QueryBuilder {
         const mock = {};
         // Performance: Use pre-computed column name map if available
         const columnNameMap = getColumnNameMapForSchema(schema);
+        // Performance: Lazy-cache FieldRef objects
+        const fieldRefCache = {};
         // Add columns as FieldRef objects with table alias
         for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
-                get: () => ({
-                    __fieldName: colName,
-                    __dbColumnName: dbColumnName,
-                    __tableAlias: alias,
-                }),
+                get() {
+                    let cached = fieldRefCache[colName];
+                    if (!cached) {
+                        cached = fieldRefCache[colName] = {
+                            __fieldName: colName,
+                            __dbColumnName: dbColumnName,
+                            __tableAlias: alias,
+                        };
+                    }
+                    return cached;
+                },
                 enumerable: true,
                 configurable: true,
             });
@@ -711,14 +745,22 @@ class SelectQueryBuilder {
         const mock = {};
         // Performance: Use pre-computed column name map if available
         const columnNameMap = getColumnNameMapForSchema(schema);
+        // Performance: Lazy-cache FieldRef objects
+        const fieldRefCache = {};
         // Add columns as FieldRef objects with table alias
         for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
-                get: () => ({
-                    __fieldName: colName,
-                    __dbColumnName: dbColumnName,
-                    __tableAlias: alias,
-                }),
+                get() {
+                    let cached = fieldRefCache[colName];
+                    if (!cached) {
+                        cached = fieldRefCache[colName] = {
+                            __fieldName: colName,
+                            __dbColumnName: dbColumnName,
+                            __tableAlias: alias,
+                        };
+                    }
+                    return cached;
+                },
                 enumerable: true,
                 configurable: true,
             });
@@ -986,65 +1028,94 @@ class SelectQueryBuilder {
      * Collection results are automatically resolved to arrays
      */
     async toList() {
-        const context = {
+        const options = this.executor?.getOptions();
+        const tracer = new db_context_1.TimeTracer(options?.traceTime ?? false, options?.logger);
+        // Query Build Phase
+        tracer.startPhase('queryBuild');
+        const context = tracer.trace('createContext', () => ({
             ctes: new Map(),
             cteCounter: 0,
             paramCounter: 1,
             allParams: [],
             collectionStrategy: this.collectionStrategy,
             executor: this.executor,
-        };
+        }));
         // Analyze the selector to extract nested queries
-        const mockRow = this.createMockRow();
-        const selectionResult = this.selector(mockRow);
+        const mockRow = tracer.trace('createMockRow', () => this.createMockRow());
+        const selectionResult = tracer.trace('evaluateSelector', () => this.selector(mockRow));
         // Check if we're using temp table strategy and have collections
-        const collections = this.detectCollections(selectionResult);
+        const collections = tracer.trace('detectCollections', () => this.detectCollections(selectionResult));
         const useTempTableStrategy = this.collectionStrategy === 'temptable' && collections.length > 0;
+        tracer.endPhase();
+        let results;
         if (useTempTableStrategy) {
             // Two-phase execution for temp table strategy
-            return this.executeWithTempTables(selectionResult, context, collections);
+            results = await this.executeWithTempTables(selectionResult, context, collections, tracer);
         }
         else {
             // Single-phase execution for JSONB strategy (current behavior)
-            return this.executeSinglePhase(selectionResult, context);
+            results = await this.executeSinglePhase(selectionResult, context, tracer);
         }
+        // Log trace summary if tracing is enabled
+        tracer.logSummary(results.length);
+        return results;
     }
     /**
      * Execute query using single-phase approach (JSONB/CTE strategy)
      */
-    async executeSinglePhase(selectionResult, context) {
+    async executeSinglePhase(selectionResult, context, tracer) {
         // Build the query
-        const { sql, params } = this.buildQuery(selectionResult, context);
+        tracer.startPhase('queryBuild');
+        const { sql, params } = tracer.trace('buildQuery', () => this.buildQuery(selectionResult, context));
+        tracer.endPhase();
         // Execute using executor if available, otherwise use client directly
-        const result = this.executor
+        tracer.startPhase('queryExecution');
+        const result = await tracer.traceAsync('executeQuery', async () => this.executor
             ? await this.executor.query(sql, params)
-            : await this.client.query(sql, params);
+            : await this.client.query(sql, params), { rowCount: 'pending' });
+        tracer.endPhase();
+        // If rawResult is enabled, return raw rows without any processing
+        if (this.executor?.getOptions().rawResult) {
+            return result.rows;
+        }
         // Transform results
-        return this.transformResults(result.rows, selectionResult);
+        tracer.startPhase('resultProcessing');
+        const transformed = tracer.trace('transformResults', () => this.transformResults(result.rows, selectionResult), { rowCount: result.rows.length });
+        tracer.endPhase();
+        return transformed;
     }
     /**
      * Execute query using two-phase approach (temp table strategy)
      */
-    async executeWithTempTables(selectionResult, context, collections) {
+    async executeWithTempTables(selectionResult, context, collections, tracer) {
         // Build base selection (excludes collections, includes foreign keys)
-        const baseSelection = this.buildBaseSelection(selectionResult, collections);
-        const { sql: baseSql, params: baseParams } = this.buildQuery(baseSelection, {
+        tracer.startPhase('queryBuild');
+        const baseSelection = tracer.trace('buildBaseSelection', () => this.buildBaseSelection(selectionResult, collections));
+        const { sql: baseSql, params: baseParams } = tracer.trace('buildBaseQuery', () => this.buildQuery(baseSelection, {
             ...context,
             ctes: new Map(), // Clear CTEs since we're not using them for collections
-        });
+        }));
+        tracer.endPhase();
         // Check if we can use fully optimized single-query approach
         // Requirements: PostgresClient with querySimpleMulti support AND no parameters in base query
         const canUseFullOptimization = this.client.supportsMultiStatementQueries() &&
             baseParams.length === 0 &&
             collections.length > 0;
         if (canUseFullOptimization) {
-            return this.executeFullyOptimized(baseSql, baseSelection, selectionResult, context, collections);
+            return this.executeFullyOptimized(baseSql, baseSelection, selectionResult, context, collections, tracer);
         }
         // Legacy two-phase approach: execute base query first
-        const baseResult = this.executor
+        tracer.startPhase('queryExecution');
+        const baseResult = await tracer.traceAsync('executeBaseQuery', async () => this.executor
             ? await this.executor.query(baseSql, baseParams)
-            : await this.client.query(baseSql, baseParams);
+            : await this.client.query(baseSql, baseParams));
+        // If rawResult is enabled, return raw rows without any processing
+        if (this.executor?.getOptions().rawResult) {
+            tracer.endPhase();
+            return baseResult.rows;
+        }
         if (baseResult.rows.length === 0) {
+            tracer.endPhase();
             return [];
         }
         // Extract parent IDs from base results (using the known alias we added in buildBaseSelection)
@@ -1055,7 +1126,7 @@ class SelectQueryBuilder {
         for (const collection of collections) {
             const builder = collection.builder;
             // Call buildCTE with parent IDs - this will use the temp table strategy
-            const aggResult = await builder.buildCTE(context, this.client, parentIds);
+            const aggResult = await tracer.traceAsync(`buildCTE:${collection.name}`, async () => builder.buildCTE(context, this.client, parentIds));
             // aggResult is a Promise<CollectionAggregationResult> for temp table strategy
             const result = await aggResult;
             // If the result has a tableName, it means temp tables were created and we need to query them
@@ -1068,9 +1139,9 @@ class SelectQueryBuilder {
                 else {
                     // Temp table strategy (legacy) - query the aggregation table
                     const aggQuery = `SELECT parent_id, data FROM ${result.tableName}`;
-                    const aggQueryResult = this.executor
+                    const aggQueryResult = await tracer.traceAsync(`queryCollection:${collection.name}`, async () => this.executor
                         ? await this.executor.query(aggQuery, [])
-                        : await this.client.query(aggQuery, []);
+                        : await this.client.query(aggQuery, []));
                     // Cleanup temp tables if needed
                     if (result.cleanupSql) {
                         await this.client.query(result.cleanupSql);
@@ -1088,8 +1159,10 @@ class SelectQueryBuilder {
                 throw new Error('Expected temp table result but got CTE');
             }
         }
+        tracer.endPhase();
         // Phase 3: Merge base results with collection results
-        const mergedRows = baseResult.rows.map(baseRow => {
+        tracer.startPhase('resultProcessing');
+        const mergedRows = tracer.trace('mergeResults', () => baseResult.rows.map(baseRow => {
             const merged = { ...baseRow };
             for (const collection of collections) {
                 const resultMap = collectionResults.get(collection.name);
@@ -1099,84 +1172,104 @@ class SelectQueryBuilder {
             // Remove the internal __pk_id field before returning
             delete merged.__pk_id;
             return merged;
-        });
+        }), { rowCount: baseResult.rows.length });
         // Transform results using the original selection
-        return this.transformResults(mergedRows, selectionResult);
+        const transformed = tracer.trace('transformResults', () => this.transformResults(mergedRows, selectionResult), { rowCount: mergedRows.length });
+        tracer.endPhase();
+        return transformed;
     }
     /**
      * Execute using fully optimized single-query approach (PostgresClient only)
      * Combines base query + all collections into ONE multi-statement query
      */
-    async executeFullyOptimized(baseSql, baseSelection, selectionResult, context, collections) {
+    async executeFullyOptimized(baseSql, baseSelection, selectionResult, context, collections, tracer) {
+        tracer.startPhase('queryBuild');
         const baseTempTable = `tmp_base_${context.cteCounter++}`;
         // Build SQL for each collection
-        const collectionSQLs = [];
-        for (const collection of collections) {
-            const builderAny = collection.builder;
-            const targetTable = builderAny.targetTable;
-            const foreignKey = builderAny.foreignKey;
-            const selector = builderAny.selector;
-            const orderByFields = builderAny.orderByFields || [];
-            // Build selected fields
-            let selectedFieldsSQL = '';
-            if (selector) {
-                const mockItem = builderAny.createMockItem();
-                const selectedFields = selector(mockItem);
-                const fieldParts = [];
-                for (const [alias, field] of Object.entries(selectedFields)) {
-                    if (typeof field === 'object' && field !== null && '__dbColumnName' in field) {
-                        const dbColumnName = field.__dbColumnName;
-                        fieldParts.push(`"${dbColumnName}" as "${alias}"`);
+        const collectionSQLs = tracer.trace('buildCollectionSQLs', () => {
+            const sqls = [];
+            for (const collection of collections) {
+                const builderAny = collection.builder;
+                const targetTable = builderAny.targetTable;
+                const foreignKey = builderAny.foreignKey;
+                const selector = builderAny.selector;
+                const orderByFields = builderAny.orderByFields || [];
+                // Build selected fields
+                let selectedFieldsSQL = '';
+                if (selector) {
+                    const mockItem = builderAny.createMockItem();
+                    const selectedFields = selector(mockItem);
+                    const fieldParts = [];
+                    for (const [alias, field] of Object.entries(selectedFields)) {
+                        if (typeof field === 'object' && field !== null && '__dbColumnName' in field) {
+                            const dbColumnName = field.__dbColumnName;
+                            fieldParts.push(`"${dbColumnName}" as "${alias}"`);
+                        }
                     }
+                    selectedFieldsSQL = fieldParts.join(', ');
                 }
-                selectedFieldsSQL = fieldParts.join(', ');
-            }
-            // Build ORDER BY
-            let orderBySQL = orderByFields.length > 0
-                ? ` ORDER BY ${orderByFields.map(({ field, direction }) => `"${field}" ${direction}`).join(', ')}`
-                : ` ORDER BY "id" DESC`;
-            const collectionSQL = `SELECT "${foreignKey}" as parent_id, ${selectedFieldsSQL} FROM "${targetTable}" WHERE "${foreignKey}" IN (SELECT "__pk_id" FROM ${baseTempTable})${orderBySQL}`;
-            collectionSQLs.push(collectionSQL);
-        }
+                // Build ORDER BY
+                let orderBySQL = orderByFields.length > 0
+                    ? ` ORDER BY ${orderByFields.map(({ field, direction }) => `"${field}" ${direction}`).join(', ')}`
+                    : ` ORDER BY "id" DESC`;
+                const collectionSQL = `SELECT "${foreignKey}" as parent_id, ${selectedFieldsSQL} FROM "${targetTable}" WHERE "${foreignKey}" IN (SELECT "__pk_id" FROM ${baseTempTable})${orderBySQL}`;
+                sqls.push(collectionSQL);
+            }
+            return sqls;
+        });
         // Build mega multi-statement SQL
-        const statements = [
-            `CREATE TEMP TABLE ${baseTempTable} AS ${baseSql}`,
-            `SELECT * FROM ${baseTempTable}`,
-            ...collectionSQLs,
-            `DROP TABLE IF EXISTS ${baseTempTable}`
-        ];
-        const multiStatementSQL = statements.join(';\n');
+        const multiStatementSQL = tracer.trace('buildMultiStatement', () => {
+            const statements = [
+                `CREATE TEMP TABLE ${baseTempTable} AS ${baseSql}`,
+                `SELECT * FROM ${baseTempTable}`,
+                ...collectionSQLs,
+                `DROP TABLE IF EXISTS ${baseTempTable}`
+            ];
+            return statements.join(';\n');
+        });
+        tracer.endPhase();
         // Execute via querySimpleMulti
+        tracer.startPhase('queryExecution');
         const executor = this.executor || this.client;
         let resultSets;
         if ('querySimpleMulti' in executor && typeof executor.querySimpleMulti === 'function') {
-            resultSets = await executor.querySimpleMulti(multiStatementSQL);
+            resultSets = await tracer.traceAsync('executeMultiStatement', async () => executor.querySimpleMulti(multiStatementSQL));
         }
         else {
             throw new Error('Fully optimized mode requires querySimpleMulti support');
         }
+        tracer.endPhase();
         // Parse result sets: [0]=CREATE, [1]=base, [2..N]=collections, [N+1]=DROP
         const baseResult = resultSets[1];
+        // If rawResult is enabled, return raw rows without any processing
+        if (this.executor?.getOptions().rawResult) {
+            return baseResult?.rows || [];
+        }
         if (!baseResult || baseResult.rows.length === 0) {
             return [];
         }
+        // Result processing phase
+        tracer.startPhase('resultProcessing');
         // Group collection results by parent_id
-        const collectionResults = new Map();
-        collections.forEach((collection, idx) => {
-            const collectionResultSet = resultSets[2 + idx];
-            const dataMap = new Map();
-            for (const row of collectionResultSet.rows) {
-                const parentId = row.parent_id;
-                if (!dataMap.has(parentId)) {
-                    dataMap.set(parentId, []);
-                }
-                const { parent_id, ...rowData } = row;
-                dataMap.get(parentId).push(rowData);
-            }
-            collectionResults.set(collection.name, dataMap);
+        const collectionResults = tracer.trace('groupCollectionResults', () => {
+            const results = new Map();
+            collections.forEach((collection, idx) => {
+                const collectionResultSet = resultSets[2 + idx];
+                const dataMap = new Map();
+                for (const row of collectionResultSet.rows) {
+                    const parentId = row.parent_id;
+                    if (!dataMap.has(parentId)) {
+                        dataMap.set(parentId, []);
+                    }
+                    const { parent_id, ...rowData } = row;
+                    dataMap.get(parentId).push(rowData);
+                }
+                results.set(collection.name, dataMap);
+            });
+            return results;
         });
         // Merge base results with collection results
-        const mergedRows = baseResult.rows.map((baseRow) => {
+        const mergedRows = tracer.trace('mergeResults', () => baseResult.rows.map((baseRow) => {
             const merged = { ...baseRow };
             for (const collection of collections) {
                 const resultMap = collectionResults.get(collection.name);
@@ -1185,8 +1278,10 @@ class SelectQueryBuilder {
             }
             delete merged.__pk_id;
             return merged;
-        });
-        return this.transformResults(mergedRows, selectionResult);
+        }), { rowCount: baseResult.rows.length });
+        const transformed = tracer.trace('transformResults', () => this.transformResults(mergedRows, selectionResult), { rowCount: mergedRows.length });
+        tracer.endPhase();
+        return transformed;
     }
     /**
      * Detect collections in the selection result
@@ -1340,16 +1435,25 @@ class SelectQueryBuilder {
      */
     createMockRow() {
         const mock = {};
+        const tableAlias = this.schema.name;
         // Performance: Use pre-computed column name map if available
         const columnNameMap = getColumnNameMapForSchema(this.schema);
+        // Performance: Lazy-cache FieldRef objects
+        const fieldRefCache = {};
         // Add columns as FieldRef objects - type-safe with property name and database column name
         for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
-                get: () => ({
-                    __fieldName: colName,
-                    __dbColumnName: dbColumnName,
-                    __tableAlias: this.schema.name,
-                }),
+                get() {
+                    let cached = fieldRefCache[colName];
+                    if (!cached) {
+                        cached = fieldRefCache[colName] = {
+                            __fieldName: colName,
+                            __dbColumnName: dbColumnName,
+                            __tableAlias: tableAlias,
+                        };
+                    }
+                    return cached;
+                },
                 enumerable: true,
                 configurable: true,
             });
@@ -1365,13 +1469,22 @@ class SelectQueryBuilder {
             if (!mock[join.alias]) {
                 mock[join.alias] = {};
             }
+            // Lazy-cache for joined table
+            const joinFieldRefCache = {};
+            const joinAlias = join.alias;
             for (const [colName, dbColumnName] of joinColumnNameMap) {
                 Object.defineProperty(mock[join.alias], colName, {
-                    get: () => ({
-                        __fieldName: colName,
-                        __dbColumnName: dbColumnName,
-                        __tableAlias: join.alias,
-                    }),
+                    get() {
+                        let cached = joinFieldRefCache[colName];
+                        if (!cached) {
+                            cached = joinFieldRefCache[colName] = {
+                                __fieldName: colName,
+                                __dbColumnName: dbColumnName,
+                                __tableAlias: joinAlias,
+                            };
+                        }
+                        return cached;
+                    },
                     enumerable: true,
                     configurable: true,
                 });
@@ -2046,181 +2159,199 @@ class SelectQueryBuilder {
      * Transform database results
      */
     transformResults(rows, selection) {
+        if (rows.length === 0) {
+            return [];
+        }
         // Check if mappers are disabled for performance
         const disableMappers = this.executor?.getOptions().disableMappers ?? false;
-        // Pre-analyze selection structure once instead of per-row
-        // This avoids repeated Object.entries() calls and type checks
-        const selectionKeys = Object.keys(selection);
-        const selectionEntries = Object.entries(selection);
-        // Pre-cache navigation placeholders to avoid repeated checks
-        // Only cache actual navigation properties (arrays and getter-based navigation)
-        const navigationPlaceholders = {};
-        for (const [key, value] of selectionEntries) {
+        // Pre-analyze selection structure ONCE and categorize each field
+        // This moves all type checks out of the per-row loop
+        const schemaColumnCache = this.schema.columnMetadataCache;
+        const fieldConfigs = [];
+        // Single pass to categorize all fields
+        for (const key in selection) {
+            const value = selection[key];
+            // Check for navigation placeholders first (most common early exit)
             if (Array.isArray(value) && value.length === 0) {
-                navigationPlaceholders[key] = [];
+                fieldConfigs.push({ key, type: 0 /* FieldType.NAVIGATION */, value: [] });
+                continue;
             }
-            else if (value === undefined) {
-                navigationPlaceholders[key] = undefined;
+            if (value === undefined) {
+                fieldConfigs.push({ key, type: 0 /* FieldType.NAVIGATION */, value: undefined });
+                continue;
             }
-            else if (value && typeof value === 'object' && !('__dbColumnName' in value) && !('__fieldName' in value)) {
-                // Check if it's a navigation property mock (object with getters)
-                // Exclude FieldRef objects by checking for __fieldName
+            // Check for navigation property mocks (objects with getters)
+            // These are treated as SIMPLE because the actual value comes from json_build_object in the row
+            // The navigation mock is just a placeholder - actual data processing happens via FieldType.SIMPLE
+            if (value && typeof value === 'object' && !('__dbColumnName' in value) && !('__fieldName' in value) && !('__collectionResult' in value) && !('__isAggregationArray' in value)) {
                 const props = Object.getOwnPropertyNames(value);
                 if (props.length > 0) {
-                    const firstProp = props[0];
-                    const descriptor = Object.getOwnPropertyDescriptor(value, firstProp);
+                    const descriptor = Object.getOwnPropertyDescriptor(value, props[0]);
                     if (descriptor && descriptor.get) {
-                        navigationPlaceholders[key] = undefined;
+                        // Navigation mock - treat as simple, data will come from row via json_build_object
+                        // If row has no data, convertValue will return undefined
+                        fieldConfigs.push({ key, type: 8 /* FieldType.SIMPLE */, value });
+                        continue;
                     }
                 }
             }
-        }
-        // Pre-build column metadata cache to avoid repeated schema lookups
-        const columnMetadataCache = {};
-        if (!disableMappers) {
-            for (const [key, value] of selectionEntries) {
-                if (typeof value === 'object' && value !== null && '__fieldName' in value) {
+            // Collection types
+            if (value instanceof CollectionQueryBuilder || (value && typeof value === 'object' && '__collectionResult' in value)) {
+                const isScalarAgg = value instanceof CollectionQueryBuilder && value.isScalarAggregation();
+                if (isScalarAgg) {
+                    const aggregationType = value.getAggregationType();
+                    fieldConfigs.push({
+                        key,
+                        type: 1 /* FieldType.COLLECTION_SCALAR */,
+                        value,
+                        aggregationType
+                    });
+                }
+                else {
+                    const isArrayAgg = value && typeof value === 'object' && 'isArrayAggregation' in value && value.isArrayAggregation();
+                    if (isArrayAgg) {
+                        fieldConfigs.push({ key, type: 2 /* FieldType.COLLECTION_ARRAY */, value });
+                    }
+                    else {
+                        fieldConfigs.push({
+                            key,
+                            type: 3 /* FieldType.COLLECTION_JSON */,
+                            value,
+                            collectionBuilder: value instanceof CollectionQueryBuilder ? value : undefined
+                        });
+                    }
+                }
+                continue;
+            }
+            // CTE aggregation array
+            if (typeof value === 'object' && value !== null && '__isAggregationArray' in value && value.__isAggregationArray) {
+                fieldConfigs.push({
+                    key,
+                    type: 4 /* FieldType.CTE_AGGREGATION */,
+                    value,
+                    innerMetadata: value.__innerSelectionMetadata
+                });
+                continue;
+            }
+            // SqlFragment with mapper
+            if (typeof value === 'object' && value !== null && typeof value.getMapper === 'function') {
+                let mapper = disableMappers ? null : value.getMapper();
+                if (mapper && typeof mapper.getType === 'function') {
+                    mapper = mapper.getType();
+                }
+                if (mapper && typeof mapper.fromDriver === 'function') {
+                    fieldConfigs.push({ key, type: 5 /* FieldType.SQL_FRAGMENT_MAPPER */, value, mapper });
+                }
+                else {
+                    fieldConfigs.push({ key, type: 8 /* FieldType.SIMPLE */, value });
+                }
+                continue;
+            }
+            // FieldRef with potential mapper
+            if (typeof value === 'object' && value !== null && '__fieldName' in value) {
+                if (disableMappers) {
+                    fieldConfigs.push({ key, type: 7 /* FieldType.FIELD_REF_NO_MAPPER */, value });
+                }
+                else {
                     const fieldName = value.__fieldName;
-                    const column = this.schema.columns[fieldName];
-                    if (column) {
-                        const config = column.build();
-                        columnMetadataCache[key] = {
-                            hasMapper: !!config.mapper,
-                            mapper: config.mapper,
-                            config: config,
-                        };
+                    const cached = schemaColumnCache?.get(fieldName);
+                    if (cached && cached.hasMapper) {
+                        fieldConfigs.push({ key, type: 6 /* FieldType.FIELD_REF_MAPPER */, value, mapper: cached.mapper });
+                    }
+                    else if (cached) {
+                        fieldConfigs.push({ key, type: 7 /* FieldType.FIELD_REF_NO_MAPPER */, value });
+                    }
+                    else {
+                        // Not in schema - treat as simple value
+                        fieldConfigs.push({ key, type: 8 /* FieldType.SIMPLE */, value });
                     }
                 }
+                continue;
             }
+            // Default: simple value
+            fieldConfigs.push({ key, type: 8 /* FieldType.SIMPLE */, value });
         }
-        return rows.map(row => {
+        // Transform each row using pre-analyzed field configs
+        // Using while(i--) for maximum performance - decrement and compare to 0 is faster
+        const results = new Array(rows.length);
+        const configCount = fieldConfigs.length;
+        let rowIdx = rows.length;
+        while (rowIdx--) {
+            const row = rows[rowIdx];
             const result = {};
-            // Copy navigation placeholders without iteration
-            Object.assign(result, navigationPlaceholders);
-            // Then process actual data fields
-            for (const [key, value] of selectionEntries) {
-                // Skip if we already set this key as a navigation placeholder
-                // UNLESS there's actual data for this key in the row (e.g., from json_build_object)
-                if (key in result && (result[key] === undefined || Array.isArray(result[key])) && !(key in row && row[key] !== undefined && row[key] !== null)) {
+            let i = configCount;
+            // Process all fields using pre-computed types
+            while (i--) {
+                const config = fieldConfigs[i];
+                const key = config.key;
+                // Handle navigation placeholders separately
+                if (config.type === 0 /* FieldType.NAVIGATION */) {
+                    result[key] = config.value;
                     continue;
                 }
-                if (value instanceof CollectionQueryBuilder || (value && typeof value === 'object' && '__collectionResult' in value)) {
-                    // Check if this is a scalar aggregation (count, sum, max, min)
-                    const isScalarAgg = value instanceof CollectionQueryBuilder && value.isScalarAggregation();
-                    if (isScalarAgg) {
-                        // For scalar aggregations, return the value directly
-                        // For COUNT, convertValue will handle numeric conversion (NULL is already COALESCE'd to 0 in SQL)
-                        // For MAX/MIN/SUM, we want to keep NULL as null (not undefined)
-                        const aggregationType = value.getAggregationType();
-                        if (aggregationType === 'COUNT') {
-                            result[key] = this.convertValue(row[key]);
+                const rawValue = row[key];
+                switch (config.type) {
+                    case 1 /* FieldType.COLLECTION_SCALAR */: {
+                        if (config.aggregationType === 'COUNT') {
+                            result[key] = this.convertValue(rawValue);
                         }
                         else {
-                            // For MAX/MIN/SUM, preserve NULL and convert numeric strings to numbers
-                            const rawValue = row[key];
+                            // MAX/MIN/SUM: preserve NULL, convert numeric strings
                             if (rawValue === null) {
                                 result[key] = null;
                             }
                             else if (typeof rawValue === 'string' && NUMERIC_REGEX.test(rawValue)) {
-                                result[key] = Number(rawValue);
+                                result[key] = +rawValue;
                             }
                             else {
                                 result[key] = rawValue;
                             }
                         }
+                        break;
                     }
-                    else {
-                        // Check if this is a flattened array result (toNumberList/toStringList)
-                        const isArrayAgg = value && typeof value === 'object' && 'isArrayAggregation' in value && value.isArrayAggregation();
-                        if (isArrayAgg) {
-                            // For flattened arrays, PostgreSQL returns a native array - use it directly
-                            result[key] = row[key] || [];
+                    case 2 /* FieldType.COLLECTION_ARRAY */:
+                        result[key] = rawValue || [];
+                        break;
+                    case 3 /* FieldType.COLLECTION_JSON */: {
+                        const items = rawValue || [];
+                        if (config.collectionBuilder) {
+                            result[key] = this.transformCollectionItems(items, config.collectionBuilder);
                         }
                         else {
-                            // Parse JSON array from CTE (both CollectionQueryBuilder and CollectionResult are treated the same at runtime)
-                            const collectionItems = row[key] || [];
-                            // Apply fromDriver mappers to collection items if needed
-                            if (value instanceof CollectionQueryBuilder) {
-                                result[key] = this.transformCollectionItems(collectionItems, value);
-                            }
-                            else {
-                                result[key] = collectionItems;
-                            }
+                            result[key] = items;
                         }
+                        break;
                     }
-                }
-                else if (typeof value === 'object' && value !== null && '__isAggregationArray' in value && value.__isAggregationArray) {
-                    // CTE withAggregation array - apply mappers to items inside
-                    const collectionItems = row[key] || [];
-                    const innerMetadata = value.__innerSelectionMetadata;
-                    if (innerMetadata && !disableMappers) {
-                        result[key] = this.transformCteAggregationItems(collectionItems, innerMetadata);
-                    }
-                    else {
-                        result[key] = collectionItems;
-                    }
-                }
-                else if (typeof value === 'object' && value !== null && typeof value.getMapper === 'function') {
-                    // SqlFragment with custom mapper (check this BEFORE FieldRef to handle subquery/CTE fields with mappers)
-                    const rawValue = row[key];
-                    if (disableMappers) {
-                        // Skip mapper transformation for performance
-                        result[key] = this.convertValue(rawValue);
-                    }
-                    else {
-                        let mapper = value.getMapper();
-                        if (mapper && rawValue !== null && rawValue !== undefined) {
-                            // If mapper is a CustomTypeBuilder, get the actual type
-                            if (typeof mapper.getType === 'function') {
-                                mapper = mapper.getType();
-                            }
-                            // Apply the fromDriver transformation
-                            if (typeof mapper.fromDriver === 'function') {
-                                result[key] = mapper.fromDriver(rawValue);
-                            }
-                            else {
-                                // Fallback if fromDriver doesn't exist
-                                result[key] = this.convertValue(rawValue);
-                            }
-                        }
-                        else {
-                            // No mapper or null value - convert normally
-                            result[key] = this.convertValue(rawValue);
-                        }
-                    }
-                }
-                else if (typeof value === 'object' && value !== null && '__fieldName' in value) {
-                    // FieldRef object - check if it has a custom mapper
-                    const rawValue = row[key];
-                    if (disableMappers) {
-                        // Skip mapper transformation for performance
-                        result[key] = rawValue === null ? undefined : rawValue;
-                    }
-                    else {
-                        // Use pre-cached column metadata instead of repeated lookups
-                        const cached = columnMetadataCache[key];
-                        if (cached) {
-                            // Field is in our schema - use cached mapper info
-                            result[key] = rawValue === null
-                                ? undefined
-                                : (cached.hasMapper ? cached.mapper.fromDriver(rawValue) : rawValue);
+                    case 4 /* FieldType.CTE_AGGREGATION */: {
+                        const items = rawValue || [];
+                        if (config.innerMetadata && !disableMappers) {
+                            result[key] = this.transformCteAggregationItems(items, config.innerMetadata);
                         }
                         else {
-                            // Field not in schema (e.g., CTE field, joined table field)
-                            // Always call convertValue to handle numeric string conversion
-                            result[key] = this.convertValue(row[key]);
+                            result[key] = items;
                         }
+                        break;
                     }
-                }
-                else {
-                    // Convert null to undefined for all other values
-                    // Also convert numeric strings to numbers for scalar subqueries (PostgreSQL returns NUMERIC as string)
-                    const converted = this.convertValue(row[key]);
-                    result[key] = converted;
+                    case 5 /* FieldType.SQL_FRAGMENT_MAPPER */:
+                        // mapWith wraps user functions to handle null
+                        result[key] = config.mapper.fromDriver(rawValue);
+                        break;
+                    case 6 /* FieldType.FIELD_REF_MAPPER */:
+                        // Column mappers (customType) - null check done here
+                        result[key] = config.mapper.fromDriver(rawValue);
+                        break;
+                    case 7 /* FieldType.FIELD_REF_NO_MAPPER */:
+                        result[key] = rawValue;
+                        break;
+                    case 8 /* FieldType.SIMPLE */:
+                    default:
+                        result[key] = this.convertValue(rawValue);
+                        break;
                 }
             }
-            return result;
-        });
+            results[rowIdx] = result;
+        }
+        return results;
     }
     /**
      * Convert database values: null to undefined, numeric strings to numbers
@@ -2231,11 +2362,9 @@ class SelectQueryBuilder {
         }
         // Check if it's a numeric string (PostgreSQL NUMERIC type)
         // This handles scalar subqueries with aggregates like AVG, SUM, etc.
+        // The regex validates format, so Number() is guaranteed to produce a valid number
         if (typeof value === 'string' && NUMERIC_REGEX.test(value)) {
-            const num = Number(value);
-            if (!isNaN(num)) {
-                return num;
-            }
+            return +value; // Faster than Number(value)
         }
         return value;
     }
@@ -2253,24 +2382,47 @@ class SelectQueryBuilder {
             // Skip mapper transformation for performance - return items as-is
             return items;
         }
-        return items.map(item => {
+        // Use pre-cached column metadata from target schema
+        // This avoids repeated column.build() calls for each item
+        const columnCache = targetSchema.columnMetadataCache;
+        if (!columnCache || columnCache.size === 0) {
+            // Fallback for schemas without cache (shouldn't happen, but be safe)
+            return items.map(item => {
+                const transformedItem = {};
+                for (const [key, value] of Object.entries(item)) {
+                    const column = targetSchema.columns[key];
+                    if (column) {
+                        const config = column.build();
+                        transformedItem[key] = config.mapper
+                            ? config.mapper.fromDriver(value)
+                            : value;
+                    }
+                    else {
+                        transformedItem[key] = value;
+                    }
+                }
+                return transformedItem;
+            });
+        }
+        // Optimized path using cached metadata and while(i--) loop
+        const results = new Array(items.length);
+        let i = items.length;
+        while (i--) {
+            const item = items[i];
             const transformedItem = {};
-            for (const [key, value] of Object.entries(item)) {
-                // Find the column in target schema
-                const column = targetSchema.columns[key];
-                if (column) {
-                    const config = column.build();
-                    // Apply fromDriver mapper if present
-                    transformedItem[key] = config.mapper
-                        ? config.mapper.fromDriver(value)
-                        : value;
+            for (const key in item) {
+                const value = item[key];
+                const cached = columnCache.get(key);
+                if (cached && cached.hasMapper) {
+                    transformedItem[key] = cached.mapper.fromDriver(value);
                 }
                 else {
                     transformedItem[key] = value;
                 }
             }
-            return transformedItem;
-        });
+            results[i] = transformedItem;
+        }
+        return results;
     }
     /**
      * Transform CTE aggregation items applying fromDriver mappers from selection metadata
@@ -2279,9 +2431,12 @@ class SelectQueryBuilder {
         if (!items || items.length === 0) {
             return [];
         }
+        // Use pre-cached column metadata from schema
+        const schemaColumnCache = this.schema.columnMetadataCache;
         // Build mapper cache from selection metadata
         const mapperCache = {};
-        for (const [key, value] of Object.entries(selectionMetadata)) {
+        for (const key in selectionMetadata) {
+            const value = selectionMetadata[key];
             // Check if value has getMapper (SqlFragment or field with mapper)
             if (typeof value === 'object' && value !== null && typeof value.getMapper === 'function') {
                 let mapper = value.getMapper();
@@ -2296,29 +2451,45 @@ class SelectQueryBuilder {
             // Check if it's a FieldRef with schema column mapper
             else if (typeof value === 'object' && value !== null && '__fieldName' in value) {
                 const fieldName = value.__fieldName;
-                const column = this.schema.columns[fieldName];
-                if (column) {
-                    const config = column.build();
-                    if (config.mapper && typeof config.mapper.fromDriver === 'function') {
-                        mapperCache[key] = config.mapper;
+                // Use cached column metadata instead of column.build()
+                if (schemaColumnCache) {
+                    const cached = schemaColumnCache.get(fieldName);
+                    if (cached && cached.hasMapper && typeof cached.mapper.fromDriver === 'function') {
+                        mapperCache[key] = cached.mapper;
+                    }
+                }
+                else {
+                    // Fallback for schemas without cache
+                    const column = this.schema.columns[fieldName];
+                    if (column) {
+                        const config = column.build();
+                        if (config.mapper && typeof config.mapper.fromDriver === 'function') {
+                            mapperCache[key] = config.mapper;
+                        }
                     }
                 }
             }
         }
-        // Transform items
-        return items.map(item => {
+        // Transform items using while(i--) loop - decrement and compare to 0 is fastest
+        const results = new Array(items.length);
+        let i = items.length;
+        while (i--) {
+            const item = items[i];
             const transformedItem = {};
-            for (const [key, value] of Object.entries(item)) {
+            for (const key in item) {
+                const value = item[key];
                 const mapper = mapperCache[key];
-                if (mapper && value !== null && value !== undefined) {
+                // Mappers handle null internally (mapWith wraps user functions)
+                if (mapper) {
                     transformedItem[key] = mapper.fromDriver(value);
                 }
                 else {
                     transformedItem[key] = value;
                 }
             }
-            return transformedItem;
-        });
+            results[i] = transformedItem;
+        }
+        return results;
     }
     /**
      * Build aggregation query (MIN, MAX, SUM)
@@ -2564,13 +2735,22 @@ class ReferenceQueryBuilder {
             const mock = {};
             // Add columns - use pre-computed column name map if available
             const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
+            // Performance: Lazy-cache FieldRef objects
+            const fieldRefCache = {};
+            const tableAlias = this.relationName;
             for (const [colName, dbColumnName] of columnNameMap) {
                 Object.defineProperty(mock, colName, {
-                    get: () => ({
-                        __fieldName: colName,
-                        __dbColumnName: dbColumnName,
-                        __tableAlias: this.relationName, // Mark which table this belongs to
-                    }),
+                    get() {
+                        let cached = fieldRefCache[colName];
+                        if (!cached) {
+                            cached = fieldRefCache[colName] = {
+                                __fieldName: colName,
+                                __dbColumnName: dbColumnName,
+                                __tableAlias: tableAlias, // Mark which table this belongs to
+                            };
+                        }
+                        return cached;
+                    },
                     enumerable: true,
                     configurable: true,
                 });
@@ -2701,13 +2881,21 @@ class CollectionQueryBuilder {
             const mock = {};
             // Performance: Use pre-computed column name map if available
             const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
+            // Performance: Lazy-cache FieldRef objects
+            const fieldRefCache = {};
             // Add columns
             for (const [colName, dbColumnName] of columnNameMap) {
                 Object.defineProperty(mock, colName, {
-                    get: () => ({
-                        __fieldName: colName,
-                        __dbColumnName: dbColumnName,
-                    }),
+                    get() {
+                        let cached = fieldRefCache[colName];
+                        if (!cached) {
+                            cached = fieldRefCache[colName] = {
+                                __fieldName: colName,
+                                __dbColumnName: dbColumnName,
+                            };
+                        }
+                        return cached;
+                    },
                     enumerable: true,
                     configurable: true,
                 });
@@ -2998,8 +3186,10 @@ class CollectionQueryBuilder {
     resolveNavigationJoins(allTableAliases, joins, startSchema) {
         // Keep resolving until we've resolved all aliases or can't make progress
         let resolved = new Set();
-        let maxIterations = allTableAliases.size * 2; // Prevent infinite loops
-        while (resolved.size < allTableAliases.size && maxIterations-- > 0) {
+        let lastResolvedCount = -1;
+        let maxIterations = 100; // Prevent infinite loops
+        while (resolved.size < allTableAliases.size && resolved.size !== lastResolvedCount && maxIterations-- > 0) {
+            lastResolvedCount = resolved.size;
             // Build a map of already joined schemas for path resolution
             const joinedSchemas = new Map();
             joinedSchemas.set(this.targetTable, startSchema);
@@ -3018,19 +3208,80 @@ class CollectionQueryBuilder {
                     resolved.add(alias);
                     continue;
                 }
-                // Look for this alias in any of the already joined schemas
+                // First, look for this alias in any of the already joined schemas (direct lookup)
+                let found = false;
                 for (const [schemaAlias, schema] of joinedSchemas) {
                     if (schema.relations && schema.relations[alias]) {
                         const relation = schema.relations[alias];
                         if (relation.type === 'one') {
                             this.addNavigationJoin(alias, relation, joins, schemaAlias);
                             resolved.add(alias);
+                            found = true;
                             break;
                         }
                     }
                 }
+                // If not found directly, search transitively through all schemas in registry
+                // to find an intermediate path
+                if (!found && this.schemaRegistry) {
+                    const path = this.findNavigationPath(alias, joinedSchemas, startSchema);
+                    if (path.length > 0) {
+                        // Add all intermediate joins
+                        for (const step of path) {
+                            if (!joins.some(j => j.alias === step.alias)) {
+                                this.addNavigationJoin(step.alias, step.relation, joins, step.sourceAlias);
+                            }
+                        }
+                        resolved.add(alias);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Find a path from already-joined schemas to the target alias
+     * Uses BFS to find the shortest path through the schema graph
+     */
+    findNavigationPath(targetAlias, joinedSchemas, _startSchema) {
+        if (!this.schemaRegistry) {
+            return [];
+        }
+        // BFS to find path from any joined schema to the target alias
+        const queue = [];
+        // Start from all currently joined schemas
+        for (const [schemaAlias, schema] of joinedSchemas) {
+            queue.push({ schemaAlias, schema, path: [] });
+        }
+        const visited = new Set();
+        for (const [alias] of joinedSchemas) {
+            visited.add(alias);
+        }
+        while (queue.length > 0) {
+            const { schemaAlias, schema, path } = queue.shift();
+            if (!schema.relations) {
+                continue;
+            }
+            for (const [relName, relConfig] of Object.entries(schema.relations)) {
+                if (relConfig.type !== 'one') {
+                    continue; // Only follow reference (one-to-one/many-to-one) relations
+                }
+                if (visited.has(relName)) {
+                    continue;
+                }
+                const newPath = [...path, { alias: relName, relation: relConfig, sourceAlias: schemaAlias }];
+                // Found the target!
+                if (relName === targetAlias) {
+                    return newPath;
+                }
+                // Continue searching through this relation's schema
+                visited.add(relName);
+                const nextSchema = this.schemaRegistry.get(relConfig.targetTable);
+                if (nextSchema) {
+                    queue.push({ schemaAlias: relName, schema: nextSchema, path: newPath });
+                }
             }
         }
+        return []; // No path found
     }
     /**
      * Build CTE for this collection query
@@ -3065,6 +3316,50 @@ class CollectionQueryBuilder {
                 context.paramCounter = sqlBuildContext.paramCounter;
                 return { alias, expression: fragmentSql };
             }
+            else if (field instanceof CollectionQueryBuilder) {
+                // Nested collection query builder
+                // For temptable strategy, nested collections are not supported - need lateral/CTE
+                if (strategyType === 'temptable') {
+                    throw new Error(`Nested collections in temptable strategy are not supported. ` +
+                        `The field "${alias}" contains a nested collection query. ` +
+                        `Use collectionStrategy: 'lateral' or 'cte' for queries with nested collections.`);
+                }
+                // For lateral/CTE strategies, build the nested collection as a subquery
+                const nestedCtx = {
+                    ...context,
+                    cteCounter: context.cteCounter,
+                };
+                const nestedResult = field.buildCTE(nestedCtx, client);
+                context.cteCounter = nestedCtx.cteCounter;
+                // For CTE/LATERAL strategy, we need to track the nested join
+                // The nested aggregation needs to be joined in the outer collection's subquery
+                if (nestedResult.tableName) {
+                    let nestedJoinClause;
+                    if (nestedResult.isCTE) {
+                        // CTE strategy: join by parent_id
+                        // The join should be: this.targetTable.id = nestedCte.parent_id
+                        nestedJoinClause = `LEFT JOIN "${nestedResult.tableName}" ON "${this.targetTable}"."id" = "${nestedResult.tableName}".parent_id`;
+                    }
+                    else if (nestedResult.joinClause) {
+                        // LATERAL strategy: use the provided join clause (contains full LATERAL subquery)
+                        nestedJoinClause = nestedResult.joinClause;
+                    }
+                    else {
+                        // Fallback for other strategies
+                        nestedJoinClause = `LEFT JOIN "${nestedResult.tableName}" ON "${this.targetTable}"."id" = "${nestedResult.tableName}".parent_id`;
+                    }
+                    return {
+                        alias,
+                        expression: nestedResult.selectExpression || nestedResult.sql,
+                        nestedCteJoin: {
+                            cteName: nestedResult.tableName,
+                            joinClause: nestedJoinClause,
+                        },
+                    };
+                }
+                // The nested collection becomes a correlated subquery in SELECT
+                return { alias, expression: nestedResult.selectExpression || nestedResult.sql };
+            }
             else if (typeof field === 'object' && field !== null && '__dbColumnName' in field) {
                 // FieldRef object - use database column name with optional table alias
                 const dbColumnName = field.__dbColumnName;