linkgress-orm 0.1.0 → 0.1.2

package/dist/query/query-builder.js

@@ -1,12 +1,117 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectionQueryBuilder = exports.ReferenceQueryBuilder = exports.SelectQueryBuilder = exports.QueryBuilder = void 0;
+exports.getColumnNameMapForSchema = getColumnNameMapForSchema;
+exports.getRelationEntriesForSchema = getRelationEntriesForSchema;
+exports.getTargetSchemaForRelation = getTargetSchemaForRelation;
+exports.createNestedFieldRefProxy = createNestedFieldRefProxy;
 const conditions_1 = require("./conditions");
 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");
+/**
+ * Performance utility: Get column name map from schema, using cached version if available
+ */
+function getColumnNameMapForSchema(schema) {
+    if (schema.columnNameMap) {
+        return schema.columnNameMap;
+    }
+    // Fallback: build the map (for schemas that weren't built with the new TableBuilder)
+    const map = new Map();
+    for (const [colName, colBuilder] of Object.entries(schema.columns)) {
+        map.set(colName, colBuilder.build().name);
+    }
+    return map;
+}
+/**
+ * Performance utility: Get relation entries array from schema, using cached version if available
+ */
+function getRelationEntriesForSchema(schema) {
+    if (schema.relationEntries) {
+        return schema.relationEntries;
+    }
+    // Fallback: build the array (for schemas that weren't built with the new TableBuilder)
+    return Object.entries(schema.relations);
+}
+/**
+ * Performance utility: Get target schema for a relation, using cached version if available
+ */
+function getTargetSchemaForRelation(schema, relName, relConfig) {
+    // Try cached version first
+    if (schema.relationSchemaCache) {
+        const cached = schema.relationSchemaCache.get(relName);
+        if (cached)
+            return cached;
+    }
+    // Fallback: build the schema
+    if (relConfig.targetTableBuilder) {
+        return relConfig.targetTableBuilder.build();
+    }
+    return undefined;
+}
+// Performance: Cache nested field ref proxies per table alias
+const nestedFieldRefProxyCache = new Map();
+/**
+ * Creates a nested proxy that supports accessing properties at any depth.
+ * This allows patterns like `p.product.priceMode` to work even without full schema information.
+ * Each property access returns an object that is both a FieldRef and can be further accessed.
+ *
+ * @param tableAlias The table alias to use for the FieldRef
+ * @returns A proxy that creates FieldRefs for any property access
+ */
+function createNestedFieldRefProxy(tableAlias) {
+    // Return cached proxy if available
+    const cached = nestedFieldRefProxyCache.get(tableAlias);
+    if (cached)
+        return cached;
+    const handler = {
+        get: (_target, prop) => {
+            // Handle Symbol.toPrimitive for string conversion (used in template literals)
+            if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+                return () => `[NestedFieldRefProxy:${tableAlias}]`;
+            }
+            if (typeof prop === 'symbol')
+                return undefined;
+            // Return an object that is both a FieldRef AND a proxy for further nesting
+            const fieldRef = {
+                __fieldName: prop,
+                __dbColumnName: prop,
+                __tableAlias: tableAlias,
+            };
+            // Return a proxy that acts as both the FieldRef and allows further property access
+            return new Proxy(fieldRef, {
+                get: (fieldTarget, nestedProp) => {
+                    // Handle Symbol.toPrimitive for string conversion (used in template literals)
+                    if (nestedProp === Symbol.toPrimitive || nestedProp === 'toString' || nestedProp === 'valueOf') {
+                        return () => fieldTarget.__dbColumnName;
+                    }
+                    if (typeof nestedProp === 'symbol')
+                        return undefined;
+                    // If accessing FieldRef properties, return them
+                    if (nestedProp === '__fieldName' || nestedProp === '__dbColumnName' || nestedProp === '__tableAlias') {
+                        return fieldTarget[nestedProp];
+                    }
+                    // Otherwise, treat as nested navigation and create a new nested proxy
+                    // The nested table alias is the property name (e.g., 'product' for p.product)
+                    return createNestedFieldRefProxy(prop)[nestedProp];
+                },
+                has: (_fieldTarget, _nestedProp) => true,
+            });
+        },
+        has: (_target, prop) => {
+            // The outer proxy doesn't have FieldRef properties - only field names
+            if (prop === '__fieldName' || prop === '__dbColumnName' || prop === '__tableAlias') {
+                return false;
+            }
+            return true;
+        },
+    };
+    const proxy = new Proxy({}, handler);
+    nestedFieldRefProxyCache.set(tableAlias, proxy);
+    return proxy;
+}
 /**
  * Cached regex for numeric string detection
  * Used to convert PostgreSQL NUMERIC/BIGINT strings to numbers
@@ -16,7 +121,7 @@ const NUMERIC_REGEX = /^-?\d+(\.\d+)?$/;
  * Query builder for a table
  */
 class QueryBuilder {
-    constructor(schema, client, whereCond, limit, offset, orderBy, executor, manualJoins, joinCounter, collectionStrategy) {
+    constructor(schema, client, whereCond, limit, offset, orderBy, executor, manualJoins, joinCounter, collectionStrategy, schemaRegistry) {
         this.orderByFields = [];
         this.manualJoins = [];
         this.joinCounter = 0;
@@ -30,6 +135,7 @@ class QueryBuilder {
         this.manualJoins = manualJoins || [];
         this.joinCounter = joinCounter || 0;
         this.collectionStrategy = collectionStrategy;
+        this.schemaRegistry = schemaRegistry;
     }
     /**
      * Get qualified table name with schema prefix if specified
@@ -43,7 +149,7 @@ class QueryBuilder {
      */
     select(selector) {
         return new SelectQueryBuilder(this.schema, this.client, selector, this.whereCond, this.limitValue, this.offsetValue, this.orderByFields, this.executor, this.manualJoins, this.joinCounter, false, // isDistinct defaults to false
-        undefined, // schemaRegistry
+        this.schemaRegistry, // Pass schema registry for nested navigation resolution
         [], // ctes - start with empty array
         this.collectionStrategy);
     }
@@ -66,7 +172,8 @@ class QueryBuilder {
      * Add CTEs (Common Table Expressions) to the query
      */
     with(...ctes) {
-        return new SelectQueryBuilder(this.schema, this.client, (row) => row, this.whereCond, this.limitValue, this.offsetValue, this.orderByFields, this.executor, this.manualJoins, this.joinCounter, false, undefined, ctes, this.collectionStrategy);
+        return new SelectQueryBuilder(this.schema, this.client, (row) => row, this.whereCond, this.limitValue, this.offsetValue, this.orderByFields, this.executor, this.manualJoins, this.joinCounter, false, this.schemaRegistry, // Pass schema registry for nested navigation resolution
+        ctes, this.collectionStrategy);
     }
     /**
      * Create mock row for analysis
@@ -77,14 +184,10 @@ class QueryBuilder {
             return this._cachedMockRow;
         }
         const mock = {};
-        // Performance: Build column configs once and cache them
-        const columnEntries = Object.entries(this.schema.columns);
-        const columnConfigs = new Map();
-        for (const [colName, colBuilder] of columnEntries) {
-            columnConfigs.set(colName, colBuilder.build().name);
-        }
+        // Performance: Use pre-computed column name map if available
+        const columnNameMap = getColumnNameMapForSchema(this.schema);
         // Add columns as FieldRef objects - type-safe with property name and database column name
-        for (const [colName, dbColumnName] of columnConfigs) {
+        for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
                 get: () => ({
                     __fieldName: colName,
@@ -95,20 +198,20 @@ class QueryBuilder {
                 configurable: true,
             });
         }
-        // Performance: Cache target schemas for relations to avoid repeated .build() calls
-        const relationSchemas = new Map();
-        for (const [relName, relConfig] of Object.entries(this.schema.relations)) {
-            if (relConfig.targetTableBuilder) {
-                relationSchemas.set(relName, relConfig.targetTableBuilder.build());
-            }
-        }
+        // Performance: Use pre-computed relation entries and cached schemas
+        const relationEntries = getRelationEntriesForSchema(this.schema);
         // Add relations (both collections and single references)
-        for (const [relName, relConfig] of Object.entries(this.schema.relations)) {
+        for (const [relName, relConfig] of relationEntries) {
+            // Performance: Use cached target schema, but prefer registry lookup for full relations
+            let targetSchema = this.schemaRegistry?.get(relConfig.targetTable);
+            if (!targetSchema) {
+                targetSchema = getTargetSchemaForRelation(this.schema, relName, relConfig);
+            }
             if (relConfig.type === 'many') {
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
-                        return new CollectionQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKey || relConfig.foreignKeys?.[0] || '', this.schema.name, targetSchema);
+                        return new CollectionQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKey || relConfig.foreignKeys?.[0] || '', this.schema.name, targetSchema, this.schemaRegistry // Pass schema registry for nested navigation resolution
+                        );
                     },
                     enumerable: true,
                     configurable: true,
@@ -116,10 +219,10 @@ class QueryBuilder {
             }
             else {
                 // Single reference navigation (many-to-one, one-to-one)
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
-                        const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema);
+                        const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema, this.schemaRegistry // Pass schema registry for nested navigation resolution
+                        );
                         return refBuilder.createMockTargetRow();
                     },
                     enumerable: true,
@@ -234,14 +337,10 @@ class QueryBuilder {
      */
     createMockRowForTable(schema, alias) {
         const mock = {};
-        // Performance: Build column configs once and cache them
-        const columnEntries = Object.entries(schema.columns);
-        const columnConfigs = new Map();
-        for (const [colName, colBuilder] of columnEntries) {
-            columnConfigs.set(colName, colBuilder.build().name);
-        }
+        // Performance: Use pre-computed column name map if available
+        const columnNameMap = getColumnNameMapForSchema(schema);
         // Add columns as FieldRef objects with table alias
-        for (const [colName, dbColumnName] of columnConfigs) {
+        for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
                 get: () => ({
                     __fieldName: colName,
@@ -252,18 +351,14 @@ class QueryBuilder {
                 configurable: true,
             });
         }
-        // Performance: Cache target schemas for relations
-        const relationSchemas = new Map();
-        for (const [relName, relConfig] of Object.entries(schema.relations)) {
-            if (relConfig.targetTableBuilder) {
-                relationSchemas.set(relName, relConfig.targetTableBuilder.build());
-            }
-        }
+        // Performance: Use pre-computed relation entries and cached schemas
+        const relationEntries = getRelationEntriesForSchema(schema);
         // Add navigation properties (single references and collections)
-        for (const [relName, relConfig] of Object.entries(schema.relations)) {
+        for (const [relName, relConfig] of relationEntries) {
+            // Performance: Use cached target schema
+            const targetSchema = getTargetSchemaForRelation(schema, relName, relConfig);
             if (relConfig.type === 'many') {
                 // Collection navigation
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
                         return new CollectionQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKey || relConfig.foreignKeys?.[0] || '', schema.name, targetSchema);
@@ -274,7 +369,6 @@ class QueryBuilder {
             }
             else {
                 // Single reference navigation
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
                         const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema);
@@ -383,7 +477,12 @@ class SelectQueryBuilder {
      *   .toList();
      */
     with(...ctes) {
-        this.ctes.push(...ctes);
+        // Add CTEs, avoiding duplicates by name
+        for (const cte of ctes) {
+            if (!this.ctes.some(existing => existing.name === cte.name)) {
+                this.ctes.push(cte);
+            }
+        }
         return this;
     }
     /**
@@ -610,14 +709,10 @@ class SelectQueryBuilder {
      */
     createMockRowForTable(schema, alias) {
         const mock = {};
-        // Performance: Build column configs once and cache them
-        const columnEntries = Object.entries(schema.columns);
-        const columnConfigs = new Map();
-        for (const [colName, colBuilder] of columnEntries) {
-            columnConfigs.set(colName, colBuilder.build().name);
-        }
+        // Performance: Use pre-computed column name map if available
+        const columnNameMap = getColumnNameMapForSchema(schema);
         // Add columns as FieldRef objects with table alias
-        for (const [colName, dbColumnName] of columnConfigs) {
+        for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
                 get: () => ({
                     __fieldName: colName,
@@ -628,18 +723,14 @@ class SelectQueryBuilder {
                 configurable: true,
             });
         }
-        // Performance: Cache target schemas for relations
-        const relationSchemas = new Map();
-        for (const [relName, relConfig] of Object.entries(schema.relations)) {
-            if (relConfig.targetTableBuilder) {
-                relationSchemas.set(relName, relConfig.targetTableBuilder.build());
-            }
-        }
+        // Performance: Use pre-computed relation entries and cached schemas
+        const relationEntries = getRelationEntriesForSchema(schema);
         // Add navigation properties (single references and collections)
-        for (const [relName, relConfig] of Object.entries(schema.relations)) {
+        for (const [relName, relConfig] of relationEntries) {
+            // Performance: Use cached target schema
+            const targetSchema = getTargetSchemaForRelation(schema, relName, relConfig);
             if (relConfig.type === 'many') {
                 // Collection navigation
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
                         return new CollectionQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKey || relConfig.foreignKeys?.[0] || '', schema.name, targetSchema);
@@ -650,7 +741,6 @@ class SelectQueryBuilder {
             }
             else {
                 // Single reference navigation
-                const targetSchema = relationSchemas.get(relName);
                 Object.defineProperty(mock, relName, {
                     get: () => {
                         const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, targetSchema);
@@ -723,7 +813,7 @@ class SelectQueryBuilder {
             get(target, prop) {
                 if (typeof prop === 'symbol')
                     return undefined;
-                // If we have selection metadata, check if this property has a mapper
+                // If we have selection metadata, check if this property has a mapper or is an aggregation array
                 if (cte.selectionMetadata && prop in cte.selectionMetadata) {
                     const value = cte.selectionMetadata[prop];
                     // If it's a SqlFragment with a mapper, preserve it
@@ -736,6 +826,16 @@ class SelectQueryBuilder {
                             getMapper: () => value.getMapper(),
                         };
                     }
+                    // If it's a CTE aggregation array marker, preserve it with inner metadata
+                    if (typeof value === 'object' && value !== null && '__isAggregationArray' in value && value.__isAggregationArray) {
+                        return {
+                            __fieldName: prop,
+                            __dbColumnName: prop,
+                            __tableAlias: cte.name,
+                            __isAggregationArray: true,
+                            __innerSelectionMetadata: value.__innerSelectionMetadata,
+                        };
+                    }
                 }
                 // Return a regular FieldRef for any property accessed
                 return {
@@ -1238,9 +1338,10 @@ class SelectQueryBuilder {
      */
     createMockRow() {
         const mock = {};
+        // Performance: Use pre-computed column name map if available
+        const columnNameMap = getColumnNameMapForSchema(this.schema);
         // Add columns as FieldRef objects - type-safe with property name and database column name
-        for (const [colName, colBuilder] of Object.entries(this.schema.columns)) {
-            const dbColumnName = colBuilder.build().name;
+        for (const [colName, dbColumnName] of columnNameMap) {
             Object.defineProperty(mock, colName, {
                 get: () => ({
                     __fieldName: colName,
@@ -1257,13 +1358,12 @@ class SelectQueryBuilder {
             if (join.isSubquery || !join.schema) {
                 continue;
             }
-            for (const [colName, colBuilder] of Object.entries(join.schema.columns)) {
-                const dbColumnName = colBuilder.build().name;
-                // Create a unique property name by prefixing with table alias or using the column name directly
-                // For now, we'll create nested objects for each joined table
-                if (!mock[join.alias]) {
-                    mock[join.alias] = {};
-                }
+            // Performance: Use pre-computed column name map for joined schema
+            const joinColumnNameMap = getColumnNameMapForSchema(join.schema);
+            if (!mock[join.alias]) {
+                mock[join.alias] = {};
+            }
+            for (const [colName, dbColumnName] of joinColumnNameMap) {
                 Object.defineProperty(mock[join.alias], colName, {
                     get: () => ({
                         __fieldName: colName,
@@ -1275,15 +1375,18 @@ class SelectQueryBuilder {
                 });
             }
         }
+        // Performance: Use pre-computed relation entries
+        const relationEntries = getRelationEntriesForSchema(this.schema);
         // Add relations as CollectionQueryBuilder or ReferenceQueryBuilder
-        for (const [relName, relConfig] of Object.entries(this.schema.relations)) {
-            // Try to get target schema from registry (preferred, has full relations) or targetTableBuilder
+        for (const [relName, relConfig] of relationEntries) {
+            // Try to get target schema from registry (preferred, has full relations) or cached schema
             let targetSchema;
             if (this.schemaRegistry) {
                 targetSchema = this.schemaRegistry.get(relConfig.targetTable);
             }
-            if (!targetSchema && relConfig.targetTableBuilder) {
-                targetSchema = relConfig.targetTableBuilder.build();
+            if (!targetSchema) {
+                // Performance: Use cached target schema
+                targetSchema = getTargetSchemaForRelation(this.schema, relName, relConfig);
             }
             if (relConfig.type === 'many') {
                 Object.defineProperty(mock, relName, {
@@ -1376,40 +1479,142 @@ class SelectQueryBuilder {
     }
     /**
      * Detect navigation property references in selection and add necessary JOINs
+     * Supports multi-level navigation like task.level.createdBy
      */
     detectAndAddJoinsFromSelection(selection, joins) {
         if (!selection || typeof selection !== 'object') {
             return;
         }
-        for (const [key, value] of Object.entries(selection)) {
+        // First pass: collect all table aliases
+        const allTableAliases = new Set();
+        this.collectTableAliasesFromSelection(selection, allTableAliases);
+        // Second pass: resolve all joins through the schema graph
+        this.resolveJoinsForTableAliases(allTableAliases, joins);
+    }
+    /**
+     * Collect all table aliases from a selection
+     */
+    collectTableAliasesFromSelection(selection, allTableAliases) {
+        if (!selection || typeof selection !== 'object') {
+            return;
+        }
+        for (const [_key, value] of Object.entries(selection)) {
             if (value && typeof value === 'object' && '__tableAlias' in value && '__dbColumnName' in value) {
-                // This is a FieldRef with a table alias - check if it's from a related table
+                // This is a FieldRef with a table alias
                 const tableAlias = value.__tableAlias;
-                if (tableAlias !== this.schema.name && !joins.some(j => j.alias === tableAlias)) {
-                    // This references a related table - find the relation and add a JOIN
-                    const relation = this.schema.relations[tableAlias];
-                    if (relation && relation.type === 'one') {
-                        // Get target schema from targetTableBuilder if available
-                        let targetSchema;
-                        if (relation.targetTableBuilder) {
-                            const targetTableSchema = relation.targetTableBuilder.build();
-                            targetSchema = targetTableSchema.schema;
+                if (tableAlias && tableAlias !== this.schema.name) {
+                    allTableAliases.add(tableAlias);
+                }
+            }
+            else if (value instanceof conditions_1.SqlFragment) {
+                // SqlFragment may contain navigation property references
+                const fieldRefs = value.getFieldRefs();
+                for (const fieldRef of fieldRefs) {
+                    if ('__tableAlias' in fieldRef && fieldRef.__tableAlias) {
+                        const tableAlias = fieldRef.__tableAlias;
+                        if (tableAlias && tableAlias !== this.schema.name) {
+                            allTableAliases.add(tableAlias);
                         }
-                        // Add a JOIN for this reference
-                        joins.push({
-                            alias: tableAlias,
-                            targetTable: relation.targetTable,
-                            targetSchema,
-                            foreignKeys: relation.foreignKeys || [relation.foreignKey || ''],
-                            matches: relation.matches || [],
-                            isMandatory: relation.isMandatory ?? false,
-                        });
                     }
                 }
             }
-            else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            else if (value && typeof value === 'object' && !Array.isArray(value) && !(value instanceof CollectionQueryBuilder)) {
                 // Recursively check nested objects
-                this.detectAndAddJoinsFromSelection(value, joins);
+                this.collectTableAliasesFromSelection(value, allTableAliases);
+            }
+        }
+    }
+    /**
+     * Resolve all navigation joins by finding the correct path through the schema graph
+     * This handles multi-level navigation like task.level.createdBy
+     */
+    resolveJoinsForTableAliases(allTableAliases, joins) {
+        if (allTableAliases.size === 0) {
+            return;
+        }
+        // Keep resolving until we've resolved all aliases or can't make progress
+        const resolved = new Set();
+        let maxIterations = allTableAliases.size * 3; // Prevent infinite loops
+        while (resolved.size < allTableAliases.size && maxIterations-- > 0) {
+            // Build a map of already joined schemas for path resolution
+            const joinedSchemas = new Map();
+            joinedSchemas.set(this.schema.name, this.schema);
+            for (const join of joins) {
+                let schema;
+                if (this.schemaRegistry) {
+                    schema = this.schemaRegistry.get(join.targetTable);
+                }
+                if (schema) {
+                    joinedSchemas.set(join.alias, schema);
+                }
+            }
+            // Try to resolve each unresolved alias
+            for (const alias of allTableAliases) {
+                if (resolved.has(alias) || joins.some(j => j.alias === alias)) {
+                    resolved.add(alias);
+                    continue;
+                }
+                // Look for this alias in any of the already joined schemas
+                for (const [sourceAlias, schema] of joinedSchemas) {
+                    if (schema.relations && schema.relations[alias]) {
+                        const relation = schema.relations[alias];
+                        if (relation.type === 'one') {
+                            // Get target schema
+                            let targetSchema;
+                            let targetSchemaName;
+                            if (this.schemaRegistry) {
+                                targetSchema = this.schemaRegistry.get(relation.targetTable);
+                                targetSchemaName = targetSchema?.schema;
+                            }
+                            if (!targetSchema && relation.targetTableBuilder) {
+                                targetSchema = relation.targetTableBuilder.build();
+                                targetSchemaName = targetSchema?.schema;
+                            }
+                            joins.push({
+                                alias,
+                                targetTable: relation.targetTable,
+                                targetSchema: targetSchemaName,
+                                foreignKeys: relation.foreignKeys || [relation.foreignKey || ''],
+                                matches: relation.matches || ['id'],
+                                isMandatory: relation.isMandatory ?? false,
+                                sourceAlias, // Track where this join comes from
+                            });
+                            resolved.add(alias);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Add a JOIN for a FieldRef if it references a related table
+     * @deprecated Use detectAndAddJoinsFromSelection with multi-level resolution instead
+     */
+    addJoinForFieldRef(fieldRef, joins) {
+        if (!fieldRef || typeof fieldRef !== 'object' || !('__tableAlias' in fieldRef) || !('__dbColumnName' in fieldRef)) {
+            return;
+        }
+        const tableAlias = fieldRef.__tableAlias;
+        if (tableAlias && tableAlias !== this.schema.name && !joins.some(j => j.alias === tableAlias)) {
+            // This references a related table - find the relation and add a JOIN
+            const relation = this.schema.relations[tableAlias];
+            if (relation && relation.type === 'one') {
+                // Get target schema from targetTableBuilder if available
+                let targetSchema;
+                if (relation.targetTableBuilder) {
+                    const targetTableSchema = relation.targetTableBuilder.build();
+                    targetSchema = targetTableSchema.schema;
+                }
+                // Add a JOIN for this reference
+                joins.push({
+                    alias: tableAlias,
+                    targetTable: relation.targetTable,
+                    targetSchema,
+                    foreignKeys: relation.foreignKeys || [relation.foreignKey || ''],
+                    matches: relation.matches || [],
+                    isMandatory: relation.isMandatory ?? false,
+                });
             }
         }
     }
@@ -1420,35 +1625,19 @@ class SelectQueryBuilder {
         if (!condition) {
             return;
         }
-        // Get all field references from the condition
+        // Collect all table aliases from the condition
+        const allTableAliases = new Set();
         const fieldRefs = condition.getFieldRefs();
         for (const fieldRef of fieldRefs) {
             if ('__tableAlias' in fieldRef && fieldRef.__tableAlias) {
                 const tableAlias = fieldRef.__tableAlias;
-                // Check if this references a related table that isn't already joined
-                if (tableAlias !== this.schema.name && !joins.some(j => j.alias === tableAlias)) {
-                    // Find the relation config for this navigation
-                    const relation = this.schema.relations[tableAlias];
-                    if (relation && relation.type === 'one') {
-                        // Get target schema from targetTableBuilder if available
-                        let targetSchema;
-                        if (relation.targetTableBuilder) {
-                            const targetTableSchema = relation.targetTableBuilder.build();
-                            targetSchema = targetTableSchema.schema;
-                        }
-                        // Add a JOIN for this reference
-                        joins.push({
-                            alias: tableAlias,
-                            targetTable: relation.targetTable,
-                            targetSchema,
-                            foreignKeys: relation.foreignKeys || [relation.foreignKey || ''],
-                            matches: relation.matches || [],
-                            isMandatory: relation.isMandatory ?? false,
-                        });
-                    }
+                if (tableAlias !== this.schema.name) {
+                    allTableAliases.add(tableAlias);
                 }
             }
         }
+        // Resolve all joins through the schema graph
+        this.resolveJoinsForTableAliases(allTableAliases, joins);
     }
     /**
      * Build SQL query
@@ -1530,6 +1719,7 @@ class SelectQueryBuilder {
                     if ('__tableAlias' in value && value.__tableAlias && typeof value.__tableAlias === 'string') {
                         // This is a field from a joined table
                         const tableAlias = value.__tableAlias;
+                        const columnName = value.__dbColumnName;
                         // Find the relation config for this navigation
                         const relConfig = this.schema.relations[tableAlias];
                         if (relConfig) {
@@ -1551,7 +1741,15 @@ class SelectQueryBuilder {
                                 });
                             }
                         }
-                        selectParts.push(`"${tableAlias}"."${value.__dbColumnName}" as "${key}"`);
+                        // Check if this is a CTE aggregation column that needs COALESCE
+                        const cteJoin = this.manualJoins.find(j => j.cte && j.cte.name === tableAlias);
+                        if (cteJoin && cteJoin.cte && cteJoin.cte.isAggregationColumn(columnName)) {
+                            // CTE aggregation column - wrap with COALESCE to return empty array instead of null
+                            selectParts.push(`COALESCE("${tableAlias}"."${columnName}", '[]'::jsonb) as "${key}"`);
+                        }
+                        else {
+                            selectParts.push(`"${tableAlias}"."${columnName}" as "${key}"`);
+                        }
                     }
                     else {
                         // Regular field from the main table
@@ -1599,9 +1797,10 @@ class SelectQueryBuilder {
                                 // Select all columns from the target table and group them
                                 // We'll need to use JSON object building in SQL
                                 const fieldParts = [];
-                                for (const [colKey, col] of Object.entries(targetSchema.columns)) {
-                                    const config = col.build();
-                                    fieldParts.push(`'${colKey}', "${alias}"."${config.name}"`);
+                                // Performance: Use cached column name map
+                                const targetColMap = getColumnNameMapForSchema(targetSchema);
+                                for (const [colKey, dbColName] of targetColMap) {
+                                    fieldParts.push(`'${colKey}', "${alias}"."${dbColName}"`);
                                 }
                                 selectParts.push(`json_build_object(${fieldParts.join(', ')}) as "${key}"`);
                             }
@@ -1631,11 +1830,8 @@ class SelectQueryBuilder {
                                             const relConfig = this.schema.relations[alias];
                                             if (relConfig && relConfig.type === 'one') {
                                                 // This is a reference navigation - select all fields from the target table
-                                                // Find the target table schema
-                                                let targetSchema;
-                                                if (relConfig.targetTableBuilder) {
-                                                    targetSchema = relConfig.targetTableBuilder.build();
-                                                }
+                                                // Performance: Use cached target schema
+                                                const targetSchema = getTargetSchemaForRelation(this.schema, alias, relConfig);
                                                 if (targetSchema) {
                                                     // Add JOIN if not already added
                                                     if (!joins.find(j => j.alias === alias)) {
@@ -1654,9 +1850,10 @@ class SelectQueryBuilder {
                                                     }
                                                     // Select all columns from the target table and group them into a JSON object
                                                     const fieldParts = [];
-                                                    for (const [colKey, col] of Object.entries(targetSchema.columns)) {
-                                                        const config = col.build();
-                                                        fieldParts.push(`'${colKey}', "${alias}"."${config.name}"`);
+                                                    // Performance: Use cached column name map
+                                                    const targetColMap = getColumnNameMapForSchema(targetSchema);
+                                                    for (const [colKey, dbColName] of targetColMap) {
+                                                        fieldParts.push(`'${colKey}', "${alias}"."${dbColName}"`);
                                                     }
                                                     selectParts.push(`json_build_object(${fieldParts.join(', ')}) as "${key}"`);
                                                     continue;
@@ -1811,11 +2008,14 @@ class SelectQueryBuilder {
         for (const join of joins) {
             const joinType = join.isMandatory ? 'INNER JOIN' : 'LEFT JOIN';
             // Build ON clause for the join
+            // For multi-level navigation, use the sourceAlias (the intermediate table)
+            // For direct navigation, use the main table name
+            const sourceTable = join.sourceAlias || this.schema.name;
             const onConditions = [];
             for (let i = 0; i < join.foreignKeys.length; i++) {
                 const fk = join.foreignKeys[i];
                 const match = join.matches[i];
-                onConditions.push(`"${this.schema.name}"."${fk}" = "${join.alias}"."${match}"`);
+                onConditions.push(`"${sourceTable}"."${fk}" = "${join.alias}"."${match}"`);
             }
             // Use schema-qualified table name if schema is specified
             const joinTableName = this.getQualifiedTableName(join.targetTable, join.targetSchema);
@@ -1947,6 +2147,17 @@ class SelectQueryBuilder {
                         }
                     }
                 }
+                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];
@@ -2059,6 +2270,54 @@ class SelectQueryBuilder {
             return transformedItem;
         });
     }
+    /**
+     * Transform CTE aggregation items applying fromDriver mappers from selection metadata
+     */
+    transformCteAggregationItems(items, selectionMetadata) {
+        if (!items || items.length === 0) {
+            return [];
+        }
+        // Build mapper cache from selection metadata
+        const mapperCache = {};
+        for (const [key, value] of Object.entries(selectionMetadata)) {
+            // Check if value has getMapper (SqlFragment or field with mapper)
+            if (typeof value === 'object' && value !== null && typeof value.getMapper === 'function') {
+                let mapper = value.getMapper();
+                // If mapper is a CustomTypeBuilder, get the actual type
+                if (mapper && typeof mapper.getType === 'function') {
+                    mapper = mapper.getType();
+                }
+                if (mapper && typeof mapper.fromDriver === 'function') {
+                    mapperCache[key] = mapper;
+                }
+            }
+            // 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;
+                    }
+                }
+            }
+        }
+        // Transform items
+        return items.map(item => {
+            const transformedItem = {};
+            for (const [key, value] of Object.entries(item)) {
+                const mapper = mapperCache[key];
+                if (mapper && value !== null && value !== undefined) {
+                    transformedItem[key] = mapper.fromDriver(value);
+                }
+                else {
+                    transformedItem[key] = value;
+                }
+            }
+            return transformedItem;
+        });
+    }
     /**
      * Build aggregation query (MIN, MAX, SUM)
      */
@@ -2301,9 +2560,9 @@ class ReferenceQueryBuilder {
     createMockTargetRow() {
         if (this.targetTableSchema) {
             const mock = {};
-            // Add columns
-            for (const [colName, colBuilder] of Object.entries(this.targetTableSchema.columns)) {
-                const dbColumnName = colBuilder.build().name;
+            // Add columns - use pre-computed column name map if available
+            const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
+            for (const [colName, dbColumnName] of columnNameMap) {
                 Object.defineProperty(mock, colName, {
                     get: () => ({
                         __fieldName: colName,
@@ -2356,15 +2615,8 @@ class ReferenceQueryBuilder {
             return mock;
         }
         else {
-            // Fallback: generic proxy
-            const handler = {
-                get: (target, prop) => ({
-                    __fieldName: prop,
-                    __dbColumnName: prop,
-                    __tableAlias: this.relationName,
-                }),
-            };
-            return new Proxy({}, handler);
+            // Fallback: use the shared nested proxy that supports deep property access
+            return createNestedFieldRefProxy(this.relationName);
         }
     }
 }
@@ -2399,7 +2651,8 @@ class CollectionQueryBuilder {
      * Select specific fields from collection items
      */
     select(selector) {
-        const newBuilder = new CollectionQueryBuilder(this.relationName, this.targetTable, this.foreignKey, this.sourceTable, this.targetTableSchema);
+        const newBuilder = new CollectionQueryBuilder(this.relationName, this.targetTable, this.foreignKey, this.sourceTable, this.targetTableSchema, this.schemaRegistry // Pass schema registry for nested navigation resolution
+        );
         newBuilder.selector = selector;
         newBuilder.whereCond = this.whereCond;
         newBuilder.limitValue = this.limitValue;
@@ -2444,14 +2697,10 @@ class CollectionQueryBuilder {
         if (this.targetTableSchema) {
             // If we have schema information, create a properly typed mock
             const mock = {};
-            // Performance: Build column configs once and cache them
-            const columnEntries = Object.entries(this.targetTableSchema.columns);
-            const columnConfigs = new Map();
-            for (const [colName, colBuilder] of columnEntries) {
-                columnConfigs.set(colName, colBuilder.build().name);
-            }
+            // Performance: Use pre-computed column name map if available
+            const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
             // Add columns
-            for (const [colName, dbColumnName] of columnConfigs) {
+            for (const [colName, dbColumnName] of columnNameMap) {
                 Object.defineProperty(mock, colName, {
                     get: () => ({
                         __fieldName: colName,
@@ -2500,14 +2749,8 @@ class CollectionQueryBuilder {
             return mock;
         }
         else {
-            // Fallback: generic proxy (don't cache as it's dynamic)
-            const handler = {
-                get: (target, prop) => ({
-                    __fieldName: prop,
-                    __dbColumnName: prop,
-                }),
-            };
-            return new Proxy({}, handler);
+            // Fallback: use the shared nested proxy that supports deep property access
+            return createNestedFieldRefProxy(this.targetTable);
         }
     }
     /**
@@ -2642,6 +2885,151 @@ class CollectionQueryBuilder {
     getFlattenResultType() {
         return this.flattenResultType;
     }
+    /**
+     * Detect navigation property references in the selected fields and add necessary JOINs
+     * This supports multi-level navigation like p.task.level.createdBy.username
+     */
+    detectNavigationJoins(selection, joins, currentSourceAlias, currentSchema) {
+        if (!selection || typeof selection !== 'object') {
+            return;
+        }
+        // Collect all table aliases referenced in the selection
+        const allTableAliases = new Set();
+        // Helper to collect from a single selection
+        const collectFromSelection = (sel) => {
+            if (!sel || typeof sel !== 'object') {
+                return;
+            }
+            // Handle single FieldRef
+            if ('__tableAlias' in sel && '__dbColumnName' in sel) {
+                this.addNavigationJoinForFieldRef(sel, joins, currentSourceAlias, currentSchema, allTableAliases);
+                return;
+            }
+            // Handle object with multiple fields
+            for (const [_key, value] of Object.entries(sel)) {
+                if (value && typeof value === 'object' && '__tableAlias' in value && '__dbColumnName' in value) {
+                    // This is a FieldRef with a table alias
+                    this.addNavigationJoinForFieldRef(value, joins, currentSourceAlias, currentSchema, allTableAliases);
+                }
+                else if (value instanceof conditions_1.SqlFragment) {
+                    // SqlFragment may contain navigation property references
+                    const fieldRefs = value.getFieldRefs();
+                    for (const fieldRef of fieldRefs) {
+                        this.addNavigationJoinForFieldRef(fieldRef, joins, currentSourceAlias, currentSchema, allTableAliases);
+                    }
+                }
+                else if (value && typeof value === 'object' && !Array.isArray(value) && !(value instanceof CollectionQueryBuilder)) {
+                    // Recursively check nested objects
+                    collectFromSelection(value);
+                }
+            }
+        };
+        // First pass: collect all table aliases
+        collectFromSelection(selection);
+        // Second pass: resolve all navigation joins by finding the correct path through schemas
+        if (allTableAliases.size > 0) {
+            this.resolveNavigationJoins(allTableAliases, joins, currentSchema);
+        }
+    }
+    /**
+     * Add a navigation JOIN for a FieldRef if it references a related table
+     * Handles multi-level navigation by recursively resolving the join chain
+     */
+    addNavigationJoinForFieldRef(fieldRef, joins, sourceAlias, sourceSchema, allTableAliases) {
+        if (!fieldRef || typeof fieldRef !== 'object' || !('__tableAlias' in fieldRef)) {
+            return;
+        }
+        const tableAlias = fieldRef.__tableAlias;
+        // If this references the target table directly, no join needed
+        if (!tableAlias || tableAlias === this.targetTable) {
+            return;
+        }
+        // Collect this table alias for later resolution
+        allTableAliases.add(tableAlias);
+        // Check if we already have this join
+        if (joins.some(j => j.alias === tableAlias)) {
+            return;
+        }
+        // Find the relation in the current schema
+        const relation = sourceSchema.relations?.[tableAlias];
+        if (relation && relation.type === 'one') {
+            this.addNavigationJoin(tableAlias, relation, joins, sourceAlias);
+        }
+    }
+    /**
+     * Add a navigation join and return the target schema
+     */
+    addNavigationJoin(alias, relation, joins, sourceAlias) {
+        // Check if already added
+        if (joins.some(j => j.alias === alias)) {
+            return undefined;
+        }
+        // Get the target table schema
+        let targetSchema;
+        let targetSchemaName;
+        if (this.schemaRegistry) {
+            targetSchema = this.schemaRegistry.get(relation.targetTable);
+            targetSchemaName = targetSchema?.schema;
+        }
+        if (!targetSchema && relation.targetTableBuilder) {
+            targetSchema = relation.targetTableBuilder.build();
+            targetSchemaName = targetSchema?.schema;
+        }
+        // Build the join info
+        const foreignKeys = relation.foreignKeys || [relation.foreignKey || ''];
+        const matches = relation.matches || ['id']; // Default to 'id' as the PK
+        joins.push({
+            alias,
+            targetTable: relation.targetTable,
+            targetSchema: targetSchemaName,
+            foreignKeys,
+            matches,
+            isMandatory: relation.isMandatory ?? false,
+            sourceAlias,
+        });
+        return targetSchema;
+    }
+    /**
+     * Resolve all navigation joins by finding the correct path through the schema graph
+     * This handles multi-level navigation like task.level.createdBy
+     */
+    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) {
+            // Build a map of already joined schemas for path resolution
+            const joinedSchemas = new Map();
+            joinedSchemas.set(this.targetTable, startSchema);
+            for (const join of joins) {
+                let schema;
+                if (this.schemaRegistry) {
+                    schema = this.schemaRegistry.get(join.targetTable);
+                }
+                if (schema) {
+                    joinedSchemas.set(join.alias, schema);
+                }
+            }
+            // Try to resolve each unresolved alias
+            for (const alias of allTableAliases) {
+                if (resolved.has(alias) || joins.some(j => j.alias === alias)) {
+                    resolved.add(alias);
+                    continue;
+                }
+                // Look for this alias in any of the already joined schemas
+                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);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
     /**
      * Build CTE for this collection query
      * Now delegates to collection strategy pattern
@@ -2676,8 +3064,13 @@ class CollectionQueryBuilder {
                 return { alias, expression: fragmentSql };
             }
             else if (typeof field === 'object' && field !== null && '__dbColumnName' in field) {
-                // FieldRef object - use database column name
+                // FieldRef object - use database column name with optional table alias
                 const dbColumnName = field.__dbColumnName;
+                const tableAlias = field.__tableAlias;
+                // If tableAlias differs from the target table, it's a navigation property reference
+                if (tableAlias && tableAlias !== this.targetTable) {
+                    return { alias, expression: `"${tableAlias}"."${dbColumnName}"` };
+                }
                 return { alias, expression: `"${dbColumnName}"` };
             }
             else if (typeof field === 'string') {
@@ -2724,9 +3117,9 @@ class CollectionQueryBuilder {
         else {
             // No selector - select all fields from the target table schema
             if (this.targetTableSchema && this.targetTableSchema.columns) {
-                for (const [colName, colBuilder] of Object.entries(this.targetTableSchema.columns)) {
-                    const colConfig = colBuilder.build ? colBuilder.build() : colBuilder;
-                    const dbColumnName = colConfig.name || colName;
+                // Performance: Use cached column name map
+                const colNameMap = getColumnNameMapForSchema(this.targetTableSchema);
+                for (const [colName, dbColumnName] of colNameMap) {
                     selectedFieldConfigs.push({
                         alias: colName,
                         expression: `"${dbColumnName}"`,
@@ -2756,13 +3149,11 @@ class CollectionQueryBuilder {
         // Step 3: Build ORDER BY clause SQL (without ORDER BY keyword)
         let orderByClause;
         if (this.orderByFields.length > 0) {
+            // Performance: Pre-compute column name map for ORDER BY lookups
+            const colNameMap = this.targetTableSchema ? getColumnNameMapForSchema(this.targetTableSchema) : null;
             const orderParts = this.orderByFields.map(({ field, direction }) => {
-                // Look up the database column name from the schema if available
-                let dbColumnName = field;
-                if (this.targetTableSchema && this.targetTableSchema.columns[field]) {
-                    const colBuilder = this.targetTableSchema.columns[field];
-                    dbColumnName = colBuilder.build().name;
-                }
+                // Look up the database column name from the cached map if available
+                const dbColumnName = colNameMap?.get(field) ?? field;
                 return `"${dbColumnName}" ${direction}`;
             });
             orderByClause = orderParts.join(', ');
@@ -2802,7 +3193,14 @@ class CollectionQueryBuilder {
             aggregationType = 'jsonb';
             defaultValue = "'[]'::jsonb";
         }
-        // Step 5: Build CollectionAggregationConfig object
+        // Step 5: Detect navigation joins from the selected fields
+        const navigationJoins = [];
+        if (this.selector && this.targetTableSchema) {
+            const mockItem = this.createMockItem();
+            const selectedFields = this.selector(mockItem);
+            this.detectNavigationJoins(selectedFields, navigationJoins, this.targetTable, this.targetTableSchema);
+        }
+        // Step 6: Build CollectionAggregationConfig object
         const config = {
             relationName: this.relationName,
             targetTable: this.targetTable,
@@ -2821,6 +3219,7 @@ class CollectionQueryBuilder {
             arrayField,
             defaultValue,
             counter: context.cteCounter++,
+            navigationJoins: navigationJoins.length > 0 ? navigationJoins : undefined,
         };
         // Step 6: Call the strategy
         const result = strategy.buildAggregation(config, context, client);