metal-orm 1.0.57 → 1.0.59

package/src/query-builder/select.ts

@@ -2,21 +2,20 @@ import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column-types.js';
 import { OrderingTerm, SelectQueryNode, SetOperationKind } from '../core/ast/query.js';
 import { HydrationPlan } from '../core/hydration/types.js';
-import {
-  ColumnNode,
-  ExpressionNode,
-  FunctionNode,
-  BinaryExpressionNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
-  and,
-  exists,
-  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';
+import {
+  ColumnNode,
+  ExpressionNode,
+  FunctionNode,
+  BinaryExpressionNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  and,
+  exists,
+  notExists,
+  OperandNode
+} from '../core/ast/expression.js';
+import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
+import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 
 type SelectDialectInput = Dialect | DialectKey;
 
@@ -28,42 +27,46 @@ 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 type { RelationDef } from '../schema/relation.js';
+import { ColumnSelector } from './column-selector.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 { 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 { 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 { 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;
 
-type DeepSelectEntry<TTable extends TableDef> = {
-  type: 'root';
-  columns: (keyof TTable['columns'] & string)[];
-} | {
-  type: 'relation';
-  relationName: keyof TTable['relations'] & string;
-  columns: string[];
-};
+type DeepSelectEntry<TTable extends TableDef> = {
+  type: 'root';
+  columns: (keyof TTable['columns'] & string)[];
+} | {
+  type: 'relation';
+  relationName: keyof TTable['relations'] & string;
+  columns: string[];
+};
 
 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
@@ -71,11 +74,18 @@ type RelationCallback = <TChildTable extends TableDef>(
  * @typeParam TTable - Table definition being queried
  */
 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 lazyRelations: Set<string>;
+  private readonly env: SelectQueryBuilderEnvironment;
+  private readonly context: SelectQueryBuilderContext;
+  private readonly columnSelector: ColumnSelector;
+  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>;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -89,20 +99,30 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     state?: SelectQueryState,
     hydration?: HydrationManager,
     dependencies?: Partial<SelectQueryBuilderDependencies>,
-    lazyRelations?: Set<string>
-  ) {
-    const deps = resolveSelectQueryBuilderDependencies(dependencies);
-    this.env = { table, deps };
-    const initialState = state ?? deps.createState(table);
-    const initialHydration = hydration ?? deps.createHydration(table);
-    this.context = {
-      state: initialState,
-      hydration: initialHydration
-    };
-    this.lazyRelations = new Set(lazyRelations ?? []);
-    this.columnSelector = deps.createColumnSelector(this.env);
-    this.relationManager = deps.createRelationManager(this.env);
-  }
+    lazyRelations?: Set<string>,
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>
+  ) {
+    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 = {
+      state: initialState,
+      hydration: initialHydration
+    };
+    this.lazyRelations = new Set(lazyRelations ?? []);
+    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
+    this.columnSelector = deps.createColumnSelector(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);
+  }
 
   /**
    * Creates a new SelectQueryBuilder instance with updated context and lazy relations
@@ -112,24 +132,27 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    */
   private clone(
     context: SelectQueryBuilderContext = this.context,
-    lazyRelations = new Set(this.lazyRelations)
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions)
   ): SelectQueryBuilder<T, TTable> {
-    return new SelectQueryBuilder(this.env.table as TTable, context.state, context.hydration, this.env.deps, lazyRelations);
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions
+    );
   }
 
   /**
    * Applies an alias to the root FROM table.
    * @param alias - Alias to apply
    */
-  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));
-    return this.clone(nextContext);
-  }
+  as(alias: string): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.fromFacet.as(this.context, alias);
+    return this.clone(nextContext);
+  }
 
 
 
@@ -157,52 +180,19 @@ 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
-   * @param query - Query to combine with
-   * @returns Updated query context with set operation
-   */
-  private applySetOperation<TSub extends TableDef>(
-    operator: SetOperationKind,
-    query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
-  ): SelectQueryBuilderContext {
-    const subAst = resolveSelectQuery(query);
-    return this.applyAst(this.context, service => service.withSetOperation(operator, subAst));
-  }
+  /**
+   * Applies a set operation to the query
+   * @param operator - Set operation kind
+   * @param query - Query to combine with
+   * @returns Updated query context with set operation
+   */
+  private applySetOperation<TSub extends TableDef>(
+    operator: SetOperationKind,
+    query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+  ): SelectQueryBuilderContext {
+    const subAst = resolveSelectQuery(query);
+    return this.setOpFacet.applySetOperation(this.context, operator, subAst);
+  }
 
 
   /**
@@ -219,10 +209,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     ...args: K[] | [Record<string, ColumnSelectionValue>]
   ): SelectQueryBuilder<T, TTable> {
     // 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));
-    }
+    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.projectionFacet.select(this.context, columns));
+    }
 
     // Otherwise, treat as column names
     const cols = args as K[];
@@ -235,17 +225,17 @@ 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
    */
