metal-orm 1.0.57 → 1.0.59

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
@@ -3852,20 +3853,21 @@ var RelationProjectionHelper = class {
 var assertNever = (value) => {
   throw new Error(`Unhandled relation type: ${JSON.stringify(value)}`);
 };
-var baseRelationCondition = (root, relation, rootAlias) => {
+var baseRelationCondition = (root, relation, rootAlias, targetTableName) => {
   const rootTable = rootAlias || root.name;
+  const targetTable = targetTableName ?? relation.target.name;
   const defaultLocalKey = relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne ? findPrimaryKey(root) : findPrimaryKey(relation.target);
   const localKey = relation.localKey || defaultLocalKey;
   switch (relation.type) {
     case RelationKinds.HasMany:
     case RelationKinds.HasOne:
       return eq(
-        { type: "Column", table: relation.target.name, name: relation.foreignKey },
+        { type: "Column", table: targetTable, name: relation.foreignKey },
         { type: "Column", table: rootTable, name: localKey }
       );
     case RelationKinds.BelongsTo:
       return eq(
-        { type: "Column", table: relation.target.name, name: localKey },
+        { type: "Column", table: targetTable, name: localKey },
         { type: "Column", table: rootTable, name: relation.foreignKey }
       );
     case RelationKinds.BelongsToMany:
@@ -3874,7 +3876,7 @@ var baseRelationCondition = (root, relation, rootAlias) => {
       return assertNever(relation);
   }
 };
-var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, rootAlias) => {
+var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, rootAlias, targetTable, targetTableName) => {
   const rootKey = relation.localKey || findPrimaryKey(root);
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const rootTable = rootAlias || root.name;
@@ -3887,8 +3889,14 @@ var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, ro
     { type: "Table", name: relation.pivotTable.name, schema: relation.pivotTable.schema },
     pivotCondition
   );
+  const targetSource = targetTable ?? {
+    type: "Table",
+    name: relation.target.name,
+    schema: relation.target.schema
+  };
+  const effectiveTargetName = targetTableName ?? relation.target.name;
   let targetCondition = eq(
-    { type: "Column", table: relation.target.name, name: targetKey },
+    { type: "Column", table: effectiveTargetName, name: targetKey },
     { type: "Column", table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
   );
   if (extra) {
@@ -3896,141 +3904,487 @@ var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, ro
   }
   const targetJoin = createJoinNode(
     joinKind,
-    { type: "Table", name: relation.target.name, schema: relation.target.schema },
+    targetSource,
     targetCondition,
     relationName
   );
   return [pivotJoin, targetJoin];
 };
-var buildRelationJoinCondition = (root, relation, extra, rootAlias) => {
-  const base = baseRelationCondition(root, relation, rootAlias);
+var buildRelationJoinCondition = (root, relation, extra, rootAlias, targetTableName) => {
+  const base = baseRelationCondition(root, relation, rootAlias, targetTableName);
   return extra ? and(base, extra) : base;
 };
-var buildRelationCorrelation = (root, relation, rootAlias) => {
-  return baseRelationCondition(root, relation, rootAlias);
+var buildRelationCorrelation = (root, relation, rootAlias, targetTableName) => {
+  return baseRelationCondition(root, relation, rootAlias, targetTableName);
 };
 
 // src/core/ast/join-metadata.ts
 var getJoinRelationName = (join) => join.meta?.relationName;
 
-// 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)
-    );
+// 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);
+    }
   }
-  /**
-   * 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) {
-    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition);
-    return { state: nextState, hydration: this.hydration };
+  return { selfFilters, crossFilters };
+};
+var flattenAnd = (node) => {
+  if (!node) return [];
+  if (node.type === "LogicalExpression" && node.operator === "AND") {
+    return node.operands.flatMap((operand) => flattenAnd(operand));
   }
-  /**
-   * 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 [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;
+    }
   }
-  /**
-   * 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);
-    if (!alreadyJoined) {
-      const joined = this.joinRelation(relationName, options?.joinKind ?? JOIN_KINDS.LEFT, options?.filter);
-      state = joined.state;
+  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;
+      }
+      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;
+  }
+};
+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;
+  }
+};
+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 ?? {
+        type: "Table",
+        name: relation.target.name,
+        schema: relation.target.schema
+      };
+      const targetName2 = this.resolveTargetTableName(targetTableSource, relation);
+      const joins = buildBelongsToManyJoins(
+        this.table,
+        relationName,
+        relation,
+        joinKind,
+        extraCondition,
+        rootAlias,
+        targetTableSource,
+        targetName2
+      );
+      return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
     }
-    const projectionResult = this.projectionHelper.ensureBaseProjection(state, hydration);
-    state = projectionResult.state;
-    hydration = projectionResult.hydration;
-    const targetColumns = options?.columns?.length ? options.columns : Object.keys(relation.target.columns);
-    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 targetTable = tableSource ?? {
+      type: "Table",
+      name: relation.target.name,
+      schema: relation.target.schema
     };
-    const targetSelection = buildTypedSelection(
-      relation.target.columns,
-      aliasPrefix,
-      targetColumns,
-      (key) => `Column '${key}' not found on relation '${relationName}'`
+    const targetName = this.resolveTargetTableName(targetTable, relation);
+    const condition = buildRelationJoinCondition(
+      this.table,
+      relation,
+      extraCondition,
+      rootAlias,
+      targetName
     );
-    if (relation.type !== RelationKinds.BelongsToMany) {
-      const relationSelectionResult2 = this.selectColumns(state, hydration, targetSelection);
-      state = relationSelectionResult2.state;
-      hydration = relationSelectionResult2.hydration;
-      hydration = hydration.onRelationIncluded(
-        state,
+    const joinNode = createJoinNode(joinKind, targetTable, condition, relationName);
+    return this.astService(state).withJoin(joinNode);
+  }
+  astService(state) {
+    return this.createQueryAstService(this.table, state);
+  }
+  resolveTargetTableName(target, relation) {
+    if (target.type === "Table") {
+      return target.alias ?? target.name;
+    }
+    if (target.type === "DerivedTable") {
+      return target.alias;
+    }
+    if (target.type === "FunctionTable") {
+      return target.alias ?? relation.target.name;
+    }
+    return relation.target.name;
+  }
+};
+
+// src/query-builder/relation-cte-builder.ts
+var RelationCteBuilder = class {
+  constructor(table, createQueryAstService) {
+    this.table = table;
+    this.createQueryAstService = createQueryAstService;
+  }
+  createFilteredRelationCte(state, relationName, relation, predicate) {
+    const cteName = this.generateUniqueCteName(state, relationName);
+    if (!predicate) {
+      throw new Error("Unable to build filter CTE without predicates.");
+    }
+    const columns = Object.keys(relation.target.columns).map((name) => ({
+      type: "Column",
+      table: relation.target.name,
+      name
+    }));
+    const cteQuery = {
+      type: "SelectQuery",
+      from: { type: "Table", name: relation.target.name, schema: relation.target.schema },
+      columns,
+      joins: [],
+      where: predicate
+    };
+    const nextState = this.astService(state).withCte(cteName, cteQuery);
+    const tableNode3 = {
+      type: "Table",
+      name: cteName,
+      alias: relation.target.name
+    };
+    return { state: nextState, table: tableNode3 };
+  }
+  generateUniqueCteName(state, relationName) {
+    const existing = new Set((state.ast.ctes ?? []).map((cte) => cte.name));
+    let candidate = `${relationName}__filtered`;
+    let suffix = 1;
+    while (existing.has(candidate)) {
+      candidate = `${relationName}__filtered_${suffix}`;
+      suffix += 1;
+    }
+    return candidate;
+  }
+  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));
+    }
+    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);
+    }
+    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;
+    }
+    if (!alreadyJoined) {
+      state = this.joinPlanner.withJoin(
+        state,
         relationName,
-        aliasPrefix,
-        targetColumns
+        relation,
+        options?.joinKind ?? JOIN_KINDS.LEFT,
+        joinCondition,
+        tableSourceOverride
       );
-      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(
+    }
+    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,
-      targetColumns,
-      { aliasPrefix: pivotAliasPrefix, columns: pivotColumns }
-    );
-    return { state, hydration };
+      options,
+      selectColumns: (nextState, nextHydration, columns) => this.selectColumns(nextState, nextHydration, columns)
+    });
+    return { state: result.state, hydration: result.hydration };
   }
   /**
    * Applies relation correlation to a query AST
@@ -4051,37 +4405,6 @@ var RelationService = class {
       where: whereInSubquery
     };
   }
-  /**
-   * 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) {
-    const relation = this.getRelation(relationName);
-    const rootAlias = state.ast.from.type === "Table" ? state.ast.from.alias : void 0;
-    if (relation.type === RelationKinds.BelongsToMany) {
-      const joins = buildBelongsToManyJoins(
-        this.table,
-        relationName,
-        relation,
-        joinKind,
-        extraCondition,
-        rootAlias
-      );
-      return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
-    }
-    const condition = buildRelationJoinCondition(this.table, relation, extraCondition, rootAlias);
-    const joinNode = createJoinNode(
-      joinKind,
-      { type: "Table", name: relation.target.name, schema: relation.target.schema },
-      condition,
-      relationName
-    );
-    return this.astService(state).withJoin(joinNode);
-  }
   /**
    * Selects columns for a relation
    * @param state - Current query state
@@ -4096,6 +4419,15 @@ var RelationService = class {
       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
    * @param relationName - Name of the relation
@@ -4384,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, {
@@ -4419,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
@@ -4433,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;
@@ -4446,6 +4822,18 @@ var DefaultHasManyCollection = class {
   getItems() {
     return this.items;
   }
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length() {
+    return this.items.length;
+  }
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
   /**
    * Adds a new child entity to the collection.
    * @param data - Partial data for the new entity
@@ -4533,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, {
@@ -4566,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",
@@ -4581,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();
@@ -4589,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;
@@ -4661,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, {
@@ -4694,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();
@@ -4706,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;
@@ -4763,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, {
@@ -4796,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.
@@ -4808,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);
@@ -4827,6 +5215,18 @@ var DefaultManyToManyCollection = class {
   getItems() {
     return this.items;
   }
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length() {
+    return this.items.length;
+  }
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator]() {
+    return this.items[Symbol.iterator]();
+  }
   /**
    * Attaches an entity to the collection.
    * Registers an 'attach' change in the entity context.
@@ -4878,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);
       }
@@ -4933,11 +5333,28 @@ var DefaultManyToManyCollection = class {
   }
 };
 
-// src/orm/lazy-batch.ts
-var selectAllColumns = (table) => Object.entries(table.columns).reduce((acc, [name, def]) => {
-  acc[name] = def;
-  return acc;
-}, {});
+// src/orm/lazy-batch/shared.ts
+var hasColumns = (columns) => Boolean(columns && columns.length > 0);
+var buildColumnSelection = (table, columns, missingMsg) => {
+  return columns.reduce((acc, column) => {
+    const def = table.columns[column];
+    if (!def) {
+      throw new Error(missingMsg(column));
+    }
+    acc[column] = def;
+    return acc;
+  }, {});
+};
+var filterRow = (row, columns) => {
+  const filtered = {};
+  for (const column of columns) {
+    if (column in row) {
+      filtered[column] = row[column];
+    }
+  }
+  return filtered;
+};
+var filterRows = (rows, columns) => rows.map((row) => filterRow(row, columns));
 var rowsFromResults = (results) => {
   const rows = [];
   for (const result of results) {
@@ -4957,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) {
@@ -4969,9 +5386,12 @@ var collectKeysFromRoots = (roots, key) => {
   return collected;
 };
 var buildInListValues = (keys) => Array.from(keys);
-var fetchRowsForKeys = async (ctx, table, column, keys) => {
-  const qb = new SelectQueryBuilder(table).select(selectAllColumns(table));
-  qb.where(inList(column, buildInListValues(keys)));
+var fetchRowsForKeys = async (ctx, table, column, keys, selection, filter) => {
+  let qb = new SelectQueryBuilder(table).select(selection);
+  qb = qb.where(inList(column, buildInListValues(keys)));
+  if (filter) {
+    qb = qb.where(filter);
+  }
   return executeQuery(ctx, qb);
 };
 var groupRowsByMany = (rows, keyColumn) => {
@@ -4979,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);
@@ -4991,14 +5411,16 @@ 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;
 };
-var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
+
+// 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);
   const keys = collectKeysFromRoots(roots, localKey);
@@ -5007,10 +5429,32 @@ var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
   }
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return /* @__PURE__ */ new Map();
-  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
-  return groupRowsByMany(rows, relation.foreignKey);
+  const requestedColumns = hasColumns(options?.columns) ? [...options.columns] : void 0;
+  const targetPrimaryKey = findPrimaryKey(relation.target);
+  const selectedColumns = requestedColumns ? [...requestedColumns] : Object.keys(relation.target.columns);
+  if (!selectedColumns.includes(targetPrimaryKey)) {
+    selectedColumns.push(targetPrimaryKey);
+  }
+  const queryColumns = new Set(selectedColumns);
+  queryColumns.add(relation.foreignKey);
+  const selection = buildColumnSelection(
+    relation.target,
+    Array.from(queryColumns),
+    (column) => `Column '${column}' not found on relation '${relationName}'`
+  );
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys, selection, options?.filter);
+  const grouped = groupRowsByMany(rows, relation.foreignKey);
+  if (!requestedColumns) return grouped;
+  const visibleColumns = new Set(selectedColumns);
+  const filtered = /* @__PURE__ */ new Map();
+  for (const [key, bucket] of grouped.entries()) {
+    filtered.set(key, filterRows(bucket, visibleColumns));
+  }
+  return filtered;
 };
