metal-orm 1.0.58 → 1.0.60

package/src/query-builder/select.ts

@@ -14,7 +14,6 @@ import {
   notExists,
   OperandNode
 } from '../core/ast/expression.js';
-import { derivedTable, fnTable } from '../core/ast/builders.js';
 import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 
@@ -28,20 +27,31 @@ import {
   SelectQueryBuilderDependencies,
   SelectQueryBuilderEnvironment
 } from './select-query-builder-deps.js';
-import { QueryAstService } from './query-ast-service.js';
 import { ColumnSelector } from './column-selector.js';
-import { RelationManager } from './relation-manager.js';
-import { RelationIncludeOptions } from './relation-types.js';
-import { RelationKinds, type RelationDef } from '../schema/relation.js';
+import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
+import { RelationKinds } from '../schema/relation.js';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
-import { EntityInstance, RelationMap, RelationTargetTable } from '../schema/types.js';
+import { EntityInstance, RelationMap } from '../schema/types.js';
 import { OrmSession } from '../orm/orm-session.ts';
 import { ExecutionContext } from '../orm/execution-context.js';
 import { HydrationContext } from '../orm/hydration-context.js';
 import { executeHydrated, executeHydratedWithContexts } from '../orm/execute.js';
-import { createJoinNode } from '../core/ast/join-node.js';
 import { resolveSelectQuery } from './query-resolution.js';
-
+import {
+  applyOrderBy,
+  buildWhereHasPredicate,
+  executeCount,
+  executePagedQuery,
+  RelationCallback,
+  WhereHasOptions
+} from './select/select-operations.js';
+import { SelectFromFacet } from './select/from-facet.js';
+import { SelectJoinFacet } from './select/join-facet.js';
+import { SelectProjectionFacet } from './select/projection-facet.js';
+import { SelectPredicateFacet } from './select/predicate-facet.js';
+import { SelectCTEFacet } from './select/cte-facet.js';
+import { SelectSetOpFacet } from './select/setop-facet.js';
+import { SelectRelationFacet } from './select/relation-facet.js';
 
 type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
 