-  selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable> {
-    return this.clone(this.columnSelector.selectRaw(this.context, cols));
-  }
+  selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable> {
+    return this.clone(this.projectionFacet.selectRaw(this.context, cols));
+  }
 
   /**
    * Adds a Common Table Expression (CTE) to the query
@@ -254,11 +244,11 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the CTE
    */
-  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));
-    return this.clone(nextContext);
-  }
+  with<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable> {
+    const subAst = resolveSelectQuery(query);
+    const nextContext = this.cteFacet.withCTE(this.context, name, subAst, columns, false);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a recursive Common Table Expression (CTE) to the query
@@ -267,11 +257,11 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param columns - Optional column names for the CTE
    * @returns New query builder instance with the recursive CTE
    */
-  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));
-    return this.clone(nextContext);
-  }
+  withRecursive<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable> {
+    const subAst = resolveSelectQuery(query);
+    const nextContext = this.cteFacet.withCTE(this.context, name, subAst, columns, true);
+    return this.clone(nextContext);
+  }
 
   /**
    * Replaces the FROM clause with a derived table (subquery with alias)
@@ -280,16 +270,15 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param columnAliases - Optional column alias list
    * @returns New query builder instance with updated FROM
    */
-  fromSubquery<TSub extends TableDef>(
-    subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
-    alias: string,
-    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));
-    return this.clone(nextContext);
-  }
+  fromSubquery<TSub extends TableDef>(
+    subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
+    alias: string,
+    columnAliases?: string[]
+  ): SelectQueryBuilder<T, TTable> {
+    const subAst = resolveSelectQuery(subquery);
+    const nextContext = this.fromFacet.fromSubquery(this.context, subAst, alias, columnAliases);
+    return this.clone(nextContext);
+  }
 
   /**
    * Replaces the FROM clause with a function table expression.
@@ -298,16 +287,15 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param alias - Optional alias for the function table
    * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
    */
-  fromFunctionTable(
-    name: string,
-    args: OperandNode[] = [],
-    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));
-    return this.clone(nextContext);
-  }
+  fromFunctionTable(
+    name: string,
+    args: OperandNode[] = [],
+    alias?: string,
+    options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+  ): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.fromFacet.fromFunctionTable(this.context, name, args, alias, options);
+    return this.clone(nextContext);
+  }
 
   /**
    * Selects a subquery as a column
@@ -315,10 +303,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param sub - Query builder or query node for the subquery
    * @returns New query builder instance with the subquery selection
    */
-  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));
-  }
+  selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
+    const query = resolveSelectQuery(sub);
+    return this.clone(this.projectionFacet.selectSubquery(this.context, alias, query));
+  }
 
   /**
    * Adds a JOIN against a derived table (subquery with alias)
@@ -329,18 +317,17 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param columnAliases - Optional column alias list for the derived table
    * @returns New query builder instance with the derived-table join
    */
-  joinSubquery<TSub extends TableDef>(
-    subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
-    alias: string,
-    condition: BinaryExpressionNode,
-    joinKind: JoinKind = JOIN_KINDS.INNER,
-    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));
-    return this.clone(nextContext);
-  }
+  joinSubquery<TSub extends TableDef>(
+    subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode,
+    alias: string,
+    condition: BinaryExpressionNode,
+    joinKind: JoinKind = JOIN_KINDS.INNER,
+    columnAliases?: string[]
+  ): SelectQueryBuilder<T, TTable> {
+    const subAst = resolveSelectQuery(subquery);
+    const nextContext = this.joinFacet.joinSubquery(this.context, subAst, alias, condition, joinKind, columnAliases);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a join against a function table (e.g., `generate_series`) using `fnTable` internally.
@@ -351,19 +338,17 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param joinKind - Kind of join (defaults to INNER)
    * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
    */
-  joinFunctionTable(
-    name: string,
-    args: OperandNode[] = [],
-    alias: string,
-    condition: BinaryExpressionNode,
-    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));
-    return this.clone(nextContext);
-  }
+  joinFunctionTable(
+    name: string,
+    args: OperandNode[] = [],
+    alias: string,
+    condition: BinaryExpressionNode,
+    joinKind: JoinKind = JOIN_KINDS.INNER,
+    options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+  ): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.joinFacet.joinFunctionTable(this.context, name, args, alias, condition, joinKind, options);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds an INNER JOIN to the query
@@ -371,10 +356,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param condition - Join condition expression
    * @returns New query builder instance with the INNER JOIN
    */