-var loadHasOneRelation = async (ctx, rootTable, _relationName, relation) => {
+
+// 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);
   const keys = collectKeysFromRoots(roots, localKey);
@@ -5019,22 +5463,102 @@ var loadHasOneRelation = async (ctx, rootTable, _relationName, relation) => {
   }
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return /* @__PURE__ */ new Map();
-  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
-  return groupRowsByUnique(rows, relation.foreignKey);
+  const requestedColumns = hasColumns(options?.columns) ? [...options.columns] : void 0;
+  const targetPrimaryKey = findPrimaryKey(relation.target);
+  const selectedColumns = requestedColumns ? [...requestedColumns] : Object.keys(relation.target.columns);
+  if (!selectedColumns.includes(targetPrimaryKey)) {
+    selectedColumns.push(targetPrimaryKey);
+  }
+  const queryColumns = new Set(selectedColumns);
+  queryColumns.add(relation.foreignKey);
+  const selection = buildColumnSelection(
+    relation.target,
+    Array.from(queryColumns),
+    (column) => `Column '${column}' not found on relation '${relationName}'`
+  );
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys, selection, options?.filter);
+  const grouped = groupRowsByUnique(rows, relation.foreignKey);
+  if (!requestedColumns) return grouped;
+  const visibleColumns = new Set(selectedColumns);
+  const filtered = /* @__PURE__ */ new Map();
+  for (const [key, row] of grouped.entries()) {
+    filtered.set(key, filterRow(row, visibleColumns));
+  }
+  return filtered;
 };