@@ -56,15 +66,6 @@ type DeepSelectEntry<TTable extends TableDef> = {
 
 type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
 
-type WhereHasOptions = {
-  correlate?: ExpressionNode;
-};
-
-type RelationCallback = <TChildTable extends TableDef>(
-  qb: SelectQueryBuilder<unknown, TChildTable>
-) => SelectQueryBuilder<unknown, TChildTable>;
-
-
 /**
  * Main query builder class for constructing SQL SELECT queries
  * @typeParam T - Result type for projections (unused)
@@ -74,7 +75,13 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   private readonly env: SelectQueryBuilderEnvironment;
   private readonly context: SelectQueryBuilderContext;
   private readonly columnSelector: ColumnSelector;
-  private readonly relationManager: RelationManager;
+  private readonly fromFacet: SelectFromFacet;
+  private readonly joinFacet: SelectJoinFacet;
+  private readonly projectionFacet: SelectProjectionFacet;
+  private readonly predicateFacet: SelectPredicateFacet;
+  private readonly cteFacet: SelectCTEFacet;
+  private readonly setOpFacet: SelectSetOpFacet;
+  private readonly relationFacet: SelectRelationFacet;
   private readonly lazyRelations: Set<string>;
   private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
 
@@ -95,6 +102,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
+    const createAstService = (nextState: SelectQueryState) => deps.createQueryAstService(table, nextState);
     const initialState = state ?? deps.createState(table);
     const initialHydration = hydration ?? deps.createHydration(table);
     this.context = {
@@ -104,7 +112,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     this.lazyRelations = new Set(lazyRelations ?? []);
     this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
     this.columnSelector = deps.createColumnSelector(this.env);
-    this.relationManager = deps.createRelationManager(this.env);
+    const relationManager = deps.createRelationManager(this.env);
+    this.fromFacet = new SelectFromFacet(this.env, createAstService);
+    this.joinFacet = new SelectJoinFacet(this.env, createAstService);
+    this.projectionFacet = new SelectProjectionFacet(this.columnSelector);
+    this.predicateFacet = new SelectPredicateFacet(this.env, createAstService);
+    this.cteFacet = new SelectCTEFacet(this.env, createAstService);
+    this.setOpFacet = new SelectSetOpFacet(this.env, createAstService);
+    this.relationFacet = new SelectRelationFacet(relationManager);
   }
 
   /**
@@ -131,19 +146,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   /**
    * Applies an alias to the root FROM table.
    * @param alias - Alias to apply
+   * @example
+   * const qb = new SelectQueryBuilder(userTable).as('u');
    */
   as(alias: string): SelectQueryBuilder<T, TTable> {
-    const from = this.context.state.ast.from;
-    if (from.type !== 'Table') {
-      throw new Error('Cannot alias non-table FROM sources');
-    }
-    const nextFrom = { ...from, alias };
-    const nextContext = this.applyAst(this.context, service => service.withFrom(nextFrom));
+    const nextContext = this.fromFacet.as(this.context, alias);
     return this.clone(nextContext);
   }
 
-
-
   /**
    * Applies correlation expression to the query AST
    * @param ast - Query AST to modify
@@ -168,39 +178,6 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     return new SelectQueryBuilder(table, undefined, undefined, this.env.deps);
   }
 
-  /**
-   * Applies an AST mutation using the query AST service
-   * @param context - Current query context
-   * @param mutator - Function that mutates the AST
-   * @returns Updated query context
-   */
-  private applyAst(
-    context: SelectQueryBuilderContext,
-    mutator: (service: QueryAstService) => SelectQueryState
-  ): SelectQueryBuilderContext {
-    const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
-    const nextState = mutator(astService);
-    return { state: nextState, hydration: context.hydration };
-  }
-
-  /**
-   * Applies a join to the query context
-   * @param context - Current query context
-   * @param table - Table to join
-   * @param condition - Join condition
-   * @param kind - Join kind
-   * @returns Updated query context with join applied
-   */
-  private applyJoin(
-    context: SelectQueryBuilderContext,
-    table: TableDef,
-    condition: BinaryExpressionNode,
-    kind: JoinKind
-  ): SelectQueryBuilderContext {
-    const joinNode = createJoinNode(kind, { type: 'Table', name: table.name, schema: table.schema }, condition);
-    return this.applyAst(context, service => service.withJoin(joinNode));
-  }
-
   /**
    * Applies a set operation to the query
    * @param operator - Set operation kind
@@ -212,15 +189,23 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
   ): SelectQueryBuilderContext {
     const subAst = resolveSelectQuery(query);
-    return this.applyAst(this.context, service => service.withSetOperation(operator, subAst));
+    return this.setOpFacet.applySetOperation(this.context, operator, subAst);
   }
 
-
   /**
    * Selects columns for the query (unified overloaded method).
    * Can be called with column names or a projection object.
    * @param args - Column names or projection object
    * @returns New query builder instance with selected columns
+   * @example
+   * // Select specific columns
+   * qb.select('id', 'name', 'email');
+   * @example
+   * // Select with aliases and expressions
+   * qb.select({
+   *   id: userTable.columns.id,
+   *   fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
+   * });
    */
   select<K extends keyof TTable['columns'] & string>(
     ...args: K[]
@@ -232,7 +217,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     // If first arg is an object (not a string), treat as projection map
     if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null && typeof args[0] !== 'string') {
       const columns = args[0] as Record<string, ColumnSelectionValue>;
-      return this.clone(this.columnSelector.select(this.context, columns));
+      return this.clone(this.projectionFacet.select(this.context, columns));
     }
 
     // Otherwise, treat as column names
@@ -246,16 +231,18 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
       selection[key] = col;
     }
 
-    return this.clone(this.columnSelector.select(this.context, selection));
+    return this.clone(this.projectionFacet.select(this.context, selection));
   }
 
   /**
    * Selects raw column expressions
    * @param cols - Column expressions as strings
    * @returns New query builder instance with raw column selections
+   * @example
+   * qb.selectRaw('COUNT(*) as total', 'UPPER(name) as upper_name');
    */
   selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable> {
-    return this.clone(this.columnSelector.selectRaw(this.context, cols));
+    return this.clone(this.projectionFacet.selectRaw(this.context, cols));
   }
 
   /**
@@ -264,10 +251,16 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param query - Query builder or query node for the CTE
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the CTE
+   * @example
+   * const recentUsers = new SelectQueryBuilder(userTable)
+   *   .where(gt(userTable.columns.createdAt, subDays(now(), 30)));
+   * const qb = new SelectQueryBuilder(userTable)
+   *   .with('recent_users', recentUsers)
+   *   .from('recent_users');
    */
   with<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable> {
     const subAst = resolveSelectQuery(query);
-    const nextContext = this.applyAst(this.context, service => service.withCte(name, subAst, columns, false));
+    const nextContext = this.cteFacet.withCTE(this.context, name, subAst, columns, false);
     return this.clone(nextContext);
   }
 
