linkgress-orm 0.0.3 → 0.1.1

package/dist/entity/db-context.d.ts

@@ -3,15 +3,34 @@ import { TableBuilder, TableSchema, InferTableType } from '../schema/table-build
 import { UnwrapDbColumns, InsertData, ExtractDbColumns } from './db-column';
 import { DbEntity, EntityConstructor } from './entity-base';
 import { DbModelConfig } from './model-config';
-import { Condition, SqlFragment } from '../query/conditions';
+import { Condition, SqlFragment, UnwrapSelection, FieldRef } from '../query/conditions';
 import { ResolveCollectionResults, SelectQueryBuilder, QueryBuilder } from '../query/query-builder';
 import { InferRowType } from '../schema/row-type';
 import { DbSchemaManager } from '../migration/db-schema-manager';
 import { DbSequence, SequenceConfig } from '../schema/sequence-builder';
+import type { DbCte } from '../query/cte-builder';
 /**
  * Collection aggregation strategy type
  */
-export type CollectionStrategyType = 'jsonb' | 'temptable';
+export type CollectionStrategyType = 'cte' | 'temptable' | 'lateral';
+/**
+ * Order direction for orderBy clauses
+ */
+export type OrderDirection = 'ASC' | 'DESC';
+/**
+ * A single field that can be used in orderBy.
+ * At runtime, this is analyzed to extract the column reference.
+ * The type is intentionally broad to support various usage patterns.
+ */
+export type OrderableField<T = unknown> = T;
+/**
+ * Order by specification with direction - a tuple of [field, direction]
+ */
+export type OrderByTuple<T = unknown> = [T, OrderDirection];
+/**
+ * Order by selector result - can be a single field, array of fields, or array of [field, direction] tuples
+ */
+export type OrderByResult<T = unknown> = T | T[] | Array<OrderByTuple<T>>;
 /**
  * Query execution options
  */
@@ -24,7 +43,7 @@ export interface QueryOptions {
     logExecutionTime?: boolean;
     /** Log query parameters */
     logParameters?: boolean;
-    /** Collection aggregation strategy (default: 'jsonb') */
+    /** Collection aggregation strategy (default: 'lateral') */
     collectionStrategy?: CollectionStrategyType;
     /**
      * Disable automatic mapper transformations (fromDriver/toDriver).
@@ -125,6 +144,79 @@ export interface UpsertConfig {
      */
     updateColumnFilter?: (columnName: string) => boolean;
 }
+/**
+ * Returning clause configuration
+ * - undefined: no RETURNING clause (returns void)
+ * - true: return all columns
+ * - selector function: return selected columns
+ */
+export type ReturningConfig<TEntity, TResult = unknown> = undefined | true | ((entity: TEntity) => TResult);
+/**
+ * Helper type to infer the result type based on ReturningConfig
+ * Note: Uses conditional types to properly infer return types
+ */
+export type ReturningResult<TEntity, TReturning> = TReturning extends undefined ? void : TReturning extends true ? TEntity : TReturning extends (entity: TEntity) => infer R ? R : TReturning extends (...args: any[]) => infer R ? R : never;
+/**
+ * Base type for returning option - used in method signatures
+ */
+export type ReturningOption<TEntity> = undefined | true | ((entity: TEntity) => any);
+/**
+ * Fluent insert operation that can be awaited directly or chained with .returning()
+ *
+ * @example
+ * ```typescript
+ * // No returning (default) - returns void
+ * await db.users.insert({ username: 'alice' });
+ *
+ * // 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 }));
+ * ```
+ */
+export interface FluentInsert<TEntity extends DbEntity> extends PromiseLike<void> {
+    /** Return all columns from the inserted row */
+    returning(): PromiseLike<UnwrapDbColumns<TEntity>>;
+    /** Return selected columns from the inserted row */
+    returning<TResult>(selector: (entity: EntityQuery<TEntity>) => TResult): PromiseLike<UnwrapDbColumns<TResult>>;
+}
+/**
+ * Fluent insert many operation
+ */
+export interface FluentInsertMany<TEntity extends DbEntity> extends PromiseLike<void> {
+    /** Return all columns from the inserted rows */
+    returning(): PromiseLike<UnwrapDbColumns<TEntity>[]>;
+    /** Return selected columns from the inserted rows */
+    returning<TResult>(selector: (entity: EntityQuery<TEntity>) => TResult): PromiseLike<UnwrapDbColumns<TResult>[]>;
+}
+/**
+ * Fluent update operation
+ */
+export interface FluentUpdate<TEntity extends DbEntity> extends PromiseLike<void> {
+    /** Return all columns from the updated rows */
+    returning(): PromiseLike<UnwrapDbColumns<TEntity>[]>;
+    /** Return selected columns from the updated rows */
+    returning<TResult>(selector: (entity: EntityQuery<TEntity>) => TResult): PromiseLike<UnwrapDbColumns<TResult>[]>;
+}
+/**
+ * Fluent bulk update operation
+ */
+export interface FluentBulkUpdate<TEntity extends DbEntity> extends PromiseLike<void> {
+    /** Return all columns from the updated rows */
+    returning(): PromiseLike<UnwrapDbColumns<TEntity>[]>;
+    /** Return selected columns from the updated rows */
+    returning<TResult>(selector: (entity: EntityQuery<TEntity>) => TResult): PromiseLike<UnwrapDbColumns<TResult>[]>;
+}
+/**
+ * Fluent upsert operation
+ */
+export interface FluentUpsert<TEntity extends DbEntity> extends PromiseLike<void> {
+    /** Return all columns from the upserted rows */
+    returning(): PromiseLike<UnwrapDbColumns<TEntity>[]>;
+    /** Return selected columns from the upserted rows */
+    returning<TResult>(selector: (entity: EntityQuery<TEntity>) => TResult): PromiseLike<UnwrapDbColumns<TResult>[]>;
+}
 /**
  * Insert builder for upsert operations
  */