-var loadBelongsToRelation = async (ctx, rootTable, _relationName, relation) => {
+
+// src/orm/lazy-batch/belongs-to.ts
+var loadBelongsToRelation = async (ctx, rootTable, relationName, relation, options) => {
   const roots = ctx.getEntitiesForTable(rootTable);
-  const foreignKeys = collectKeysFromRoots(roots, relation.foreignKey);
+  const getForeignKeys = () => collectKeysFromRoots(roots, relation.foreignKey);
+  let foreignKeys = getForeignKeys();
+  if (!foreignKeys.size) {
+    const pkName = findPrimaryKey(rootTable);
+    const pkColumn2 = rootTable.columns[pkName];
+    const fkColumn = rootTable.columns[relation.foreignKey];
+    if (pkColumn2 && fkColumn) {
+      const missingKeys = /* @__PURE__ */ new Set();
+      const entityByPk = /* @__PURE__ */ new Map();
+      for (const tracked of roots) {
+        const entity = tracked.entity;
+        const pkValue = entity[pkName];
+        if (pkValue === void 0 || pkValue === null) continue;
+        const fkValue = entity[relation.foreignKey];
+        if (fkValue === void 0 || fkValue === null) {
+          missingKeys.add(pkValue);
+          entityByPk.set(pkValue, entity);
+        }
+      }
+      if (missingKeys.size) {
+        const selection2 = buildColumnSelection(
+          rootTable,
+          [pkName, relation.foreignKey],
+          (column) => `Column '${column}' not found on table '${rootTable.name}'`
+        );
+        const keyRows = await fetchRowsForKeys(ctx, rootTable, pkColumn2, missingKeys, selection2);
+        for (const row of keyRows) {
+          const pkValue = row[pkName];
+          if (pkValue === void 0 || pkValue === null) continue;
+          const entity = entityByPk.get(pkValue);
+          if (!entity) continue;
+          const fkValue = row[relation.foreignKey];
+          if (fkValue !== void 0 && fkValue !== null) {
+            entity[relation.foreignKey] = fkValue;
+          }
+        }
+        foreignKeys = getForeignKeys();
+      }
+    }
+  }
   if (!foreignKeys.size) {
     return /* @__PURE__ */ new Map();
   }
   const targetKey = relation.localKey || findPrimaryKey(relation.target);
   const pkColumn = relation.target.columns[targetKey];
   if (!pkColumn) return /* @__PURE__ */ new Map();
-  const rows = await fetchRowsForKeys(ctx, relation.target, pkColumn, foreignKeys);
-  return groupRowsByUnique(rows, targetKey);
+  const requestedColumns = hasColumns(options?.columns) ? [...options.columns] : void 0;
+  const selectedColumns = requestedColumns ? [...requestedColumns] : Object.keys(relation.target.columns);
+  if (!selectedColumns.includes(targetKey)) {
+    selectedColumns.push(targetKey);
+  }
+  const selection = buildColumnSelection(
+    relation.target,
+    selectedColumns,
+    (column) => `Column '${column}' not found on relation '${relationName}'`
+  );
+  const rows = await fetchRowsForKeys(ctx, relation.target, pkColumn, foreignKeys, selection, options?.filter);
+  const grouped = groupRowsByUnique(rows, targetKey);
+  if (!requestedColumns) return grouped;
+  const visibleColumns = new Set(selectedColumns);
+  const filtered = /* @__PURE__ */ new Map();
+  for (const [key, row] of grouped.entries()) {
+    filtered.set(key, filterRow(row, visibleColumns));
+  }
+  return filtered;
 };
-var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation) => {
+
+// 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);
   const rootIds = collectKeysFromRoots(roots, rootKey);
@@ -5043,21 +5567,41 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
   }
   const pivotColumn = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
   if (!pivotColumn) return /* @__PURE__ */ new Map();