@@ -277,10 +270,23 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param query - Query builder or query node for the CTE
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the recursive CTE
+   * @example
+   * // Base case: select root nodes
+   * const baseQuery = new SelectQueryBuilder(orgTable)
+   *   .where(eq(orgTable.columns.parentId, 1));
+   * // Recursive case: join with the CTE itself
+   * const recursiveQuery = new SelectQueryBuilder(orgTable)
+   *   .join('org_hierarchy', 'oh', eq(orgTable.columns.parentId, col('oh.id')));
+   * // Combine base and recursive parts
+   * const orgHierarchy = baseQuery.union(recursiveQuery);
+   * // Use in main query
+   * const qb = new SelectQueryBuilder(orgTable)
+   *   .withRecursive('org_hierarchy', orgHierarchy)
+   *   .from('org_hierarchy');
    */
   withRecursive<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable> {
     const subAst = resolveSelectQuery(query);
-    const nextContext = this.applyAst(this.context, service => service.withCte(name, subAst, columns, true));
+    const nextContext = this.cteFacet.withCTE(this.context, name, subAst, columns, true);
     return this.clone(nextContext);
   }
 
@@ -290,6 +296,11 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param alias - Alias for the derived table
    * @param columnAliases - Optional column alias list
    * @returns New query builder instance with updated FROM
+   * @example
+   * const subquery = new SelectQueryBuilder(userTable)
+   *   .select('id', 'name')
+   *   .where(gt(userTable.columns.score, 100));
+   * qb.fromSubquery(subquery, 'high_scorers', ['userId', 'userName']);
    */
   fromSubquery<TSub extends TableDef>(
     subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
@@ -297,8 +308,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     columnAliases?: string[]
   ): SelectQueryBuilder<T, TTable> {
     const subAst = resolveSelectQuery(subquery);
-    const fromNode = derivedTable(subAst, alias, columnAliases);
-    const nextContext = this.applyAst(this.context, service => service.withFrom(fromNode));
+    const nextContext = this.fromFacet.fromSubquery(this.context, subAst, alias, columnAliases);
     return this.clone(nextContext);
   }
 
@@ -308,6 +318,13 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param args - Optional function arguments
    * @param alias - Optional alias for the function table
    * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
+   * @example
+   * qb.fromFunctionTable(
+   *   'generate_series',
+   *   [literal(1), literal(10), literal(1)],
+   *   'series',
+   *   { columnAliases: ['value'] }
+   * );
    */
   fromFunctionTable(
     name: string,
@@ -315,8 +332,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     alias?: string,
     options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
   ): SelectQueryBuilder<T, TTable> {
-    const functionTable = fnTable(name, args, alias, options);
-    const nextContext = this.applyAst(this.context, service => service.withFrom(functionTable));
+    const nextContext = this.fromFacet.fromFunctionTable(this.context, name, args, alias, options);
     return this.clone(nextContext);
   }
 
@@ -325,10 +341,16 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param alias - Alias for the subquery column
    * @param sub - Query builder or query node for the subquery
    * @returns New query builder instance with the subquery selection
+   * @example
+   * const postCount = new SelectQueryBuilder(postTable)
+   *   .select(count(postTable.columns.id))
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.select('id', 'name')
+   *   .selectSubquery('postCount', postCount);
    */
   selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     const query = resolveSelectQuery(sub);
-    return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
+    return this.clone(this.projectionFacet.selectSubquery(this.context, alias, query));
   }
 
   /**
@@ -339,6 +361,15 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param joinKind - Join kind (defaults to INNER)
    * @param columnAliases - Optional column alias list for the derived table
    * @returns New query builder instance with the derived-table join
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * qb.joinSubquery(
+   *   activeUsers,
+   *   'au',
+   *   eq(col('t.userId'), col('au.id')),
+   *   JOIN_KINDS.LEFT
+   * );
    */
   joinSubquery<TSub extends TableDef>(
     subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
@@ -348,8 +379,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     columnAliases?: string[]
   ): SelectQueryBuilder<T, TTable> {
     const subAst = resolveSelectQuery(subquery);
-    const joinNode = createJoinNode(joinKind, derivedTable(subAst, alias, columnAliases), condition);
-    const nextContext = this.applyAst(this.context, service => service.withJoin(joinNode));
+    const nextContext = this.joinFacet.joinSubquery(this.context, subAst, alias, condition, joinKind, columnAliases);
     return this.clone(nextContext);
   }
 