@@ -141,10 +233,6 @@ export declare class InsertBuilder<TSchema extends TableSchema> {
     private setWhereClause?;
     private overridingSystemValue;
     constructor(schema: TSchema, client: DatabaseClient, executor?: QueryExecutor | undefined);
-    /**
-     * Get qualified table name with schema prefix if specified
-     */
-    private getQualifiedTableName;
     /**
      * Set the values to insert (single row or multiple rows)
      */
@@ -205,24 +293,29 @@ export declare class TableAccessor<TBuilder extends TableBuilder<any>> {
     withQueryOptions(options: QueryOptions): TableAccessor<TBuilder>;
     /**
      * Start a select query with automatic type inference
+     * UnwrapSelection extracts the value types from SqlFragment<T> expressions
      */
-    select<TSelection>(selector: (row: InferRowType<TBuilder>) => TSelection): SelectQueryBuilder<TSelection>;
+    select<TSelection>(selector: (row: InferRowType<TBuilder>) => TSelection): SelectQueryBuilder<UnwrapSelection<TSelection>>;
     /**
      * Add WHERE condition before select
      */
     where(condition: (row: InferRowType<TBuilder>) => Condition): QueryBuilder<TableSchema, InferRowType<TBuilder>>;
+    /**
+     * Add CTEs (Common Table Expressions) to the query
+     */
+    with(...ctes: DbCte<any>[]): SelectQueryBuilder<InferRowType<TBuilder>>;
     /**
      * Left join with another table and selector
      */
     leftJoin<TRight, TSelection>(rightTable: {
         _getSchema: () => TableSchema;
-    } | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: InferRowType<TBuilder>, right: TRight) => Condition, selector: (left: InferRowType<TBuilder>, right: TRight) => TSelection, alias?: string): SelectQueryBuilder<TSelection>;
+    } | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: InferRowType<TBuilder>, right: TRight) => Condition, selector: (left: InferRowType<TBuilder>, right: TRight) => TSelection, alias?: string): SelectQueryBuilder<UnwrapSelection<TSelection>>;
     /**
      * Inner join with another table or subquery and selector
      */
     innerJoin<TRight, TSelection>(rightTable: {
         _getSchema: () => TableSchema;
-    } | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: InferRowType<TBuilder>, right: TRight) => Condition, selector: (left: InferRowType<TBuilder>, right: TRight) => TSelection, alias?: string): SelectQueryBuilder<TSelection>;
+    } | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: InferRowType<TBuilder>, right: TRight) => Condition, selector: (left: InferRowType<TBuilder>, right: TRight) => TSelection, alias?: string): SelectQueryBuilder<UnwrapSelection<TSelection>>;
     /**
      * Get table schema (internal use for joins)
      */
