linkgress-orm 0.2.1 → 0.2.3

package/dist/query/query-builder.js

@@ -6,6 +6,7 @@ exports.getRelationEntriesForSchema = getRelationEntriesForSchema;
 exports.getTargetSchemaForRelation = getTargetSchemaForRelation;
 exports.createNestedFieldRefProxy = createNestedFieldRefProxy;
 const conditions_1 = require("./conditions");
+const prepared_query_1 = require("./prepared-query");
 const db_context_1 = require("../entity/db-context");
 const query_utils_1 = require("./query-utils");
 const subquery_1 = require("./subquery");
@@ -1200,7 +1201,28 @@ class SelectQueryBuilder {
             for (const collection of collections) {
                 const resultMap = collectionResults.get(collection.name);
                 const parentId = baseRow.__pk_id;
-                const collectionData = resultMap?.get(parentId) || this.getDefaultValueForCollection(collection.builder);
+                const rawData = resultMap?.get(parentId);
+                // Check if this is a single result (firstOrDefault) - return first item or null
+                const isSingleResult = collection.builder.isSingleResult();
+                let collectionData;
+                if (isSingleResult) {
+                    // For single results, rawData might already be an object (from temp table strategy)
+                    // or might be an array (from other strategies) that we need to extract the first item from
+                    if (rawData === undefined || rawData === null) {
+                        collectionData = null;
+                    }
+                    else if (Array.isArray(rawData)) {
+                        collectionData = rawData.length > 0 ? rawData[0] : null;
+                    }
+                    else {
+                        // Already a single object
+                        collectionData = rawData;
+                    }
+                }
+                else {
+                    // For list results, ensure we return an array
+                    collectionData = rawData || this.getDefaultValueForCollection(collection.builder);
+                }
                 // Handle nested paths
                 if (collection.path.length > 0) {
                     // Navigate to the nested object and set the collection there
@@ -1348,7 +1370,28 @@ class SelectQueryBuilder {
             for (const collection of collections) {
                 const resultMap = collectionResults.get(collection.name);
                 const parentId = baseRow.__pk_id;
-                const collectionData = resultMap?.get(parentId) || [];
+                const rawData = resultMap?.get(parentId);
+                // Check if this is a single result (firstOrDefault) - return first item or null
+                const isSingleResult = collection.builder.isSingleResult();
+                let collectionData;
+                if (isSingleResult) {
+                    // For single results, rawData might already be an object (from temp table strategy)
+                    // or might be an array (from other strategies) that we need to extract the first item from
+                    if (rawData === undefined || rawData === null) {
+                        collectionData = null;
+                    }
+                    else if (Array.isArray(rawData)) {
+                        collectionData = rawData.length > 0 ? rawData[0] : null;
+                    }
+                    else {
+                        // Already a single object
+                        collectionData = rawData;
+                    }
+                }
+                else {
+                    // For list results, ensure we return an array
+                    collectionData = rawData || [];
+                }
                 // Handle nested paths
                 if (collection.path.length > 0) {
                     // Navigate to the nested object and set the collection there
@@ -1577,6 +1620,74 @@ class SelectQueryBuilder {
         }
         return result;
     }
+    /**
+     * Create a prepared query for efficient reusable parameterized execution.
+     *
+     * Prepared queries build the SQL once and allow multiple executions
+     * with different parameter values. This is useful for:
+     * 1. Query building optimization - Build SQL once, execute many times
+     * 2. Type-safe placeholders - Named parameters with validation
+     * 3. Developer ergonomics - Cleaner API for reusable queries
+     *
+     * @param name - A name for the prepared query (for debugging)
+     * @returns PreparedQuery that can be executed multiple times with different parameters
+     *
+     * @example
+     * ```typescript
+     * // Create a prepared query with a placeholder
+     * const getUserById = db.users
+     *   .where(u => eq(u.id, sql.placeholder('userId')))
+     *   .prepare('getUserById');
+     *
+     * // Execute multiple times with different values
+     * const user1 = await getUserById.execute({ userId: 10 });
+     * const user2 = await getUserById.execute({ userId: 20 });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple placeholders
+     * const searchUsers = db.users
+     *   .where(u => and(
+     *     gt(u.age, sql.placeholder('minAge')),
+     *     like(u.name, sql.placeholder('namePattern'))
+     *   ))
+     *   .prepare('searchUsers');
+     *
+     * await searchUsers.execute({ minAge: 18, namePattern: '%john%' });
+     * ```
+     */
+    prepare(name) {
+        // Build query with placeholder tracking
+        const context = {
+            ctes: new Map(),
+            cteCounter: 0,
+            paramCounter: 1,
+            allParams: [],
+            placeholders: new Map(),
+            collectionStrategy: this.collectionStrategy,
+            executor: this.executor,
+        };
+        // Analyze the selector to extract nested queries
+        const mockRow = this._createMockRow();
+        const selectionResult = this.selector(mockRow);
+        // Build the query - this populates context.placeholders
+        const { sql, nestedPaths } = this.buildQuery(selectionResult, context);
+        // Create transform function (closure over schema, selection, nestedPaths)
+        const transformFn = (rows) => {
+            // If rawResult is enabled, return raw rows without any processing
+            if (this.executor?.getOptions().rawResult) {
+                return rows;
+            }
+            // Reconstruct nested objects from flat row data (if any)
+            if (nestedPaths.size > 0) {
+                rows = rows.map(row => this.reconstructNestedObjects(row, nestedPaths));
+            }
+            // Transform results
+            return this.transformResults(rows, selectionResult);
+        };
+        return new prepared_query_1.PreparedQuery(sql, context.placeholders || new Map(), context.paramCounter - 1, this.client, transformFn, name);
+    }
     /**
      * Delete records matching the current WHERE condition
      * Returns a fluent builder that can be awaited directly or chained with .returning()
@@ -2702,10 +2813,14 @@ class SelectQueryBuilder {
         let whereClause = '';
         if (this.whereCond) {
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql, params } = condBuilder.build(this.whereCond, context.paramCounter);
+            const { sql, params, placeholders, paramCounter: newParamCounter } = condBuilder.build(this.whereCond, context.paramCounter, context.placeholders);
             whereClause = `WHERE ${sql}`;
-            context.paramCounter += params.length;
+            context.paramCounter = newParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...params);
+            // Update placeholders from the condition builder (for prepared statements)
+            if (placeholders) {
+                context.placeholders = placeholders;
+            }
         }
         // Build ORDER BY clause
         let orderByClause = '';
@@ -2761,9 +2876,12 @@ class SelectQueryBuilder {
             const joinTypeStr = manualJoin.type === 'INNER' ? 'INNER JOIN' : 'LEFT JOIN';
             // Build ON condition
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql: condSql, params: condParams } = condBuilder.build(manualJoin.condition, context.paramCounter);
-            context.paramCounter += condParams.length;
+            const { sql: condSql, params: condParams, placeholders: joinPlaceholders, paramCounter: newParamCounter } = condBuilder.build(manualJoin.condition, context.paramCounter, context.placeholders);
+            context.paramCounter = newParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...condParams);
+            if (joinPlaceholders) {
+                context.placeholders = joinPlaceholders;
+            }
             // Check if this is a CTE join
             if (manualJoin.cte) {
                 // Join with CTE - use CTE name directly
@@ -2998,14 +3116,18 @@ class SelectQueryBuilder {
                         break;
                     }
                     case 9 /* FieldType.COLLECTION_SINGLE */: {
-                        // firstOrDefault() - return first item or null
-                        const items = rawValue || [];
-                        if (config.collectionBuilder && items.length > 0) {
-                            const transformedItems = this.transformCollectionItems(items, config.collectionBuilder);
+                        // firstOrDefault() - return single object or null
+                        // With CTE/LATERAL single result, rawValue is already a single object (not array)
+                        if (rawValue === null || rawValue === undefined) {
+                            result[key] = null;
+                        }
+                        else if (config.collectionBuilder) {
+                            // Transform the single item using collection mapper if available
+                            const transformedItems = this.transformCollectionItems([rawValue], config.collectionBuilder);
                             result[key] = transformedItems[0] ?? null;
                         }
                         else {
-                            result[key] = items[0] ?? null;
+                            result[key] = rawValue;
                         }
                         break;
                     }
@@ -3123,6 +3245,18 @@ class SelectQueryBuilder {
                 }
             }
         }
+        // Build cache of nested collection info (fields that are themselves nested collections)
+        // This is used for recursive transformation of nested collection results
+        const nestedCollectionCache = new Map();
+        if (selectedFieldConfigs) {
+            for (const field of selectedFieldConfigs) {
+                if (field.nestedCollectionInfo) {
+                    nestedCollectionCache.set(field.alias, field.nestedCollectionInfo);
+                }
+            }
+        }
+        // Get schema registry for nested collection transformation
+        const schemaRegistry = collectionBuilder.getSchemaRegistry() || this.schemaRegistry;
         // Transform items using pre-built mapper cache
         const results = new Array(items.length);
         let i = items.length;
@@ -3136,13 +3270,114 @@ class SelectQueryBuilder {
                     transformedItem[key] = mapper.fromDriver(value);
                 }
                 else {
-                    transformedItem[key] = value;
+                    // Check if this field is a nested collection that needs recursive transformation
+                    const nestedInfo = nestedCollectionCache.get(key);
+                    if (nestedInfo && value !== null && value !== undefined && schemaRegistry) {
+                        transformedItem[key] = this.transformNestedCollectionValue(value, nestedInfo, schemaRegistry);
+                    }
+                    else {
+                        transformedItem[key] = value;
+                    }
                 }
             }
             results[i] = transformedItem;
         }
         return results;
     }
+    /**
+     * Transform a nested collection value (from firstOrDefault or toList inside another collection)
+     * Applies custom mappers to fields within the nested collection result.
+     */
+    transformNestedCollectionValue(value, nestedInfo, schemaRegistry) {
+        const nestedSchema = schemaRegistry.get(nestedInfo.targetTable);
+        if (!nestedSchema?.columnMetadataCache) {
+            return value; // No schema info, return as-is
+        }
+        const columnCache = nestedSchema.columnMetadataCache;
+        const selectedFieldConfigs = nestedInfo.selectedFieldConfigs;
+        // Build mapper cache for nested collection fields
+        const mapperCache = new Map();
+        // First, add mappers from selected field configs (for aliased/navigation fields)
+        if (selectedFieldConfigs) {
+            for (const field of selectedFieldConfigs) {
+                if (field.propertyName) {
+                    let mapper = null;
+                    if (field.sourceTable) {
+                        // Navigation field - look up from source table's schema
+                        const navSchema = schemaRegistry.get(field.sourceTable);
+                        if (navSchema?.columnMetadataCache) {
+                            const cached = navSchema.columnMetadataCache.get(field.propertyName);
+                            if (cached?.hasMapper) {
+                                mapper = cached.mapper;
+                            }
+                        }
+                    }
+                    else {
+                        // Regular field from target schema
+                        const cached = columnCache.get(field.propertyName);
+                        if (cached?.hasMapper) {
+                            mapper = cached.mapper;
+                        }
+                    }
+                    if (mapper) {
+                        mapperCache.set(field.alias, mapper);
+                    }
+                }
+            }
+        }
+        // Also add direct property matches from target schema
+        for (const [propertyName, cached] of columnCache) {
+            if (!mapperCache.has(propertyName) && cached.hasMapper) {
+                mapperCache.set(propertyName, cached.mapper);
+            }
+        }
+        // Build cache for any deeply nested collections
+        const deeplyNestedCache = new Map();
+        if (selectedFieldConfigs) {
+            for (const field of selectedFieldConfigs) {
+                if (field.nestedCollectionInfo) {
+                    deeplyNestedCache.set(field.alias, field.nestedCollectionInfo);
+                }
+            }
+        }
+        // Transform the value(s)
+        const transformItem = (item) => {
+            if (item === null || item === undefined) {
+                return item;
+            }
+            const transformedItem = {};
+            for (const key in item) {
+                const fieldValue = item[key];
+                const mapper = mapperCache.get(key);
+                if (mapper) {
+                    transformedItem[key] = mapper.fromDriver(fieldValue);
+                }
+                else {
+                    // Check for deeply nested collections
+                    const deepNestedInfo = deeplyNestedCache.get(key);
+                    if (deepNestedInfo && fieldValue !== null && fieldValue !== undefined) {
+                        transformedItem[key] = this.transformNestedCollectionValue(fieldValue, deepNestedInfo, schemaRegistry);
+                    }
+                    else {
+                        transformedItem[key] = fieldValue;
+                    }
+                }
+            }
+            return transformedItem;
+        };
+        if (nestedInfo.isSingleResult) {
+            // Single item (firstOrDefault)
+            return transformItem(value);
+        }
+        else if (Array.isArray(value)) {
+            // Array of items (toList)
+            return value.map(transformItem);
+        }
+        else {
+            // Single object that should be treated as single result
+            return transformItem(value);
+        }
+    }
     /**
      * Transform CTE aggregation items applying fromDriver mappers from selection metadata
      */
@@ -3233,10 +3468,13 @@ class SelectQueryBuilder {
         let whereClause = '';
         if (this.whereCond) {
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql, params } = condBuilder.build(this.whereCond, context.paramCounter);
+            const { sql, params, placeholders, paramCounter: newParamCounter } = condBuilder.build(this.whereCond, context.paramCounter, context.placeholders);
             whereClause = `WHERE ${sql}`;
-            context.paramCounter += params.length;
+            context.paramCounter = newParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...params);
+            if (placeholders) {
+                context.placeholders = placeholders;
+            }
         }
         // Build FROM clause with JOINs
         let fromClause = `FROM "${this.schema.name}"`;