@@ -361,6 +391,15 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param condition - Join condition expression
    * @param joinKind - Kind of join (defaults to INNER)
    * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
+   * @example
+   * qb.joinFunctionTable(
+   *   'generate_series',
+   *   [literal(1), literal(10)],
+   *   'gs',
+   *   eq(col('t.value'), col('gs.value')),
+   *   JOIN_KINDS.INNER,
+   *   { columnAliases: ['value'] }
+   * );
    */
   joinFunctionTable(
     name: string,
@@ -370,9 +409,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     joinKind: JoinKind = JOIN_KINDS.INNER,
     options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
   ): SelectQueryBuilder<T, TTable> {
-    const functionTable = fnTable(name, args, alias, options);
-    const joinNode = createJoinNode(joinKind, functionTable, condition);
-    const nextContext = this.applyAst(this.context, service => service.withJoin(joinNode));
+    const nextContext = this.joinFacet.joinFunctionTable(this.context, name, args, alias, condition, joinKind, options);
     return this.clone(nextContext);
   }
 
@@ -381,9 +418,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the INNER JOIN
+   * @example
+   * qb.innerJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
     return this.clone(nextContext);
   }
 
@@ -392,9 +434,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the LEFT JOIN
+   * @example
+   * qb.leftJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
     return this.clone(nextContext);
   }
 
@@ -403,9 +450,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param table - Table to join
    * @param condition - Join condition expression
    * @returns New query builder instance with the RIGHT JOIN
+   * @example
+   * qb.rightJoin(
+   *   postTable,
+   *   eq(userTable.columns.id, postTable.columns.userId)
+   * );
    */
   rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
     return this.clone(nextContext);
   }
 
@@ -414,12 +466,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param relationName - Name of the relationship to match
    * @param predicate - Optional predicate expression
    * @returns New query builder instance with the relationship match
+   * @example
+   * qb.match('posts', eq(postTable.columns.published, true));
    */
   match<K extends keyof TTable['relations'] & string>(
     relationName: K,
     predicate?: ExpressionNode
   ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationManager.match(this.context, relationName, predicate);
+    const nextContext = this.relationFacet.match(this.context, relationName, predicate);
     return this.clone(nextContext);
   }
 
@@ -429,13 +483,17 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param joinKind - Type of join (defaults to INNER)
    * @param extraCondition - Optional additional join condition
    * @returns New query builder instance with the relationship join
+   * @example
+   * qb.joinRelation('posts', JOIN_KINDS.LEFT);
+   * @example
+   * qb.joinRelation('posts', JOIN_KINDS.INNER, eq(postTable.columns.published, true));
    */
   joinRelation<K extends keyof TTable['relations'] & string>(
     relationName: K,
     joinKind: JoinKind = JOIN_KINDS.INNER,
     extraCondition?: ExpressionNode
   ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationManager.joinRelation(this.context, relationName, joinKind, extraCondition);
+    const nextContext = this.relationFacet.joinRelation(this.context, relationName, joinKind, extraCondition);
     return this.clone(nextContext);
   }
 
@@ -444,12 +502,21 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param relationName - Name of the relationship to include
    * @param options - Optional include options
    * @returns New query builder instance with the relationship inclusion
+   * @example
+   * qb.include('posts');
+   * @example
+   * qb.include('posts', { columns: ['id', 'title', 'published'] });
+   * @example
+   * qb.include('posts', {
+   *   columns: ['id', 'title'],
+   *   where: eq(postTable.columns.published, true)
+   * });
    */
   include<K extends keyof TTable['relations'] & string>(
     relationName: K,
-    options?: RelationIncludeOptions
+    options?: TypedRelationIncludeOptions<TTable['relations'][K]>
   ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationManager.include(this.context, relationName, options);
+    const nextContext = this.relationFacet.include(this.context, relationName, options);
     return this.clone(nextContext);
   }
 
@@ -458,54 +525,64 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param relationName - Name of the relation to include lazily
    * @param options - Optional include options for lazy loading
    * @returns New query builder instance with lazy relation inclusion