@@ -235,10 +328,6 @@ export declare class TableAccessor<TBuilder extends TableBuilder<any>> {
      * Get table name
      */
     getTableName(): string;
-    /**
-     * Get qualified table name with schema prefix if specified
-     */
-    private getQualifiedTableName;
     /**
      * Insert a row
      */
@@ -365,11 +454,52 @@ export type EntityUpsertConfig<TEntity extends DbEntity> = {
      */
     updateColumnFilter?: (columnName: string) => boolean;
 };
+/**
+ * Type helper to detect if a type is a class instance (has prototype methods)
+ * vs a plain data object. Used to prevent Date, Map, Set, etc. from being
+ * treated as DbEntity.
+ * Excludes DbColumn and SqlFragment which have valueOf but are not value types.
+ */
+type IsClassInstance<T> = T extends {
+    __isDbColumn: true;
+} ? false : T extends SqlFragment<any> ? false : T extends {
+    valueOf(): infer V;
+} ? V extends T ? true : V extends number | string | boolean | bigint | symbol ? true : false : false;
+/**
+ * Check for types with known class method signatures
+ */
+type HasClassMethods<T> = T extends {
+    getTime(): number;
+} ? true : T extends {
+    size: number;
+    has(value: any): boolean;
+} ? true : T extends {
+    byteLength: number;
+} ? true : T extends {
+    then(onfulfilled?: any): any;
+} ? true : T extends {
+    message: string;
+    name: string;
+} ? true : T extends {
+    exec(string: string): any;
+} ? true : false;
+/**
+ * Combined check for value types that should not be treated as DbEntity
+ */
+type IsValueType<T> = IsClassInstance<T> extends true ? true : HasClassMethods<T> extends true ? true : false;
+/**
+ * Type helper to convert plain object values to FieldRefs for use in conditions
+ * This is used when TSelection is not a DbEntity but needs to be used in where/join conditions
+ */
+type ToFieldRefs<T> = T extends object ? IsValueType<T> extends true ? FieldRef<string, T> : {
+    [K in keyof T]: FieldRef<string, T[K]>;
+} : FieldRef<string, T>;
 /**
  * Type helper to build entity query type with navigation support
+ * Preserves class instances (Date, Map, Set, etc.) as-is without recursively mapping them
  */
 export type EntityQuery<TEntity extends DbEntity> = {
-    [K in keyof TEntity]: TEntity[K] extends (infer U)[] | undefined ? U extends DbEntity ? EntityCollectionQuery<U> : TEntity[K] : TEntity[K] extends DbEntity | undefined ? EntityQuery<NonNullable<TEntity[K]>> : TEntity[K];
+    [K in keyof TEntity]: TEntity[K] extends (infer U)[] | undefined ? U extends DbEntity ? EntityCollectionQuery<U> : TEntity[K] : IsValueType<NonNullable<TEntity[K]>> extends true ? TEntity[K] : TEntity[K] extends DbEntity | undefined ? EntityQuery<NonNullable<TEntity[K]>> : TEntity[K];
 };
 /**
  * Collection query builder type for navigation collections
@@ -377,10 +507,10 @@ export type EntityQuery<TEntity extends DbEntity> = {
 export interface EntityCollectionQuery<TEntity extends DbEntity> {
     select<TSelection>(selector: (item: EntityQuery<TEntity>) => TSelection): EntityCollectionQueryWithSelect<TEntity, TSelection>;
     selectDistinct<TSelection>(selector: (item: EntityQuery<TEntity>) => TSelection): EntityCollectionQueryWithSelect<TEntity, TSelection>;
-    where(condition: (item: EntityQuery<TEntity>) => any): this;
-    orderBy(selector: (item: EntityQuery<TEntity>) => any): this;
-    orderBy(selector: (item: EntityQuery<TEntity>) => any[]): this;
-    orderBy(selector: (item: EntityQuery<TEntity>) => Array<[any, 'ASC' | 'DESC']>): this;
+    where(condition: (item: EntityQuery<TEntity>) => Condition): this;
+    orderBy<T>(selector: (item: EntityQuery<TEntity>) => T): this;
+    orderBy<T>(selector: (item: EntityQuery<TEntity>) => T[]): this;
+    orderBy<T>(selector: (item: EntityQuery<TEntity>) => Array<[T, OrderDirection]>): this;
     limit(count: number): this;
     offset(count: number): this;
     min<TSelection>(selector: (item: EntityQuery<TEntity>) => TSelection): SqlFragment<number | null>;
@@ -392,10 +522,10 @@ export interface EntityCollectionQuery<TEntity extends DbEntity> {
     toList(asName: string): TEntity[];
 }
 export interface EntityCollectionQueryWithSelect<TEntity extends DbEntity, TSelection> {
-    where(condition: (item: EntityQuery<TEntity>) => any): this;
-    orderBy(selector: (item: TSelection) => any): this;
-    orderBy(selector: (item: TSelection) => any[]): this;
-    orderBy(selector: (item: TSelection) => Array<[any, 'ASC' | 'DESC']>): this;
+    where(condition: (item: EntityQuery<TEntity>) => Condition): this;
+    orderBy<T>(selector: (item: TSelection) => T): this;
+    orderBy<T>(selector: (item: TSelection) => T[]): this;
+    orderBy<T>(selector: (item: TSelection) => Array<[T, OrderDirection]>): this;
     limit(count: number): this;
     offset(count: number): this;
     min(): Promise<TSelection | null>;
@@ -406,25 +536,101 @@ export interface EntityCollectionQueryWithSelect<TEntity extends DbEntity, TSele
     toStringList(asName?: string): string[];
     toList(asName: string): TSelection[];
 }
+/**
+ * Interface for queryable entity collections that can be filtered with .where()
+ * Use this type when you need to store a query in a variable and add more .where() conditions.
+ *
+ * @example
+ * ```typescript
+ * let query: IEntityQueryable<User> = db.users;
+ * if (onlyActive) {
+ *   query = query.where(u => eq(u.isActive, true));
+ * }
+ * if (minAge) {
+ *   query = query.where(u => gte(u.age, minAge));
+ * }
+ * const results = await query.toList();
+ * ```
+ */
+export interface IEntityQueryable<TEntity extends DbEntity> {
+    /**
+     * Add a WHERE condition. Multiple where() calls are chained with AND logic.
+     */
+    where(condition: (entity: EntityQuery<TEntity>) => Condition): IEntityQueryable<TEntity>;
+    /**
+     * Select specific fields from the entity
+     */
+    select<TSelection>(selector: (entity: EntityQuery<TEntity>) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Order by field(s)
+     */
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => T): IEntityQueryable<TEntity>;
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => T[]): IEntityQueryable<TEntity>;
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => Array<[T, OrderDirection]>): IEntityQueryable<TEntity>;
+    /**
+     * Limit results
+     */
+    limit(count: number): IEntityQueryable<TEntity>;
+    /**
+     * Offset results
+     */
+    offset(count: number): IEntityQueryable<TEntity>;
+    /**
+     * Add CTEs (Common Table Expressions) to the query
+     */
+    with(...ctes: import('../query/cte-builder').DbCte<any>[]): IEntityQueryable<TEntity>;
+    /**
+     * Left join with another table, CTE, or subquery
+     */
+    leftJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    leftJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    leftJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: EntityQuery<TEntity>, right: ToFieldRefs<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Inner join with another table, CTE, or subquery
+     */
+    innerJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    innerJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    innerJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: EntityQuery<TEntity>, right: ToFieldRefs<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Execute query and return all results
+     */
+    toList(): Promise<UnwrapDbColumns<TEntity>[]>;
+    /**
+     * Execute query and return first result
+     */
+    first(): Promise<UnwrapDbColumns<TEntity>>;
+    /**
+     * Execute query and return first result or null if not found
+     */
+    firstOrDefault(): Promise<UnwrapDbColumns<TEntity> | null>;
+    /**
+     * Count matching records
+     */
+    count(): Promise<number>;
+}
 /**
  * Strongly-typed query builder for entities
- * Results automatically unwrap DbColumn<T> to T
+ * Results automatically unwrap DbColumn<T> to T and SqlFragment<T> to T
  */
 export interface EntitySelectQueryBuilder<TEntity extends DbEntity, TSelection> {
-    select<TNewSelection>(selector: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TNewSelection): EntitySelectQueryBuilder<TEntity, TNewSelection>;
-    selectDistinct<TNewSelection>(selector: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TNewSelection): EntitySelectQueryBuilder<TEntity, TNewSelection>;
-    where(condition: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => any): EntitySelectQueryBuilder<TEntity, TSelection>;
-    orderBy(selector: (row: TSelection) => any): EntitySelectQueryBuilder<TEntity, TSelection>;
-    orderBy(selector: (row: TSelection) => any[]): EntitySelectQueryBuilder<TEntity, TSelection>;
-    orderBy(selector: (row: TSelection) => Array<[any, 'ASC' | 'DESC']>): EntitySelectQueryBuilder<TEntity, TSelection>;
+    select<TNewSelection>(selector: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TNewSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    selectDistinct<TNewSelection>(selector: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TNewSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    where(condition: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>) => Condition): EntitySelectQueryBuilder<TEntity, TSelection>;
+    orderBy<T>(selector: (row: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => T): EntitySelectQueryBuilder<TEntity, TSelection>;
+    orderBy<T>(selector: (row: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => T[]): EntitySelectQueryBuilder<TEntity, TSelection>;
+    orderBy<T>(selector: (row: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => Array<[T, OrderDirection]>): EntitySelectQueryBuilder<TEntity, TSelection>;
     limit(count: number): EntitySelectQueryBuilder<TEntity, TSelection>;
     offset(count: number): EntitySelectQueryBuilder<TEntity, TSelection>;
     count(): Promise<number>;
     first(): Promise<ResolveCollectionResults<TSelection>>;
     firstOrDefault(): Promise<ResolveCollectionResults<TSelection> | null>;
     firstOrThrow(): Promise<ResolveCollectionResults<TSelection>>;
-    leftJoin<TRight extends DbEntity | Record<string, any>, TNewSelection>(rightTable: DbEntityTable<TRight extends DbEntity ? TRight : never> | import('../query/subquery').Subquery<TRight, 'table'> | import('../query/cte-builder').DbCte<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight extends DbEntity ? (EntityQuery<TRight> | TRight) : TRight) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight extends DbEntity ? (EntityQuery<TRight> | TRight) : TRight) => TNewSelection, alias?: string): EntitySelectQueryBuilder<TEntity, TNewSelection>;
-    innerJoin<TRight extends DbEntity | Record<string, any>, TNewSelection>(rightTable: DbEntityTable<TRight extends DbEntity ? TRight : never> | import('../query/subquery').Subquery<TRight, 'table'> | import('../query/cte-builder').DbCte<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight extends DbEntity ? (EntityQuery<TRight> | TRight) : TRight) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight extends DbEntity ? (EntityQuery<TRight> | TRight) : TRight) => TNewSelection, alias?: string): EntitySelectQueryBuilder<TEntity, TNewSelection>;
+    leftJoin<TRight extends Record<string, any>, TNewSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: ToFieldRefs<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight) => TNewSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    leftJoin<TRight extends Record<string, any>, TNewSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: ToFieldRefs<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight) => TNewSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    leftJoin<TRight extends DbEntity, TNewSelection>(rightTable: DbEntityTable<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: EntityQuery<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: EntityQuery<TRight>) => TNewSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    innerJoin<TRight extends Record<string, any>, TNewSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: ToFieldRefs<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight) => TNewSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    innerJoin<TRight extends Record<string, any>, TNewSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: ToFieldRefs<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: TRight) => TNewSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
+    innerJoin<TRight extends DbEntity, TNewSelection>(rightTable: DbEntityTable<TRight>, condition: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : ToFieldRefs<TSelection>, right: EntityQuery<TRight>) => Condition, selector: (left: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, right: EntityQuery<TRight>) => TNewSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TNewSelection>>;
     groupBy<TGroupingKey>(selector: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TGroupingKey): import('../query/grouped-query').GroupedQueryBuilder<TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection, TGroupingKey>;
     min<TResult = TSelection>(selector?: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TResult): Promise<TResult | null>;
     max<TResult = TSelection>(selector?: (entity: TSelection extends DbEntity ? EntityQuery<TSelection> : TSelection) => TResult): Promise<TResult | null>;