-  const pivotRows = await fetchRowsForKeys(ctx, relation.pivotTable, pivotColumn, rootIds);
+  const pivotColumnsRequested = hasColumns(options?.pivot?.columns) ? [...options.pivot.columns] : void 0;
+  const useIncludeDefaults = options !== void 0;
+  let pivotSelectedColumns;
+  if (pivotColumnsRequested) {
+    pivotSelectedColumns = [...pivotColumnsRequested];
+  } else if (useIncludeDefaults) {
+    const pivotPk = relation.pivotPrimaryKey || findPrimaryKey(relation.pivotTable);
+    pivotSelectedColumns = relation.defaultPivotColumns ?? buildDefaultPivotColumns(relation, pivotPk);
+  } else {
+    pivotSelectedColumns = Object.keys(relation.pivotTable.columns);
+  }
+  const pivotQueryColumns = new Set(pivotSelectedColumns);
+  pivotQueryColumns.add(relation.pivotForeignKeyToRoot);
+  pivotQueryColumns.add(relation.pivotForeignKeyToTarget);
+  const pivotSelection = buildColumnSelection(
+    relation.pivotTable,
+    Array.from(pivotQueryColumns),
+    (column) => `Column '${column}' not found on pivot table '${relation.pivotTable.name}'`
+  );
+  const pivotRows = await fetchRowsForKeys(ctx, relation.pivotTable, pivotColumn, rootIds, pivotSelection);
   const rootLookup = /* @__PURE__ */ new Map();
   const targetIds = /* @__PURE__ */ new Set();