+   * @example
+   * const qb = new SelectQueryBuilder(userTable).includeLazy('posts');
+   * const users = await qb.execute(session);
+   * // Access posts later - they will be loaded on demand
+   * const posts = await users[0].posts;
    */
-  includeLazy<K extends keyof RelationMap<TTable>>(
-    relationName: K,
-    options?: RelationIncludeOptions
-  ): SelectQueryBuilder<T, TTable> {
-    let nextContext = this.context;
-    const relation = this.env.table.relations[relationName as string];
-    if (relation?.type === RelationKinds.BelongsTo) {
-      const foreignKey = relation.foreignKey;
-      const fkColumn = this.env.table.columns[foreignKey];
-      if (fkColumn) {
-        const hasAlias = nextContext.state.ast.columns.some(col => {
-          const node = col as { alias?: string; name?: string };
-          return (node.alias ?? node.name) === foreignKey;
-        });
-        if (!hasAlias) {
-          nextContext = this.columnSelector.select(nextContext, { [foreignKey]: fkColumn });
-        }
-      }
-    }
-    const nextLazy = new Set(this.lazyRelations);
-    nextLazy.add(relationName as string);
-    const nextOptions = new Map(this.lazyRelationOptions);
-    if (options) {
-      nextOptions.set(relationName as string, options);
-    } else {
-      nextOptions.delete(relationName as string);
-    }
-    return this.clone(nextContext, nextLazy, nextOptions);
-  }
+  includeLazy<K extends keyof RelationMap<TTable>>(
+    relationName: K,
+    options?: TypedRelationIncludeOptions<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable> {
+    let nextContext = this.context;
+    const relation = this.env.table.relations[relationName as string];
+    if (relation?.type === RelationKinds.BelongsTo) {
+      const foreignKey = relation.foreignKey;
+      const fkColumn = this.env.table.columns[foreignKey];
+      if (fkColumn) {
+        const hasAlias = nextContext.state.ast.columns.some(col => {
+          const node = col as { alias?: string; name?: string };
+          return (node.alias ?? node.name) === foreignKey;
+        });
+        if (!hasAlias) {
+          nextContext = this.columnSelector.select(nextContext, { [foreignKey]: fkColumn });
+        }
+      }
+    }
+    const nextLazy = new Set(this.lazyRelations);
+    nextLazy.add(relationName as string);
+    const nextOptions = new Map(this.lazyRelationOptions);
+    if (options) {
+      nextOptions.set(relationName as string, options);
+    } else {
+      nextOptions.delete(relationName as string);
+    }
+    return this.clone(nextContext, nextLazy, nextOptions);
+  }
 
   /**
    * Convenience alias for including only specific columns from a relation.
+   * @example
+   * qb.includePick('posts', ['id', 'title', 'createdAt']);
    */
   includePick<
     K extends keyof TTable['relations'] & string,
-    TRel extends RelationDef = TTable['relations'][K],
-    TTarget extends TableDef = RelationTargetTable<TRel>,
-    C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string
+    C extends RelationTargetColumns<TTable['relations'][K]>
   >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
-    return this.include(relationName, { columns: cols as readonly string[] });
+    const options = { columns: cols as readonly C[] } as unknown as TypedRelationIncludeOptions<TTable['relations'][K]>;
+    return this.include(relationName, options);
   }
 
-
   /**
    * Selects columns for the root table and relations from an array of entries
    * @param config - Configuration array for deep column selection
    * @returns New query builder instance with deep column selections
+   * @example
+   * qb.selectColumnsDeep([
+   *   { type: 'root', columns: ['id', 'name'] },
+   *   { type: 'relation', relationName: 'posts', columns: ['id', 'title'] }
+   * ]);
    */
   selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable> {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -515,7 +592,8 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
       if (entry.type === 'root') {
         currBuilder = currBuilder.select(...entry.columns);
       } else {
-        currBuilder = currBuilder.include(entry.relationName, { columns: entry.columns as string[] });
+        const options = { columns: entry.columns } as unknown as TypedRelationIncludeOptions<TTable['relations'][typeof entry.relationName]>;
+        currBuilder = currBuilder.include(entry.relationName, options);
       }
     }
 
@@ -550,67 +628,36 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Executes the query and returns hydrated results
    * @param ctx - ORM session context
    * @returns Promise of entity instances
+   * @example
+   * const users = await qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .execute(session);
    */
   async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
     return executeHydrated(ctx, this);
   }
 