@@ -514,6 +720,15 @@ export declare class DbEntityTable<TEntity extends DbEntity> {
      * Select all records - returns full entities with unwrapped DbColumns
      */
     toList(): Promise<UnwrapDbColumns<TEntity>[]>;
+    /**
+     * Get first record
+     * @throws Error if no records exist
+     */
+    first(): Promise<UnwrapDbColumns<TEntity>>;
+    /**
+     * Get first record or null if none exist
+     */
+    firstOrDefault(): Promise<UnwrapDbColumns<TEntity> | null>;
     /**
      * Count all records
      */
@@ -521,21 +736,22 @@ export declare class DbEntityTable<TEntity extends DbEntity> {
     /**
      * Order by field(s)
      */
-    orderBy(selector: (row: TEntity) => any): EntitySelectQueryBuilder<TEntity, TEntity>;
-    orderBy(selector: (row: TEntity) => any[]): EntitySelectQueryBuilder<TEntity, TEntity>;
-    orderBy(selector: (row: TEntity) => Array<[any, 'ASC' | 'DESC']>): EntitySelectQueryBuilder<TEntity, TEntity>;
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => T): IEntityQueryable<TEntity>;
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => T[]): IEntityQueryable<TEntity>;
+    orderBy<T>(selector: (row: EntityQuery<TEntity>) => Array<[T, OrderDirection]>): IEntityQueryable<TEntity>;
     /**
      * Limit results
      */
