linkgress-orm 0.0.3 → 0.1.1

package/dist/entity/db-context.js

@@ -7,6 +7,7 @@ const conditions_1 = require("../query/conditions");
 const query_builder_1 = require("../query/query-builder");
 const db_schema_manager_1 = require("../migration/db-schema-manager");
 const sequence_builder_1 = require("../schema/sequence-builder");
+const sql_utils_1 = require("../query/sql-utils");
 /**
  * Query executor with optional logging
  */
@@ -134,14 +135,6 @@ class InsertBuilder {
         this.conflictAction = 'nothing';
         this.overridingSystemValue = false;
     }
-    /**
-     * Get qualified table name with schema prefix if specified
-     */
-    getQualifiedTableName() {
-        return this.schema.schema
-            ? `"${this.schema.schema}"."${this.schema.name}"`
-            : `"${this.schema.name}"`;
-    }
     /**
      * Set the values to insert (single row or multiple rows)
      */
@@ -241,15 +234,9 @@ class InsertBuilder {
             }
             valuePlaceholders.push(`(${rowPlaceholders.join(', ')})`);
         }
-        const columnNames = columns.map(key => {
-            const column = this.schema.columns[key];
-            const config = column.build();
-            return `"${config.name}"`;
-        });
-        const returningColumns = Object.entries(this.schema.columns)
-            .map(([_, col]) => `"${col.build().name}"`)
-            .join(', ');
-        const qualifiedTableName = this.getQualifiedTableName();
+        const columnNames = (0, sql_utils_1.buildColumnNamesList)(this.schema, columns);
+        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
         let sql = `INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})`;
         // Add OVERRIDING SYSTEM VALUE if specified
         if (this.overridingSystemValue) {
@@ -354,6 +341,7 @@ class TableAccessor {
     }
     /**
      * Start a select query with automatic type inference
+     * UnwrapSelection extracts the value types from SqlFragment<T> expressions
      */
     select(selector) {
         return new query_builder_1.SelectQueryBuilder(this.schema, this.client, selector, undefined, undefined, undefined, undefined, this.executor, undefined, undefined, undefined, this.schemaRegistry, undefined, this.collectionStrategy);
@@ -365,6 +353,13 @@ class TableAccessor {
         const qb = new query_builder_1.QueryBuilder(this.schema, this.client, undefined, undefined, undefined, undefined, this.executor, undefined, undefined, this.collectionStrategy);
         return qb.where(condition);
     }
+    /**
+     * Add CTEs (Common Table Expressions) to the query
+     */
+    with(...ctes) {
+        const qb = new query_builder_1.QueryBuilder(this.schema, this.client, undefined, undefined, undefined, undefined, this.executor, undefined, undefined, this.collectionStrategy);
+        return qb.with(...ctes);
+    }
     /**
      * Left join with another table and selector
      */
@@ -397,14 +392,6 @@ class TableAccessor {
     getTableName() {
         return this.schema.name;
     }
-    /**
-     * Get qualified table name with schema prefix if specified
-     */
-    getQualifiedTableName() {
-        return this.schema.schema
-            ? `"${this.schema.schema}"."${this.schema.name}"`
-            : `"${this.schema.name}"`;
-    }
     /**
      * Insert a row
      */
@@ -428,10 +415,8 @@ class TableAccessor {
                 }
             }
         }
-        const returningColumns = Object.entries(this.schema.columns)
-            .map(([_, col]) => `"${col.build().name}"`)
-            .join(', ');
-        const qualifiedTableName = this.getQualifiedTableName();
+        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
         const sql = `
       INSERT INTO ${qualifiedTableName} (${columns.join(', ')})
       VALUES (${placeholders.join(', ')})
@@ -451,15 +436,10 @@ class TableAccessor {
             return [];
         }
         // Calculate chunk size based on max rows per batch
-        let chunkSize = insertConfig?.chunkSize;
-        if (chunkSize == null && dataArray.length > 0) {
-            const POSTGRES_MAX_PARAMS = 65535; // PostgreSQL parameter limit
-            const columnCount = Object.keys(dataArray[0]).length;
-            const maxRowsPerBatch = Math.floor(POSTGRES_MAX_PARAMS / columnCount);
-            chunkSize = Math.floor(maxRowsPerBatch * 0.6); // Use 60% of max to be safe
-        }
+        const columnCount = Object.keys(dataArray[0]).length;
+        const chunkSize = (0, sql_utils_1.calculateOptimalChunkSize)(columnCount, insertConfig?.chunkSize);
         // Check if we need to chunk
-        if (chunkSize && dataArray.length > chunkSize) {
+        if (dataArray.length > chunkSize) {
             const results = [];
             for (let i = 0; i < dataArray.length; i += chunkSize) {
                 const chunk = dataArray.slice(i, i + chunkSize);
@@ -480,56 +460,28 @@ class TableAccessor {
             return [];
         }
         // Extract all unique column names from all data objects
-        const columnSet = new Set();
-        for (const data of dataArray) {
-            for (const key of Object.keys(data)) {
-                const column = this.schema.columns[key];
-                if (column) {
-                    const config = column.build();
-                    if (!config.autoIncrement || insertConfig?.overridingSystemValue) {
-                        columnSet.add(key);
-                    }
-                }
-            }
-        }
-        const columns = Array.from(columnSet);
-        const values = [];
-        const valuePlaceholders = [];
-        let paramIndex = 1;
-        // Build placeholders for each row
-        for (const data of dataArray) {
-            const rowPlaceholders = [];
-            for (const key of columns) {
-                const value = data[key];
-                const column = this.schema.columns[key];
-                const config = column.build();
-                // Apply toDriver mapper if present
-                const mappedValue = config.mapper
-                    ? config.mapper.toDriver(value !== undefined ? value : null)
-                    : (value !== undefined ? value : null);
-                values.push(mappedValue);
-                rowPlaceholders.push(`$${paramIndex++}`);
-            }
-            valuePlaceholders.push(`(${rowPlaceholders.join(', ')})`);
+        const columns = (0, sql_utils_1.extractUniqueColumnKeys)(dataArray, this.schema, insertConfig?.overridingSystemValue);
+        if (columns.length === 0) {
+            return [];
         }
-        const columnNames = columns.map(key => {
-            const column = this.schema.columns[key];
-            const config = column.build();
-            return `"${config.name}"`;
-        });
-        const returningColumns = Object.entries(this.schema.columns)
-            .map(([_, col]) => `"${col.build().name}"`)
-            .join(', ');
-        const qualifiedTableName = this.getQualifiedTableName();
-        let sql = `INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})`;
+        const columnConfigs = (0, sql_utils_1.buildColumnConfigs)(this.schema, columns, insertConfig?.overridingSystemValue);
+        const { valueClauses, params } = (0, sql_utils_1.buildValuesClause)(dataArray, columnConfigs);
+        const columnNames = columnConfigs.map(c => `"${c.dbName}"`);
+        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        let sql = `
+      INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})`;
+        // Add OVERRIDING SYSTEM VALUE if specified
         if (insertConfig?.overridingSystemValue) {
             sql += '\n      OVERRIDING SYSTEM VALUE';
         }
-        sql += `\n      VALUES ${valuePlaceholders.join(', ')}
-      RETURNING ${returningColumns}`;
+        sql += `
+      VALUES ${valueClauses.join(', ')}
+      RETURNING ${returningColumns}
+    `;
         const result = this.executor
-            ? await this.executor.query(sql, values)
-            : await this.client.query(sql, values);
+            ? await this.executor.query(sql, params)
+            : await this.client.query(sql, params);
         return result.rows;
     }
     /**
@@ -541,33 +493,12 @@ class TableAccessor {
         }
         const referenceItem = config?.referenceItem || values[0];
         // Determine primary keys
-        let primaryKeys = [];
-        if (config?.primaryKey) {
-            primaryKeys = Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey];
-        }
-        else {
-            // Auto-detect from schema
-            for (const [key, colBuilder] of Object.entries(this.schema.columns)) {
-                const colConfig = colBuilder.build();
-                if (colConfig.primaryKey) {
-                    primaryKeys.push(key);
-                }
-            }
-        }
+        const primaryKeys = config?.primaryKey
+            ? (Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey])
+            : (0, sql_utils_1.detectPrimaryKeys)(this.schema);
         // Auto-detect overridingSystemValue
-        let overridingSystemValue = config?.overridingSystemValue;
-        if (overridingSystemValue == null) {
-            for (const key of Object.keys(referenceItem)) {
-                const column = this.schema.columns[key];
-                if (column) {
-                    const colConfig = column.build();
-                    if (colConfig.primaryKey && colConfig.autoIncrement) {
-                        overridingSystemValue = true;
-                        break;
-                    }
-                }
-            }
-        }
+        const overridingSystemValue = config?.overridingSystemValue ??
+            (0, sql_utils_1.hasAutoIncrementPrimaryKey)(this.schema, Object.keys(referenceItem));
         // Determine which columns to update
         let updateColumnFilter = config?.updateColumnFilter;
         if (updateColumnFilter == null && config?.updateColumns) {
@@ -578,15 +509,10 @@ class TableAccessor {
             updateColumnFilter = (colId) => !primaryKeys.includes(colId);
         }
         // Calculate chunk size based on max rows per batch
-        let chunkSize = config?.chunkSize;
-        if (chunkSize == null && values.length > 0) {
-            const POSTGRES_MAX_PARAMS = 65535;
-            const columnCount = Object.keys(values[0]).length;
-            const maxRowsPerBatch = Math.floor(POSTGRES_MAX_PARAMS / columnCount);
-            chunkSize = Math.floor(maxRowsPerBatch * 0.6); // Use 60% of max to be safe
-        }
+        const columnCount = Object.keys(values[0]).length;
+        const chunkSize = (0, sql_utils_1.calculateOptimalChunkSize)(columnCount, config?.chunkSize);
         // Check if we need to chunk
-        if (chunkSize && values.length > chunkSize) {
+        if (values.length > chunkSize) {
             const results = [];
             for (let i = 0; i < values.length; i += chunkSize) {
                 const chunk = values.slice(i, i + chunkSize);
@@ -661,7 +587,7 @@ class TableAccessor {
         const returningColumns = Object.entries(this.schema.columns)
             .map(([_, col]) => `"${col.build().name}"`)
             .join(', ');
-        const qualifiedTableName = this.getQualifiedTableName();
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
         const sql = `
       INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})
       VALUES ${valuePlaceholders.join(', ')}