-  private withAst(ast: SelectQueryNode): SelectQueryBuilder<T, TTable> {
-    const nextState = new SelectQueryState(this.env.table as TTable, ast);
-    const nextContext: SelectQueryBuilderContext = {
-      ...this.context,
-      state: nextState
-    };
-    return this.clone(nextContext);
-  }
-
+  /**
+   * Executes a count query for the current builder without LIMIT/OFFSET clauses.
+   *
+   * @example
+   * const total = await qb.count(session);
+   */
   async count(session: OrmSession): Promise<number> {
-    const unpagedAst: SelectQueryNode = {
-      ...this.context.state.ast,
-      orderBy: undefined,
-      limit: undefined,
-      offset: undefined
-    };
-
-    const subAst = this.withAst(unpagedAst).getAST();
-
-    const countQuery: SelectQueryNode = {
-      type: 'SelectQuery',
-      from: derivedTable(subAst, '__metal_count'),
-      columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
-      joins: []
-    };
-
-    const execCtx = session.getExecutionContext();
-    const compiled = execCtx.dialect.compileSelect(countQuery);
-    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-    const value = results[0]?.values?.[0]?.[0];
-
-    if (typeof value === 'number') return value;
-    if (typeof value === 'bigint') return Number(value);
-    if (typeof value === 'string') return Number(value);
-    return value === null || value === undefined ? 0 : Number(value);
+    return executeCount(this.context, this.env, session);
   }
 
+  /**
+   * Executes the query and returns both the paged items and the total.
+   *
+   * @example
+   * const { items, totalItems } = await qb.executePaged(session, { page: 1, pageSize: 20 });
+   */
   async executePaged(
     session: OrmSession,
     options: { page: number; pageSize: number }
   ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
-    const { page, pageSize } = options;
-    if (!Number.isInteger(page) || page < 1) {
-      throw new Error('executePaged: page must be an integer >= 1');
-    }
-    if (!Number.isInteger(pageSize) || pageSize < 1) {
-      throw new Error('executePaged: pageSize must be an integer >= 1');
-    }
-
-    const offset = (page - 1) * pageSize;
-    const [items, totalItems] = await Promise.all([
-      this.limit(pageSize).offset(offset).execute(session),
-      this.count(session)
-    ]);
-
-    return { items, totalItems };
+    return executePagedQuery(this, session, options, sess => this.count(sess));
   }
 
   /**
@@ -618,6 +665,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param execCtx - Execution context
    * @param hydCtx - Hydration context
    * @returns Promise of entity instances
+   * @example
+   * const execCtx = new ExecutionContext(session);
+   * const hydCtx = new HydrationContext();
+   * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
   async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]> {
     return executeHydratedWithContexts(execCtx, hydCtx, this);
@@ -627,9 +678,16 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a WHERE condition to the query
    * @param expr - Expression for the WHERE clause
    * @returns New query builder instance with the WHERE condition
+   * @example
+   * qb.where(eq(userTable.columns.id, 1));
+   * @example
+   * qb.where(and(
+   *   eq(userTable.columns.active, true),
+   *   gt(userTable.columns.createdAt, subDays(now(), 30))
+   * ));
    */
   where(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withWhere(expr));
+    const nextContext = this.predicateFacet.where(this.context, expr);
     return this.clone(nextContext);
   }
 
@@ -637,9 +695,12 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a GROUP BY clause to the query
    * @param term - Column definition or ordering term to group by
    * @returns New query builder instance with the GROUP BY clause
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId);
    */
   groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withGroupBy(term));
+    const nextContext = this.predicateFacet.groupBy(this.context, term);
     return this.clone(nextContext);
   }
 
@@ -647,30 +708,30 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a HAVING condition to the query
    * @param expr - Expression for the HAVING clause
    * @returns New query builder instance with the HAVING condition
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId)
+   *   .having(gt(count(userTable.columns.id), 5));
    */
   having(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withHaving(expr));
+    const nextContext = this.predicateFacet.having(this.context, expr);
     return this.clone(nextContext);
   }
 