@@ -3244,9 +3482,12 @@ class SelectQueryBuilder {
         for (const manualJoin of this.manualJoins) {
             const joinTypeStr = manualJoin.type === 'INNER' ? 'INNER JOIN' : 'LEFT JOIN';
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql: condSql, params: condParams } = condBuilder.build(manualJoin.condition, context.paramCounter);
-            context.paramCounter += condParams.length;
+            const { sql: condSql, params: condParams, placeholders: joinPlaceholders, paramCounter: newJoinParamCounter } = condBuilder.build(manualJoin.condition, context.paramCounter, context.placeholders);
+            context.paramCounter = newJoinParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...condParams);
+            if (joinPlaceholders) {
+                context.placeholders = joinPlaceholders;
+            }
             // Check if this is a subquery join
             if (manualJoin.isSubquery && manualJoin.subquery) {
                 const subqueryBuildContext = {
@@ -3275,10 +3516,13 @@ class SelectQueryBuilder {
         let whereClause = '';
         if (this.whereCond) {
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql, params } = condBuilder.build(this.whereCond, context.paramCounter);
+            const { sql, params, placeholders, paramCounter: newParamCounter } = condBuilder.build(this.whereCond, context.paramCounter, context.placeholders);
             whereClause = `WHERE ${sql}`;
-            context.paramCounter += params.length;
+            context.paramCounter = newParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...params);
+            if (placeholders) {
+                context.placeholders = placeholders;
+            }
         }
         // Build FROM clause with JOINs
         let fromClause = `FROM "${this.schema.name}"`;
@@ -3286,9 +3530,12 @@ class SelectQueryBuilder {
         for (const manualJoin of this.manualJoins) {
             const joinTypeStr = manualJoin.type === 'INNER' ? 'INNER JOIN' : 'LEFT JOIN';
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql: condSql, params: condParams } = condBuilder.build(manualJoin.condition, context.paramCounter);
-            context.paramCounter += condParams.length;
+            const { sql: condSql, params: condParams, placeholders: joinPlaceholders, paramCounter: newJoinParamCounter } = condBuilder.build(manualJoin.condition, context.paramCounter, context.placeholders);
+            context.paramCounter = newJoinParamCounter; // Use returned counter (handles both params and placeholders)
             context.allParams.push(...condParams);
+            if (joinPlaceholders) {
+                context.placeholders = joinPlaceholders;
+            }
             // Check if this is a subquery join
             if (manualJoin.isSubquery && manualJoin.subquery) {
                 const subqueryBuildContext = {
@@ -3334,12 +3581,13 @@ class SelectQueryBuilder {
     asSubquery(mode = 'table') {
         // Create a function that builds the subquery SQL when called
         const sqlBuilder = (outerContext) => {
-            // Create a fresh context for this subquery
+            // Create a fresh context for this subquery, inheriting placeholders from outer context
             const context = {
                 ctes: new Map(),
                 cteCounter: 0,
                 paramCounter: outerContext.paramCounter,
                 allParams: outerContext.params,
+                placeholders: outerContext.placeholders, // Pass placeholders through for prepared statements
                 executor: this.executor,
             };
             // Analyze the selector to extract nested queries
@@ -3829,6 +4077,12 @@ class CollectionQueryBuilder {
     getTargetTableSchema() {
         return this.targetTableSchema;
     }
+    /**
+     * Get target table name
+     */
+    getTargetTable() {
+        return this.targetTable;
+    }
     /**
      * Get selected field configs (for mapper lookup during transformation)
      */
@@ -4107,6 +4361,7 @@ class CollectionQueryBuilder {
                 const sqlBuildContext = {
                     paramCounter: context.paramCounter,
                     params: context.allParams,
+                    placeholders: context.placeholders, // Pass placeholders for prepared statements
                 };
                 const fragmentSql = field.buildSql(sqlBuildContext);
                 context.paramCounter = sqlBuildContext.paramCounter;
@@ -4153,10 +4408,25 @@ class CollectionQueryBuilder {
                             cteName: nestedResult.tableName,
                             joinClause: nestedJoinClause,
                         },
+                        // Store nested collection info for recursive mapper transformation
+                        nestedCollectionInfo: {
+                            targetTable: field.getTargetTable(),
+                            selectedFieldConfigs: field.getSelectedFieldConfigs(),
+                            isSingleResult: field.isSingleResult(),
+                        },
                     };
                 }
                 // The nested collection becomes a correlated subquery in SELECT
-                return { alias, expression: nestedResult.selectExpression || nestedResult.sql };
+                return {
+                    alias,
+                    expression: nestedResult.selectExpression || nestedResult.sql,
+                    // Store nested collection info for recursive mapper transformation
+                    nestedCollectionInfo: {
+                        targetTable: field.getTargetTable(),
+                        selectedFieldConfigs: field.getSelectedFieldConfigs(),
+                        isSingleResult: field.isSingleResult(),
+                    },
+                };
             }
             else if (typeof field === 'object' && field !== null && '__dbColumnName' in field) {
                 // FieldRef object - use database column name with optional table alias
@@ -4241,12 +4511,15 @@ class CollectionQueryBuilder {
         let whereParams;
         if (this.whereCond) {
             const condBuilder = new conditions_1.ConditionBuilder();
-            const { sql, params } = condBuilder.build(this.whereCond, context.paramCounter);
+            const { sql, params, placeholders, paramCounter: newParamCounter } = condBuilder.build(this.whereCond, context.paramCounter, context.placeholders);
             whereClause = sql;
             whereParams = params;
-            context.paramCounter += params.length;
+            context.paramCounter = newParamCounter; // Use returned counter (handles both params and placeholders)
             localParams.push(...params);
             context.allParams.push(...params);
+            if (placeholders) {
+                context.placeholders = placeholders;
+            }
         }
         // Step 3: Build ORDER BY clauses SQL (without ORDER BY keyword)
         // We need two versions:
@@ -4337,9 +4610,11 @@ class CollectionQueryBuilder {
             whereParams, // Pass WHERE clause parameters
             orderByClause,
             orderByClauseAlias, // For json_agg ORDER BY which uses aliases
+            orderByFields: this.orderByFields.length > 0 ? this.orderByFields : undefined, // For including ORDER BY columns in inner SELECT
             limitValue: this.limitValue,
             offsetValue: this.offsetValue,
             isDistinct: this.isDistinct,
+            isSingleResult: this.isSingleResult(), // For firstOrDefault() - returns single object instead of array
             aggregationType,
             aggregateField,
             arrayField,