-    limit(count: number): EntitySelectQueryBuilder<TEntity, TEntity>;
+    limit(count: number): IEntityQueryable<TEntity>;
     /**
      * Offset results
      */
-    offset(count: number): EntitySelectQueryBuilder<TEntity, TEntity>;
+    offset(count: number): IEntityQueryable<TEntity>;
     /**
      * Select query
+     * UnwrapSelection extracts the value types from SqlFragment<T> expressions
      */
-    select<TSelection>(selector: (entity: EntityQuery<TEntity>) => TSelection): EntitySelectQueryBuilder<TEntity, TSelection>;
+    select<TSelection>(selector: (entity: EntityQuery<TEntity>) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
     /**
      * Select distinct
      */
@@ -543,37 +759,133 @@ export declare class DbEntityTable<TEntity extends DbEntity> {
     /**
      * Where query - returns all columns by default
      */
-    where(condition: (entity: EntityQuery<TEntity>) => any): EntitySelectQueryBuilder<TEntity, TEntity>;
+    where(condition: (entity: EntityQuery<TEntity>) => Condition): IEntityQueryable<TEntity>;
     /**
-     * Left join with another table or subquery and selector
+     * Add CTEs (Common Table Expressions) to the query
      */
-    leftJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight> | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight> | TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight> | TRight) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, TSelection>;
+    with(...ctes: DbCte<any>[]): IEntityQueryable<TEntity>;
     /**
-     * Inner join with another table or subquery and selector
+     * Left join with another table (DbEntity)
+     */
+    leftJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Left join with a subquery (plain object result, not DbEntity)
+     */
+    leftJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Left join with a CTE
+     */
+    leftJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: EntityQuery<TEntity>, right: ToFieldRefs<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Inner join with another table (DbEntity)
      */
-    innerJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight> | import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight> | TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight> | TRight) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, TSelection>;
+    innerJoin<TRight extends DbEntity, TSelection>(rightTable: DbEntityTable<TRight>, condition: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: EntityQuery<TRight>) => TSelection, alias?: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Inner join with a subquery (plain object result, not DbEntity)
+     */
+    innerJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/subquery').Subquery<TRight, 'table'>, condition: (left: EntityQuery<TEntity>, right: TRight) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection, alias: string): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
+    /**
+     * Inner join with a CTE
+     */
+    innerJoin<TRight extends Record<string, any>, TSelection>(rightTable: import('../query/cte-builder').DbCte<TRight>, condition: (left: EntityQuery<TEntity>, right: ToFieldRefs<TRight>) => Condition, selector: (left: EntityQuery<TEntity>, right: TRight) => TSelection): EntitySelectQueryBuilder<TEntity, UnwrapSelection<TSelection>>;
     /**
      * 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 }));
+     * ```
      */