+  const pivotVisibleColumns = new Set(pivotSelectedColumns);
   for (const pivot of pivotRows) {
     const rootValue = pivot[relation.pivotForeignKeyToRoot];
     const targetValue = pivot[relation.pivotForeignKeyToTarget];
     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: { ...pivot }
+      pivot: pivotVisibleColumns.size ? filterRow(pivot, pivotVisibleColumns) : {}
     });
-    rootLookup.set(toKey6(rootValue), bucket);
+    rootLookup.set(toKey7(rootValue), bucket);
     targetIds.add(targetValue);
   }
   if (!targetIds.size) {
@@ -5066,16 +5610,34 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const targetPkColumn = relation.target.columns[targetKey];
   if (!targetPkColumn) return /* @__PURE__ */ new Map();
-  const targetRows = await fetchRowsForKeys(ctx, relation.target, targetPkColumn, targetIds);
+  const targetRequestedColumns = hasColumns(options?.columns) ? [...options.columns] : void 0;
+  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));
+      const targetRow = targetMap.get(toKey7(entry.targetId));
       if (!targetRow) continue;
       bucket.push({
-        ...targetRow,
+        ...targetRequestedColumns ? filterRow(targetRow, targetVisibleColumns) : targetRow,
         _pivot: entry.pivot
       });
     }
@@ -5084,7 +5646,7 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
   return result;
 };
 
-// src/orm/entity.ts
+// src/orm/entity-relation-cache.ts
 var relationLoaderCache = (meta, relationName, factory) => {
   if (meta.relationCache.has(relationName)) {
     return meta.relationCache.get(relationName);
@@ -5105,200 +5667,147 @@ var relationLoaderCache = (meta, relationName, factory) => {
   }
   return promise;
 };
-var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
-  const target = { ...row };
-  const meta = {
-    ctx,
-    table,
-    lazyRelations: [...lazyRelations],
-    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;
+
+// src/orm/entity-relations.ts
+var proxifyRelationWrapper = (wrapper) => {
+  return new Proxy(wrapper, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop, receiver);
       }
-      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 (prop in target) {
+        return Reflect.get(target, prop, receiver);
       }
-      if (typeof prop === "string" && table.relations[prop]) {
-        return getRelationWrapper(meta, prop, receiver);
+      const getItems = target.getItems;
+      if (typeof getItems === "function") {
+        const items = getItems.call(target);
+        if (items && prop in items) {
+          const propName = prop;
+          const value = items[propName];
+          return typeof value === "function" ? value.bind(items) : value;
+        }
       }
-      return Reflect.get(targetObj, prop, receiver);
+      const getRef = target.get;
+      if (typeof getRef === "function") {
+        const current = getRef.call(target);
+        if (current && prop in current) {
+          const propName = prop;
+          const value = current[propName];
+          return typeof value === "function" ? value.bind(current) : value;
+        }
+      }
+      return void 0;
     },
-    set(targetObj, prop, value, receiver) {
-      const result = Reflect.set(targetObj, prop, value, receiver);
-      if (typeof prop === "string" && table.columns[prop]) {
-        ctx.markDirty(receiver);
+    set(target, prop, value, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.set(target, prop, value, receiver);
       }
-      return result;
-    }
-  };
-  const proxy = new Proxy(target, handler);
-  populateHydrationCache(proxy, row, meta);
-  return proxy;
-};
-var createEntityFromRow = (ctx, table, row, lazyRelations = []) => {
-  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);
-  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;
-    }
-    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 (prop in target) {
+        return Reflect.set(target, prop, value, receiver);
       }
