metal-orm 1.0.58 → 1.0.60

package/dist/index.js

@@ -51,6 +51,9 @@ var defineTable = (name, columns, relations = {}, hooks, options = {}) => {
     collation: options.collation
   };
 };
+function setRelations(table, relations) {
+  table.relations = relations;
+}
 var TABLE_REF_CACHE = /* @__PURE__ */ new WeakMap();
 var withColumnProps = (table) => {
   const cached = TABLE_REF_CACHE.get(table);
@@ -694,6 +697,7 @@ var variance = buildAggregate("VARIANCE");
 
 // src/core/ast/expression-visitor.ts
 var DispatcherRegistry = class _DispatcherRegistry {
+  dispatchers;
   constructor(dispatchers = /* @__PURE__ */ new Map()) {
     this.dispatchers = dispatchers;
   }
@@ -827,61 +831,9 @@ var toTableRef = (table) => ({
   alias: hasAlias(table) ? table.alias : void 0
 });
 
-// src/core/ast/builders.ts
-var isColumnNode = (col2) => "type" in col2 && col2.type === "Column";
-var resolveTableName = (def, table) => {
-  if (!def.table) {
-    return table.alias || table.name;
-  }
-  if (table.alias && def.table === table.name) {
-    return table.alias;
-  }
-  return def.table;
-};
-var buildColumnNode = (table, column) => {
-  if (isColumnNode(column)) {
-    return column;
-  }
-  const def = column;
-  const baseTable = resolveTableName(def, table);
-  return {
-    type: "Column",
-    table: baseTable,
-    name: def.name
-  };
-};
-var buildColumnNodes = (table, names) => names.map((name) => ({
-  type: "Column",
-  table: table.alias || table.name,
-  name
-}));
-var createTableNode = (table) => ({
-  type: "Table",
-  name: table.name,
-  schema: table.schema
-});
-var fnTable = (name, args = [], alias, opts) => ({
-  type: "FunctionTable",
-  name,
-  args,
-  alias,
-  lateral: opts?.lateral,
-  withOrdinality: opts?.withOrdinality,
-  columnAliases: opts?.columnAliases,
-  schema: opts?.schema
-});
-var derivedTable = (query, alias, columnAliases) => ({
-  type: "DerivedTable",
-  query,
-  alias,
-  columnAliases
-});
-
 // src/core/functions/function-registry.ts
 var FunctionRegistry = class {
-  constructor() {
-    this.renderers = /* @__PURE__ */ new Map();
-  }
+  renderers = /* @__PURE__ */ new Map();
   /**
    * Registers or overrides a renderer for the given function name.
    */
@@ -1176,6 +1128,7 @@ function renderStandardGroupConcat(ctx) {
 
 // src/core/functions/standard-strategy.ts
 var StandardFunctionStrategy = class {
+  registry;
   /**
    * Creates a new StandardFunctionStrategy and registers standard functions.
    */
@@ -1241,17 +1194,13 @@ var StandardFunctionStrategy = class {
   getGroupConcatSeparatorOperand(ctx) {
     return getGroupConcatSeparatorOperand(ctx);
   }
-  static {
-    /** Default separator for GROUP_CONCAT, a comma. */
-    this.DEFAULT_GROUP_CONCAT_SEPARATOR = DEFAULT_GROUP_CONCAT_SEPARATOR;
-  }
+  /** Default separator for GROUP_CONCAT, a comma. */
+  static DEFAULT_GROUP_CONCAT_SEPARATOR = DEFAULT_GROUP_CONCAT_SEPARATOR;
 };
 
 // src/core/functions/standard-table-strategy.ts
 var StandardTableFunctionStrategy = class {
-  constructor() {
-    this.renderers = /* @__PURE__ */ new Map();
-  }
+  renderers = /* @__PURE__ */ new Map();
   add(key, renderer) {
     this.renderers.set(key, renderer);
   }
@@ -1430,6 +1379,10 @@ var Dialect = class _Dialect {
     const combinedCtes = [...normalized.ctes ?? [], ...hoistedCtes];
     return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
   }
+  expressionCompilers;
+  operandCompilers;
+  functionStrategy;
+  tableFunctionStrategy;
   constructor(functionStrategy, tableFunctionStrategy) {
     this.expressionCompilers = /* @__PURE__ */ new Map();
     this.operandCompilers = /* @__PURE__ */ new Map();
@@ -1445,10 +1398,7 @@ var Dialect = class _Dialect {
    */
   static create(functionStrategy, tableFunctionStrategy) {
     class TestDialect extends _Dialect {
-      constructor() {
-        super(...arguments);
-        this.dialect = "sqlite";
-      }
+      dialect = "sqlite";
       quoteIdentifier(id) {
         return `"${id}"`;
       }
@@ -1888,11 +1838,8 @@ var OrderByCompiler = class {
 
 // src/core/dialect/base/sql-dialect.ts
 var SqlDialectBase = class extends Dialect {
-  constructor() {
-    super(...arguments);
-    this.paginationStrategy = new StandardLimitOffsetPagination();
-    this.returningStrategy = new NoReturningStrategy();
-  }
+  paginationStrategy = new StandardLimitOffsetPagination();
+  returningStrategy = new NoReturningStrategy();
   compileSelectAst(ast, ctx) {
     const hasSetOps = !!(ast.setOps && ast.setOps.length);
     const ctes = CteCompiler.compileCtes(
@@ -2280,12 +2227,12 @@ var PostgresTableFunctionStrategy = class extends StandardTableFunctionStrategy
 
 // src/core/dialect/postgres/index.ts
 var PostgresDialect = class extends SqlDialectBase {
+  dialect = "postgres";
   /**
    * Creates a new PostgresDialect instance
    */
   constructor() {
     super(new PostgresFunctionStrategy(), new PostgresTableFunctionStrategy());
-    this.dialect = "postgres";
     this.registerExpressionCompiler("BitwiseExpression", (node, ctx) => {
       const left2 = this.compileOperand(node.left, ctx);
       const right2 = this.compileOperand(node.right, ctx);
@@ -2419,12 +2366,12 @@ var MysqlFunctionStrategy = class extends StandardFunctionStrategy {
 
 // src/core/dialect/mysql/index.ts
 var MySqlDialect = class extends SqlDialectBase {
+  dialect = "mysql";
   /**
    * Creates a new MySqlDialect instance
    */
   constructor() {
     super(new MysqlFunctionStrategy());
-    this.dialect = "mysql";
   }
   /**
    * Quotes an identifier using MySQL backtick syntax
@@ -2575,12 +2522,12 @@ var SqliteFunctionStrategy = class extends StandardFunctionStrategy {
 
 // src/core/dialect/sqlite/index.ts
 var SqliteDialect = class extends SqlDialectBase {
+  dialect = "sqlite";
   /**
    * Creates a new SqliteDialect instance
    */
   constructor() {
     super(new SqliteFunctionStrategy());
-    this.dialect = "sqlite";
     this.registerExpressionCompiler("BitwiseExpression", (node, ctx) => {
       const left2 = this.compileOperand(node.left, ctx);
       const right2 = this.compileOperand(node.right, ctx);
@@ -2753,12 +2700,12 @@ var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
 
 // src/core/dialect/mssql/index.ts
 var SqlServerDialect = class extends SqlDialectBase {
+  dialect = "mssql";
   /**
    * Creates a new SqlServerDialect instance
    */
   constructor() {
     super(new MssqlFunctionStrategy());
-    this.dialect = "mssql";
   }
   /**
    * Quotes an identifier using SQL Server bracket syntax
@@ -2885,12 +2832,8 @@ var SqlServerDialect = class extends SqlDialectBase {
 
 // src/core/dialect/dialect-factory.ts
 var DialectFactory = class {
-  static {
-    this.registry = /* @__PURE__ */ new Map();
-  }
-  static {
-    this.defaultsInitialized = false;
-  }
+  static registry = /* @__PURE__ */ new Map();
+  static defaultsInitialized = false;
   static ensureDefaults() {
     if (this.defaultsInitialized) return;
     this.defaultsInitialized = true;
@@ -2949,8 +2892,66 @@ var resolveDialectInput = (dialect) => {
   return dialect;
 };
 
+// src/core/ast/builders.ts
+var isColumnNode = (col2) => "type" in col2 && col2.type === "Column";
+var resolveTableName = (def, table) => {
+  if (!def.table) {
+    return table.alias || table.name;
+  }
+  if (table.alias && def.table === table.name) {
+    return table.alias;
+  }
+  return def.table;
+};
+var buildColumnNode = (table, column) => {
+  if (isColumnNode(column)) {
+    return column;
+  }
+  const def = column;
+  const baseTable = resolveTableName(def, table);
+  return {
+    type: "Column",
+    table: baseTable,
+    name: def.name
+  };
+};
+var buildColumnNodes = (table, names) => names.map((name) => ({
+  type: "Column",
+  table: table.alias || table.name,
+  name
+}));
+var createTableNode = (table) => ({
+  type: "Table",
+  name: table.name,
+  schema: table.schema
+});
+var fnTable = (name, args = [], alias, opts) => ({
+  type: "FunctionTable",
+  name,
+  args,
+  alias,
+  lateral: opts?.lateral,
+  withOrdinality: opts?.withOrdinality,
+  columnAliases: opts?.columnAliases,
+  schema: opts?.schema
+});
+var derivedTable = (query, alias, columnAliases) => ({
+  type: "DerivedTable",
+  query,
+  alias,
+  columnAliases
+});
+
 // src/query-builder/select-query-state.ts
 var SelectQueryState = class _SelectQueryState {
+  /**
+   * Table definition for the query
+   */
+  table;
+  /**
+   * Abstract Syntax Tree (AST) representation of the query
+   */
+  ast;
   /**
    * Creates a new SelectQueryState instance
    * @param table - Table definition
@@ -3920,199 +3921,150 @@ var buildRelationCorrelation = (root, relation, rootAlias, targetTableName) => {
 // src/core/ast/join-metadata.ts
 var getJoinRelationName = (join) => join.meta?.relationName;
 
-// src/query-builder/relation-service.ts
-var hasRelationForeignKey = (relation) => relation.type !== RelationKinds.BelongsToMany;
-var RelationService = class {
-  /**
-   * Creates a new RelationService instance
-   * @param table - Table definition
-   * @param state - Current query state
-   * @param hydration - Hydration manager
-   */
-  constructor(table, state, hydration, createQueryAstService) {
-    this.table = table;
-    this.state = state;
-    this.hydration = hydration;
-    this.createQueryAstService = createQueryAstService;
-    this.projectionHelper = new RelationProjectionHelper(
-      table,
-      (state2, hydration2, columns) => this.selectColumns(state2, hydration2, columns)
-    );
-  }
-  /**
-   * Joins a relation to the query
-   * @param relationName - Name of the relation to join
-   * @param joinKind - Type of join to use
-   * @param extraCondition - Additional join condition
-   * @returns Relation result with updated state and hydration
-   */
-  joinRelation(relationName, joinKind, extraCondition, tableSource) {
-    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition, tableSource);
-    return { state: nextState, hydration: this.hydration };
+// src/query-builder/relation-filter-utils.ts
+var splitFilterExpressions = (filter, allowedTables) => {
+  const terms = flattenAnd(filter);
+  const selfFilters = [];
+  const crossFilters = [];
+  for (const term of terms) {
+    if (isExpressionSelfContained(term, allowedTables)) {
+      selfFilters.push(term);
+    } else {
+      crossFilters.push(term);
+    }
   }
-  /**
-   * Matches records based on a relation with an optional predicate
-   * @param relationName - Name of the relation to match
-   * @param predicate - Optional predicate expression
-   * @returns Relation result with updated state and hydration
-   */
-  match(relationName, predicate) {
-    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
-    const pk = findPrimaryKey(this.table);
-    const distinctCols = [{ type: "Column", table: this.rootTableName(), name: pk }];
-    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
-    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
-    return { state: nextState, hydration: joined.hydration };
+  return { selfFilters, crossFilters };
+};
+var flattenAnd = (node) => {
+  if (!node) return [];
+  if (node.type === "LogicalExpression" && node.operator === "AND") {
+    return node.operands.flatMap((operand) => flattenAnd(operand));
   }
-  /**
-   * Includes a relation in the query result
-   * @param relationName - Name of the relation to include
-   * @param options - Options for relation inclusion
-   * @returns Relation result with updated state and hydration
-   */
-  include(relationName, options) {
-    let state = this.state;
-    let hydration = this.hydration;
-    const relation = this.getRelation(relationName);
-    const aliasPrefix = options?.aliasPrefix ?? relationName;
-    const alreadyJoined = state.ast.joins.some((j) => getJoinRelationName(j) === relationName);
-    const { selfFilters, crossFilters } = this.splitFilterExpressions(
-      options?.filter,
-      /* @__PURE__ */ new Set([relation.target.name])
-    );
-    const canUseCte = !alreadyJoined && selfFilters.length > 0;
-    const joinFilters = [...crossFilters];
-    if (!canUseCte) {
-      joinFilters.push(...selfFilters);
-    }
-    const joinCondition = this.combineWithAnd(joinFilters);
-    let tableSourceOverride;
-    if (canUseCte) {
-      const cteInfo = this.createFilteredRelationCte(state, relationName, relation, selfFilters);
-      state = cteInfo.state;
-      tableSourceOverride = cteInfo.table;
-    }
-    if (!alreadyJoined) {
-      state = this.withJoin(
-        state,
-        relationName,
-        options?.joinKind ?? JOIN_KINDS.LEFT,
-        joinCondition,
-        tableSourceOverride
-      );
+  return [node];
+};
+var isExpressionSelfContained = (expr, allowedTables) => {
+  const collector = collectReferencedTables(expr);
+  if (collector.hasSubquery) return false;
+  if (collector.tables.size === 0) return true;
+  for (const table of collector.tables) {
+    if (!allowedTables.has(table)) {
+      return false;
     }
-    const projectionResult = this.projectionHelper.ensureBaseProjection(state, hydration);
-    state = projectionResult.state;
-    hydration = projectionResult.hydration;
-    if (hasRelationForeignKey(relation)) {
-      const fkColumn = this.table.columns[relation.foreignKey];
-      if (fkColumn) {
-        const hasForeignKeySelected = state.ast.columns.some((col2) => {
-          if (col2.type !== "Column") return false;
-          const node = col2;
-          const alias = node.alias ?? node.name;
-          return alias === relation.foreignKey;
-        });
-        if (!hasForeignKeySelected) {
-          const fkSelectionResult = this.selectColumns(state, hydration, {
-            [relation.foreignKey]: fkColumn
-          });
-          state = fkSelectionResult.state;
-          hydration = fkSelectionResult.hydration;
-        }
+  }
+  return true;
+};
+var collectReferencedTables = (expr) => {
+  const collector = {
+    tables: /* @__PURE__ */ new Set(),
+    hasSubquery: false
+  };
+  collectFromExpression(expr, collector);
+  return collector;
+};
+var collectFromExpression = (expr, collector) => {
+  switch (expr.type) {
+    case "BinaryExpression":
+      collectFromOperand(expr.left, collector);
+      collectFromOperand(expr.right, collector);
+      break;
+    case "LogicalExpression":
+      expr.operands.forEach((operand) => collectFromExpression(operand, collector));
+      break;
+    case "NullExpression":
+      collectFromOperand(expr.left, collector);
+      break;
+    case "InExpression":
+      collectFromOperand(expr.left, collector);
+      if (Array.isArray(expr.right)) {
+        expr.right.forEach((value) => collectFromOperand(value, collector));
+      } else {
+        collector.hasSubquery = true;
       }
-    }
-    const requestedColumns = options?.columns?.length ? [...options.columns] : Object.keys(relation.target.columns);
-    const targetPrimaryKey = findPrimaryKey(relation.target);
-    if (!requestedColumns.includes(targetPrimaryKey)) {
-      requestedColumns.push(targetPrimaryKey);
-    }
-    const targetColumns = requestedColumns;
-    const buildTypedSelection = (columns, prefix, keys, missingMsg) => {
-      return keys.reduce((acc, key) => {
-        const def = columns[key];
-        if (!def) {
-          throw new Error(missingMsg(key));
-        }
-        acc[makeRelationAlias(prefix, key)] = def;
-        return acc;
-      }, {});
-    };
-    const targetSelection = buildTypedSelection(
-      relation.target.columns,
-      aliasPrefix,
-      targetColumns,
-      (key) => `Column '${key}' not found on relation '${relationName}'`
-    );
-    if (relation.type !== RelationKinds.BelongsToMany) {
-      const relationSelectionResult2 = this.selectColumns(state, hydration, targetSelection);
-      state = relationSelectionResult2.state;
-      hydration = relationSelectionResult2.hydration;
-      hydration = hydration.onRelationIncluded(
-        state,
-        relation,
-        relationName,
-        aliasPrefix,
-        targetColumns
-      );
-      return { state, hydration };
-    }
-    const many = relation;
-    const pivotAliasPrefix = options?.pivot?.aliasPrefix ?? `${aliasPrefix}_pivot`;
-    const pivotPk = many.pivotPrimaryKey || findPrimaryKey(many.pivotTable);
-    const pivotColumns = options?.pivot?.columns ?? many.defaultPivotColumns ?? buildDefaultPivotColumns(many, pivotPk);
-    const pivotSelection = buildTypedSelection(
-      many.pivotTable.columns,
-      pivotAliasPrefix,
-      pivotColumns,
-      (key) => `Column '${key}' not found on pivot table '${many.pivotTable.name}'`
-    );
-    const combinedSelection = {
-      ...targetSelection,
-      ...pivotSelection
-    };
-    const relationSelectionResult = this.selectColumns(state, hydration, combinedSelection);
-    state = relationSelectionResult.state;
-    hydration = relationSelectionResult.hydration;
-    hydration = hydration.onRelationIncluded(
-      state,
-      relation,
-      relationName,
-      aliasPrefix,
-      targetColumns,
-      { aliasPrefix: pivotAliasPrefix, columns: pivotColumns }
-    );
-    return { state, hydration };
+      break;
+    case "ExistsExpression":
+      collector.hasSubquery = true;
+      break;
+    case "BetweenExpression":
+      collectFromOperand(expr.left, collector);
+      collectFromOperand(expr.lower, collector);
+      collectFromOperand(expr.upper, collector);
+      break;
+    case "ArithmeticExpression":
+    case "BitwiseExpression":
+      collectFromOperand(expr.left, collector);
+      collectFromOperand(expr.right, collector);
+      break;
+    default:
+      break;
   }
-  /**
-   * Applies relation correlation to a query AST
-   * @param relationName - Name of the relation
-   * @param ast - Query AST to modify
-   * @returns Modified query AST with relation correlation
-   */
-  applyRelationCorrelation(relationName, ast, additionalCorrelation) {
-    const relation = this.getRelation(relationName);
-    const rootAlias = this.state.ast.from.type === "Table" ? this.state.ast.from.alias : void 0;
-    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
-    if (additionalCorrelation) {
-      correlation = and(correlation, additionalCorrelation);
-    }
-    const whereInSubquery = ast.where ? and(correlation, ast.where) : correlation;
-    return {
-      ...ast,
-      where: whereInSubquery
-    };
+};
+var collectFromOperand = (node, collector) => {
+  switch (node.type) {
+    case "Column":
+      collector.tables.add(node.table);
+      break;
+    case "Function":
+      node.args.forEach((arg) => collectFromOperand(arg, collector));
+      if (node.separator) {
+        collectFromOperand(node.separator, collector);
+      }
+      if (node.orderBy) {
+        node.orderBy.forEach((order) => collectFromOrderingTerm(order.term, collector));
+      }
+      break;
+    case "JsonPath":
+      collectFromOperand(node.column, collector);
+      break;
+    case "ScalarSubquery":
+      collector.hasSubquery = true;
+      break;
+    case "CaseExpression":
+      node.conditions.forEach(({ when, then }) => {
+        collectFromExpression(when, collector);
+        collectFromOperand(then, collector);
+      });
+      if (node.else) {
+        collectFromOperand(node.else, collector);
+      }
+      break;
+    case "Cast":
+      collectFromOperand(node.expression, collector);
+      break;
+    case "WindowFunction":
+      node.args.forEach((arg) => collectFromOperand(arg, collector));
+      node.partitionBy?.forEach((part) => collectFromOperand(part, collector));
+      node.orderBy?.forEach((order) => collectFromOrderingTerm(order.term, collector));
+      break;
+    case "Collate":
+      collectFromOperand(node.expression, collector);
+      break;
+    case "ArithmeticExpression":
+    case "BitwiseExpression":
+      collectFromOperand(node.left, collector);
+      collectFromOperand(node.right, collector);
+      break;
+    case "Literal":
+    case "AliasRef":
+      break;
+    default:
+      break;
   }
-  /**
-   * Creates a join node for a relation
-   * @param state - Current query state
-   * @param relationName - Name of the relation
-   * @param joinKind - Type of join to use
-   * @param extraCondition - Additional join condition
-   * @returns Updated query state with join
-   */
-  withJoin(state, relationName, joinKind, extraCondition, tableSource) {
-    const relation = this.getRelation(relationName);
+};
+var collectFromOrderingTerm = (term, collector) => {
+  if (isOperandNode(term)) {
+    collectFromOperand(term, collector);
+    return;
+  }
+  collectFromExpression(term, collector);
+};
+
+// src/query-builder/relation-join-planner.ts
+var RelationJoinPlanner = class {
+  constructor(table, createQueryAstService) {
+    this.table = table;
+    this.createQueryAstService = createQueryAstService;
+  }
+  withJoin(state, relationName, relation, joinKind, extraCondition, tableSource) {
     const rootAlias = state.ast.from.type === "Table" ? state.ast.from.alias : void 0;
     if (relation.type === RelationKinds.BelongsToMany) {
       const targetTableSource = tableSource ?? {
@@ -4149,167 +4101,31 @@ var RelationService = class {
     const joinNode = createJoinNode(joinKind, targetTable, condition, relationName);
     return this.astService(state).withJoin(joinNode);
   }
-  /**
-   * Selects columns for a relation
-   * @param state - Current query state
-   * @param hydration - Hydration manager
-   * @param columns - Columns to select
-   * @returns Relation result with updated state and hydration
-   */
-  selectColumns(state, hydration, columns) {
-    const { state: nextState, addedColumns } = this.astService(state).select(columns);
-    return {
-      state: nextState,
-      hydration: hydration.onColumnsSelected(nextState, addedColumns)
-    };
-  }
-  combineWithAnd(expressions) {
-    if (expressions.length === 0) return void 0;
-    if (expressions.length === 1) return expressions[0];
-    return {
-      type: "LogicalExpression",
-      operator: "AND",
-      operands: expressions
-    };
-  }
-  splitFilterExpressions(filter, allowedTables) {
-    const terms = this.flattenAnd(filter);
-    const selfFilters = [];
-    const crossFilters = [];
-    for (const term of terms) {
-      if (this.isExpressionSelfContained(term, allowedTables)) {
-        selfFilters.push(term);
-      } else {
-        crossFilters.push(term);
-      }
-    }
-    return { selfFilters, crossFilters };
-  }
-  flattenAnd(node) {
-    if (!node) return [];
-    if (node.type === "LogicalExpression" && node.operator === "AND") {
-      return node.operands.flatMap((operand) => this.flattenAnd(operand));
-    }
-    return [node];
+  astService(state) {
+    return this.createQueryAstService(this.table, state);
   }
-  isExpressionSelfContained(expr, allowedTables) {
-    const collector = this.collectReferencedTables(expr);
-    if (collector.hasSubquery) return false;
-    if (collector.tables.size === 0) return true;
-    for (const table of collector.tables) {
-      if (!allowedTables.has(table)) {
-        return false;
-      }
+  resolveTargetTableName(target, relation) {
+    if (target.type === "Table") {
+      return target.alias ?? target.name;
     }
-    return true;
-  }
-  collectReferencedTables(expr) {
-    const collector = {
-      tables: /* @__PURE__ */ new Set(),
-      hasSubquery: false
-    };
-    this.collectFromExpression(expr, collector);
-    return collector;
-  }
-  collectFromExpression(expr, collector) {
-    switch (expr.type) {
-      case "BinaryExpression":
-        this.collectFromOperand(expr.left, collector);
-        this.collectFromOperand(expr.right, collector);
-        break;
-      case "LogicalExpression":
-        expr.operands.forEach((operand) => this.collectFromExpression(operand, collector));
-        break;
-      case "NullExpression":
-        this.collectFromOperand(expr.left, collector);
-        break;
-      case "InExpression":
-        this.collectFromOperand(expr.left, collector);
-        if (Array.isArray(expr.right)) {
-          expr.right.forEach((value) => this.collectFromOperand(value, collector));
-        } else {
-          collector.hasSubquery = true;
-        }
-        break;
-      case "ExistsExpression":
-        collector.hasSubquery = true;
-        break;
-      case "BetweenExpression":
-        this.collectFromOperand(expr.left, collector);
-        this.collectFromOperand(expr.lower, collector);
-        this.collectFromOperand(expr.upper, collector);
-        break;
-      case "ArithmeticExpression":
-      case "BitwiseExpression":
-        this.collectFromOperand(expr.left, collector);
-        this.collectFromOperand(expr.right, collector);
-        break;
-      default:
-        break;
+    if (target.type === "DerivedTable") {
+      return target.alias;
     }
-  }
-  collectFromOperand(node, collector) {
-    switch (node.type) {
-      case "Column":
-        collector.tables.add(node.table);
-        break;
-      case "Function":
-        node.args.forEach((arg) => this.collectFromOperand(arg, collector));
-        if (node.separator) {
-          this.collectFromOperand(node.separator, collector);
-        }
-        if (node.orderBy) {
-          node.orderBy.forEach((order) => this.collectFromOrderingTerm(order.term, collector));
-        }
-        break;
-      case "JsonPath":
-        this.collectFromOperand(node.column, collector);
-        break;
-      case "ScalarSubquery":
-        collector.hasSubquery = true;
-        break;
-      case "CaseExpression":
-        node.conditions.forEach(({ when, then }) => {
-          this.collectFromExpression(when, collector);
-          this.collectFromOperand(then, collector);
-        });
-        if (node.else) {
-          this.collectFromOperand(node.else, collector);
-        }
-        break;
-      case "Cast":
-        this.collectFromOperand(node.expression, collector);
-        break;
-      case "WindowFunction":
-        node.args.forEach((arg) => this.collectFromOperand(arg, collector));
-        node.partitionBy?.forEach((part) => this.collectFromOperand(part, collector));
-        node.orderBy?.forEach((order) => this.collectFromOrderingTerm(order.term, collector));
-        break;
-      case "Collate":
-        this.collectFromOperand(node.expression, collector);
-        break;
-      case "ArithmeticExpression":
-      case "BitwiseExpression":
-        this.collectFromOperand(node.left, collector);
-        this.collectFromOperand(node.right, collector);
-        break;
-      case "Literal":
-      case "AliasRef":
-        break;
-      default:
-        break;
+    if (target.type === "FunctionTable") {
+      return target.alias ?? relation.target.name;
     }
+    return relation.target.name;
   }
-  collectFromOrderingTerm(term, collector) {
-    if (isOperandNode(term)) {
-      this.collectFromOperand(term, collector);
-      return;
-    }
-    this.collectFromExpression(term, collector);
+};
+
+// src/query-builder/relation-cte-builder.ts
+var RelationCteBuilder = class {
+  constructor(table, createQueryAstService) {
+    this.table = table;
+    this.createQueryAstService = createQueryAstService;
   }
-  createFilteredRelationCte(state, relationName, relation, filters) {
+  createFilteredRelationCte(state, relationName, relation, predicate) {
     const cteName = this.generateUniqueCteName(state, relationName);
-    const predicate = this.combineWithAnd(filters);
     if (!predicate) {
       throw new Error("Unable to build filter CTE without predicates.");
     }
@@ -4343,17 +4159,274 @@ var RelationService = class {
     }
     return candidate;
   }
-  resolveTargetTableName(target, relation) {
-    if (target.type === "Table") {
-      return target.alias ?? target.name;
+  astService(state) {
+    return this.createQueryAstService(this.table, state);
+  }
+};
+
+// src/query-builder/relation-include-strategies.ts
+var buildTypedSelection = (columns, prefix, keys, missingMsg) => {
+  return keys.reduce((acc, key) => {
+    const def = columns[key];
+    if (!def) {
+      throw new Error(missingMsg(key));
     }
-    if (target.type === "DerivedTable") {
-      return target.alias;
+    acc[makeRelationAlias(prefix, key)] = def;
+    return acc;
+  }, {});
+};
+var resolveTargetColumns = (relation, options) => {
+  const requestedColumns = options?.columns?.length ? [...options.columns] : Object.keys(relation.target.columns);
+  const targetPrimaryKey = findPrimaryKey(relation.target);
+  if (!requestedColumns.includes(targetPrimaryKey)) {
+    requestedColumns.push(targetPrimaryKey);
+  }
+  return requestedColumns;
+};
+var ensureRootForeignKeySelected = (context, relation) => {
+  const fkColumn = context.rootTable.columns[relation.foreignKey];
+  if (!fkColumn) {
+    return { state: context.state, hydration: context.hydration };
+  }
+  const hasForeignKeySelected = context.state.ast.columns.some((col2) => {
+    if (col2.type !== "Column") return false;
+    const node = col2;
+    const alias = node.alias ?? node.name;
+    return alias === relation.foreignKey;
+  });
+  if (hasForeignKeySelected) {
+    return { state: context.state, hydration: context.hydration };
+  }
+  return context.selectColumns(context.state, context.hydration, {
+    [relation.foreignKey]: fkColumn
+  });
+};
+var standardIncludeStrategy = (context) => {
+  const relation = context.relation;
+  let { state, hydration } = context;
+  const fkSelectionResult = ensureRootForeignKeySelected(context, relation);
+  state = fkSelectionResult.state;
+  hydration = fkSelectionResult.hydration;
+  const targetColumns = resolveTargetColumns(relation, context.options);
+  const targetSelection = buildTypedSelection(
+    relation.target.columns,
+    context.aliasPrefix,
+    targetColumns,
+    (key) => `Column '${key}' not found on relation '${context.relationName}'`
+  );
+  const relationSelectionResult = context.selectColumns(state, hydration, targetSelection);
+  state = relationSelectionResult.state;
+  hydration = relationSelectionResult.hydration;
+  hydration = hydration.onRelationIncluded(
+    state,
+    relation,
+    context.relationName,
+    context.aliasPrefix,
+    targetColumns
+  );
+  return { state, hydration };
+};
+var belongsToManyStrategy = (context) => {
+  const relation = context.relation;
+  let { state, hydration } = context;
+  const targetColumns = resolveTargetColumns(relation, context.options);
+  const targetSelection = buildTypedSelection(
+    relation.target.columns,
+    context.aliasPrefix,
+    targetColumns,
+    (key) => `Column '${key}' not found on relation '${context.relationName}'`
+  );
+  const pivotAliasPrefix = context.options?.pivot?.aliasPrefix ?? `${context.aliasPrefix}_pivot`;
+  const pivotPk = relation.pivotPrimaryKey || findPrimaryKey(relation.pivotTable);
+  const defaultPivotColumns = relation.defaultPivotColumns ?? buildDefaultPivotColumns(relation, pivotPk);
+  const pivotColumns = context.options?.pivot?.columns ? [...context.options.pivot.columns] : [...defaultPivotColumns];
+  const pivotSelection = buildTypedSelection(
+    relation.pivotTable.columns,
+    pivotAliasPrefix,
+    pivotColumns,
+    (key) => `Column '${key}' not found on pivot table '${relation.pivotTable.name}'`
+  );
+  const combinedSelection = {
+    ...targetSelection,
+    ...pivotSelection
+  };
+  const relationSelectionResult = context.selectColumns(state, hydration, combinedSelection);
+  state = relationSelectionResult.state;
+  hydration = relationSelectionResult.hydration;
+  hydration = hydration.onRelationIncluded(
+    state,
+    relation,
+    context.relationName,
+    context.aliasPrefix,
+    targetColumns,
+    { aliasPrefix: pivotAliasPrefix, columns: pivotColumns }
+  );
+  return { state, hydration };
+};
+var relationIncludeStrategies = {
+  [RelationKinds.HasMany]: standardIncludeStrategy,
+  [RelationKinds.HasOne]: standardIncludeStrategy,
+  [RelationKinds.BelongsTo]: standardIncludeStrategy,
+  [RelationKinds.BelongsToMany]: belongsToManyStrategy
+};
+
+// src/query-builder/relation-service.ts
+var RelationService = class {
+  /**
+   * Creates a new RelationService instance
+   * @param table - Table definition
+   * @param state - Current query state
+   * @param hydration - Hydration manager
+   */
+  constructor(table, state, hydration, createQueryAstService) {
+    this.table = table;
+    this.state = state;
+    this.hydration = hydration;
+    this.createQueryAstService = createQueryAstService;
+    this.projectionHelper = new RelationProjectionHelper(
+      table,
+      (state2, hydration2, columns) => this.selectColumns(state2, hydration2, columns)
+    );
+    this.joinPlanner = new RelationJoinPlanner(table, createQueryAstService);
+    this.cteBuilder = new RelationCteBuilder(table, createQueryAstService);
+  }
+  projectionHelper;
+  joinPlanner;
+  cteBuilder;
+  /**
+   * Joins a relation to the query
+   * @param relationName - Name of the relation to join
+   * @param joinKind - Type of join to use
+   * @param extraCondition - Additional join condition
+   * @returns Relation result with updated state and hydration
+   */
+  joinRelation(relationName, joinKind, extraCondition, tableSource) {
+    const relation = this.getRelation(relationName);
+    const nextState = this.joinPlanner.withJoin(
+      this.state,
+      relationName,
+      relation,
+      joinKind,
+      extraCondition,
+      tableSource
+    );
+    return { state: nextState, hydration: this.hydration };
+  }
+  /**
+   * Matches records based on a relation with an optional predicate
+   * @param relationName - Name of the relation to match
+   * @param predicate - Optional predicate expression
+   * @returns Relation result with updated state and hydration
+   */
+  match(relationName, predicate) {
+    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
+    const pk = findPrimaryKey(this.table);
+    const distinctCols = [{ type: "Column", table: this.rootTableName(), name: pk }];
+    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
+    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
+    return { state: nextState, hydration: joined.hydration };
+  }
+  /**
+   * Includes a relation in the query result
+   * @param relationName - Name of the relation to include
+   * @param options - Options for relation inclusion
+   * @returns Relation result with updated state and hydration
+   */
+  include(relationName, options) {
+    let state = this.state;
+    let hydration = this.hydration;
+    const relation = this.getRelation(relationName);
+    const aliasPrefix = options?.aliasPrefix ?? relationName;
+    const alreadyJoined = state.ast.joins.some((j) => getJoinRelationName(j) === relationName);
+    const { selfFilters, crossFilters } = splitFilterExpressions(
+      options?.filter,
+      /* @__PURE__ */ new Set([relation.target.name])
+    );
+    const canUseCte = !alreadyJoined && selfFilters.length > 0;
+    const joinFilters = [...crossFilters];
+    if (!canUseCte) {
+      joinFilters.push(...selfFilters);
     }
-    if (target.type === "FunctionTable") {
-      return target.alias ?? relation.target.name;
+    const joinCondition = this.combineWithAnd(joinFilters);
+    let tableSourceOverride;
+    if (canUseCte) {
+      const predicate = this.combineWithAnd(selfFilters);
+      const cteInfo = this.cteBuilder.createFilteredRelationCte(
+        state,
+        relationName,
+        relation,
+        predicate
+      );
+      state = cteInfo.state;
+      tableSourceOverride = cteInfo.table;
     }
-    return relation.target.name;
+    if (!alreadyJoined) {
+      state = this.joinPlanner.withJoin(
+        state,
+        relationName,
+        relation,
+        options?.joinKind ?? JOIN_KINDS.LEFT,
+        joinCondition,
+        tableSourceOverride
+      );
+    }
+    const projectionResult = this.projectionHelper.ensureBaseProjection(state, hydration);
+    state = projectionResult.state;
+    hydration = projectionResult.hydration;
+    const strategy = relationIncludeStrategies[relation.type];
+    const result = strategy({
+      rootTable: this.table,
+      state,
+      hydration,
+      relation,
+      relationName,
+      aliasPrefix,
+      options,
+      selectColumns: (nextState, nextHydration, columns) => this.selectColumns(nextState, nextHydration, columns)
+    });
+    return { state: result.state, hydration: result.hydration };
+  }
+  /**
+   * Applies relation correlation to a query AST
+   * @param relationName - Name of the relation
+   * @param ast - Query AST to modify
+   * @returns Modified query AST with relation correlation
+   */
+  applyRelationCorrelation(relationName, ast, additionalCorrelation) {
+    const relation = this.getRelation(relationName);
+    const rootAlias = this.state.ast.from.type === "Table" ? this.state.ast.from.alias : void 0;
+    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
+    if (additionalCorrelation) {
+      correlation = and(correlation, additionalCorrelation);
+    }
+    const whereInSubquery = ast.where ? and(correlation, ast.where) : correlation;
+    return {
+      ...ast,
+      where: whereInSubquery
+    };
+  }
+  /**
+   * Selects columns for a relation
+   * @param state - Current query state
+   * @param hydration - Hydration manager
+   * @param columns - Columns to select
+   * @returns Relation result with updated state and hydration
+   */
+  selectColumns(state, hydration, columns) {
+    const { state: nextState, addedColumns } = this.astService(state).select(columns);
+    return {
+      state: nextState,
+      hydration: hydration.onColumnsSelected(nextState, addedColumns)
+    };
+  }
+  combineWithAnd(expressions) {
+    if (expressions.length === 0) return void 0;
+    if (expressions.length === 1) return expressions[0];
+    return {
+      type: "LogicalExpression",
+      operator: "AND",
+      operands: expressions
+    };
   }
   /**
    * Gets a relation definition by name
@@ -4643,8 +4716,52 @@ var hasEntityMeta = (entity) => {
   return Boolean(getEntityMeta(entity));
 };
 
-// src/orm/relations/has-many.ts
+// src/orm/entity-hydration.ts
 var toKey2 = (value) => value === null || value === void 0 ? "" : String(value);
+var populateHydrationCache = (entity, row, meta) => {
+  for (const relationName of Object.keys(meta.table.relations)) {
+    const relation = meta.table.relations[relationName];
+    const data = row[relationName];
+    if (relation.type === RelationKinds.HasOne) {
+      const localKey = relation.localKey || findPrimaryKey(meta.table);
+      const rootValue = entity[localKey];
+      if (rootValue === void 0 || rootValue === null) continue;
+      if (!data || typeof data !== "object") continue;
+      const cache = /* @__PURE__ */ new Map();
+      cache.set(toKey2(rootValue), data);
+      meta.relationHydration.set(relationName, cache);
+      meta.relationCache.set(relationName, Promise.resolve(cache));
+      continue;
+    }
+    if (!Array.isArray(data)) continue;
+    if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
+      const localKey = relation.localKey || findPrimaryKey(meta.table);
+      const rootValue = entity[localKey];
+      if (rootValue === void 0 || rootValue === null) continue;
+      const cache = /* @__PURE__ */ new Map();
+      cache.set(toKey2(rootValue), data);
+      meta.relationHydration.set(relationName, cache);
+      meta.relationCache.set(relationName, Promise.resolve(cache));
+      continue;
+    }
+    if (relation.type === RelationKinds.BelongsTo) {
+      const targetKey = relation.localKey || findPrimaryKey(relation.target);
+      const cache = /* @__PURE__ */ new Map();
+      for (const item of data) {
+        const pkValue = item[targetKey];
+        if (pkValue === void 0 || pkValue === null) continue;
+        cache.set(toKey2(pkValue), item);
+      }
+      if (cache.size) {
+        meta.relationHydration.set(relationName, cache);
+        meta.relationCache.set(relationName, Promise.resolve(cache));
+      }
+    }
+  }
+};
+
+// src/orm/relations/has-many.ts
+var toKey3 = (value) => value === null || value === void 0 ? "" : String(value);
 var hideInternal = (obj, keys) => {
   for (const key of keys) {
     Object.defineProperty(obj, key, {
@@ -4678,13 +4795,13 @@ var DefaultHasManyCollection = class {
     this.loader = loader;
     this.createEntity = createEntity;
     this.localKey = localKey;
-    this.loaded = false;
-    this.items = [];
-    this.added = /* @__PURE__ */ new Set();
-    this.removed = /* @__PURE__ */ new Set();
     hideInternal(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
+  loaded = false;
+  items = [];
+  added = /* @__PURE__ */ new Set();
+  removed = /* @__PURE__ */ new Set();
   /**
    * Loads the related entities if not already loaded.
    * @returns Promise resolving to the array of child entities
@@ -4692,7 +4809,7 @@ var DefaultHasManyCollection = class {
   async load() {
     if (this.loaded) return this.items;
     const map = await this.loader();
-    const key = toKey2(this.root[this.localKey]);
+    const key = toKey3(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
     this.items = rows.map((row) => this.createEntity(row));
     this.loaded = true;
@@ -4804,7 +4921,7 @@ var DefaultHasManyCollection = class {
 };
 
 // src/orm/relations/has-one.ts
-var toKey3 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
 var hideInternal2 = (obj, keys) => {
   for (const key of keys) {
     Object.defineProperty(obj, key, {
@@ -4837,8 +4954,6 @@ var DefaultHasOneReference = class {
     this.loader = loader;
     this.createEntity = createEntity;
     this.localKey = localKey;
-    this.loaded = false;
-    this.current = null;
     hideInternal2(this, [
       "ctx",
       "meta",
@@ -4852,6 +4967,8 @@ var DefaultHasOneReference = class {
     ]);
     this.populateFromHydrationCache();
   }
+  loaded = false;
+  current = null;
   async load() {
     if (this.loaded) return this.current;
     const map = await this.loader();
@@ -4860,7 +4977,7 @@ var DefaultHasOneReference = class {
       this.loaded = true;
       return this.current;
     }
-    const row = map.get(toKey3(keyValue));
+    const row = map.get(toKey4(keyValue));
     this.current = row ? this.createEntity(row) : null;
     this.loaded = true;
     return this.current;
@@ -4932,7 +5049,7 @@ var DefaultHasOneReference = class {
 };
 
 // src/orm/relations/belongs-to.ts
-var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey5 = (value) => value === null || value === void 0 ? "" : String(value);
 var hideInternal3 = (obj, keys) => {
   for (const key of keys) {
     Object.defineProperty(obj, key, {
@@ -4965,11 +5082,11 @@ var DefaultBelongsToReference = class {
     this.loader = loader;
     this.createEntity = createEntity;
     this.targetKey = targetKey;
-    this.loaded = false;
-    this.current = null;
     hideInternal3(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "targetKey"]);
     this.populateFromHydrationCache();
   }
+  loaded = false;
+  current = null;
   async load() {
     if (this.loaded) return this.current;
     const map = await this.loader();
@@ -4977,7 +5094,7 @@ var DefaultBelongsToReference = class {
     if (fkValue === null || fkValue === void 0) {
       this.current = null;
     } else {
-      const row = map.get(toKey4(fkValue));
+      const row = map.get(toKey5(fkValue));
       this.current = row ? this.createEntity(row) : null;
     }
     this.loaded = true;
@@ -5034,7 +5151,7 @@ var DefaultBelongsToReference = class {
 };
 
 // src/orm/relations/many-to-many.ts
-var toKey5 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey6 = (value) => value === null || value === void 0 ? "" : String(value);
 var hideInternal4 = (obj, keys) => {
   for (const key of keys) {
     Object.defineProperty(obj, key, {
@@ -5067,11 +5184,11 @@ var DefaultManyToManyCollection = class {
     this.loader = loader;
     this.createEntity = createEntity;
     this.localKey = localKey;
-    this.loaded = false;
-    this.items = [];
     hideInternal4(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
+  loaded = false;
+  items = [];
   /**
    * Loads the collection items if not already loaded.
    * @returns A promise that resolves to the array of target entities.
@@ -5079,7 +5196,7 @@ var DefaultManyToManyCollection = class {
   async load() {
     if (this.loaded) return this.items;
     const map = await this.loader();
-    const key = toKey5(this.root[this.localKey]);
+    const key = toKey6(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
     this.items = rows.map((row) => {
       const entity = this.createEntity(row);
@@ -5161,15 +5278,15 @@ var DefaultManyToManyCollection = class {
    */
   async syncByIds(ids) {
     await this.load();
-    const normalized = new Set(ids.map((id) => toKey5(id)));
-    const currentIds = new Set(this.items.map((item) => toKey5(this.extractId(item))));
+    const normalized = new Set(ids.map((id) => toKey6(id)));
+    const currentIds = new Set(this.items.map((item) => toKey6(this.extractId(item))));
     for (const id of normalized) {
       if (!currentIds.has(id)) {
         this.attach(id);
       }
     }
     for (const item of [...this.items]) {
-      const itemId = toKey5(this.extractId(item));
+      const itemId = toKey6(this.extractId(item));
       if (!normalized.has(itemId)) {
         this.detach(item);
       }
@@ -5216,7 +5333,7 @@ var DefaultManyToManyCollection = class {
   }
 };
 
-// src/orm/lazy-batch.ts
+// src/orm/lazy-batch/shared.ts
 var hasColumns = (columns) => Boolean(columns && columns.length > 0);
 var buildColumnSelection = (table, columns, missingMsg) => {
   return columns.reduce((acc, column) => {
@@ -5257,7 +5374,7 @@ var executeQuery = async (ctx, qb) => {
   const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
   return rowsFromResults(results);
 };
-var toKey6 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey7 = (value) => value === null || value === void 0 ? "" : String(value);
 var collectKeysFromRoots = (roots, key) => {
   const collected = /* @__PURE__ */ new Set();
   for (const tracked of roots) {
@@ -5282,7 +5399,7 @@ var groupRowsByMany = (rows, keyColumn) => {
   for (const row of rows) {
     const value = row[keyColumn];
     if (value === null || value === void 0) continue;
-    const key = toKey6(value);
+    const key = toKey7(value);
     const bucket = grouped.get(key) ?? [];
     bucket.push(row);
     grouped.set(key, bucket);
@@ -5294,13 +5411,15 @@ var groupRowsByUnique = (rows, keyColumn) => {
   for (const row of rows) {
     const value = row[keyColumn];
     if (value === null || value === void 0) continue;
-    const key = toKey6(value);
+    const key = toKey7(value);
     if (!lookup.has(key)) {
       lookup.set(key, row);
     }
   }
   return lookup;
 };
+
+// src/orm/lazy-batch/has-many.ts
 var loadHasManyRelation = async (ctx, rootTable, relationName, relation, options) => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
@@ -5333,6 +5452,8 @@ var loadHasManyRelation = async (ctx, rootTable, relationName, relation, options
   }
   return filtered;
 };
+
+// src/orm/lazy-batch/has-one.ts
 var loadHasOneRelation = async (ctx, rootTable, relationName, relation, options) => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
@@ -5365,6 +5486,8 @@ var loadHasOneRelation = async (ctx, rootTable, relationName, relation, options)
   }
   return filtered;
 };
+
+// src/orm/lazy-batch/belongs-to.ts
 var loadBelongsToRelation = async (ctx, rootTable, relationName, relation, options) => {
   const roots = ctx.getEntitiesForTable(rootTable);
   const getForeignKeys = () => collectKeysFromRoots(roots, relation.foreignKey);
@@ -5433,6 +5556,8 @@ var loadBelongsToRelation = async (ctx, rootTable, relationName, relation, optio
   }
   return filtered;
 };
+
+// src/orm/lazy-batch/belongs-to-many.ts
 var loadBelongsToManyRelation = async (ctx, rootTable, relationName, relation, options) => {
   const rootKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
@@ -5471,12 +5596,12 @@ var loadBelongsToManyRelation = async (ctx, rootTable, relationName, relation, o
     if (rootValue === null || rootValue === void 0 || targetValue === null || targetValue === void 0) {
       continue;
     }
-    const bucket = rootLookup.get(toKey6(rootValue)) ?? [];
+    const bucket = rootLookup.get(toKey7(rootValue)) ?? [];
     bucket.push({
       targetId: targetValue,
       pivot: pivotVisibleColumns.size ? filterRow(pivot, pivotVisibleColumns) : {}
     });
-    rootLookup.set(toKey6(rootValue), bucket);
+    rootLookup.set(toKey7(rootValue), bucket);
     targetIds.add(targetValue);
   }
   if (!targetIds.size) {
@@ -5489,156 +5614,61 @@ var loadBelongsToManyRelation = async (ctx, rootTable, relationName, relation, o
   const targetSelectedColumns = targetRequestedColumns ? [...targetRequestedColumns] : Object.keys(relation.target.columns);
   if (!targetSelectedColumns.includes(targetKey)) {
     targetSelectedColumns.push(targetKey);
-  }
-  const targetSelection = buildColumnSelection(
-    relation.target,
-    targetSelectedColumns,
-    (column) => `Column '${column}' not found on relation '${relationName}'`
-  );
-  const targetRows = await fetchRowsForKeys(ctx, relation.target, targetPkColumn, targetIds, targetSelection, options?.filter);
-  const targetMap = groupRowsByUnique(targetRows, targetKey);
-  const targetVisibleColumns = new Set(targetSelectedColumns);
-  const result = /* @__PURE__ */ new Map();
-  for (const [rootId, entries] of rootLookup.entries()) {
-    const bucket = [];
-    for (const entry of entries) {
-      const targetRow = targetMap.get(toKey6(entry.targetId));
-      if (!targetRow) continue;
-      bucket.push({
-        ...targetRequestedColumns ? filterRow(targetRow, targetVisibleColumns) : targetRow,
-        _pivot: entry.pivot
-      });
-    }
-    result.set(rootId, bucket);
-  }
-  return result;
-};
-
-// src/orm/entity.ts
-var relationLoaderCache = (meta, relationName, factory) => {
-  if (meta.relationCache.has(relationName)) {
-    return meta.relationCache.get(relationName);
-  }
-  const promise = factory().then((value) => {
-    for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
-      const otherMeta = getEntityMeta(tracked.entity);
-      if (!otherMeta) continue;
-      otherMeta.relationHydration.set(relationName, value);
-    }
-    return value;
-  });
-  meta.relationCache.set(relationName, promise);
-  for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
-    const otherMeta = getEntityMeta(tracked.entity);
-    if (!otherMeta) continue;
-    otherMeta.relationCache.set(relationName, promise);
-  }
-  return promise;
-};
-var createEntityProxy = (ctx, table, row, lazyRelations = [], lazyRelationOptions = /* @__PURE__ */ new Map()) => {
-  const target = { ...row };
-  const meta = {
-    ctx,
-    table,
-    lazyRelations: [...lazyRelations],
-    lazyRelationOptions: new Map(lazyRelationOptions),
-    relationCache: /* @__PURE__ */ new Map(),
-    relationHydration: /* @__PURE__ */ new Map(),
-    relationWrappers: /* @__PURE__ */ new Map()
-  };
-  Object.defineProperty(target, ENTITY_META, {
-    value: meta,
-    enumerable: false,
-    writable: false
-  });
-  const handler = {
-    get(targetObj, prop, receiver) {
-      if (prop === ENTITY_META) {
-        return meta;
-      }
-      if (prop === "$load") {
-        return async (relationName) => {
-          const wrapper = getRelationWrapper(meta, relationName, receiver);
-          if (wrapper && typeof wrapper.load === "function") {
-            return wrapper.load();
-          }
-          return void 0;
-        };
-      }
-      if (typeof prop === "string" && table.relations[prop]) {
-        return getRelationWrapper(meta, prop, receiver);
-      }
-      return Reflect.get(targetObj, prop, receiver);
-    },
-    set(targetObj, prop, value, receiver) {
-      const result = Reflect.set(targetObj, prop, value, receiver);
-      if (typeof prop === "string" && table.columns[prop]) {
-        ctx.markDirty(receiver);
-      }
-      return result;
-    }
-  };
-  const proxy = new Proxy(target, handler);
-  populateHydrationCache(proxy, row, meta);
-  return proxy;
-};
-var createEntityFromRow = (ctx, table, row, lazyRelations = [], lazyRelationOptions = /* @__PURE__ */ new Map()) => {
-  const pkName = findPrimaryKey(table);
-  const pkValue = row[pkName];
-  if (pkValue !== void 0 && pkValue !== null) {
-    const tracked = ctx.getEntity(table, pkValue);
-    if (tracked) return tracked;
-  }
-  const entity = createEntityProxy(ctx, table, row, lazyRelations, lazyRelationOptions);
-  if (pkValue !== void 0 && pkValue !== null) {
-    ctx.trackManaged(table, pkValue, entity);
-  } else {
-    ctx.trackNew(table, entity);
-  }
-  return entity;
-};
-var toKey7 = (value) => value === null || value === void 0 ? "" : String(value);
-var populateHydrationCache = (entity, row, meta) => {
-  for (const relationName of Object.keys(meta.table.relations)) {
-    const relation = meta.table.relations[relationName];
-    const data = row[relationName];
-    if (relation.type === RelationKinds.HasOne) {
-      const localKey = relation.localKey || findPrimaryKey(meta.table);
-      const rootValue = entity[localKey];
-      if (rootValue === void 0 || rootValue === null) continue;
-      if (!data || typeof data !== "object") continue;
-      const cache = /* @__PURE__ */ new Map();
-      cache.set(toKey7(rootValue), data);
-      meta.relationHydration.set(relationName, cache);
-      meta.relationCache.set(relationName, Promise.resolve(cache));
-      continue;
-    }
-    if (!Array.isArray(data)) continue;
-    if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
-      const localKey = relation.localKey || findPrimaryKey(meta.table);
-      const rootValue = entity[localKey];
-      if (rootValue === void 0 || rootValue === null) continue;
-      const cache = /* @__PURE__ */ new Map();
-      cache.set(toKey7(rootValue), data);
-      meta.relationHydration.set(relationName, cache);
-      meta.relationCache.set(relationName, Promise.resolve(cache));
-      continue;
+  }
+  const targetSelection = buildColumnSelection(
+    relation.target,
+    targetSelectedColumns,
+    (column) => `Column '${column}' not found on relation '${relationName}'`
+  );
+  const targetRows = await fetchRowsForKeys(
+    ctx,
+    relation.target,
+    targetPkColumn,
+    targetIds,
+    targetSelection,
+    options?.filter
+  );
+  const targetMap = groupRowsByUnique(targetRows, targetKey);
+  const targetVisibleColumns = new Set(targetSelectedColumns);
+  const result = /* @__PURE__ */ new Map();
+  for (const [rootId, entries] of rootLookup.entries()) {
+    const bucket = [];
+    for (const entry of entries) {
+      const targetRow = targetMap.get(toKey7(entry.targetId));
+      if (!targetRow) continue;
+      bucket.push({
+        ...targetRequestedColumns ? filterRow(targetRow, targetVisibleColumns) : targetRow,
+        _pivot: entry.pivot
+      });
     }
-    if (relation.type === RelationKinds.BelongsTo) {
-      const targetKey = relation.localKey || findPrimaryKey(relation.target);
-      const cache = /* @__PURE__ */ new Map();
-      for (const item of data) {
-        const pkValue = item[targetKey];
-        if (pkValue === void 0 || pkValue === null) continue;
-        cache.set(toKey7(pkValue), item);
-      }
-      if (cache.size) {
-        meta.relationHydration.set(relationName, cache);
-        meta.relationCache.set(relationName, Promise.resolve(cache));
-      }
+    result.set(rootId, bucket);
+  }
+  return result;
+};
+
+// src/orm/entity-relation-cache.ts
+var relationLoaderCache = (meta, relationName, factory) => {
+  if (meta.relationCache.has(relationName)) {
+    return meta.relationCache.get(relationName);
+  }
+  const promise = factory().then((value) => {
+    for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+      const otherMeta = getEntityMeta(tracked.entity);
+      if (!otherMeta) continue;
+      otherMeta.relationHydration.set(relationName, value);
     }
+    return value;
+  });
+  meta.relationCache.set(relationName, promise);
+  for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+    const otherMeta = getEntityMeta(tracked.entity);
+    if (!otherMeta) continue;
+    otherMeta.relationCache.set(relationName, promise);
   }
+  return promise;
 };
+
+// src/orm/entity-relations.ts
 var proxifyRelationWrapper = (wrapper) => {
   return new Proxy(wrapper, {
     get(target, prop, receiver) {
@@ -5691,98 +5721,93 @@ var proxifyRelationWrapper = (wrapper) => {
     }
   });
 };
-var getRelationWrapper = (meta, relationName, owner) => {
-  if (meta.relationWrappers.has(relationName)) {
-    return meta.relationWrappers.get(relationName);
+var getRelationWrapper = (meta, relationName, owner, createEntity) => {
+  const relationKey = relationName;
+  if (meta.relationWrappers.has(relationKey)) {
+    return meta.relationWrappers.get(relationKey);
   }
-  const relation = meta.table.relations[relationName];
+  const relation = meta.table.relations[relationKey];
   if (!relation) return void 0;
-  const wrapper = instantiateWrapper(meta, relationName, relation, owner);
+  const wrapper = instantiateWrapper(meta, relationKey, relation, owner, createEntity);
   if (!wrapper) return void 0;
   const proxied = proxifyRelationWrapper(wrapper);
-  meta.relationWrappers.set(relationName, proxied);
+  meta.relationWrappers.set(relationKey, proxied);
   return proxied;
 };
-var instantiateWrapper = (meta, relationName, relation, owner) => {
+var instantiateWrapper = (meta, relationName, relation, owner, createEntity) => {
+  const metaBase = meta;
   const lazyOptions = meta.lazyRelationOptions.get(relationName);
+  const loadCached = (factory) => relationLoaderCache(metaBase, relationName, factory);
   switch (relation.type) {
     case RelationKinds.HasOne: {
       const hasOne2 = relation;
       const localKey = hasOne2.localKey || findPrimaryKey(meta.table);
-      const loader = () => relationLoaderCache(
-        meta,
-        relationName,
+      const loader = () => loadCached(
         () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2, lazyOptions)
       );
       return new DefaultHasOneReference(
         meta.ctx,
-        meta,
+        metaBase,
         owner,
         relationName,
         hasOne2,
         meta.table,
         loader,
-        (row) => createEntityFromRow(meta.ctx, hasOne2.target, row),
+        (row) => createEntity(hasOne2.target, row),
         localKey
       );
     }
     case RelationKinds.HasMany: {
       const hasMany2 = relation;
       const localKey = hasMany2.localKey || findPrimaryKey(meta.table);
-      const loader = () => relationLoaderCache(
-        meta,
-        relationName,
+      const loader = () => loadCached(
         () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2, lazyOptions)
       );
       return new DefaultHasManyCollection(
         meta.ctx,
-        meta,
+        metaBase,
         owner,
         relationName,
         hasMany2,
         meta.table,
         loader,
-        (row) => createEntityFromRow(meta.ctx, relation.target, row),
+        (row) => createEntity(relation.target, row),
         localKey
       );
     }
     case RelationKinds.BelongsTo: {
       const belongsTo2 = relation;
       const targetKey = belongsTo2.localKey || findPrimaryKey(belongsTo2.target);
-      const loader = () => relationLoaderCache(
-        meta,
-        relationName,
+      const loader = () => loadCached(
         () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2, lazyOptions)
       );
       return new DefaultBelongsToReference(
         meta.ctx,
-        meta,
+        metaBase,
         owner,
         relationName,
         belongsTo2,
         meta.table,
         loader,
-        (row) => createEntityFromRow(meta.ctx, relation.target, row),
+        (row) => createEntity(relation.target, row),
         targetKey
       );
     }
     case RelationKinds.BelongsToMany: {
       const many = relation;
       const localKey = many.localKey || findPrimaryKey(meta.table);
-      const loader = () => relationLoaderCache(
-        meta,
-        relationName,
+      const loader = () => loadCached(
         () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
       );
       return new DefaultManyToManyCollection(
         meta.ctx,
-        meta,
+        metaBase,
         owner,
         relationName,
         many,
         meta.table,
         loader,
-        (row) => createEntityFromRow(meta.ctx, relation.target, row),
+        (row) => createEntity(relation.target, row),
         localKey
       );
     }
@@ -5791,6 +5816,71 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
   }
 };
 
+// src/orm/entity.ts
+var createEntityProxy = (ctx, table, row, lazyRelations = [], lazyRelationOptions = /* @__PURE__ */ new Map()) => {
+  const target = { ...row };
+  const meta = {
+    ctx,
+    table,
+    lazyRelations: [...lazyRelations],
+    lazyRelationOptions: new Map(lazyRelationOptions),
+    relationCache: /* @__PURE__ */ new Map(),
+    relationHydration: /* @__PURE__ */ new Map(),
+    relationWrappers: /* @__PURE__ */ new Map()
+  };
+  const createRelationEntity = (relationTable, relationRow) => createEntityFromRow(meta.ctx, relationTable, relationRow);
+  Object.defineProperty(target, ENTITY_META, {
+    value: meta,
+    enumerable: false,
+    writable: false
+  });
+  const handler = {
+    get(targetObj, prop, receiver) {
+      if (prop === ENTITY_META) {
+        return meta;
+      }
+      if (prop === "$load") {
+        return async (relationName) => {
+          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
+          if (wrapper && typeof wrapper.load === "function") {
+            return wrapper.load();
+          }
+          return void 0;
+        };
+      }
+      if (typeof prop === "string" && table.relations[prop]) {
+        return getRelationWrapper(meta, prop, receiver, createRelationEntity);
+      }
+      return Reflect.get(targetObj, prop, receiver);
+    },
+    set(targetObj, prop, value, receiver) {
+      const result = Reflect.set(targetObj, prop, value, receiver);
+      if (typeof prop === "string" && table.columns[prop]) {
+        ctx.markDirty(receiver);
+      }
+      return result;
+    }
+  };
+  const proxy = new Proxy(target, handler);
+  populateHydrationCache(proxy, row, meta);
+  return proxy;
+};
+var createEntityFromRow = (ctx, table, row, lazyRelations = [], lazyRelationOptions = /* @__PURE__ */ new Map()) => {
+  const pkName = findPrimaryKey(table);
+  const pkValue = row[pkName];
+  if (pkValue !== void 0 && pkValue !== null) {
+    const tracked = ctx.getEntity(table, pkValue);
+    if (tracked) return tracked;
+  }
+  const entity = createEntityProxy(ctx, table, row, lazyRelations, lazyRelationOptions);
+  if (pkValue !== void 0 && pkValue !== null) {
+    ctx.trackManaged(table, pkValue, entity);
+  } else {
+    ctx.trackNew(table, entity);
+  }
+  return entity;
+};
+
 // src/orm/execute.ts
 var flattenResults = (results) => {
   const rows = [];
@@ -5880,14 +5970,416 @@ var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOp
   }
 };
 
-// src/query-builder/query-resolution.ts
-function resolveSelectQuery(query) {
-  const candidate = query;
-  return typeof candidate.getAST === "function" && candidate.getAST ? candidate.getAST() : query;
-}
+// src/query-builder/query-resolution.ts
+function resolveSelectQuery(query) {
+  const candidate = query;
+  return typeof candidate.getAST === "function" && candidate.getAST ? candidate.getAST() : query;
+}
+
+// src/query-builder/select/select-operations.ts
+function applyOrderBy(context, predicateFacet, term, directionOrOptions) {
+  const options = typeof directionOrOptions === "string" ? { direction: directionOrOptions } : directionOrOptions;
+  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
+  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
+}
+async function executeCount(context, env, session) {
+  const unpagedAst = {
+    ...context.state.ast,
+    orderBy: void 0,
+    limit: void 0,
+    offset: void 0
+  };
+  const nextState = new SelectQueryState(env.table, unpagedAst);
+  const nextContext = {
+    ...context,
+    state: nextState
+  };
+  const subAst = nextContext.hydration.applyToAst(nextState.ast);
+  const countQuery = {
+    type: "SelectQuery",
+    from: derivedTable(subAst, "__metal_count"),
+    columns: [{ type: "Function", name: "COUNT", args: [], alias: "total" }],
+    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 === void 0 ? 0 : Number(value);
+}
+async function executePagedQuery(builder, session, options, countCallback) {
+  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([
+    builder.limit(pageSize).offset(offset).execute(session),
+    countCallback(session)
+  ]);
+  return { items, totalItems };
+}
+function buildWhereHasPredicate(env, context, relationFacet, createChildBuilder, relationName, callbackOrOptions, maybeOptions, negate = false) {
+  const relation = env.table.relations[relationName];
+  if (!relation) {
+    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
+  }
+  const callback = typeof callbackOrOptions === "function" ? callbackOrOptions : void 0;
+  const options = typeof callbackOrOptions === "function" ? maybeOptions : callbackOrOptions;
+  let subQb = createChildBuilder(relation.target);
+  if (callback) {
+    subQb = callback(subQb);
+  }
+  const subAst = subQb.getAST();
+  const finalSubAst = relationFacet.applyRelationCorrelation(
+    context,
+    relationName,
+    subAst,
+    options?.correlate
+  );
+  return negate ? notExists(finalSubAst) : exists(finalSubAst);
+}
+
+// src/query-builder/select/from-facet.ts
+var SelectFromFacet = class {
+  /**
+   * Creates a new SelectFromFacet instance
+   * @param env - Query builder environment
+   * @param createAstService - Function to create AST service
+   */
+  constructor(env, createAstService) {
+    this.env = env;
+    this.createAstService = createAstService;
+  }
+  /**
+   * Applies an alias to the FROM table
+   * @param context - Current query context
+   * @param alias - Alias to apply
+   * @returns Updated query context with aliased FROM
+   */
+  as(context, alias) {
+    const from = context.state.ast.from;
+    if (from.type !== "Table") {
+      throw new Error("Cannot alias non-table FROM sources");
+    }
+    const nextFrom = { ...from, alias };
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withFrom(nextFrom);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Sets the FROM clause to a subquery
+   * @param context - Current query context
+   * @param subAst - Subquery AST
+   * @param alias - Alias for the subquery
+   * @param columnAliases - Optional column aliases
+   * @returns Updated query context with subquery FROM
+   */
+  fromSubquery(context, subAst, alias, columnAliases) {
+    const fromNode = derivedTable(subAst, alias, columnAliases);
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withFrom(fromNode);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Sets the FROM clause to a function table
+   * @param context - Current query context
+   * @param name - Function name
+   * @param args - Function arguments
+   * @param alias - Optional alias for the function table
+   * @param options - Optional function table options
+   * @returns Updated query context with function table FROM
+   */
+  fromFunctionTable(context, name, args, alias, options) {
+    const functionTable = fnTable(name, args, alias, options);
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withFrom(functionTable);
+    return { state: nextState, hydration: context.hydration };
+  }
+};
+
+// src/query-builder/select/join-facet.ts
+var SelectJoinFacet = class {
+  constructor(env, createAstService) {
+    this.env = env;
+    this.createAstService = createAstService;
+  }
+  applyJoin(context, table, condition, kind) {
+    const joinNode = createJoinNode(kind, { type: "Table", name: table.name, schema: table.schema }, condition);
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withJoin(joinNode);
+    return { state: nextState, hydration: context.hydration };
+  }
+  joinSubquery(context, subAst, alias, condition, joinKind, columnAliases) {
+    const joinNode = createJoinNode(joinKind, derivedTable(subAst, alias, columnAliases), condition);
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withJoin(joinNode);
+    return { state: nextState, hydration: context.hydration };
+  }
+  joinFunctionTable(context, name, args, alias, condition, joinKind, options) {
+    const functionTable = fnTable(name, args, alias, options);
+    const joinNode = createJoinNode(joinKind, functionTable, condition);
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withJoin(joinNode);
+    return { state: nextState, hydration: context.hydration };
+  }
+};
+
+// src/query-builder/select/projection-facet.ts
+var SelectProjectionFacet = class {
+  /**
+   * Creates a new SelectProjectionFacet instance
+   * @param columnSelector - Column selector dependency
+   */
+  constructor(columnSelector) {
+    this.columnSelector = columnSelector;
+  }
+  /**
+   * Selects columns for the query
+   * @param context - Current query context
+   * @param columns - Columns to select
+   * @returns Updated query context with selected columns
+   */
+  select(context, columns) {
+    return this.columnSelector.select(context, columns);
+  }
+  /**
+   * Selects raw column expressions
+   * @param context - Current query context
+   * @param cols - Raw column expressions
+   * @returns Updated query context with raw column selections
+   */
+  selectRaw(context, cols) {
+    return this.columnSelector.selectRaw(context, cols);
+  }
+  /**
+   * Selects a subquery as a column
+   * @param context - Current query context
+   * @param alias - Alias for the subquery
+   * @param query - Subquery to select
+   * @returns Updated query context with subquery selection
+   */
+  selectSubquery(context, alias, query) {
+    return this.columnSelector.selectSubquery(context, alias, query);
+  }
+  /**
+   * Adds DISTINCT clause to the query
+   * @param context - Current query context
+   * @param cols - Columns to make distinct
+   * @returns Updated query context with DISTINCT clause
+   */
+  distinct(context, cols) {
+    return this.columnSelector.distinct(context, cols);
+  }
+};
+
+// src/query-builder/select/predicate-facet.ts
+var SelectPredicateFacet = class {
+  /**
+   * Creates a new SelectPredicateFacet instance
+   * @param env - Query builder environment
+   * @param createAstService - Function to create AST service
+   */
+  constructor(env, createAstService) {
+    this.env = env;
+    this.createAstService = createAstService;
+  }
+  /**
+   * Adds a WHERE condition to the query
+   * @param context - Current query context
+   * @param expr - WHERE expression
+   * @returns Updated query context with WHERE condition
+   */
+  where(context, expr) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withWhere(expr);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Adds a GROUP BY clause to the query
+   * @param context - Current query context
+   * @param term - Column or ordering term to group by
+   * @returns Updated query context with GROUP BY clause
+   */
+  groupBy(context, term) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withGroupBy(term);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Adds a HAVING condition to the query
+   * @param context - Current query context
+   * @param expr - HAVING expression
+   * @returns Updated query context with HAVING condition
+   */
+  having(context, expr) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withHaving(expr);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Adds an ORDER BY clause to the query
+   * @param context - Current query context
+   * @param term - Column or ordering term to order by
+   * @param direction - Order direction
+   * @param nulls - Nulls ordering
+   * @param collation - Collation
+   * @returns Updated query context with ORDER BY clause
+   */
+  orderBy(context, term, direction, nulls, collation) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withOrderBy(term, direction, nulls, collation);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Adds a LIMIT clause to the query
+   * @param context - Current query context
+   * @param n - Maximum number of rows
+   * @returns Updated query context with LIMIT clause
+   */
+  limit(context, n) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withLimit(n);
+    return { state: nextState, hydration: context.hydration };
+  }
+  /**
+   * Adds an OFFSET clause to the query
+   * @param context - Current query context
+   * @param n - Number of rows to skip
+   * @returns Updated query context with OFFSET clause
+   */
+  offset(context, n) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withOffset(n);
+    return { state: nextState, hydration: context.hydration };
+  }
+};
+
+// src/query-builder/select/cte-facet.ts
+var SelectCTEFacet = class {
+  /**
+   * Creates a new SelectCTEFacet instance
+   * @param env - Query builder environment
+   * @param createAstService - Function to create AST service
+   */
+  constructor(env, createAstService) {
+    this.env = env;
+    this.createAstService = createAstService;
+  }
+  /**
+   * Adds a Common Table Expression to the query
+   * @param context - Current query context
+   * @param name - CTE name
+   * @param subAst - CTE query AST
+   * @param columns - Optional column names
+   * @param recursive - Whether the CTE is recursive
+   * @returns Updated query context with CTE
+   */
+  withCTE(context, name, subAst, columns, recursive) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withCte(name, subAst, columns, recursive);
+    return { state: nextState, hydration: context.hydration };
+  }
+};
+
+// src/query-builder/select/setop-facet.ts
+var SelectSetOpFacet = class {
+  /**
+   * Creates a new SelectSetOpFacet instance
+   * @param env - Query builder environment
+   * @param createAstService - Function to create AST service
+   */
+  constructor(env, createAstService) {
+    this.env = env;
+    this.createAstService = createAstService;
+  }
+  /**
+   * Applies a set operation to the query
+   * @param context - Current query context
+   * @param operator - Set operation kind
+   * @param subAst - Subquery AST to combine
+   * @returns Updated query context with set operation
+   */
+  applySetOperation(context, operator, subAst) {
+    const astService = this.createAstService(context.state);
+    const nextState = astService.withSetOperation(operator, subAst);
+    return { state: nextState, hydration: context.hydration };
+  }
+};
+
+// src/query-builder/select/relation-facet.ts
+var SelectRelationFacet = class {
+  /**
+   * Creates a new SelectRelationFacet instance
+   * @param relationManager - Relation manager dependency
+   */
+  constructor(relationManager) {
+    this.relationManager = relationManager;
+  }
+  /**
+   * Matches records based on a relationship
+   * @param context - Current query context
+   * @param relationName - Name of the relationship
+   * @param predicate - Optional predicate
+   * @returns Updated query context with relation match
+   */
+  match(context, relationName, predicate) {
+    return this.relationManager.match(context, relationName, predicate);
+  }
+  /**
+   * Joins a related table
+   * @param context - Current query context
+   * @param relationName - Name of the relationship
+   * @param joinKind - Type of join
+   * @param extraCondition - Optional additional condition
+   * @returns Updated query context with relation join
+   */
+  joinRelation(context, relationName, joinKind, extraCondition) {
+    return this.relationManager.joinRelation(context, relationName, joinKind, extraCondition);
+  }
+  /**
+   * Includes related data in the query results
+   * @param context - Current query context
+   * @param relationName - Name of the relationship to include
+   * @param options - Optional include options
+   * @returns Updated query context with relation inclusion
+   */
+  include(context, relationName, options) {
+    return this.relationManager.include(context, relationName, options);
+  }
+  /**
+   * Applies correlation for relation-based subqueries
+   * @param context - Current query context
+   * @param relationName - Name of the relationship
+   * @param subAst - Subquery AST
+   * @param extraCorrelate - Optional additional correlation
+   * @returns Modified subquery AST with correlation
+   */
+  applyRelationCorrelation(context, relationName, subAst, extraCorrelate) {
+    return this.relationManager.applyRelationCorrelation(context, relationName, subAst, extraCorrelate);
+  }
+};
 
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
+  env;
+  context;
+  columnSelector;
+  fromFacet;
+  joinFacet;
+  projectionFacet;
+  predicateFacet;
+  cteFacet;
+  setOpFacet;
+  relationFacet;
+  lazyRelations;
+  lazyRelationOptions;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -5898,6 +6390,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
+    const createAstService = (nextState) => deps.createQueryAstService(table, nextState);
     const initialState = state ?? deps.createState(table);
     const initialHydration = hydration ?? deps.createHydration(table);
     this.context = {
@@ -5907,7 +6400,14 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     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);
   }
   /**
    * Creates a new SelectQueryBuilder instance with updated context and lazy relations
@@ -5928,14 +6428,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * Applies an alias to the root FROM table.
    * @param alias - Alias to apply
+   * @example
+   * const qb = new SelectQueryBuilder(userTable).as('u');
    */
   as(alias) {
-    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);
   }
   /**
@@ -5960,29 +6457,6 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   createChildBuilder(table) {
     return new _SelectQueryBuilder(table, void 0, void 0, 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
-   */
-  applyAst(context, mutator) {
-    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
-   */
-  applyJoin(context, table, condition, kind) {
-    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
@@ -5991,12 +6465,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   applySetOperation(operator, query) {
     const subAst = resolveSelectQuery(query);
-    return this.applyAst(this.context, (service) => service.withSetOperation(operator, subAst));
+    return this.setOpFacet.applySetOperation(this.context, operator, subAst);
   }
   select(...args) {
     if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && typeof args[0] !== "string") {
       const columns = args[0];
-      return this.clone(this.columnSelector.select(this.context, columns));
+      return this.clone(this.projectionFacet.select(this.context, columns));
     }
     const cols = args;
     const selection = {};
@@ -6007,15 +6481,17 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       }
       selection[key] = col2;
     }
-    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) {
-    return this.clone(this.columnSelector.selectRaw(this.context, cols));
+    return this.clone(this.projectionFacet.selectRaw(this.context, cols));
   }
   /**
    * Adds a Common Table Expression (CTE) to the query
@@ -6023,10 +6499,16 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(name, query, columns) {
     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);
   }
   /**
@@ -6035,10 +6517,23 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(name, query, columns) {
     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);
   }
   /**
@@ -6047,11 +6542,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(subquery, alias, columnAliases) {
     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);
   }
   /**
@@ -6060,10 +6559,16 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, args = [], alias, options) {
-    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);
   }
   /**
@@ -6071,10 +6576,16 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(alias, sub2) {
     const query = resolveSelectQuery(sub2);
-    return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
+    return this.clone(this.projectionFacet.selectSubquery(this.context, alias, query));
   }
   /**
    * Adds a JOIN against a derived table (subquery with alias)
@@ -6084,11 +6595,19 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(subquery, alias, condition, joinKind = JOIN_KINDS.INNER, columnAliases) {
     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);
   }
   /**
@@ -6099,11 +6618,18 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, args = [], alias, condition, joinKind = JOIN_KINDS.INNER, options) {
-    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);
   }
   /**
@@ -6111,9 +6637,14 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, condition) {
-    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);
   }
   /**
@@ -6121,9 +6652,14 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, condition) {
-    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);
   }
   /**
@@ -6131,9 +6667,14 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, condition) {
-    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);
   }
   /**
@@ -6141,9 +6682,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(relationName, predicate) {
-    const nextContext = this.relationManager.match(this.context, relationName, predicate);
+    const nextContext = this.relationFacet.match(this.context, relationName, predicate);
     return this.clone(nextContext);
   }
   /**
@@ -6152,9 +6695,13 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(relationName, joinKind = JOIN_KINDS.INNER, extraCondition) {
-    const nextContext = this.relationManager.joinRelation(this.context, relationName, joinKind, extraCondition);
+    const nextContext = this.relationFacet.joinRelation(this.context, relationName, joinKind, extraCondition);
     return this.clone(nextContext);
   }
   /**
@@ -6162,9 +6709,18 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(relationName, options) {
-    const nextContext = this.relationManager.include(this.context, relationName, options);
+    const nextContext = this.relationFacet.include(this.context, relationName, options);
     return this.clone(nextContext);
   }
   /**
@@ -6172,6 +6728,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(relationName, options) {
     let nextContext = this.context;
@@ -6201,14 +6762,22 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   }
   /**
    * Convenience alias for including only specific columns from a relation.
+   * @example
+   * qb.includePick('posts', ['id', 'title', 'createdAt']);
    */
   includePick(relationName, cols) {
-    return this.include(relationName, { columns: cols });
+    const options = { columns: cols };
+    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) {
     let currBuilder = this;
@@ -6216,7 +6785,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       if (entry.type === "root") {
         currBuilder = currBuilder.select(...entry.columns);
       } else {
-        currBuilder = currBuilder.include(entry.relationName, { columns: entry.columns });
+        const options = { columns: entry.columns };
+        currBuilder = currBuilder.include(entry.relationName, options);
       }
     }
     return currBuilder;
@@ -6246,61 +6816,41 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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) {
     return executeHydrated(ctx, this);
   }
-  withAst(ast) {
-    const nextState = new SelectQueryState(this.env.table, ast);
-    const nextContext = {
-      ...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) {
-    const unpagedAst = {
-      ...this.context.state.ast,
-      orderBy: void 0,
-      limit: void 0,
-      offset: void 0
-    };
-    const subAst = this.withAst(unpagedAst).getAST();
-    const countQuery = {
-      type: "SelectQuery",
-      from: derivedTable(subAst, "__metal_count"),
-      columns: [{ type: "Function", name: "COUNT", args: [], alias: "total" }],
-      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 === void 0 ? 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, options) {
-    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));
   }
   /**
    * Executes the query with provided execution and hydration contexts
    * @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, hydCtx) {
     return executeHydratedWithContexts(execCtx, hydCtx, this);
@@ -6309,27 +6859,41 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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) {
-    const nextContext = this.applyAst(this.context, (service) => service.withWhere(expr));
+    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
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId);
    */
   groupBy(term) {
-    const nextContext = this.applyAst(this.context, (service) => service.withGroupBy(term));
+    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
+   * @example
+   * qb.select('departmentId', count(userTable.columns.id))
+   *   .groupBy(userTable.columns.departmentId)
+   *   .having(gt(count(userTable.columns.id), 5));
    */
   having(expr) {
-    const nextContext = this.applyAst(this.context, (service) => service.withHaving(expr));
+    const nextContext = this.predicateFacet.having(this.context, expr);
     return this.clone(nextContext);
   }
   /**
@@ -6337,46 +6901,62 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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, directionOrOptions = ORDER_DIRECTIONS.ASC) {
-    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);
   }
   /**
    * 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) {
-    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) {
-    const nextContext = this.applyAst(this.context, (service) => service.withLimit(n));
+    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
+   * @example
+   * qb.offset(10);
+   * @example
+   * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
    */
   offset(n) {
-    const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
+    const nextContext = this.predicateFacet.offset(this.context, n);
     return this.clone(nextContext);
   }
   /**
    * 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(query) {
     return this.clone(this.applySetOperation("UNION", query));
@@ -6385,6 +6965,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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(query) {
     return this.clone(this.applySetOperation("UNION ALL", query));
@@ -6393,6 +6977,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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(query) {
     return this.clone(this.applySetOperation("INTERSECT", query));
@@ -6401,6 +6991,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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(query) {
     return this.clone(this.applySetOperation("EXCEPT", query));
@@ -6409,6 +7004,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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(subquery, correlate) {
     const subAst = resolveSelectQuery(subquery);
@@ -6419,6 +7018,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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(subquery, correlate) {
     const subAst = resolveSelectQuery(subquery);
@@ -6430,47 +7033,54 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @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(relationName, callbackOrOptions, maybeOptions) {
-    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 : void 0;
-    const options = typeof callbackOrOptions === "function" ? maybeOptions : callbackOrOptions;
-    let subQb = this.createChildBuilder(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));
+    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(relationName, callbackOrOptions, maybeOptions) {
-    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 : void 0;
-    const options = typeof callbackOrOptions === "function" ? maybeOptions : callbackOrOptions;
-    let subQb = this.createChildBuilder(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));
+    const predicate = buildWhereHasPredicate(
+      this.env,
+      this.context,
+      this.relationFacet,
+      (table) => this.createChildBuilder(table),
+      relationName,
+      callbackOrOptions,
+      maybeOptions,
+      true
+    );
+    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) {
     const resolved = resolveDialectInput(dialect);
@@ -6480,6 +7090,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * 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) {
     return this.compile(dialect).sql;
@@ -6487,6 +7102,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * 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() {
     return this.context.hydration.getPlan();
@@ -6494,6 +7112,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * 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() {
     return this.context.hydration.applyToAst(this.context.state.ast);
@@ -6597,23 +7219,44 @@ var resolveTableTarget = (target, tableMap) => {
   }
   return table;
 };
+var toSnakeCase = (value) => {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-z0-9_]+/gi, "_").replace(/__+/g, "_").replace(/^_|_$/g, "").toLowerCase();
+};
+var normalizeEntityName = (value) => {
+  const stripped = value.replace(/Entity$/i, "");
+  const normalized = toSnakeCase(stripped || value);
+  return normalized || "unknown";
+};
+var getPivotKeyBaseFromTarget = (target) => {
+  const resolved = unwrapTarget(target);
+  if (isTableDef(resolved)) {
+    return toSnakeCase(resolved.name || "unknown");
+  }
+  const ctor = resolved;
+  return normalizeEntityName(ctor.name || "unknown");
+};
+var getPivotKeyBaseFromRoot = (meta) => {
+  return normalizeEntityName(meta.target.name || meta.tableName || "unknown");
+};
 var buildRelationDefinitions = (meta, tableMap) => {
   const relations = {};
   for (const [name, relation] of Object.entries(meta.relations)) {
     switch (relation.kind) {
       case RelationKinds.HasOne: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
         relations[name] = hasOne(
           resolveTableTarget(relation.target, tableMap),
-          relation.foreignKey,
+          foreignKey,
           relation.localKey,
           relation.cascade
         );
         break;
       }
       case RelationKinds.HasMany: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
         relations[name] = hasMany(
           resolveTableTarget(relation.target, tableMap),
-          relation.foreignKey,
+          foreignKey,
           relation.localKey,
           relation.cascade
         );
@@ -6629,12 +7272,14 @@ var buildRelationDefinitions = (meta, tableMap) => {
         break;
       }
       case RelationKinds.BelongsToMany: {
+        const pivotForeignKeyToRoot = relation.pivotForeignKeyToRoot ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
+        const pivotForeignKeyToTarget = relation.pivotForeignKeyToTarget ?? `${getPivotKeyBaseFromTarget(relation.target)}_id`;
         relations[name] = belongsToMany(
           resolveTableTarget(relation.target, tableMap),
           resolveTableTarget(relation.pivotTable, tableMap),
           {
-            pivotForeignKeyToRoot: relation.pivotForeignKeyToRoot,
-            pivotForeignKeyToTarget: relation.pivotForeignKeyToTarget,
+            pivotForeignKeyToRoot,
+            pivotForeignKeyToTarget,
             localKey: relation.localKey,
             targetKey: relation.targetKey,
             pivotPrimaryKey: relation.pivotPrimaryKey,
@@ -6715,6 +7360,8 @@ function esel(entity, ...props) {
 
 // src/query-builder/insert-query-state.ts
 var InsertQueryState = class _InsertQueryState {
+  table;
+  ast;
   /**
    * Creates a new InsertQueryState instance
    * @param table - The table definition for the INSERT query
@@ -6835,6 +7482,8 @@ var InsertQueryState = class _InsertQueryState {
 
 // src/query-builder/insert.ts
 var InsertQueryBuilder = class _InsertQueryBuilder {
+  table;
+  state;
   /**
    * Creates a new InsertQueryBuilder instance
    * @param table - The table definition for the INSERT query
@@ -6934,6 +7583,8 @@ var isUpdateValue = (value) => {
   }
 };
 var UpdateQueryState = class _UpdateQueryState {
+  table;
+  ast;
   /**
    * Creates a new UpdateQueryState instance
    * @param table - Table definition for the update
@@ -7044,6 +7695,8 @@ var UpdateQueryState = class _UpdateQueryState {
 
 // src/query-builder/update.ts
 var UpdateQueryBuilder = class _UpdateQueryBuilder {
+  table;
+  state;
   /**
    * Creates a new UpdateQueryBuilder instance
    * @param table - The table definition for the UPDATE query
@@ -7161,6 +7814,8 @@ var isTableSourceNode = (source) => typeof source.type === "string";
 
 // src/query-builder/delete-query-state.ts
 var DeleteQueryState = class _DeleteQueryState {
+  table;
+  ast;
   /**
    * Creates a new DeleteQueryState instance
    * @param table - The table definition for the DELETE query
@@ -7239,6 +7894,8 @@ var DeleteQueryState = class _DeleteQueryState {
 
 // src/query-builder/delete.ts
 var DeleteQueryBuilder = class _DeleteQueryBuilder {
+  table;
+  state;
   /**
    * Creates a new DeleteQueryBuilder instance
    * @param table - The table definition for the DELETE query
@@ -7345,6 +8002,39 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
 };
 var isTableSourceNode2 = (source) => typeof source.type === "string";
 
+// src/query/target.ts
+var resolveEntityTarget = (ctor) => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators`);
+  }
+  return table;
+};
+var resolveTable = (target) => {
+  if (isTableDef(target)) {
+    return target;
+  }
+  return resolveEntityTarget(target);
+};
+
+// src/query/index.ts
+var selectFrom = (target) => {
+  const table = resolveTable(target);
+  return new SelectQueryBuilder(table);
+};
+var insertInto = (target) => {
+  const table = resolveTable(target);
+  return new InsertQueryBuilder(table);
+};
+var update = (target) => {
+  const table = resolveTable(target);
+  return new UpdateQueryBuilder(table);
+};
+var deleteFrom = (target) => {
+  const table = resolveTable(target);
+  return new DeleteQueryBuilder(table);
+};
+
 // src/core/ddl/sql-writing.ts
 var resolvePrimaryKey = (table) => {
   if (Array.isArray(table.primaryKey) && table.primaryKey.length > 0) {
@@ -7366,7 +8056,8 @@ var renderColumnDefinition = (table, col2, dialect, options = {}) => {
   if (col2.default !== void 0) {
     parts.push(`DEFAULT ${dialect.renderDefault(col2.default, col2)}`);
   }
-  if (options.includePrimary && col2.primary) {
+  const autoIncIncludesPrimary = typeof autoInc === "string" && /\bPRIMARY\s+KEY\b/i.test(autoInc);
+  if (options.includePrimary && col2.primary && !autoIncIncludesPrimary) {
     parts.push("PRIMARY KEY");
   }
   if (col2.check) {
@@ -7424,6 +8115,16 @@ var generateSchemaSql = (tables, dialect) => {
   });
   return statements;
 };
+var generateSchemaSqlFor = (dialect, ...tables) => generateSchemaSql(tables, dialect);
+var executeSchemaSql = async (executor, tables, dialect) => {
+  const statements = generateSchemaSql(tables, dialect);
+  for (const sql of statements) {
+    await executor.executeSql(sql);
+  }
+};
+var executeSchemaSqlFor = async (executor, dialect, ...tables) => {
+  await executeSchemaSql(executor, tables, dialect);
+};
 var orderTablesByDependencies = (tables) => {
   const map = /* @__PURE__ */ new Map();
   tables.forEach((t) => map.set(t.name, t));
@@ -9330,6 +10031,7 @@ var arrayAppend = (array, value) => fn7("ARRAY_APPEND", [array, value]);
 
 // src/orm/als.ts
 var AsyncLocalStorage = class {
+  store;
   /**
    * Executes a callback function within a context containing the specified store value.
    * The store value is only available during the callback's execution and is automatically
@@ -9826,9 +10528,7 @@ var TypeScriptGenerator = class {
 
 // src/orm/identity-map.ts
 var IdentityMap = class {
-  constructor() {
-    this.buckets = /* @__PURE__ */ new Map();
-  }
+  buckets = /* @__PURE__ */ new Map();
   get bucketsMap() {
     return this.buckets;
   }
@@ -9898,8 +10598,8 @@ var UnitOfWork = class {
     this.executor = executor;
     this.identityMap = identityMap;
     this.hookContext = hookContext;
-    this.trackedEntities = /* @__PURE__ */ new Map();
   }
+  trackedEntities = /* @__PURE__ */ new Map();
   /**
    * Gets the identity buckets map.
    */
@@ -10229,12 +10929,12 @@ var UnitOfWork = class {
 
 // src/orm/domain-event-bus.ts
 var DomainEventBus = class {
+  handlers = /* @__PURE__ */ new Map();
   /**
    * Creates a new DomainEventBus instance.
    * @param initialHandlers - Optional initial event handlers
    */
   constructor(initialHandlers) {
-    this.handlers = /* @__PURE__ */ new Map();
     if (initialHandlers) {
       for (const key in initialHandlers) {
         const type = key;
@@ -10303,8 +11003,8 @@ var RelationChangeProcessor = class {
     this.unitOfWork = unitOfWork;
     this.dialect = dialect;
     this.executor = executor;
-    this.relationChanges = [];
   }
+  relationChanges = [];
   /**
    * Registers a relation change for processing.
    * @param entry - The relation change entry
@@ -10738,25 +11438,24 @@ var saveGraphInternal = async (session, entityClass, payload, options = {}) => {
 
 // src/orm/orm-session.ts
 var OrmSession = class {
+  /** The ORM instance */
+  orm;
+  /** The database executor */
+  executor;
+  /** The identity map for tracking entity instances */
+  identityMap;
+  /** The unit of work for tracking entity changes */
+  unitOfWork;
+  /** The domain event bus */
+  domainEvents;
+  /** The relation change processor */
+  relationChanges;
+  interceptors;
   /**
    * Creates a new OrmSession instance.
    * @param opts - Session options
    */
   constructor(opts) {
-    /**
-     * Registers a relation change.
-     * @param root - The root entity
-     * @param relationKey - The relation key
-     * @param rootTable - The root table definition
-     * @param relationName - The relation name
-     * @param relation - The relation definition
-     * @param change - The relation change
-     */
-    this.registerRelationChange = (root, relationKey, rootTable, relationName, relation, change) => {
-      this.relationChanges.registerChange(
-        buildRelationChangeEntry(root, relationKey, rootTable, relationName, relation, change)
-      );
-    };
     this.orm = opts.orm;
     this.executor = createQueryLoggingExecutor(opts.executor, opts.queryLogger);
     this.interceptors = [...opts.interceptors ?? []];
@@ -10845,6 +11544,20 @@ var OrmSession = class {
   markRemoved(entity) {
     this.unitOfWork.markRemoved(entity);
   }
+  /**
+   * Registers a relation change.
+   * @param root - The root entity
+   * @param relationKey - The relation key
+   * @param rootTable - The root table definition
+   * @param relationName - The relation name
+   * @param relation - The relation definition
+   * @param change - The relation change
+   */
+  registerRelationChange = (root, relationKey, rootTable, relationName, relation, change) => {
+    this.relationChanges.registerChange(
+      buildRelationChangeEntry(root, relationKey, rootTable, relationName, relation, change)
+    );
+  };
   /**
    * Gets all tracked entities for a specific table.
    * @param table - The table definition
@@ -11050,9 +11763,7 @@ var buildRelationChangeEntry = (root, relationKey, rootTable, relationName, rela
 
 // src/orm/interceptor-pipeline.ts
 var InterceptorPipeline = class {
-  constructor() {
-    this.interceptors = [];
-  }
+  interceptors = [];
   use(interceptor) {
     this.interceptors.push(interceptor);
   }
@@ -11071,6 +11782,13 @@ var InterceptorPipeline = class {
 
 // src/orm/orm.ts
 var Orm = class {
+  /** The database dialect */
+  dialect;
+  /** The interceptors pipeline */
+  interceptors;
+  /** The naming strategy */
+  namingStrategy;
+  executorFactory;
   /**
    * Creates a new ORM instance.
    * @param opts - ORM options
@@ -11127,17 +11845,13 @@ var jsonify = (value) => {
 
 // src/decorators/decorator-metadata.ts
 var METADATA_KEY = "metal-orm:decorators";
-var isStandardDecoratorContext = (value) => {
-  return typeof value === "object" && value !== null && "kind" in value;
-};
 var getOrCreateMetadataBag = (context) => {
   const metadata = context.metadata || (context.metadata = {});
-  const existing = metadata[METADATA_KEY];
-  if (existing) {
-    return existing;
+  let bag = metadata[METADATA_KEY];
+  if (!bag) {
+    bag = { columns: [], relations: [] };
+    metadata[METADATA_KEY] = bag;
   }
-  const bag = { columns: [], relations: [] };
-  metadata[METADATA_KEY] = bag;
   return bag;
 };
 var readMetadataBag = (context) => {
@@ -11152,57 +11866,50 @@ var readMetadataBagFromConstructor = (ctor) => {
 var getDecoratorMetadata = (ctor) => readMetadataBagFromConstructor(ctor);
 
 // src/decorators/entity.ts
-var toSnakeCase = (value) => {
+var toSnakeCase2 = (value) => {
   return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-z0-9_]+/gi, "_").replace(/__+/g, "_").replace(/^_|_$/g, "").toLowerCase();
 };
 var deriveTableNameFromConstructor = (ctor) => {
   const fallback = "unknown";
   const rawName = ctor.name || fallback;
   const strippedName = rawName.replace(/Entity$/i, "");
-  const normalized = toSnakeCase(strippedName || rawName);
+  const normalized = toSnakeCase2(strippedName || rawName);
   if (!normalized) {
     return fallback;
   }
   return normalized.endsWith("s") ? normalized : `${normalized}s`;
 };
 function Entity(options = {}) {
-  const decorator = (value) => {
-    const tableName = options.tableName ?? deriveTableNameFromConstructor(value);
-    setEntityTableName(value, tableName, options.hooks);
-    return value;
-  };
-  const decoratorWithContext = (value, context) => {
+  return function(value, context) {
     const ctor = value;
-    decorator(ctor);
-    if (context && isStandardDecoratorContext(context)) {
-      const bag = readMetadataBag(context);
-      if (bag) {
-        const meta = ensureEntityMetadata(ctor);
-        for (const entry of bag.columns) {
-          if (meta.columns[entry.propertyName]) {
-            throw new Error(
-              `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
-            );
-          }
-          addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+    const tableName = options.tableName ?? deriveTableNameFromConstructor(ctor);
+    setEntityTableName(ctor, tableName, options.hooks);
+    const bag = readMetadataBag(context);
+    if (bag) {
+      const meta = ensureEntityMetadata(ctor);
+      for (const entry of bag.columns) {
+        if (meta.columns[entry.propertyName]) {
+          throw new Error(
+            `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+          );
         }
-        for (const entry of bag.relations) {
-          if (meta.relations[entry.propertyName]) {
-            throw new Error(
-              `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
-            );
-          }
-          const relationCopy = entry.relation.kind === RelationKinds.BelongsToMany ? {
-            ...entry.relation,
-            defaultPivotColumns: entry.relation.defaultPivotColumns ? [...entry.relation.defaultPivotColumns] : void 0
-          } : { ...entry.relation };
-          addRelationMetadata(ctor, entry.propertyName, relationCopy);
+        addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+      }
+      for (const entry of bag.relations) {
+        if (meta.relations[entry.propertyName]) {
+          throw new Error(
+            `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+          );
         }
+        const relationCopy = entry.relation.kind === RelationKinds.BelongsToMany ? {
+          ...entry.relation,
+          defaultPivotColumns: entry.relation.defaultPivotColumns ? [...entry.relation.defaultPivotColumns] : void 0
+        } : { ...entry.relation };
+        addRelationMetadata(ctor, entry.propertyName, relationCopy);
       }
     }
     return ctor;
   };
-  return decoratorWithContext;
 }
 
 // src/decorators/column-decorator.ts
@@ -11235,26 +11942,13 @@ var normalizePropertyName = (name) => {
   }
   return name;
 };
-var resolveConstructor = (target) => {
-  if (typeof target === "function") {
-    return target;
-  }
-  if (target && typeof target.constructor === "function") {
-    return target.constructor;
-  }
-  return void 0;
-};
-var registerColumn = (ctor, propertyName, column) => {
-  const meta = ensureEntityMetadata(ctor);
-  if (meta.columns[propertyName]) {
-    return;
-  }
-  addColumnMetadata(ctor, propertyName, column);
-};
 var registerColumnFromContext = (context, column) => {
   if (!context.name) {
     throw new Error("Column decorator requires a property name");
   }
+  if (context.private) {
+    throw new Error("Column decorator does not support private fields");
+  }
   const propertyName = normalizePropertyName(context.name);
   const bag = getOrCreateMetadataBag(context);
   if (!bag.columns.some((entry) => entry.propertyName === propertyName)) {
@@ -11263,19 +11957,9 @@ var registerColumnFromContext = (context, column) => {
 };
 function Column(definition) {
   const normalized = normalizeColumnInput(definition);
-  const decorator = (targetOrValue, propertyKeyOrContext) => {
-    if (isStandardDecoratorContext(propertyKeyOrContext)) {
-      registerColumnFromContext(propertyKeyOrContext, normalized);
-      return;
-    }
-    const propertyName = normalizePropertyName(propertyKeyOrContext);
-    const ctor = resolveConstructor(targetOrValue);
-    if (!ctor) {
-      throw new Error("Unable to resolve constructor when registering column metadata");
-    }
-    registerColumn(ctor, propertyName, { ...normalized });
+  return function(_value, context) {
+    registerColumnFromContext(context, normalized);
   };
-  return decorator;
 }
 function PrimaryKey(definition) {
   const normalized = normalizeColumnInput(definition);
@@ -11290,41 +11974,21 @@ var normalizePropertyName2 = (name) => {
   }
   return name;
 };
-var resolveConstructor2 = (instanceOrCtor) => {
-  if (typeof instanceOrCtor === "function") {
-    return instanceOrCtor;
-  }
-  if (instanceOrCtor && typeof instanceOrCtor.constructor === "function") {
-    return instanceOrCtor.constructor;
-  }
-  return void 0;
-};
-var registerRelation = (ctor, propertyName, metadata) => {
-  addRelationMetadata(ctor, propertyName, metadata);
-};
 var createFieldDecorator = (metadataFactory) => {
-  const decorator = (targetOrValue, propertyKeyOrContext) => {
-    if (isStandardDecoratorContext(propertyKeyOrContext)) {
-      const ctx = propertyKeyOrContext;
-      if (!ctx.name) {
-        throw new Error("Relation decorator requires a property name");
-      }
-      const propertyName2 = normalizePropertyName2(ctx.name);
-      const bag = getOrCreateMetadataBag(ctx);
-      const relationMetadata = metadataFactory(propertyName2);
-      if (!bag.relations.some((entry) => entry.propertyName === propertyName2)) {
-        bag.relations.push({ propertyName: propertyName2, relation: relationMetadata });
-      }
-      return;
+  return function(_value, context) {
+    if (!context.name) {
+      throw new Error("Relation decorator requires a property name");
     }
-    const propertyName = normalizePropertyName2(propertyKeyOrContext);
-    const ctor = resolveConstructor2(targetOrValue);
-    if (!ctor) {
-      throw new Error("Unable to resolve constructor when registering relation metadata");
+    if (context.private) {
+      throw new Error("Relation decorator does not support private fields");
+    }
+    const propertyName = normalizePropertyName2(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    const relationMetadata = metadataFactory(propertyName);
+    if (!bag.relations.some((entry) => entry.propertyName === propertyName)) {
+      bag.relations.push({ propertyName, relation: relationMetadata });
     }
-    registerRelation(ctor, propertyName, metadataFactory(propertyName));
   };
-  return decorator;
 };
 function HasMany(options) {
   return createFieldDecorator((propertyName) => ({
@@ -11351,7 +12015,7 @@ function BelongsTo(options) {
     kind: RelationKinds.BelongsTo,
     propertyKey: propertyName,
     target: options.target,
-    foreignKey: options.foreignKey,
+    foreignKey: options.foreignKey ?? `${propertyName}_id`,
     localKey: options.localKey,
     cascade: options.cascade
   }));
@@ -11427,13 +12091,15 @@ var deferred = () => {
   return { promise, resolve, reject };
 };
 var Pool = class {
+  adapter;
+  options;
+  destroyed = false;
+  creating = 0;
+  leased = 0;
+  idle = [];
+  waiters = [];
+  reapTimer = null;
   constructor(adapter, options) {
-    this.destroyed = false;
-    this.creating = 0;
-    this.leased = 0;
-    this.idle = [];
-    this.waiters = [];
-    this.reapTimer = null;
     if (!Number.isFinite(options.max) || options.max <= 0) {
       throw new Error("Pool options.max must be a positive number");
     }
@@ -11986,6 +12652,7 @@ export {
   dayOfWeek,
   defineTable,
   degrees,
+  deleteFrom,
   denseRank,
   diffSchema,
   div,
@@ -11995,6 +12662,8 @@ export {
   esel,
   executeHydrated,
   executeHydratedWithContexts,
+  executeSchemaSql,
+  executeSchemaSqlFor,
   exists,
   exp,
   extract,
@@ -12003,6 +12672,7 @@ export {
   fromUnixTime,
   generateCreateTableSql,
   generateSchemaSql,
+  generateSchemaSqlFor,
   getColumn,
   getDecoratorMetadata,
   getSchemaIntrospector,
@@ -12019,6 +12689,7 @@ export {
   inList,
   inSubquery,
   initcap,
+  insertInto,
   instr,
   introspectSchema,
   isCaseExpressionNode,
@@ -12107,7 +12778,9 @@ export {
   rtrim,
   second,
   sel,
+  selectFrom,
   selectFromEntity,
+  setRelations,
   sha1,
   sha2,
   shiftLeft,
@@ -12129,6 +12802,7 @@ export {
   trunc,
   truncate,
   unixTimestamp,
+  update,
   upper,
   utcNow,
   valueToOperand,