-    insert(data: InsertData<TEntity>): Promise<UnwrapDbColumns<TEntity>>;
+    insert(data: InsertData<TEntity>): FluentInsert<TEntity>;
     /**
      * 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 }));
+     * ```
      */
-    insertMany(data: InsertData<TEntity>[]): Promise<UnwrapDbColumns<TEntity>[]>;
+    insertMany(data: InsertData<TEntity>[]): FluentInsertMany<TEntity>;
     /**
      * 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();
+     * ```
      */
-    upsert(data: InsertData<TEntity>[], config?: EntityUpsertConfig<TEntity>): Promise<UnwrapDbColumns<TEntity>[]>;
+    upsert(data: InsertData<TEntity>[], config?: EntityUpsertConfig<TEntity>): FluentUpsert<TEntity>;
     /**
      * 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 });
+     * ```
      */
-    insertBulk(value: InsertData<TEntity> | InsertData<TEntity>[], insertConfig?: InsertConfig): Promise<UnwrapDbColumns<TEntity>[]>;
+    insertBulk(value: InsertData<TEntity> | InsertData<TEntity>[], options?: InsertConfig): FluentInsertMany<TEntity>;
+    /**
+     * Execute a single bulk insert batch
+     * @internal
+     */
+    private insertBulkSingle;
     /**
      * 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 }));
+     * ```
      */