-      if (cache.size) {
-        meta.relationHydration.set(relationName, cache);
-        meta.relationCache.set(relationName, Promise.resolve(cache));
+      const getRef = target.get;
+      if (typeof getRef === "function") {
+        const current = getRef.call(target);
+        if (current && typeof current === "object") {
+          return Reflect.set(current, prop, value);
+        }
+      }
+      const getItems = target.getItems;
+      if (typeof getItems === "function") {
+        const items = getItems.call(target);
+        return Reflect.set(items, prop, value);
       }
+      return Reflect.set(target, prop, value, receiver);
     }
-  }
+  });
 };
-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);
-  if (wrapper) {
-    meta.relationWrappers.set(relationName, wrapper);
-  }
-  return wrapper;
-};
-var 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(relationKey, proxied);
+  return proxied;
+};
+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,
-        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2)
+      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,
-        () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2)
+      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,
-        () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2)
+      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,
-        () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many)
+      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
       );
     }
@@ -5307,51 +5816,570 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
   }
 };
 
-// src/orm/execute.ts
-var flattenResults = (results) => {
-  const rows = [];
-  for (const result of results) {
-    const { columns, values } = result;
-    for (const valueRow of values) {
-      const row = {};
-      columns.forEach((column, idx) => {
-        row[column] = valueRow[idx];
-      });
-      rows.push(row);
-    }
+// 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 = [];
+  for (const result of results) {
+    const { columns, values } = result;
+    for (const valueRow of values) {
+      const row = {};
+      columns.forEach((column, idx) => {
+        row[column] = valueRow[idx];
+      });
+      rows.push(row);
+    }
+  }
+  return rows;
+};
+var executeWithContexts = async (execCtx, entityCtx, qb) => {
+  const ast = qb.getAST();
+  const compiled = execCtx.dialect.compileSelect(ast);
+  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const rows = flattenResults(executed);
+  const lazyRelations = qb.getLazyRelations();
+  const lazyRelationOptions = qb.getLazyRelationOptions();
+  if (ast.setOps && ast.setOps.length > 0) {
+    const proxies = rows.map((row) => createEntityProxy(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+    await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+    return proxies;
+  }
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  const entities = hydrated.map((row) => createEntityFromRow(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+  await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+  return entities;
+};
+async function executeHydrated(session, qb) {
+  return executeWithContexts(session.getExecutionContext(), session, qb);
+}
+async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
+  const entityCtx = hydCtx.entityContext;
+  if (!entityCtx) {
+    throw new Error("Hydration context is missing an EntityContext");
+  }
+  return executeWithContexts(execCtx, entityCtx, qb);
+}
+var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOptions) => {
+  if (!lazyRelations.length) return;
+  const tracked = ctx.getEntitiesForTable(table);
+  if (!tracked.length) return;
+  const meta = getEntityMeta(tracked[0].entity);
+  if (!meta) return;
+  for (const relationName of lazyRelations) {
+    const relation = table.relations[relationName];
+    if (!relation) continue;
+    const key = relationName;
+    const options = lazyRelationOptions.get(key);
+    if (!options) {
+      continue;
+    }
+    switch (relation.type) {
+      case RelationKinds.HasOne:
+        await relationLoaderCache(
+          meta,
+          key,
+          () => loadHasOneRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.HasMany:
+        await relationLoaderCache(
+          meta,
+          key,
+          () => loadHasManyRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.BelongsTo:
+        await relationLoaderCache(
+          meta,
+          key,
+          () => loadBelongsToRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.BelongsToMany:
+        await relationLoaderCache(
+          meta,
+          key,
+          () => loadBelongsToManyRelation(ctx, table, key, relation, options)
+        );
+        break;
+    }
+  }
+};
+
+// 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;
   }
-  return rows;
-};
-var executeWithContexts = async (execCtx, entityCtx, qb) => {
-  const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
-  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const rows = flattenResults(executed);
-  if (ast.setOps && ast.setOps.length > 0) {
-    return rows.map((row) => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+  /**
+   * 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 };
   }
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map((row) => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
 };
-async function executeHydrated(session, qb) {
-  return executeWithContexts(session.getExecutionContext(), session, qb);
-}
-async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
-  const entityCtx = hydCtx.entityContext;
-  if (!entityCtx) {
-    throw new Error("Hydration context is missing an EntityContext");
+
+// 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;
   }
-  return executeWithContexts(execCtx, entityCtx, qb);
-}
+  /**
+   * 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/query-resolution.ts
-function resolveSelectQuery(query) {
-  const candidate = query;
-  return typeof candidate.getAST === "function" && candidate.getAST ? candidate.getAST() : query;
-}
+// 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
@@ -5359,9 +6387,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(table, state, hydration, dependencies, lazyRelations) {
+  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 = {
@@ -5369,8 +6398,16 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       hydration: initialHydration
     };
     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
@@ -5378,20 +6415,22 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  clone(context = this.context, lazyRelations = new Set(this.lazyRelations)) {
-    return new _SelectQueryBuilder(this.env.table, context.state, context.hydration, this.env.deps, lazyRelations);
+  clone(context = this.context, lazyRelations = new Set(this.lazyRelations), lazyRelationOptions = new Map(this.lazyRelationOptions)) {
+    return new _SelectQueryBuilder(
+      this.env.table,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions
+    );
   }
   /**
    * Applies an alias to the root FROM table.
    * @param alias - Alias to apply
    */
   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);
   }
   /**
@@ -5416,29 +6455,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
@@ -5447,12 +6463,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 = {};
@@ -5463,7 +6479,7 @@ 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
@@ -5471,7 +6487,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with raw column selections
    */
   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
@@ -5482,7 +6498,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   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);
   }
   /**
@@ -5494,7 +6510,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   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);
   }
   /**
@@ -5506,8 +6522,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   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);
   }
   /**
@@ -5518,8 +6533,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
    */
   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);
   }
   /**
@@ -5530,7 +6544,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   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)
@@ -5543,8 +6557,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   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);
   }
   /**
@@ -5557,9 +6570,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
    */
   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);
   }
   /**
@@ -5569,7 +6580,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the INNER JOIN
    */
   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);
   }
   /**
@@ -5579,7 +6590,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the LEFT JOIN
    */
   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);
   }
   /**
@@ -5589,7 +6600,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the RIGHT JOIN
    */
   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);
   }
   /**
@@ -5599,7 +6610,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the relationship match
    */
   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);
   }
   /**
@@ -5610,7 +6621,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the relationship join
    */
   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);
   }
   /**
@@ -5620,42 +6631,47 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the relationship inclusion
    */
   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);
   }
   /**
    * Includes a relation lazily in the query results
    * @param relationName - Name of the relation to include lazily
+   * @param options - Optional include options for lazy loading
    * @returns New query builder instance with lazy relation inclusion
    */