@@ -725,7 +651,7 @@ class TableAccessor {
         const returningColumns = Object.entries(this.schema.columns)
             .map(([_, col]) => `"${col.build().name}"`)
             .join(', ');
-        const qualifiedTableName = this.getQualifiedTableName();
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
         const sql = `
       UPDATE ${qualifiedTableName}
       SET ${setClauses.join(', ')}
@@ -753,7 +679,7 @@ class TableAccessor {
         if (!pkColumnName) {
             throw new Error(`Table ${this.schema.name} has no primary key`);
         }
-        const qualifiedTableName = this.getQualifiedTableName();
+        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
         const sql = `DELETE FROM ${qualifiedTableName} WHERE "${pkColumnName}" = $1`;
         const result = this.executor
             ? await this.executor.query(sql, [id])
@@ -1007,6 +933,53 @@ class DbEntityTable {
             : await client.query(sql, []);
         return this.mapResultsToEntities(result.rows);
     }
+    /**
+     * Get first record
+     * @throws Error if no records exist
+     */
+    async first() {
+        const queryBuilder = this.context.getTable(this.tableName);
+        const schema = this._getSchema();
+        // Build SELECT with all columns and LIMIT 1
+        const columns = Object.entries(schema.columns)
+            .map(([_, col]) => `"${col.build().name}"`)
+            .join(', ');
+        const qualifiedTableName = this._getQualifiedTableName();
+        const sql = `SELECT ${columns} FROM ${qualifiedTableName} LIMIT 1`;
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const result = executor
+            ? await executor.query(sql, [])
+            : await client.query(sql, []);
+        if (result.rows.length === 0) {
+            throw new Error('Sequence contains no elements');
+        }
+        const mapped = this.mapResultsToEntities(result.rows);
+        return mapped[0];
+    }
+    /**
+     * Get first record or null if none exist
+     */
+    async firstOrDefault() {
+        const queryBuilder = this.context.getTable(this.tableName);
+        const schema = this._getSchema();
+        // Build SELECT with all columns and LIMIT 1
+        const columns = Object.entries(schema.columns)
+            .map(([_, col]) => `"${col.build().name}"`)
+            .join(', ');
+        const qualifiedTableName = this._getQualifiedTableName();
+        const sql = `SELECT ${columns} FROM ${qualifiedTableName} LIMIT 1`;
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const result = executor
+            ? await executor.query(sql, [])
+            : await client.query(sql, []);
+        if (result.rows.length === 0) {
+            return null;
+        }
+        const mapped = this.mapResultsToEntities(result.rows);
+        return mapped[0];
+    }
     /**
      * Count all records
      */
@@ -1065,6 +1038,7 @@ class DbEntityTable {
     }
     /**
      * Select query
+     * UnwrapSelection extracts the value types from SqlFragment<T> expressions
      */
     select(selector) {
         const queryBuilder = this.context.getTable(this.tableName).select(selector);
@@ -1092,19 +1066,16 @@ class DbEntityTable {
             for (const colName of Object.keys(schema.columns)) {
                 result[colName] = e[colName];
             }
-            // Add navigation properties
+            // Add navigation properties as enumerable getters
+            // The getter returns the actual navigation builder (CollectionQueryBuilder/ReferenceQueryBuilder)
+            // which allows chained selectors like .select(u => ({ posts: u.posts!.where(...) }))
+            // When the selection is analyzed, the builder is detected and handled appropriately
             for (const relName of Object.keys(schema.relations)) {
-                const relConfig = schema.relations[relName];
-                if (relConfig.type === 'many') {
-                    // For collections, use empty array placeholder
-                    // (prevents CollectionQueryBuilder evaluation)
-                    result[relName] = [];
-                }
-                else {
-                    // For references, copy the ReferenceQueryBuilder mock
-                    // This allows accessing fields like o.user!.username in chained selectors
-                    result[relName] = e[relName];
-                }
+                Object.defineProperty(result, relName, {
+                    get: () => e[relName],
+                    enumerable: true, // Enumerable so it's included in Object.entries
+                    configurable: true,
+                });
             }
             return result;
         };
@@ -1114,85 +1085,472 @@ class DbEntityTable {
         return queryBuilder;
     }
     /**
-     * Left join with another table or subquery and selector
+     * Add CTEs (Common Table Expressions) to the query
      */
+    with(...ctes) {
+        const schema = this._getSchema();
+        // Create a selector that selects all columns with navigation property access
+        const allColumnsSelector = (e) => {
+            const result = {};
+            // Copy all column properties
+            for (const colName of Object.keys(schema.columns)) {
+                result[colName] = e[colName];
+            }
+            // Add navigation properties as enumerable getters
+            // The getter returns the actual navigation builder (CollectionQueryBuilder/ReferenceQueryBuilder)
+            // which allows chained selectors like .select(u => ({ posts: u.posts!.where(...) }))
+            // When the selection is analyzed, the builder is detected and handled appropriately
+            for (const relName of Object.keys(schema.relations)) {
+                Object.defineProperty(result, relName, {
+                    get: () => e[relName],
+                    enumerable: true, // Enumerable so it's included in Object.entries
+                    configurable: true,
+                });
+            }
+            return result;
+        };
+        const queryBuilder = this.context.getTable(this.tableName)
+            .with(...ctes)
+            .select(allColumnsSelector);
+        return queryBuilder;
+    }
     leftJoin(rightTable, condition, selector, alias) {
         const queryBuilder = this.context.getTable(this.tableName).leftJoin(rightTable, condition, selector, alias);
         return queryBuilder;
     }
-    /**
-     * Inner join with another table or subquery and selector
-     */
     innerJoin(rightTable, condition, selector, alias) {
         const queryBuilder = this.context.getTable(this.tableName).innerJoin(rightTable, condition, selector, alias);
         return queryBuilder;
     }
     /**
      * Insert - accepts only DbColumn properties (excludes navigation properties)
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.insert({ username: 'alice', email: 'alice@test.com' });
+     *
+     * // With returning() - returns full entity
+     * const user = await db.users.insert({ username: 'alice' }).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const { id } = await db.users.insert({ username: 'alice' }).returning(u => ({ id: u.id }));
+     * ```
      */
-    async insert(data) {
-        const result = await this.context.getTable(this.tableName).insert(data);
-        return this.mapResultToEntity(result);
+    insert(data) {
+        const table = this;
+        const executeInsert = async (returning) => {
+            const schema = table._getSchema();
+            const executor = table._getExecutor();
+            const client = table._getClient();
+            // Build INSERT columns and values
+            const columns = [];
+            const values = [];
+            const placeholders = [];
+            let paramIndex = 1;
+            for (const [key, value] of Object.entries(data)) {
+                const column = schema.columns[key];
+                if (column) {
+                    const config = column.build();
+                    if (!config.autoIncrement) {
+                        columns.push(`"${config.name}"`);
+                        const mappedValue = config.mapper ? config.mapper.toDriver(value) : value;
+                        values.push(mappedValue);
+                        placeholders.push(`$${paramIndex++}`);
+                    }
+                }
+            }
+            // Build RETURNING clause
+            const returningClause = table.buildReturningClause(returning);
+            const qualifiedTableName = table._getQualifiedTableName();
+            let sql = `INSERT INTO ${qualifiedTableName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`;
+            if (returningClause) {
+                sql += ` RETURNING ${returningClause.sql}`;
+            }
+            const result = executor
+                ? await executor.query(sql, values)
+                : await client.query(sql, values);
+            if (!returningClause) {
+                return undefined;
+            }
+            const mappedResults = table.mapReturningResults(result.rows, returning);
+            return mappedResults[0];
+        };
+        return {
+            then(onfulfilled, onrejected) {
+                return executeInsert(undefined).then(onfulfilled, onrejected);
+            },
+            returning(selector) {
+                const returningConfig = selector ?? true;
+                return {
+                    then(onfulfilled, onrejected) {
+                        return executeInsert(returningConfig).then(onfulfilled, onrejected);
+                    }
+                };
+            }
+        };
     }
     /**
      * Insert multiple records
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.insertMany([{ username: 'alice' }, { username: 'bob' }]);
+     *
+     * // With returning() - returns full entities
+     * const users = await db.users.insertMany([{ username: 'alice' }]).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const results = await db.users.insertMany([{ username: 'alice' }]).returning(u => ({ id: u.id }));
+     * ```
      */
-    async insertMany(data) {
+    insertMany(data) {
         return this.insertBulk(data);
     }
     /**
      * Upsert (insert or update on conflict)
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.upsert([{ username: 'alice' }], { primaryKey: 'username' });
+     *
+     * // With returning() - returns full entities
+     * const users = await db.users.upsert([{ username: 'alice' }], { primaryKey: 'username' }).returning();
+     * ```
      */
-    async upsert(data, config) {
+    upsert(data, config) {
         return this.upsertBulk(data, config);
     }
     /**
      * Bulk insert with advanced configuration
      * Supports automatic chunking for large datasets
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.insertBulk([{ username: 'alice' }]);
+     *
+     * // With returning() - returns full entities
+     * const users = await db.users.insertBulk([{ username: 'alice' }]).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const results = await db.users.insertBulk([{ username: 'alice' }]).returning(u => ({ id: u.id }));
+     *
+     * // With options
+     * await db.users.insertBulk([{ username: 'alice' }], { chunkSize: 100 });
+     * ```
      */
-    async insertBulk(value, insertConfig) {
-        const results = await this.context.getTable(this.tableName).insertBulk(value, insertConfig);
-        return this.mapResultsToEntities(results);
+    insertBulk(value, options) {
+        const table = this;
+        const dataArray = Array.isArray(value) ? value : [value];
+        const executeInsertBulk = async (returning) => {
+            if (dataArray.length === 0) {
+                return returning === undefined ? undefined : [];
+            }
+            // Calculate chunk size
+            let chunkSize = options?.chunkSize;
+            if (chunkSize == null) {
+                const POSTGRES_MAX_PARAMS = 65535;
+                const columnCount = Object.keys(dataArray[0]).length;
+                const maxRowsPerBatch = Math.floor(POSTGRES_MAX_PARAMS / columnCount);
+                chunkSize = Math.floor(maxRowsPerBatch * 0.6);
+            }
+            // Process in chunks if needed
+            if (dataArray.length > chunkSize) {
+                const allResults = [];
+                for (let i = 0; i < dataArray.length; i += chunkSize) {
+                    const chunk = dataArray.slice(i, i + chunkSize);
+                    const chunkResults = await table.insertBulkSingle(chunk, returning, options?.overridingSystemValue);
+                    if (chunkResults)
+                        allResults.push(...chunkResults);
+                }
+                return returning === undefined ? undefined : allResults;
+            }
+            return table.insertBulkSingle(dataArray, returning, options?.overridingSystemValue);
+        };
+        return {
+            then(onfulfilled, onrejected) {
+                return executeInsertBulk(undefined).then(onfulfilled, onrejected);
+            },
+            returning(selector) {
+                const returningConfig = selector ?? true;
+                return {
+                    then(onfulfilled, onrejected) {
+                        return executeInsertBulk(returningConfig).then(onfulfilled, onrejected);
+                    }
+                };
+            }
+        };
+    }
+    /**
+     * Execute a single bulk insert batch
+     * @internal
+     */
+    async insertBulkSingle(data, returning, overridingSystemValue) {
+        const schema = this._getSchema();
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const qualifiedTableName = this._getQualifiedTableName();
+        // Get columns from first row
+        const referenceItem = data[0];
+        const columnConfigs = [];
+        for (const [propName, colBuilder] of Object.entries(schema.columns)) {
+            if (propName in referenceItem) {
+                const config = colBuilder.build();
+                if (!config.autoIncrement || overridingSystemValue) {
+                    columnConfigs.push({
+                        propName,
+                        dbName: config.name,
+                        mapper: config.mapper,
+                    });
+                }
+            }
+        }
+        // Build VALUES clauses
+        const valuesClauses = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const record of data) {
+            const rowValues = [];
+            for (const col of columnConfigs) {
+                const value = record[col.propName];
+                const mappedValue = col.mapper ? col.mapper.toDriver(value) : value;
+                rowValues.push(`$${paramIndex++}`);
+                params.push(mappedValue);
+            }
+            valuesClauses.push(`(${rowValues.join(', ')})`);
+        }
+        const columnList = columnConfigs.map(c => `"${c.dbName}"`).join(', ');
+        const returningClause = this.buildReturningClause(returning);
+        let sql = `INSERT INTO ${qualifiedTableName} (${columnList})`;
+        if (overridingSystemValue) {
+            sql += ' OVERRIDING SYSTEM VALUE';
+        }
+        sql += ` VALUES ${valuesClauses.join(', ')}`;
+        if (returningClause) {
+            sql += ` RETURNING ${returningClause.sql}`;
+        }
+        const result = executor
+            ? await executor.query(sql, params)
+            : await client.query(sql, params);
+        if (!returningClause) {
+            return undefined;
+        }
+        return this.mapReturningResults(result.rows, returning);
     }
     /**
      * Upsert with advanced configuration
      * Auto-detects primary keys and supports chunking
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.upsertBulk([{ id: 1, username: 'alice' }], { primaryKey: 'id' });
+     *
+     * // With returning() - returns full entities
+     * const users = await db.users.upsertBulk([{ id: 1, username: 'alice' }]).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const results = await db.users.upsertBulk([{ id: 1, username: 'alice' }])
+     *   .returning(u => ({ id: u.id }));
+     * ```
      */
-    async upsertBulk(values, config) {
-        // Convert typed config to base config
-        const baseConfig = {
-            chunkSize: config?.chunkSize,
-            overridingSystemValue: config?.overridingSystemValue,
-            targetWhere: config?.targetWhere,
-            setWhere: config?.setWhere,
-            referenceItem: config?.referenceItem,
-            updateColumnFilter: config?.updateColumnFilter,
-        };
-        // Handle primaryKey (can be lambda, string, or array)
-        if (config?.primaryKey) {
-            if (typeof config.primaryKey === 'function') {
-                // Lambda selector - extract property names
-                const pkProps = this.extractPropertyNames(config.primaryKey);
-                baseConfig.primaryKey = pkProps.length === 1 ? pkProps[0] : pkProps;
+    upsertBulk(values, config) {
+        const table = this;
+        const executeUpsertBulk = async (returning) => {
+            if (values.length === 0) {
+                return returning === undefined ? undefined : [];
+            }
+            const schema = table._getSchema();
+            // Handle primaryKey (can be lambda, string, or array)
+            let primaryKeys = [];
+            if (config?.primaryKey) {
+                if (typeof config.primaryKey === 'function') {
+                    const pkProps = table.extractPropertyNames(config.primaryKey);
+                    primaryKeys = pkProps;
+                }
+                else if (Array.isArray(config.primaryKey)) {
+                    primaryKeys = config.primaryKey;
+                }
+                else {
+                    primaryKeys = [config.primaryKey];
+                }
             }
             else {
-                // Direct string or array
-                baseConfig.primaryKey = config.primaryKey;
+                // Auto-detect from schema
+                for (const [key, colBuilder] of Object.entries(schema.columns)) {
+                    const colConfig = colBuilder.build();
+                    if (colConfig.primaryKey) {
+                        primaryKeys.push(key);
+                    }
+                }
+            }
+            // Handle updateColumns (can be lambda or array)
+            let updateColumns;
+            if (config?.updateColumns) {
+                if (typeof config.updateColumns === 'function') {
+                    updateColumns = table.extractPropertyNames(config.updateColumns);
+                }
+                else {
+                    updateColumns = config.updateColumns;
+                }
+            }
+            // Auto-detect overridingSystemValue
+            let overridingSystemValue = config?.overridingSystemValue;
+            if (overridingSystemValue == null) {
+                const referenceItem = config?.referenceItem || values[0];
+                for (const key of Object.keys(referenceItem)) {
+                    const column = schema.columns[key];
+                    if (column) {
+                        const colConfig = column.build();
+                        if (colConfig.primaryKey && colConfig.autoIncrement) {
+                            overridingSystemValue = true;
+                            break;
+                        }
+                    }
+                }
+            }
+            // Calculate chunk size
+            let chunkSize = config?.chunkSize;
+            if (chunkSize == null) {
+                const POSTGRES_MAX_PARAMS = 65535;
+                const columnCount = Object.keys(values[0]).length;
+                const maxRowsPerBatch = Math.floor(POSTGRES_MAX_PARAMS / columnCount);
+                chunkSize = Math.floor(maxRowsPerBatch * 0.6);
+            }
+            // Process in chunks if needed
+            if (values.length > chunkSize) {
+                const allResults = [];
+                for (let i = 0; i < values.length; i += chunkSize) {
+                    const chunk = values.slice(i, i + chunkSize);
+                    const chunkResults = await table.upsertBulkSingle(chunk, primaryKeys, updateColumns, config?.updateColumnFilter, overridingSystemValue || false, config?.targetWhere, config?.setWhere, returning);
+                    if (chunkResults)
+                        allResults.push(...chunkResults);
+                }
+                return returning === undefined ? undefined : allResults;
+            }
+            return table.upsertBulkSingle(values, primaryKeys, updateColumns, config?.updateColumnFilter, overridingSystemValue || false, config?.targetWhere, config?.setWhere, returning);
+        };
+        return {
+            then(onfulfilled, onrejected) {
+                return executeUpsertBulk(undefined).then(onfulfilled, onrejected);
+            },
+            returning(selector) {
+                const returningConfig = selector ?? true;
+                return {
+                    then(onfulfilled, onrejected) {
+                        return executeUpsertBulk(returningConfig).then(onfulfilled, onrejected);
+                    }
+                };
+            }
+        };
+    }
+    /**
+     * Execute a single upsert batch
+     * @internal
+     */
+    async upsertBulkSingle(values, primaryKeys, updateColumns, updateColumnFilter, overridingSystemValue, targetWhere, setWhere, returning) {
+        const schema = this._getSchema();
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const qualifiedTableName = this._getQualifiedTableName();
+        // Extract all unique column names from all data objects
+        const columnConfigs = [];
+        const columnSet = new Set();
+        for (const data of values) {
+            for (const key of Object.keys(data)) {
+                if (!columnSet.has(key)) {
+                    const column = schema.columns[key];
+                    if (column) {
+                        const config = column.build();
+                        if (!config.autoIncrement || overridingSystemValue) {
+                            columnSet.add(key);
+                            columnConfigs.push({
+                                propName: key,
+                                dbName: config.name,
+                                mapper: config.mapper,
+                            });
+                        }
+                    }
+                }
             }
         }
-        // Handle updateColumns (can be lambda or array)
-        if (config?.updateColumns) {
-            if (typeof config.updateColumns === 'function') {
-                // Lambda selector - extract property names
-                baseConfig.updateColumns = this.extractPropertyNames(config.updateColumns);
+        // Build VALUES clauses
+        const valuesClauses = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const record of values) {
+            const rowValues = [];
+            for (const col of columnConfigs) {
+                const value = record[col.propName];
+                const mappedValue = col.mapper
+                    ? col.mapper.toDriver(value !== undefined ? value : null)
+                    : (value !== undefined ? value : null);
+                rowValues.push(`$${paramIndex++}`);
+                params.push(mappedValue);
             }
-            else {
-                // Direct array
-                baseConfig.updateColumns = config.updateColumns;
+            valuesClauses.push(`(${rowValues.join(', ')})`);
+        }
+        const columnList = columnConfigs.map(c => `"${c.dbName}"`).join(', ');
+        // Build SQL
+        let sql = `INSERT INTO ${qualifiedTableName} (${columnList})`;
+        if (overridingSystemValue) {
+            sql += ' OVERRIDING SYSTEM VALUE';
+        }
+        sql += ` VALUES ${valuesClauses.join(', ')}`;
+        // Add ON CONFLICT clause
+        const conflictCols = primaryKeys.map(pk => {
+            const col = columnConfigs.find(c => c.propName === pk);
+            return col ? `"${col.dbName}"` : `"${pk}"`;
+        }).join(', ');
+        sql += ` ON CONFLICT (${conflictCols})`;
+        if (targetWhere) {
+            sql += ` WHERE ${targetWhere}`;
+        }
+        // Determine columns to update
+        let columnsToUpdate;
+        if (updateColumns) {
+            columnsToUpdate = updateColumns;
+        }
+        else if (updateColumnFilter) {
+            columnsToUpdate = Array.from(columnSet).filter(updateColumnFilter);
+        }
+        else {
+            columnsToUpdate = Array.from(columnSet).filter(key => !primaryKeys.includes(key));
+        }
+        if (columnsToUpdate.length === 0) {
+            sql += ' DO NOTHING';
+        }
+        else {
+            const updateSetClauses = columnsToUpdate.map(propName => {
+                const col = columnConfigs.find(c => c.propName === propName);
+                const dbName = col ? col.dbName : propName;
+                return `"${dbName}" = EXCLUDED."${dbName}"`;
+            });
+            sql += ` DO UPDATE SET ${updateSetClauses.join(', ')}`;
+            if (setWhere) {
+                sql += ` WHERE ${setWhere}`;
             }
         }
-        const results = await this.context.getTable(this.tableName).upsertBulk(values, baseConfig);
-        return this.mapResultsToEntities(results);
+        // Add RETURNING clause
+        const returningClause = this.buildReturningClause(returning);
+        if (returningClause) {
+            sql += ` RETURNING ${returningClause.sql}`;
+        }
+        const result = executor
+            ? await executor.query(sql, params)
+            : await client.query(sql, params);
+        if (!returningClause) {
+            return undefined;
+        }
+        return this.mapReturningResults(result.rows, returning);
     }
     /**
      * Map database column names back to property names
@@ -1244,48 +1602,268 @@ class DbEntityTable {
     }
     /**
      * Update records matching condition
-     * Usage: db.users.update({ age: 30 }, u => eq(u.id, 1))
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.update({ age: 30 }, u => eq(u.id, 1));
+     *
+     * // With returning() - returns full entities
+     * const users = await db.users.update({ age: 30 }, u => eq(u.id, 1)).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const results = await db.users.update({ age: 30 }, u => eq(u.id, 1))
+     *   .returning(u => ({ id: u.id, age: u.age }));
+     * ```
+     */
+    update(data, condition) {
+        const table = this;
+        const executeUpdate = async (returning) => {
+            const schema = table._getSchema();
+            const executor = table._getExecutor();
+            const client = table._getClient();
+            // Build SET clause
+            const setClauses = [];
+            const values = [];
+            let paramIndex = 1;
+            for (const [key, value] of Object.entries(data)) {
+                const column = schema.columns[key];
+                if (column) {
+                    const config = column.build();
+                    setClauses.push(`"${config.name}" = $${paramIndex++}`);
+                    values.push(value);
+                }
+            }
+            if (setClauses.length === 0) {
+                throw new Error('No valid columns to update');
+            }
+            // Build WHERE clause
+            const mockEntity = table.createMockEntity();
+            const whereCondition = condition(mockEntity);
+            const condBuilder = new conditions_1.ConditionBuilder();
+            const { sql: whereSql, params: whereParams } = condBuilder.build(whereCondition, paramIndex);
+            values.push(...whereParams);
+            // Build RETURNING clause
+            const returningClause = table.buildReturningClause(returning);
+            const qualifiedTableName = table._getQualifiedTableName();
+            let sql = `UPDATE ${qualifiedTableName} SET ${setClauses.join(', ')} WHERE ${whereSql}`;
+            if (returningClause) {
+                sql += ` RETURNING ${returningClause.sql}`;
+            }
+            const result = executor
+                ? await executor.query(sql, values)
+                : await client.query(sql, values);
+            if (!returningClause) {
+                return undefined;
+            }
+            return table.mapReturningResults(result.rows, returning);
+        };
+        return {
+            then(onfulfilled, onrejected) {
+                return executeUpdate(undefined).then(onfulfilled, onrejected);
+            },
+            returning(selector) {
+                const returningConfig = selector ?? true;
+                return {
+                    then(onfulfilled, onrejected) {
+                        return executeUpdate(returningConfig).then(onfulfilled, onrejected);
+                    }
+                };
+            }
+        };
+    }
+    /**
+     * Bulk update multiple records efficiently using PostgreSQL VALUES clause
+     * Updates records matching primary key(s) with provided data
+     * Returns a fluent builder that can be awaited directly or chained with .returning()
+     *
+     * @param data Array of objects with primary key(s) and columns to update
+     * @param config Optional configuration for the bulk update
+     *
+     * @example
+     * ```typescript
+     * // No returning (default) - returns void
+     * await db.users.bulkUpdate([
+     *   { id: 1, age: 30 },
+     *   { id: 2, age: 25 },
+     * ]);
+     *
+     * // With returning() - returns full entities
+     * const updated = await db.users.bulkUpdate([{ id: 1, age: 30 }]).returning();
+     *
+     * // With returning(selector) - returns selected columns
+     * const results = await db.users.bulkUpdate([{ id: 1, age: 30 }])
+     *   .returning(u => ({ id: u.id, age: u.age }));
+     *
+     * // With custom primary key
+     * await db.users.bulkUpdate(
+     *   [{ username: 'alice', age: 31 }],
+     *   { primaryKey: 'username' }
+     * );
+     * ```
      */
-    async update(data, condition) {
+    bulkUpdate(data, config) {
+        const table = this;
+        const executeBulkUpdate = async (returning) => {
+            if (data.length === 0) {
+                return returning === undefined ? undefined : [];
+            }
+            const schema = table._getSchema();
+            // Determine primary keys
+            let primaryKeys = [];
+            if (config?.primaryKey) {
+                primaryKeys = Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey];
+            }
+            else {
+                // Auto-detect from schema
+                for (const [key, colBuilder] of Object.entries(schema.columns)) {
+                    const colConfig = colBuilder.build();
+                    if (colConfig.primaryKey) {
+                        primaryKeys.push(key);
+                    }
+                }
+            }
+            if (primaryKeys.length === 0) {
+                throw new Error('bulkUpdate requires at least one primary key column');
+            }
+            // Validate all records have primary keys
+            for (let i = 0; i < data.length; i++) {
+                for (const pk of primaryKeys) {
+                    if (data[i][pk] === undefined) {
+                        throw new Error(`Record at index ${i} is missing primary key "${pk}"`);
+                    }
+                }
+            }
+            // Calculate chunk size
+            let chunkSize = config?.chunkSize;
+            if (chunkSize == null) {
+                const POSTGRES_MAX_PARAMS = 65535;
+                const referenceItem = data[0];
+                const columnCount = Object.keys(referenceItem).length;
+                const maxRowsPerBatch = Math.floor(POSTGRES_MAX_PARAMS / columnCount);
+                chunkSize = Math.floor(maxRowsPerBatch * 0.6);
+            }
+            // Process in chunks if needed
+            if (data.length > chunkSize) {
+                const allResults = [];
+                for (let i = 0; i < data.length; i += chunkSize) {
+                    const chunk = data.slice(i, i + chunkSize);
+                    const chunkResults = await table.bulkUpdateSingle(chunk, primaryKeys, returning);
+                    if (chunkResults)
+                        allResults.push(...chunkResults);
+                }
+                return returning === undefined ? undefined : allResults;
+            }
+            return table.bulkUpdateSingle(data, primaryKeys, returning);
+        };
+        return {
+            then(onfulfilled, onrejected) {
+                return executeBulkUpdate(undefined).then(onfulfilled, onrejected);
+            },
+            returning(selector) {
+                const returningConfig = selector ?? true;
+                return {
+                    then(onfulfilled, onrejected) {
+                        return executeBulkUpdate(returningConfig).then(onfulfilled, onrejected);
+                    }
+                };
+            }
+        };
+    }
+    /**
+     * Execute a single bulk update batch
+     * @internal
+     */
+    async bulkUpdateSingle(data, primaryKeys, returning) {
         const schema = this._getSchema();
         const executor = this._getExecutor();
         const client = this._getClient();
-        // Build SET clause
+        const qualifiedTableName = this._getQualifiedTableName();
+        const primaryKeySet = new Set(primaryKeys);
+        // Single pass: collect columns and build column info simultaneously
+        const updateColumnsSet = new Set();
+        const allColumnsSet = new Set(primaryKeys);
+        for (const record of data) {
+            for (const key of Object.keys(record)) {
+                if (schema.columns[key]) {
+                    allColumnsSet.add(key);
+                    if (!primaryKeySet.has(key)) {
+                        updateColumnsSet.add(key);
+                    }
+                }
+            }
+        }
+        if (updateColumnsSet.size === 0) {
+            throw new Error('No columns to update (only primary keys provided)');
+        }
+        // Build column info - access config once per column
+        const columnInfoList = [];
+        const valueColumnParts = [];
         const setClauses = [];
-        const values = [];
-        let paramIndex = 1;
-        for (const [key, value] of Object.entries(data)) {
-            const column = schema.columns[key];
-            if (column) {
-                const config = column.build();
-                setClauses.push(`"${config.name}" = $${paramIndex++}`);
-                values.push(value);
+        const whereClauseParts = [];
+        for (const propName of allColumnsSet) {
+            const colConfig = schema.columns[propName].build();
+            const dbName = colConfig.name;
+            const pgType = DbEntityTable.PG_TYPE_MAP[colConfig.type] || colConfig.type;
+            const isPK = primaryKeySet.has(propName);
+            const info = { propName, dbName, pgType, isPK };
+            columnInfoList.push(info);
+            // Build VALUES column list
+            valueColumnParts.push(`"${dbName}"`);
+            if (!isPK) {
+                valueColumnParts.push(`"${dbName}__provided"`);
+                // Build SET clause
+                setClauses.push(`"${dbName}" = CASE WHEN v."${dbName}__provided" THEN v."${dbName}" ELSE t."${dbName}" END`);
+            }
+            else {
+                // Build WHERE clause for PK
+                whereClauseParts.push(`t."${dbName}" = v."${dbName}"`);
             }
         }
-        if (setClauses.length === 0) {
-            throw new Error('No valid columns to update');
+        const valueColumnList = valueColumnParts.join(', ');
+        const whereClause = whereClauseParts.join(' AND ');
+        // Build VALUES clause with parameters - single pass over data
+        const valuesClauses = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const record of data) {
+            const rowValues = [];
+            for (const col of columnInfoList) {
+                const hasKey = col.propName in record;
+                const value = record[col.propName];
+                // Add the value (always cast to correct type for NULL to work in CASE expressions)
+                if (value === undefined || value === null) {
+                    rowValues.push(`NULL::${col.pgType}`);
+                }
+                else {
+                    rowValues.push(`$${paramIndex++}::${col.pgType}`);
+                    params.push(value);
+                }
+                // Add the "was provided" flag for non-PK columns
+                if (!col.isPK) {
+                    rowValues.push(hasKey ? 'true' : 'false');
+                }
+            }
+            valuesClauses.push(`(${rowValues.join(', ')})`);
         }
-        // Build WHERE clause
-        const mockEntity = this.createMockEntity();
-        const whereCondition = condition(mockEntity);
-        const condBuilder = new conditions_1.ConditionBuilder();
-        const { sql: whereSql, params: whereParams } = condBuilder.build(whereCondition, paramIndex);
-        values.push(...whereParams);
         // Build RETURNING clause
-        const returningColumns = Object.entries(schema.columns)
-            .map(([_, col]) => `"${col.build().name}"`)
-            .join(', ');
-        const qualifiedTableName = this._getQualifiedTableName();
-        const sql = `
-      UPDATE ${qualifiedTableName}
-      SET ${setClauses.join(', ')}
-      WHERE ${whereSql}
-      RETURNING ${returningColumns}
-    `;
+        const returningClause = this.buildReturningClause(returning, 't');
+        let sql = `
+UPDATE ${qualifiedTableName} AS t
+SET ${setClauses.join(', ')}
+FROM (VALUES ${valuesClauses.join(', ')}) AS v(${valueColumnList})
+WHERE ${whereClause}`.trim();
+        if (returningClause) {
+            sql += ` RETURNING ${returningClause.sql}`;
+        }
         const result = executor
-            ? await executor.query(sql, values)
-            : await client.query(sql, values);
-        return this.mapResultsToEntities(result.rows);
+            ? await executor.query(sql, params)
+            : await client.query(sql, params);
+        if (!returningClause) {
+            return undefined;
+        }
+        return this.mapReturningResults(result.rows, returning);
     }
     /**
      * Delete records matching condition
@@ -1349,8 +1927,111 @@ class DbEntityTable {
         }
         return mock;
     }
+    /**
+     * Build RETURNING clause SQL based on config
+     * @internal
+     */
+    buildReturningClause(returning, tableAlias) {
+        if (returning === undefined) {
+            return null; // No RETURNING
+        }
+        const schema = this._getSchema();
+        const prefix = tableAlias ? `${tableAlias}.` : '';
+        if (returning === true) {
+            // Return all columns
+            const columns = Object.values(schema.columns).map(col => col.build().name);
+            const sql = columns.map(name => `${prefix}"${name}"`).join(', ');
+            return { sql, columns };
+        }
+        // Selector function - extract selected columns
+        const mockEntity = this.createMockEntity();
+        const selection = returning(mockEntity);
+        if (typeof selection === 'object' && selection !== null) {
+            const columns = [];
+            const sqlParts = [];
+            for (const [alias, field] of Object.entries(selection)) {
+                if (field && typeof field === 'object' && '__dbColumnName' in field) {
+                    const dbName = field.__dbColumnName;
+                    columns.push(alias);
+                    sqlParts.push(`${prefix}"${dbName}" AS "${alias}"`);
+                }
+            }
+            return { sql: sqlParts.join(', '), columns };
+        }
+        // Single field selection
+        if (selection && typeof selection === 'object' && '__dbColumnName' in selection) {
+            const dbName = selection.__dbColumnName;
+            return { sql: `${prefix}"${dbName}"`, columns: [dbName] };
+        }
+        return null;
+    }
+    /**
+     * Map row results based on returning config
+     * @internal
+     */
+    mapReturningResults(rows, returning) {
+        if (returning === true) {
+            // Full entity mapping
+            return this.mapResultsToEntities(rows);
+        }
+        // For selector functions, rows are already in the correct shape
+        // Just apply any type mappers needed
+        const schema = this._getSchema();
+        return rows.map(row => {
+            const mapped = {};
+            for (const [key, value] of Object.entries(row)) {
+                // Try to find column by alias or name
+                const colEntry = Object.entries(schema.columns).find(([propName, col]) => {
+                    const config = col.build();
+                    return propName === key || config.name === key;
+                });
+                if (colEntry) {
+                    const [propName, col] = colEntry;
+                    const config = col.build();
+                    // Apply fromDriver mapper if present
+                    mapped[key] = config.mapper ? config.mapper.fromDriver(value) : value;
+                }
+                else {
+                    mapped[key] = value;
+                }
+            }
+            return mapped;
+        });
+    }
 }
 exports.DbEntityTable = DbEntityTable;
+/** Static type map for PostgreSQL type casting - computed once */
+DbEntityTable.PG_TYPE_MAP = {
+    'smallint': 'smallint',
+    'integer': 'integer',
+    'bigint': 'bigint',
+    'serial': 'integer',
+    'smallserial': 'smallint',
+    'bigserial': 'bigint',
+    'decimal': 'decimal',
+    'numeric': 'numeric',
+    'real': 'real',
+    'double precision': 'double precision',
+    'money': 'money',
+    'varchar': 'varchar',
+    'char': 'char',
+    'text': 'text',
+    'bytea': 'bytea',
+    'timestamp': 'timestamp',
+    'timestamptz': 'timestamptz',
+    'date': 'date',
+    'time': 'time',
+    'timetz': 'timetz',
+    'interval': 'interval',
+    'boolean': 'boolean',
+    'uuid': 'uuid',
+    'json': 'json',
+    'jsonb': 'jsonb',
+    'inet': 'inet',
+    'cidr': 'cidr',
+    'macaddr': 'macaddr',
+    'macaddr8': 'macaddr8',
+};
 /**
  * Base database context with entity-first approach
  */