-    upsertBulk(values: InsertData<TEntity>[], config?: EntityUpsertConfig<TEntity>): Promise<UnwrapDbColumns<TEntity>[]>;
+    upsertBulk(values: InsertData<TEntity>[], config?: EntityUpsertConfig<TEntity>): FluentUpsert<TEntity>;
+    /**
+     * Execute a single upsert batch
+     * @internal
+     */
+    private upsertBulkSingle;
     /**
      * Map database column names back to property names
      */
@@ -592,9 +904,65 @@ export declare class DbEntityTable<TEntity extends DbEntity> {
     values(data: InsertData<TEntity> | InsertData<TEntity>[]): EntityInsertBuilder<TEntity>;
     /**
      * 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: Partial<InsertData<TEntity>>, condition: (entity: EntityQuery<TEntity>) => Condition): Promise<UnwrapDbColumns<TEntity>[]>;
+    update(data: Partial<InsertData<TEntity>>, condition: (entity: EntityQuery<TEntity>) => Condition): FluentUpdate<TEntity>;
+    /**
+     * 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' }
+     * );
+     * ```
+     */
+    bulkUpdate(data: Array<Partial<InsertData<TEntity>> & Record<string, any>>, config?: {
+        /** Primary key column(s) to match records. Auto-detected if not specified */
+        primaryKey?: string | string[];
+        /** Chunk size for large batches. Auto-calculated if not specified */
+        chunkSize?: number;
+    }): FluentBulkUpdate<TEntity>;
+    /** Static type map for PostgreSQL type casting - computed once */
+    private static readonly PG_TYPE_MAP;
+    /**
+     * Execute a single bulk update batch
+     * @internal
+     */
+    private bulkUpdateSingle;
     /**
      * Delete records matching condition
      * Usage: db.users.delete(u => eq(u.id, 1))
@@ -604,6 +972,16 @@ export declare class DbEntityTable<TEntity extends DbEntity> {
      * Create a mock entity for type inference in lambdas
      */
     private createMockEntity;
+    /**
+     * Build RETURNING clause SQL based on config
+     * @internal
+     */
+    private buildReturningClause;
+    /**
+     * Map row results based on returning config
+     * @internal
+     */
+    private mapReturningResults;
 }
 /**
  * Base database context with entity-first approach
@@ -680,4 +1058,5 @@ export declare abstract class DatabaseContext extends DataContext {
      */
     protected table<TEntity extends DbEntity>(entityClass: EntityConstructor<TEntity>): DbEntityTable<TEntity>;
 }
+export {};
 //# sourceMappingURL=db-context.d.ts.map