-
-
   /**
    * Adds an ORDER BY clause to the query
    * @param term - Column definition or ordering term to order by
    * @param directionOrOptions - Order direction or options (defaults to ASC)
    * @returns New query builder instance with the ORDER BY clause
+   *
+   * @example
+   * qb.orderBy(userTable.columns.createdAt, 'DESC');
    */
   orderBy(
     term: ColumnDef | OrderingTerm,
     directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string } = ORDER_DIRECTIONS.ASC
   ): SelectQueryBuilder<T, TTable> {
-    const options = typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
-    const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
-
-    const nextContext = this.applyAst(this.context, service =>
-      service.withOrderBy(term, dir, options.nulls, options.collation)
-    );
+    const nextContext = applyOrderBy(this.context, this.predicateFacet, term, directionOrOptions);
 
     return this.clone(nextContext);
   }
@@ -679,18 +740,26 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a DISTINCT clause to the query
    * @param cols - Columns to make distinct
    * @returns New query builder instance with the DISTINCT clause
+   * @example
+   * qb.distinct(userTable.columns.email);
+   * @example
+   * qb.distinct(userTable.columns.firstName, userTable.columns.lastName);
    */
   distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable> {
-    return this.clone(this.columnSelector.distinct(this.context, cols));
+    return this.clone(this.projectionFacet.distinct(this.context, cols));
   }
 
   /**
    * Adds a LIMIT clause to the query
    * @param n - Maximum number of rows to return
    * @returns New query builder instance with the LIMIT clause
+   * @example
+   * qb.limit(10);
+   * @example
+   * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
    */
   limit(n: number): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withLimit(n));
+    const nextContext = this.predicateFacet.limit(this.context, n);
     return this.clone(nextContext);
   }
 
@@ -698,9 +767,13 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds an OFFSET clause to the query
    * @param n - Number of rows to skip
    * @returns New query builder instance with the OFFSET clause
+   * @example
+   * qb.offset(10);
+   * @example
+   * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
    */
   offset(n: number): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withOffset(n));
+    const nextContext = this.predicateFacet.offset(this.context, n);
     return this.clone(nextContext);
   }
 
@@ -708,6 +781,12 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Combines this query with another using UNION
    * @param query - Query to union with
    * @returns New query builder instance with the set operation
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * const inactiveUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, false));
+   * qb.union(activeUsers).union(inactiveUsers);
    */
   union<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('UNION', query));
@@ -717,6 +796,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Combines this query with another using UNION ALL
    * @param query - Query to union with
    * @returns New query builder instance with the set operation
+   * @example
+   * const q1 = new SelectQueryBuilder(userTable).where(gt(userTable.columns.score, 80));
+   * const q2 = new SelectQueryBuilder(userTable).where(lt(userTable.columns.score, 20));
+   * qb.unionAll(q1).unionAll(q2);
    */
   unionAll<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('UNION ALL', query));
@@ -726,6 +809,12 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Combines this query with another using INTERSECT
    * @param query - Query to intersect with
    * @returns New query builder instance with the set operation
+   * @example
+   * const activeUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, true));
+   * const premiumUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.premium, true));
+   * qb.intersect(activeUsers).intersect(premiumUsers);
    */
   intersect<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('INTERSECT', query));
@@ -735,6 +824,11 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Combines this query with another using EXCEPT
    * @param query - Query to subtract
    * @returns New query builder instance with the set operation
+   * @example
+   * const allUsers = new SelectQueryBuilder(userTable);
+   * const inactiveUsers = new SelectQueryBuilder(userTable)
+   *   .where(eq(userTable.columns.active, false));
+   * qb.except(allUsers).except(inactiveUsers); // Only active users
    */
   except<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('EXCEPT', query));
@@ -744,6 +838,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a WHERE EXISTS condition to the query
    * @param subquery - Subquery to check for existence
    * @returns New query builder instance with the WHERE EXISTS condition