-  innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
-    return this.clone(nextContext);
-  }
+  innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a LEFT JOIN to the query
@@ -382,10 +367,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param condition - Join condition expression
    * @returns New query builder instance with the LEFT JOIN
    */
-  leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
-    return this.clone(nextContext);
-  }
+  leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a RIGHT JOIN to the query
@@ -393,10 +378,10 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param condition - Join condition expression
    * @returns New query builder instance with the RIGHT JOIN
    */
-  rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
-    return this.clone(nextContext);
-  }
+  rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.joinFacet.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
+    return this.clone(nextContext);
+  }
 
   /**
    * Matches records based on a relationship
@@ -404,13 +389,13 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param predicate - Optional predicate expression
    * @returns New query builder instance with the relationship match
    */
-  match<K extends keyof TTable['relations'] & string>(
-    relationName: K,
-    predicate?: ExpressionNode
-  ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationManager.match(this.context, relationName, predicate);
-    return this.clone(nextContext);
-  }
+  match<K extends keyof TTable['relations'] & string>(
+    relationName: K,
+    predicate?: ExpressionNode
+  ): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.relationFacet.match(this.context, relationName, predicate);
+    return this.clone(nextContext);
+  }
 
   /**
    * Joins a related table
@@ -419,14 +404,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param extraCondition - Optional additional join condition
    * @returns New query builder instance with the relationship join
    */
-  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);
-    return this.clone(nextContext);
-  }
+  joinRelation<K extends keyof TTable['relations'] & string>(
+    relationName: K,
+    joinKind: JoinKind = JOIN_KINDS.INNER,
+    extraCondition?: ExpressionNode
+  ): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.relationFacet.joinRelation(this.context, relationName, joinKind, extraCondition);
+    return this.clone(nextContext);
+  }
 
   /**
    * Includes related data in the query results
@@ -434,62 +419,60 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param options - Optional include options
    * @returns New query builder instance with the relationship inclusion
    */
-  include<K extends keyof TTable['relations'] & string>(
-    relationName: K,
-    options?: RelationIncludeOptions
-  ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationManager.include(this.context, relationName, options);
-    return this.clone(nextContext);
-  }
+  include<K extends keyof TTable['relations'] & string>(
+    relationName: K,
+    options?: TypedRelationIncludeOptions<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.relationFacet.include(this.context, relationName, options);
+    return this.clone(nextContext);
+  }
 
   /**
    * Includes a relation lazily in the query results
    * @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
    */
-  includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable> {
+  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);
-    return this.clone(this.context, nextLazy);
-  }
-
-  /**
-   * Selects columns for a related table in a single hop.
-   */
-  selectRelationColumns<
-    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
-  >(relationName: K, ...cols: C[]): SelectQueryBuilder<T, TTable> {
-    const relation = this.env.table.relations[relationName] as RelationDef | undefined;
-    if (!relation) {
-      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
+    const nextOptions = new Map(this.lazyRelationOptions);
+    if (options) {
+      nextOptions.set(relationName as string, options);
+    } else {
+      nextOptions.delete(relationName as string);
     }
-    const target = relation.target;
-
-    for (const col of cols) {
-      if (!target.columns[col]) {
-        throw new Error(
-          `Column '${col}' not found on related table '${target.name}' for relation '${relationName}'`
-        );
-      }
-    }
-
-    return this.include(relationName as string, { columns: cols as string[] });
+    return this.clone(nextContext, nextLazy, nextOptions);
   }
 
   /**
-   * Convenience alias for selecting specific columns from a relation.
+   * Convenience alias for including only specific columns from a relation.
    */
-  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
-  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
-    return this.selectRelationColumns(relationName, ...cols);
-  }
+  includePick<
+    K extends keyof TTable['relations'] & string,
+    C extends RelationTargetColumns<TTable['relations'][K]>
+  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
+    const options = { columns: cols as readonly C[] } as unknown as TypedRelationIncludeOptions<TTable['relations'][K]>;
+    return this.include(relationName, options);
+  }
 
 
   /**
@@ -501,13 +484,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     let currBuilder: SelectQueryBuilder<T, TTable> = this;
 
-    for (const entry of config) {
-      if (entry.type === 'root') {
-        currBuilder = currBuilder.select(...entry.columns);
-      } else {
-        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...(entry.columns as string[]));
-      }
-    }
+    for (const entry of config) {
+      if (entry.type === 'root') {
+        currBuilder = currBuilder.select(...entry.columns);
+      } else {
+        const options = { columns: entry.columns } as unknown as TypedRelationIncludeOptions<TTable['relations'][typeof entry.relationName]>;
+        currBuilder = currBuilder.include(entry.relationName, options);
+      }
+    }
 
     return currBuilder;
   }
@@ -520,6 +504,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     return Array.from(this.lazyRelations) as (keyof RelationMap<TTable>)[];
   }
 
+  /**
+   * Gets lazy relation include options
+   * @returns Map of relation names to include options
+   */
+  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
+    return new Map(this.lazyRelationOptions);
+  }
+
   /**
    * Gets the table definition for this query builder
    * @returns Table definition
@@ -537,63 +529,28 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     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);
-  }
-
-  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);
-  }
-
-  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 };
-  }
+  /**
+   * 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> {
+    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 }> {
+    return executePagedQuery(this, session, options, sess => this.count(sess));
+  }
 
   /**
    * Executes the query with provided execution and hydration contexts
@@ -610,81 +567,79 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param expr - Expression for the WHERE clause
    * @returns New query builder instance with the WHERE condition
    */