-  includeLazy(relationName) {
-    const nextLazy = new Set(this.lazyRelations);
-    nextLazy.add(relationName);
-    return this.clone(this.context, nextLazy);
-  }
-  /**
-   * Selects columns for a related table in a single hop.
-   */
-  selectRelationColumns(relationName, ...cols) {
+  includeLazy(relationName, options) {
+    let nextContext = this.context;
     const relation = this.env.table.relations[relationName];
-    if (!relation) {
-      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
-    }
-    const target = relation.target;
-    for (const col2 of cols) {
-      if (!target.columns[col2]) {
-        throw new Error(
-          `Column '${col2}' not found on related table '${target.name}' for relation '${relationName}'`
-        );
+    if (relation?.type === RelationKinds.BelongsTo) {
+      const foreignKey = relation.foreignKey;
+      const fkColumn = this.env.table.columns[foreignKey];
+      if (fkColumn) {
+        const hasAlias2 = nextContext.state.ast.columns.some((col2) => {
+          const node = col2;
+          return (node.alias ?? node.name) === foreignKey;
+        });
+        if (!hasAlias2) {
+          nextContext = this.columnSelector.select(nextContext, { [foreignKey]: fkColumn });
+        }
       }
     }
-    return this.include(relationName, { columns: cols });
+    const nextLazy = new Set(this.lazyRelations);
+    nextLazy.add(relationName);
+    const nextOptions = new Map(this.lazyRelationOptions);
+    if (options) {
+      nextOptions.set(relationName, options);
+    } else {
+      nextOptions.delete(relationName);
+    }
+    return this.clone(nextContext, nextLazy, nextOptions);
   }
   /**
-   * Convenience alias for selecting specific columns from a relation.
+   * Convenience alias for including only specific columns from a relation.
    */
   includePick(relationName, cols) {
-    return this.selectRelationColumns(relationName, ...cols);
+    const options = { columns: cols };
+    return this.include(relationName, options);
   }
   /**
    * Selects columns for the root table and relations from an array of entries
@@ -5668,7 +6684,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       if (entry.type === "root") {
         currBuilder = currBuilder.select(...entry.columns);
       } else {
-        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...entry.columns);
+        const options = { columns: entry.columns };
+        currBuilder = currBuilder.include(entry.relationName, options);
       }
     }
     return currBuilder;
@@ -5680,6 +6697,13 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   getLazyRelations() {
     return Array.from(this.lazyRelations);
   }
+  /**
+   * Gets lazy relation include options
+   * @returns Map of relation names to include options
+   */
+  getLazyRelationOptions() {
+    return new Map(this.lazyRelationOptions);
+  }
   /**
    * Gets the table definition for this query builder
    * @returns Table definition
@@ -5695,51 +6719,23 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   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
@@ -5756,7 +6752,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the WHERE condition
    */
   where(expr) {
-    const nextContext = this.applyAst(this.context, (service) => service.withWhere(expr));
+    const nextContext = this.predicateFacet.where(this.context, expr);
     return this.clone(nextContext);
   }
   /**
@@ -5765,7 +6761,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the GROUP BY clause
    */
   groupBy(term) {
-    const nextContext = this.applyAst(this.context, (service) => service.withGroupBy(term));
+    const nextContext = this.predicateFacet.groupBy(this.context, term);
     return this.clone(nextContext);
   }
   /**
@@ -5774,7 +6770,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the HAVING condition
    */
   having(expr) {
-    const nextContext = this.applyAst(this.context, (service) => service.withHaving(expr));
+    const nextContext = this.predicateFacet.having(this.context, expr);
     return this.clone(nextContext);
   }
   /**
@@ -5782,14 +6778,12 @@ 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);
   }
   /**
@@ -5798,7 +6792,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the DISTINCT clause
    */
   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
@@ -5806,7 +6800,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the LIMIT clause
    */
   limit(n) {
-    const nextContext = this.applyAst(this.context, (service) => service.withLimit(n));
+    const nextContext = this.predicateFacet.limit(this.context, n);
     return this.clone(nextContext);
   }
   /**
@@ -5815,7 +6809,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the OFFSET clause
    */
   offset(n) {
-    const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
+    const nextContext = this.predicateFacet.offset(this.context, n);
     return this.clone(nextContext);
   }
   /**
@@ -5875,42 +6869,44 @@ 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
@@ -6042,23 +7038,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
         );
@@ -6074,12 +7091,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,
@@ -6160,6 +7179,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
@@ -6280,6 +7301,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
@@ -6379,6 +7402,8 @@ var isUpdateValue = (value) => {
   }
 };
 var UpdateQueryState = class _UpdateQueryState {
+  table;
+  ast;
   /**
    * Creates a new UpdateQueryState instance
    * @param table - Table definition for the update
@@ -6489,6 +7514,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
@@ -6606,6 +7633,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
@@ -6684,6 +7713,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
@@ -6811,7 +7842,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) {
@@ -6869,6 +7901,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));
@@ -8775,6 +9817,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
@@ -9271,9 +10314,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;
   }
@@ -9343,8 +10384,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.
    */
@@ -9674,12 +10715,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;
@@ -9748,8 +10789,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
@@ -10183,25 +11224,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 ?? []];
@@ -10290,6 +11330,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
@@ -10495,9 +11549,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);
   }
@@ -10516,6 +11568,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
@@ -10572,17 +11631,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) => {
@@ -10597,57 +11652,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
@@ -10680,26 +11728,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)) {
@@ -10708,19 +11743,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);
@@ -10735,41 +11760,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) => ({
@@ -10796,7 +11801,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
   }));
@@ -10872,13 +11877,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");
     }
@@ -11440,6 +12447,8 @@ export {
   esel,
   executeHydrated,
   executeHydratedWithContexts,
+  executeSchemaSql,
+  executeSchemaSqlFor,
   exists,
   exp,
   extract,
@@ -11448,6 +12457,7 @@ export {
   fromUnixTime,
   generateCreateTableSql,
   generateSchemaSql,
+  generateSchemaSqlFor,
   getColumn,
   getDecoratorMetadata,
   getSchemaIntrospector,
@@ -11538,6 +12548,7 @@ export {
   registerExpressionDispatcher,
   registerOperandDispatcher,
   registerSchemaIntrospector,
+  relationLoaderCache,
   renderColumnDefinition,
   renderTypeWithArgs,
   repeat,
@@ -11552,6 +12563,7 @@ export {
   second,
   sel,
   selectFromEntity,
+  setRelations,
   sha1,
   sha2,
   shiftLeft,