metal-orm 1.0.57 → 1.0.58

package/dist/index.cjs

@@ -241,6 +241,7 @@ __export(index_exports, {
   registerExpressionDispatcher: () => registerExpressionDispatcher,
   registerOperandDispatcher: () => registerOperandDispatcher,
   registerSchemaIntrospector: () => registerSchemaIntrospector,
+  relationLoaderCache: () => relationLoaderCache,
   renderColumnDefinition: () => renderColumnDefinition,
   renderTypeWithArgs: () => renderTypeWithArgs,
   repeat: () => repeat,
@@ -4111,20 +4112,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:
@@ -4133,7 +4135,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;
@@ -4146,8 +4148,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) {
@@ -4155,24 +4163,25 @@ 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 hasRelationForeignKey = (relation) => relation.type !== RelationKinds.BelongsToMany;
 var RelationService = class {
   /**
    * Creates a new RelationService instance
@@ -4197,8 +4206,8 @@ var RelationService = class {
    * @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);
+  joinRelation(relationName, joinKind, extraCondition, tableSource) {
+    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition, tableSource);
     return { state: nextState, hydration: this.hydration };
   }
   /**
@@ -4227,14 +4236,58 @@ var RelationService = class {
     const relation = this.getRelation(relationName);
     const aliasPrefix = options?.aliasPrefix ?? relationName;
     const alreadyJoined = state.ast.joins.some((j) => getJoinRelationName(j) === relationName);
+    const { selfFilters, crossFilters } = this.splitFilterExpressions(
+      options?.filter,
+      /* @__PURE__ */ new Set([relation.target.name])
+    );
+    const canUseCte = !alreadyJoined && selfFilters.length > 0;
+    const joinFilters = [...crossFilters];
+    if (!canUseCte) {
+      joinFilters.push(...selfFilters);
+    }
+    const joinCondition = this.combineWithAnd(joinFilters);
+    let tableSourceOverride;
+    if (canUseCte) {
+      const cteInfo = this.createFilteredRelationCte(state, relationName, relation, selfFilters);
+      state = cteInfo.state;
+      tableSourceOverride = cteInfo.table;
+    }
     if (!alreadyJoined) {
-      const joined = this.joinRelation(relationName, options?.joinKind ?? JOIN_KINDS.LEFT, options?.filter);
-      state = joined.state;
+      state = this.withJoin(
+        state,
+        relationName,
+        options?.joinKind ?? JOIN_KINDS.LEFT,
+        joinCondition,
+        tableSourceOverride
+      );
     }
     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);
+    if (hasRelationForeignKey(relation)) {
+      const fkColumn = this.table.columns[relation.foreignKey];
+      if (fkColumn) {
+        const hasForeignKeySelected = state.ast.columns.some((col2) => {
+          if (col2.type !== "Column") return false;
+          const node = col2;
+          const alias = node.alias ?? node.name;
+          return alias === relation.foreignKey;
+        });
+        if (!hasForeignKeySelected) {
+          const fkSelectionResult = this.selectColumns(state, hydration, {
+            [relation.foreignKey]: fkColumn
+          });
+          state = fkSelectionResult.state;
+          hydration = fkSelectionResult.hydration;
+        }
+      }
+    }
+    const requestedColumns = options?.columns?.length ? [...options.columns] : Object.keys(relation.target.columns);
+    const targetPrimaryKey = findPrimaryKey(relation.target);
+    if (!requestedColumns.includes(targetPrimaryKey)) {
+      requestedColumns.push(targetPrimaryKey);
+    }
+    const targetColumns = requestedColumns;
     const buildTypedSelection = (columns, prefix, keys, missingMsg) => {
       return keys.reduce((acc, key) => {
         const def = columns[key];
@@ -4318,27 +4371,42 @@ var RelationService = class {
    * @param extraCondition - Additional join condition
    * @returns Updated query state with join
    */
-  withJoin(state, relationName, joinKind, extraCondition) {
+  withJoin(state, relationName, joinKind, extraCondition, tableSource) {
     const relation = this.getRelation(relationName);
     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
+        rootAlias,
+        targetTableSource,
+        targetName2
       );
       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
+    const targetTable = tableSource ?? {
+      type: "Table",
+      name: relation.target.name,
+      schema: relation.target.schema
+    };
+    const targetName = this.resolveTargetTableName(targetTable, relation);
+    const condition = buildRelationJoinCondition(
+      this.table,
+      relation,
+      extraCondition,
+      rootAlias,
+      targetName
     );
+    const joinNode = createJoinNode(joinKind, targetTable, condition, relationName);
     return this.astService(state).withJoin(joinNode);
   }
   /**
@@ -4355,6 +4423,198 @@ 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
+    };
+  }
+  splitFilterExpressions(filter, allowedTables) {
+    const terms = this.flattenAnd(filter);
+    const selfFilters = [];
+    const crossFilters = [];
+    for (const term of terms) {
+      if (this.isExpressionSelfContained(term, allowedTables)) {
+        selfFilters.push(term);
+      } else {
+        crossFilters.push(term);
+      }
+    }
+    return { selfFilters, crossFilters };
+  }
+  flattenAnd(node) {
+    if (!node) return [];
+    if (node.type === "LogicalExpression" && node.operator === "AND") {
+      return node.operands.flatMap((operand) => this.flattenAnd(operand));
+    }
+    return [node];
+  }
+  isExpressionSelfContained(expr, allowedTables) {
+    const collector = this.collectReferencedTables(expr);
+    if (collector.hasSubquery) return false;
+    if (collector.tables.size === 0) return true;
+    for (const table of collector.tables) {
+      if (!allowedTables.has(table)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  collectReferencedTables(expr) {
+    const collector = {
+      tables: /* @__PURE__ */ new Set(),
+      hasSubquery: false
+    };
+    this.collectFromExpression(expr, collector);
+    return collector;
+  }
+  collectFromExpression(expr, collector) {
+    switch (expr.type) {
+      case "BinaryExpression":
+        this.collectFromOperand(expr.left, collector);
+        this.collectFromOperand(expr.right, collector);
+        break;
+      case "LogicalExpression":
+        expr.operands.forEach((operand) => this.collectFromExpression(operand, collector));
+        break;
+      case "NullExpression":
+        this.collectFromOperand(expr.left, collector);
+        break;
+      case "InExpression":
+        this.collectFromOperand(expr.left, collector);
+        if (Array.isArray(expr.right)) {
+          expr.right.forEach((value) => this.collectFromOperand(value, collector));
+        } else {
+          collector.hasSubquery = true;
+        }
+        break;
+      case "ExistsExpression":
+        collector.hasSubquery = true;
+        break;
+      case "BetweenExpression":
+        this.collectFromOperand(expr.left, collector);
+        this.collectFromOperand(expr.lower, collector);
+        this.collectFromOperand(expr.upper, collector);
+        break;
+      case "ArithmeticExpression":
+      case "BitwiseExpression":
+        this.collectFromOperand(expr.left, collector);
+        this.collectFromOperand(expr.right, collector);
+        break;
+      default:
+        break;
+    }
+  }
+  collectFromOperand(node, collector) {
+    switch (node.type) {
+      case "Column":
+        collector.tables.add(node.table);
+        break;
+      case "Function":
+        node.args.forEach((arg) => this.collectFromOperand(arg, collector));
+        if (node.separator) {
+          this.collectFromOperand(node.separator, collector);
+        }
+        if (node.orderBy) {
+          node.orderBy.forEach((order) => this.collectFromOrderingTerm(order.term, collector));
+        }
+        break;
+      case "JsonPath":
+        this.collectFromOperand(node.column, collector);
+        break;
+      case "ScalarSubquery":
+        collector.hasSubquery = true;
+        break;
+      case "CaseExpression":
+        node.conditions.forEach(({ when, then }) => {
+          this.collectFromExpression(when, collector);
+          this.collectFromOperand(then, collector);
+        });
+        if (node.else) {
+          this.collectFromOperand(node.else, collector);
+        }
+        break;
+      case "Cast":
+        this.collectFromOperand(node.expression, collector);
+        break;
+      case "WindowFunction":
+        node.args.forEach((arg) => this.collectFromOperand(arg, collector));
+        node.partitionBy?.forEach((part) => this.collectFromOperand(part, collector));
+        node.orderBy?.forEach((order) => this.collectFromOrderingTerm(order.term, collector));
+        break;
+      case "Collate":
+        this.collectFromOperand(node.expression, collector);
+        break;
+      case "ArithmeticExpression":
+      case "BitwiseExpression":
+        this.collectFromOperand(node.left, collector);
+        this.collectFromOperand(node.right, collector);
+        break;
+      case "Literal":
+      case "AliasRef":
+        break;
+      default:
+        break;
+    }
+  }
+  collectFromOrderingTerm(term, collector) {
+    if (isOperandNode(term)) {
+      this.collectFromOperand(term, collector);
+      return;
+    }
+    this.collectFromExpression(term, collector);
+  }
+  createFilteredRelationCte(state, relationName, relation, filters) {
+    const cteName = this.generateUniqueCteName(state, relationName);
+    const predicate = this.combineWithAnd(filters);
+    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;
+  }
+  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;
+  }
   /**
    * Gets a relation definition by name
    * @param relationName - Name of the relation
@@ -4705,6 +4965,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
@@ -5086,6 +5358,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.
@@ -5193,10 +5477,27 @@ var DefaultManyToManyCollection = class {
 };
 
 // src/orm/lazy-batch.ts
-var selectAllColumns = (table) => Object.entries(table.columns).reduce((acc, [name, def]) => {
-  acc[name] = def;
-  return acc;
-}, {});
+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) {
@@ -5228,9 +5529,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) => {
@@ -5257,7 +5561,7 @@ var groupRowsByUnique = (rows, keyColumn) => {
   }
   return lookup;
 };
-var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
+var loadHasManyRelation = async (ctx, rootTable, relationName, relation, options) => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
   const keys = collectKeysFromRoots(roots, localKey);
@@ -5266,10 +5570,30 @@ 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) => {
+var loadHasOneRelation = async (ctx, rootTable, relationName, relation, options) => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
   const keys = collectKeysFromRoots(roots, localKey);
@@ -5278,22 +5602,98 @@ 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) => {
+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) => {
+var loadBelongsToManyRelation = async (ctx, rootTable, relationName, relation, options) => {
   const rootKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
   const rootIds = collectKeysFromRoots(roots, rootKey);
@@ -5302,9 +5702,29 @@ 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];
@@ -5314,7 +5734,7 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
     const bucket = rootLookup.get(toKey6(rootValue)) ?? [];
     bucket.push({
       targetId: targetValue,
-      pivot: { ...pivot }
+      pivot: pivotVisibleColumns.size ? filterRow(pivot, pivotVisibleColumns) : {}
     });
     rootLookup.set(toKey6(rootValue), bucket);
     targetIds.add(targetValue);
@@ -5325,8 +5745,19 @@ 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 = [];
@@ -5334,7 +5765,7 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
       const targetRow = targetMap.get(toKey6(entry.targetId));
       if (!targetRow) continue;
       bucket.push({
-        ...targetRow,
+        ...targetRequestedColumns ? filterRow(targetRow, targetVisibleColumns) : targetRow,
         _pivot: entry.pivot
       });
     }
@@ -5364,12 +5795,13 @@ var relationLoaderCache = (meta, relationName, factory) => {
   }
   return promise;
 };
-var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
+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()
@@ -5410,14 +5842,14 @@ var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
   populateHydrationCache(proxy, row, meta);
   return proxy;
 };
-var createEntityFromRow = (ctx, table, row, lazyRelations = []) => {
+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);
+  const entity = createEntityProxy(ctx, table, row, lazyRelations, lazyRelationOptions);
   if (pkValue !== void 0 && pkValue !== null) {
     ctx.trackManaged(table, pkValue, entity);
   } else {
@@ -5467,6 +5899,58 @@ var populateHydrationCache = (entity, row, meta) => {
     }
   }
 };
+var proxifyRelationWrapper = (wrapper) => {
+  return new Proxy(wrapper, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (prop in target) {
+        return Reflect.get(target, 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;
+        }
+      }
+      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(target, prop, value, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.set(target, prop, value, receiver);
+      }
+      if (prop in target) {
+        return Reflect.set(target, prop, value, receiver);
+      }
+      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);
@@ -5474,12 +5958,13 @@ var getRelationWrapper = (meta, relationName, owner) => {
   const relation = meta.table.relations[relationName];
   if (!relation) return void 0;
   const wrapper = instantiateWrapper(meta, relationName, relation, owner);
-  if (wrapper) {
-    meta.relationWrappers.set(relationName, wrapper);
-  }
-  return wrapper;
+  if (!wrapper) return void 0;
+  const proxied = proxifyRelationWrapper(wrapper);
+  meta.relationWrappers.set(relationName, proxied);
+  return proxied;
 };
 var instantiateWrapper = (meta, relationName, relation, owner) => {
+  const lazyOptions = meta.lazyRelationOptions.get(relationName);
   switch (relation.type) {
     case RelationKinds.HasOne: {
       const hasOne2 = relation;
@@ -5487,7 +5972,7 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
       const loader = () => relationLoaderCache(
         meta,
         relationName,
-        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2)
+        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2, lazyOptions)
       );
       return new DefaultHasOneReference(
         meta.ctx,
@@ -5507,7 +5992,7 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
       const loader = () => relationLoaderCache(
         meta,
         relationName,
-        () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2)
+        () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2, lazyOptions)
       );
       return new DefaultHasManyCollection(
         meta.ctx,
@@ -5527,7 +6012,7 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
       const loader = () => relationLoaderCache(
         meta,
         relationName,
-        () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2)
+        () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2, lazyOptions)
       );
       return new DefaultBelongsToReference(
         meta.ctx,
@@ -5547,7 +6032,7 @@ var instantiateWrapper = (meta, relationName, relation, owner) => {
       const loader = () => relationLoaderCache(
         meta,
         relationName,
-        () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many)
+        () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
       );
       return new DefaultManyToManyCollection(
         meta.ctx,
@@ -5586,11 +6071,17 @@ var executeWithContexts = async (execCtx, entityCtx, qb) => {
   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) {
-    return rows.map((row) => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+    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());
-  return hydrated.map((row) => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+  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);
@@ -5602,6 +6093,52 @@ async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
   }
   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) {
@@ -5618,7 +6155,7 @@ 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 initialState = state ?? deps.createState(table);
@@ -5628,6 +6165,7 @@ 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);
   }
@@ -5637,8 +6175,15 @@ 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.
@@ -5885,36 +6430,40 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
    * 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);
+    return this.include(relationName, { columns: cols });
   }
   /**
    * Selects columns for the root table and relations from an array of entries
@@ -5927,7 +6476,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       if (entry.type === "root") {
         currBuilder = currBuilder.select(...entry.columns);
       } else {
-        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...entry.columns);
+        currBuilder = currBuilder.include(entry.relationName, { columns: entry.columns });
       }
     }
     return currBuilder;
@@ -5939,6 +6488,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
@@ -11798,6 +12354,7 @@ function createPooledExecutorFactory(opts) {
   registerExpressionDispatcher,
   registerOperandDispatcher,
   registerSchemaIntrospector,
+  relationLoaderCache,
   renderColumnDefinition,
   renderTypeWithArgs,
   repeat,