-  where(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withWhere(expr));
-    return this.clone(nextContext);
-  }
+  where(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.predicateFacet.where(this.context, expr);
+    return this.clone(nextContext);
+  }
 
   /**
    * 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
    */
-  groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withGroupBy(term));
-    return this.clone(nextContext);
-  }
+  groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.predicateFacet.groupBy(this.context, term);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a HAVING condition to the query
    * @param expr - Expression for the HAVING clause
    * @returns New query builder instance with the HAVING condition
    */
-  having(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withHaving(expr));
-    return this.clone(nextContext);
-  }
-
+  having(expr: ExpressionNode): SelectQueryBuilder<T, TTable> {
+    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
-   */
-  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)
-    );
 
-    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 nextContext = applyOrderBy(this.context, this.predicateFacet, term, directionOrOptions);
+
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds a DISTINCT clause to the query
    * @param cols - Columns to make distinct
    * @returns New query builder instance with the DISTINCT clause
    */
-  distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable> {
-    return this.clone(this.columnSelector.distinct(this.context, cols));
-  }
+  distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable> {
+    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
    */
-  limit(n: number): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withLimit(n));
-    return this.clone(nextContext);
-  }
+  limit(n: number): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.predicateFacet.limit(this.context, n);
+    return this.clone(nextContext);
+  }
 
   /**
    * Adds an OFFSET clause to the query
    * @param n - Number of rows to skip
    * @returns New query builder instance with the OFFSET clause
    */
-  offset(n: number): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.applyAst(this.context, service => service.withOffset(n));
-    return this.clone(nextContext);
-  }
+  offset(n: number): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.predicateFacet.offset(this.context, n);
+    return this.clone(nextContext);
+  }
 
   /**
    * Combines this query with another using UNION
@@ -750,69 +705,61 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     return this.where(notExists(correlated));
   }
 
-  /**
-   * Adds a WHERE EXISTS condition based on a relationship
-   * @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
-   */
-  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);
-
-    return this.where(exists(finalSubAst));
-  }
-
-  /**
-   * Adds a WHERE NOT EXISTS condition based on a relationship
-   * @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
-   */
-  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);
-
-    return this.where(notExists(finalSubAst));
-  }
+  /**
+   * Adds a WHERE EXISTS condition based on a relationship
+   * @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 predicate = buildWhereHasPredicate(
+      this.env,
+      this.context,
+      this.relationFacet,
+      table => this.createChildBuilder(table),
+      relationName,
+      callbackOrOptions,
+      maybeOptions,
+      false
+    );
+
+    return this.where(predicate);
+  }
+
+  /**
+   * Adds a WHERE NOT EXISTS condition based on a relationship
+   * @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 predicate = buildWhereHasPredicate(
+      this.env,
+      this.context,
+      this.relationFacet,
+      table => this.createChildBuilder(table),
+      relationName,
+      callbackOrOptions,
+      maybeOptions,
+      true
+    );
+
+    return this.where(predicate);
+  }