+   * @example
+   * const postsQuery = new SelectQueryBuilder(postTable)
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.whereExists(postsQuery);
    */
   whereExists<TSub extends TableDef>(
     subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
@@ -758,6 +856,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Adds a WHERE NOT EXISTS condition to the query
    * @param subquery - Subquery to check for non-existence
    * @returns New query builder instance with the WHERE NOT EXISTS condition
+   * @example
+   * const postsQuery = new SelectQueryBuilder(postTable)
+   *   .where(eq(postTable.columns.userId, col('u.id')));
+   * qb.whereNotExists(postsQuery); // Users without posts
    */
   whereNotExists<TSub extends TableDef>(
     subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
@@ -773,31 +875,27 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param relationName - Name of the relationship to check
    * @param callback - Optional callback to modify the relationship query
    * @returns New query builder instance with the relationship existence check
+   *
+   * @example
+   * qb.whereHas('posts', postQb => postQb.where(eq(postTable.columns.published, true)));
    */
   whereHas<K extends keyof TTable['relations'] & string>(
     relationName: K,
     callbackOrOptions?: RelationCallback | WhereHasOptions,
     maybeOptions?: WhereHasOptions
   ): SelectQueryBuilder<T, TTable> {
-    const relation = this.env.table.relations[relationName];
-
-    if (!relation) {
-      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
-    }
-
-    const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions as RelationCallback : undefined;
-    const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as WhereHasOptions | undefined;
-
-    let subQb = this.createChildBuilder<unknown, typeof relation.target>(relation.target);
-
-    if (callback) {
-      subQb = callback(subQb);
-    }
-
-    const subAst = subQb.getAST();
-    const finalSubAst = this.relationManager.applyRelationCorrelation(this.context, relationName, subAst, options?.correlate);
+    const predicate = buildWhereHasPredicate(
+      this.env,
+      this.context,
+      this.relationFacet,
+      table => this.createChildBuilder(table),
+      relationName,
+      callbackOrOptions,
+      maybeOptions,
+      false
+    );
 
-    return this.where(exists(finalSubAst));
+    return this.where(predicate);
   }
 
   /**
@@ -805,39 +903,38 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param relationName - Name of the relationship to check
    * @param callback - Optional callback to modify the relationship query
    * @returns New query builder instance with the relationship non-existence check
+   *
+   * @example
+   * qb.whereHasNot('posts', postQb => postQb.where(eq(postTable.columns.published, true)));
    */
   whereHasNot<K extends keyof TTable['relations'] & string>(
     relationName: K,
     callbackOrOptions?: RelationCallback | WhereHasOptions,
     maybeOptions?: WhereHasOptions
   ): SelectQueryBuilder<T, TTable> {
-    const relation = this.env.table.relations[relationName];
-
-    if (!relation) {
-      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
-    }
-
-    const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions as RelationCallback : undefined;
-    const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as WhereHasOptions | undefined;
-
-    let subQb = this.createChildBuilder<unknown, typeof relation.target>(relation.target);
-
-    if (callback) {
-      subQb = callback(subQb);
-    }
-
-    const subAst = subQb.getAST();
-    const finalSubAst = this.relationManager.applyRelationCorrelation(this.context, relationName, subAst, options?.correlate);
+    const predicate = buildWhereHasPredicate(
+      this.env,
+      this.context,
+      this.relationFacet,
+      table => this.createChildBuilder(table),
+      relationName,
+      callbackOrOptions,
+      maybeOptions,
+      true
+    );
 
-    return this.where(notExists(finalSubAst));
+    return this.where(predicate);
   }
 
-
-
   /**
    * Compiles the query to SQL for a specific dialect
    * @param dialect - Database dialect to compile for
    * @returns Compiled query with SQL and parameters
+   * @example
+   * const compiled = qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .compile('postgres');
+   * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
   compile(dialect: SelectDialectInput): CompiledQuery {
     const resolved = resolveDialectInput(dialect);
@@ -848,6 +945,11 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * Converts the query to SQL string for a specific dialect
    * @param dialect - Database dialect to generate SQL for
    * @returns SQL string representation of the query
+   * @example
+   * const sql = qb.select('id', 'name')
+   *   .where(eq(userTable.columns.active, true))
+   *   .toSql('postgres');
+   * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
   toSql(dialect: SelectDialectInput): string {
     return this.compile(dialect).sql;
@@ -856,6 +958,9 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   /**
    * Gets the hydration plan for the query
    * @returns Hydration plan or undefined if none exists
+   * @example
+   * const plan = qb.include('posts').getHydrationPlan();
+   * console.log(plan?.relations); // Information about included relations
    */
   getHydrationPlan(): HydrationPlan | undefined {
     return this.context.hydration.getPlan();
@@ -864,9 +969,12 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   /**
    * Gets the Abstract Syntax Tree (AST) representation of the query
    * @returns Query AST with hydration applied
+   * @example
+   * const ast = qb.select('id', 'name').getAST();
+   * console.log(ast.columns); // Array of column nodes
+   * console.log(ast.from); // From clause information
    */
   getAST(): SelectQueryNode {
     return this.context.hydration.applyToAst(this.context.state.ast);
   }
 }
-