metal-orm 1.0.115 → 1.0.116

package/dist/index.cjs

@@ -3420,6 +3420,17 @@ var SelectQueryState = class _SelectQueryState {
       joins: [...this.ast.joins ?? [], join]
     });
   }
+  /**
+   * Replaces the JOIN list.
+   * @param joins - Join nodes to set
+   * @returns New SelectQueryState with updated JOINs
+   */
+  withJoins(joins) {
+    return this.clone({
+      ...this.ast,
+      joins
+    });
+  }
   /**
    * Replaces the FROM clause.
    * @param from - Table source for the FROM clause
@@ -4342,9 +4353,6 @@ 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-filter-utils.ts
 var splitFilterExpressions = (filter, allowedTables) => {
   const terms = flattenAnd(filter);
@@ -4482,7 +4490,241 @@ var collectFromOrderingTerm = (term, collector) => {
   collectFromExpression(term, collector);
 };
 
-// src/query-builder/relation-join-planner.ts
+// src/query-builder/expression-table-mapper.ts
+var remapExpressionTable = (expr, fromTable, toTable) => {
+  if (!expr || fromTable === toTable) return expr;
+  return mapExpression(expr, fromTable, toTable);
+};
+var mapExpression = (expr, fromTable, toTable) => {
+  switch (expr.type) {
+    case "BinaryExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      const right2 = mapOperand(expr.right, fromTable, toTable);
+      if (left2 === expr.left && right2 === expr.right) return expr;
+      return { ...expr, left: left2, right: right2 };
+    }
+    case "LogicalExpression": {
+      const nextOperands = expr.operands.map((op) => mapExpression(op, fromTable, toTable));
+      if (nextOperands.every((op, i) => op === expr.operands[i])) return expr;
+      return { ...expr, operands: nextOperands };
+    }
+    case "NullExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      if (left2 === expr.left) return expr;
+      return { ...expr, left: left2 };
+    }
+    case "InExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      let right2 = expr.right;
+      if (Array.isArray(expr.right)) {
+        const mapped = expr.right.map((val) => mapOperand(val, fromTable, toTable));
+        if (!mapped.every((val, i) => val === expr.right[i])) {
+          right2 = mapped;
+        }
+      } else if (expr.right.type === "ScalarSubquery") {
+        const mapped = mapScalarSubquery(expr.right, fromTable, toTable);
+        if (mapped !== expr.right) right2 = mapped;
+      }
+      if (left2 === expr.left && right2 === expr.right) return expr;
+      return { ...expr, left: left2, right: right2 };
+    }
+    case "ExistsExpression": {
+      const mapped = mapSelectQuery(expr.subquery, fromTable, toTable);
+      if (mapped === expr.subquery) return expr;
+      return { ...expr, subquery: mapped };
+    }
+    case "BetweenExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      const lower2 = mapOperand(expr.lower, fromTable, toTable);
+      const upper2 = mapOperand(expr.upper, fromTable, toTable);
+      if (left2 === expr.left && lower2 === expr.lower && upper2 === expr.upper) return expr;
+      return { ...expr, left: left2, lower: lower2, upper: upper2 };
+    }
+    case "ArithmeticExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      const right2 = mapOperand(expr.right, fromTable, toTable);
+      if (left2 === expr.left && right2 === expr.right) return expr;
+      return { ...expr, left: left2, right: right2 };
+    }
+    case "BitwiseExpression": {
+      const left2 = mapOperand(expr.left, fromTable, toTable);
+      const right2 = mapOperand(expr.right, fromTable, toTable);
+      if (left2 === expr.left && right2 === expr.right) return expr;
+      return { ...expr, left: left2, right: right2 };
+    }
+    default:
+      return expr;
+  }
+};
+var mapColumn = (node, fromTable, toTable) => {
+  if (node.table !== fromTable) return node;
+  return { ...node, table: toTable };
+};
+var mapJsonPath = (node, fromTable, toTable) => {
+  const nextColumn = mapColumn(node.column, fromTable, toTable);
+  if (nextColumn === node.column) return node;
+  return { ...node, column: nextColumn };
+};
+var mapWindowFunctionArg = (node, fromTable, toTable) => {
+  switch (node.type) {
+    case "Column":
+      return mapColumn(node, fromTable, toTable);
+    case "JsonPath":
+      return mapJsonPath(node, fromTable, toTable);
+    default:
+      return node;
+  }
+};
+var mapOperand = (node, fromTable, toTable) => {
+  switch (node.type) {
+    case "Column":
+      return mapColumn(node, fromTable, toTable);
+    case "Function": {
+      const nextArgs = node.args.map((arg) => mapOperand(arg, fromTable, toTable));
+      const nextSeparator = node.separator ? mapOperand(node.separator, fromTable, toTable) : node.separator;
+      const nextOrderBy = node.orderBy?.map((order) => ({
+        ...order,
+        term: mapOrderingTerm(order.term, fromTable, toTable)
+      }));
+      const changed = nextArgs.some((arg, i) => arg !== node.args[i]) || nextSeparator !== node.separator || nextOrderBy && node.orderBy && nextOrderBy.some((ob, i) => ob.term !== node.orderBy[i].term);
+      if (!changed) return node;
+      return {
+        ...node,
+        args: nextArgs,
+        separator: nextSeparator,
+        orderBy: nextOrderBy
+      };
+    }
+    case "JsonPath": {
+      return mapJsonPath(node, fromTable, toTable);
+    }
+    case "ScalarSubquery": {
+      return mapScalarSubquery(node, fromTable, toTable);
+    }
+    case "CaseExpression": {
+      const nextConditions = node.conditions.map((cond) => ({
+        when: mapExpression(cond.when, fromTable, toTable),
+        then: mapOperand(cond.then, fromTable, toTable)
+      }));
+      const nextElse = node.else ? mapOperand(node.else, fromTable, toTable) : node.else;
+      const changed = nextConditions.some(
+        (cond, i) => cond.when !== node.conditions[i].when || cond.then !== node.conditions[i].then
+      ) || nextElse !== node.else;
+      if (!changed) return node;
+      return { ...node, conditions: nextConditions, else: nextElse };
+    }
+    case "Cast": {
+      const nextExpr = mapOperand(node.expression, fromTable, toTable);
+      if (nextExpr === node.expression) return node;
+      return { ...node, expression: nextExpr };
+    }
+    case "WindowFunction": {
+      const nextArgs = node.args.map((arg) => mapWindowFunctionArg(arg, fromTable, toTable));
+      const nextPartition = node.partitionBy?.map((part) => mapColumn(part, fromTable, toTable));
+      const nextOrderBy = node.orderBy?.map((order) => ({
+        ...order,
+        term: mapOrderingTerm(order.term, fromTable, toTable)
+      }));
+      const changed = nextArgs.some((arg, i) => arg !== node.args[i]) || nextPartition && node.partitionBy && nextPartition.some((p, i) => p !== node.partitionBy[i]) || nextOrderBy && node.orderBy && nextOrderBy.some((ob, i) => ob.term !== node.orderBy[i].term);
+      if (!changed) return node;
+      return {
+        ...node,
+        args: nextArgs,
+        partitionBy: nextPartition,
+        orderBy: nextOrderBy
+      };
+    }
+    case "Collate": {
+      const nextExpr = mapOperand(node.expression, fromTable, toTable);
+      if (nextExpr === node.expression) return node;
+      return { ...node, expression: nextExpr };
+    }
+    case "ArithmeticExpression": {
+      const left2 = mapOperand(node.left, fromTable, toTable);
+      const right2 = mapOperand(node.right, fromTable, toTable);
+      if (left2 === node.left && right2 === node.right) return node;
+      return { ...node, left: left2, right: right2 };
+    }
+    case "BitwiseExpression": {
+      const left2 = mapOperand(node.left, fromTable, toTable);
+      const right2 = mapOperand(node.right, fromTable, toTable);
+      if (left2 === node.left && right2 === node.right) return node;
+      return { ...node, left: left2, right: right2 };
+    }
+    default:
+      return node;
+  }
+};
+var mapOrderingTerm = (term, fromTable, toTable) => {
+  if (isOperandNode(term)) {
+    return mapOperand(term, fromTable, toTable);
+  }
+  return mapExpression(term, fromTable, toTable);
+};
+var mapScalarSubquery = (node, fromTable, toTable) => {
+  const mapped = mapSelectQuery(node.query, fromTable, toTable);
+  if (mapped === node.query) return node;
+  return { ...node, query: mapped };
+};
+var mapProjectionNode = (node, fromTable, toTable) => {
+  switch (node.type) {
+    case "Column":
+      return mapColumn(node, fromTable, toTable);
+    case "Function":
+      return mapOperand(node, fromTable, toTable);
+    case "CaseExpression":
+      return mapOperand(node, fromTable, toTable);
+    case "Cast":
+      return mapOperand(node, fromTable, toTable);
+    case "WindowFunction":
+      return mapOperand(node, fromTable, toTable);
+    case "ScalarSubquery":
+      return mapScalarSubquery(node, fromTable, toTable);
+    default:
+      return node;
+  }
+};
+var mapSelectQuery = (query, fromTable, toTable) => {
+  const nextColumns = query.columns.map((col2) => mapProjectionNode(col2, fromTable, toTable));
+  const nextJoins = query.joins.map((join) => ({
+    ...join,
+    condition: mapExpression(join.condition, fromTable, toTable)
+  }));
+  const nextWhere = query.where ? mapExpression(query.where, fromTable, toTable) : query.where;
+  const nextHaving = query.having ? mapExpression(query.having, fromTable, toTable) : query.having;
+  const nextGroupBy = query.groupBy?.map((term) => mapOrderingTerm(term, fromTable, toTable));
+  const nextOrderBy = query.orderBy?.map((ob) => ({
+    ...ob,
+    term: mapOrderingTerm(ob.term, fromTable, toTable)
+  }));
+  const nextDistinct = query.distinct?.map((col2) => mapColumn(col2, fromTable, toTable));
+  const nextSetOps = query.setOps?.map((op) => ({ ...op, query: mapSelectQuery(op.query, fromTable, toTable) }));
+  const nextCtes = query.ctes?.map((cte) => ({ ...cte, query: mapSelectQuery(cte.query, fromTable, toTable) }));
+  const changed = nextColumns.some((c, i) => c !== query.columns[i]) || nextJoins.some((j, i) => j.condition !== query.joins[i].condition) || nextWhere !== query.where || nextHaving !== query.having || nextGroupBy && query.groupBy && nextGroupBy.some((t, i) => t !== query.groupBy[i]) || nextOrderBy && query.orderBy && nextOrderBy.some((o, i) => o.term !== query.orderBy[i].term) || nextDistinct && query.distinct && nextDistinct.some((d, i) => d !== query.distinct[i]) || nextSetOps && query.setOps && nextSetOps.some((o, i) => o.query !== query.setOps[i].query) || nextCtes && query.ctes && nextCtes.some((c, i) => c.query !== query.ctes[i].query);
+  if (!changed) return query;
+  return {
+    ...query,
+    columns: nextColumns,
+    joins: nextJoins,
+    where: nextWhere,
+    having: nextHaving,
+    groupBy: nextGroupBy,
+    orderBy: nextOrderBy,
+    distinct: nextDistinct,
+    setOps: nextSetOps,
+    ctes: nextCtes
+  };
+};
+
+// src/core/ast/join-metadata.ts
+var getJoinRelationName = (join) => join.meta?.relationName;
+
+// src/query-builder/join-utils.ts
+var findJoinIndexByRelationKey = (joins, relationKey) => joins.findIndex((j) => getJoinRelationName(j) === relationKey);
+var findJoinByRelationKey = (joins, relationKey) => joins.find((j) => getJoinRelationName(j) === relationKey);
+var hasJoinForRelationKey = (joins, relationKey) => findJoinIndexByRelationKey(joins, relationKey) !== -1;
+
+// src/query-builder/table-alias-utils.ts
 var getExposedName = (ts) => {
   if (ts.type === "Table") return ts.alias ?? ts.name;
   if (ts.type === "DerivedTable") return ts.alias;
@@ -4514,69 +4756,118 @@ var ensureCorrelationName = (state, relationName, ts, extraUsed) => {
   const alias = makeUniqueAlias(relationName, used);
   return { ...ts, alias };
 };
-var RelationJoinPlanner = class {
-  constructor(table, createQueryAstService) {
-    this.table = table;
-    this.createQueryAstService = createQueryAstService;
+var getJoinCorrelationName = (state, relationName, fallback) => {
+  const join = findJoinByRelationKey(state.ast.joins, relationName);
+  if (!join) return fallback;
+  const t = join.table;
+  if (t.type === "Table") return t.alias ?? t.name;
+  if (t.type === "DerivedTable") return t.alias;
+  if (t.type === "FunctionTable") return t.alias ?? fallback;
+  return fallback;
+};
+var resolveTargetTableName = (target, fallback) => {
+  if (target.type === "Table") return target.alias ?? target.name;
+  if (target.type === "DerivedTable") return target.alias;
+  if (target.type === "FunctionTable") return target.alias ?? fallback;
+  return fallback;
+};
+
+// src/query-builder/relation-join-strategies.ts
+var buildBelongsToManyTargetCondition = (relation, targetName, extra) => {
+  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
+  let condition = eq(
+    { type: "Column", table: targetName, name: targetKey },
+    { type: "Column", table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
+  );
+  if (extra) {
+    condition = and(condition, extra);
   }
-  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) {
-      let targetTableSource = tableSource ?? {
-        type: "Table",
-        name: relation.target.name,
-        schema: relation.target.schema
-      };
-      targetTableSource = ensureCorrelationName(
-        state,
-        relationName,
-        targetTableSource,
-        [relation.pivotTable.name]
-      );
-      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);
-    }
-    let targetTable = tableSource ?? {
+  return condition;
+};
+var addRelationJoin = (params) => {
+  const { state, rootTable, rootAlias, relationKey, relation, joinKind, filter, tableSource } = params;
+  if (relation.type === RelationKinds.BelongsToMany) {
+    const many = relation;
+    let targetSource2 = tableSource ?? {
       type: "Table",
       name: relation.target.name,
       schema: relation.target.schema
     };
-    targetTable = ensureCorrelationName(state, relationName, targetTable);
-    const targetName = this.resolveTargetTableName(targetTable, relation);
-    const condition = buildRelationJoinCondition(
-      this.table,
-      relation,
-      extraCondition,
+    targetSource2 = ensureCorrelationName(state, relationKey, targetSource2, [many.pivotTable.name]);
+    const targetName2 = resolveTargetTableName(targetSource2, relation.target.name);
+    const extra2 = remapExpressionTable(filter, relation.target.name, targetName2);
+    const joins = buildBelongsToManyJoins(
+      rootTable,
+      relationKey,
+      many,
+      joinKind,
+      extra2,
       rootAlias,
-      targetName
+      targetSource2,
+      targetName2
     );
-    const joinNode = createJoinNode(joinKind, targetTable, condition, relationName);
-    return this.astService(state).withJoin(joinNode);
+    return joins.reduce((curr, join) => curr.withJoin(join), state);
   }
-  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;
+  let targetSource = tableSource ?? {
+    type: "Table",
+    name: relation.target.name,
+    schema: relation.target.schema
+  };
+  targetSource = ensureCorrelationName(state, relationKey, targetSource);
+  const targetName = resolveTargetTableName(targetSource, relation.target.name);
+  const extra = remapExpressionTable(filter, relation.target.name, targetName);
+  const condition = buildRelationJoinCondition(rootTable, relation, extra, rootAlias, targetName);
+  const joinNode = createJoinNode(joinKind, targetSource, condition, relationKey);
+  return state.withJoin(joinNode);
+};
+var updateRelationJoin = (params) => {
+  const { joins, joinIndex, relation, currentTable, currentAlias, options } = params;
+  const join = joins[joinIndex];
+  const targetName = resolveTargetTableName(join.table, relation.target.name);
+  const extra = remapExpressionTable(options.filter, relation.target.name, targetName);
+  if (relation.type === RelationKinds.BelongsToMany) {
+    const many = relation;
+    const targetCondition = buildBelongsToManyTargetCondition(many, targetName, extra);
+    joins[joinIndex] = {
+      ...join,
+      kind: options.joinKind ?? join.kind,
+      condition: targetCondition
+    };
+    if (options.joinKind && joinIndex > 0) {
+      const pivotJoin = joins[joinIndex - 1];
+      const pivotTable = pivotJoin.table.type === "Table" ? pivotJoin.table.name : void 0;
+      if (pivotTable === many.pivotTable.name) {
+        joins[joinIndex - 1] = { ...pivotJoin, kind: options.joinKind };
+      }
     }
-    return relation.target.name;
+    return joins;
+  }
+  const condition = buildRelationJoinCondition(currentTable, relation, extra, currentAlias, targetName);
+  joins[joinIndex] = {
+    ...join,
+    kind: options.joinKind ?? join.kind,
+    condition
+  };
+  return joins;
+};
+
+// src/query-builder/relation-join-planner.ts
+var RelationJoinPlanner = class {
+  constructor(table) {
+    this.table = table;
+  }
+  withJoin(state, relationName, relation, joinKind, extraCondition, tableSource) {
+    const rootAlias = state.ast.from.type === "Table" ? state.ast.from.alias : void 0;
+    return addRelationJoin({
+      state,
+      rootTable: this.table,
+      rootAlias,
+      relationKey: relationName,
+      relation,
+      joinKind,
+      filter: extraCondition,
+      tableSource
+    });
   }
 };
 
@@ -4627,15 +4918,6 @@ var RelationCteBuilder = class {
 };
 
 // src/query-builder/relation-include-strategies.ts
-var getJoinCorrelationName = (state, relationName, fallback) => {
-  const join = state.ast.joins.find((j) => getJoinRelationName(j) === relationName);
-  if (!join) return fallback;
-  const t = join.table;
-  if (t.type === "Table") return t.alias ?? t.name;
-  if (t.type === "DerivedTable") return t.alias;
-  if (t.type === "FunctionTable") return t.alias ?? fallback;
-  return fallback;
-};
 var buildTypedSelection = (columns, prefix, keys, missingMsg, tableOverride) => {
   return keys.reduce((acc, key) => {
     const def = columns[key];
@@ -4762,7 +5044,7 @@ var RelationService = class {
       table,
       (state2, hydration2, columns) => this.selectColumns(state2, hydration2, columns)
     );
-    this.joinPlanner = new RelationJoinPlanner(table, createQueryAstService);
+    this.joinPlanner = new RelationJoinPlanner(table);
     this.cteBuilder = new RelationCteBuilder(table, createQueryAstService);
   }
   projectionHelper;
@@ -4812,7 +5094,7 @@ var RelationService = class {
     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 alreadyJoined = hasJoinForRelationKey(state.ast.joins, relationName);
     const { selfFilters, crossFilters } = splitFilterExpressions(
       options?.filter,
       /* @__PURE__ */ new Set([relation.target.name])
@@ -5130,6 +5412,34 @@ var cloneRelationIncludeTree = (tree) => {
   }
   return cloned;
 };
+var getIncludeNode = (tree, segments) => {
+  let current = tree;
+  let node;
+  for (let i = 0; i < segments.length; i += 1) {
+    if (!current) return { exists: false };
+    node = current[segments[i]];
+    if (!node) return { exists: false };
+    if (i < segments.length - 1) {
+      current = node.include;
+    }
+  }
+  return { options: node?.options, exists: Boolean(node) };
+};
+var setIncludeOptions = (tree, segments, options) => {
+  let current = tree;
+  for (let i = 0; i < segments.length; i += 1) {
+    const key = segments[i];
+    const isLeaf = i === segments.length - 1;
+    const existing = current[key] ?? {};
+    if (isLeaf) {
+      current[key] = { ...existing, options };
+      return;
+    }
+    const nextInclude = existing.include ?? {};
+    current[key] = { ...existing, include: nextInclude };
+    current = nextInclude;
+  }
+};
 
 // src/orm/hydration.ts
 var hydrateRows = (rows, plan) => {
@@ -7780,6 +8090,17 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   getIncludeTree() {
     return cloneRelationIncludeTree(this.includeTree);
   }
+  /**
+   * Internal access to builder internals for advanced operations.
+   * @internal
+   */
+  getInternals() {
+    return {
+      context: this.context,
+      includeTree: this.includeTree,
+      clone: (context, includeTree) => this.clone(context, void 0, void 0, includeTree)
+    };
+  }
   /**
    * Gets the table definition for this query builder
    * @returns Table definition
@@ -14772,6 +15093,87 @@ function createPooledExecutorFactory(opts) {
   };
 }
 
+// src/query-builder/relation-key.ts
+var buildRelationKey = (segments) => segments.join(RELATION_SEPARATOR);
+
+// src/query-builder/update-include.ts
+var updateInclude = (qb, relationPath, updater) => {
+  if (!relationPath || !relationPath.trim()) {
+    return qb;
+  }
+  const segments = relationPath.split(".").filter(Boolean);
+  if (segments.length === 0) {
+    return qb;
+  }
+  const internals = qb.getInternals();
+  const { context, includeTree } = internals;
+  let state = context.state;
+  const hydration = context.hydration;
+  let currentTable = qb.getTable();
+  let currentAlias = getExposedName(state.ast.from) ?? currentTable.name;
+  const includeInfo = getIncludeNode(includeTree, segments);
+  const existingOptions = includeInfo.options ?? {};
+  const nextOptions = updater({ ...existingOptions });
+  let nextIncludeTree = includeTree;
+  const shouldCreateIncludePath = segments.length === 1 || includeInfo.exists;
+  if (shouldCreateIncludePath) {
+    nextIncludeTree = cloneRelationIncludeTree(includeTree);
+    setIncludeOptions(nextIncludeTree, segments, nextOptions);
+  }
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i];
+    const relation = currentTable.relations[segment];
+    if (!relation) {
+      throw new Error(`Relation '${segment}' not found on table '${currentTable.name}'`);
+    }
+    const relationKey = buildRelationKey(segments.slice(0, i + 1));
+    const joinIndex = findJoinIndexByRelationKey(state.ast.joins, relationKey);
+    const isLeaf = i === segments.length - 1;
+    if (isLeaf) {
+      if (joinIndex === -1) {
+        const joinKind = nextOptions.joinKind ?? JOIN_KINDS.LEFT;
+        state = addRelationJoin({
+          state,
+          rootTable: currentTable,
+          rootAlias: currentAlias,
+          relationKey,
+          relation,
+          joinKind,
+          filter: nextOptions.filter
+        });
+      } else {
+        const joins = [...state.ast.joins];
+        updateRelationJoin({
+          joins,
+          joinIndex,
+          relation,
+          currentTable,
+          currentAlias,
+          options: nextOptions
+        });
+        state = state.withJoins(joins);
+      }
+    } else if (joinIndex === -1) {
+      const segmentOptions = getIncludeNode(includeTree, segments.slice(0, i + 1)).options;
+      const joinKind = segmentOptions?.joinKind ?? JOIN_KINDS.LEFT;
+      state = addRelationJoin({
+        state,
+        rootTable: currentTable,
+        rootAlias: currentAlias,
+        relationKey,
+        relation,
+        joinKind,
+        filter: segmentOptions?.filter
+      });
+    }
+    const joinForSegment = findJoinByRelationKey(state.ast.joins, relationKey);
+    currentAlias = joinForSegment ? getExposedName(joinForSegment.table) ?? relation.target.name : relation.target.name;
+    currentTable = relation.target;
+  }
+  const nextContext = { state, hydration };
+  return internals.clone(nextContext, nextIncludeTree);
+};
+
 // src/dto/apply-filter.ts
 function buildFieldExpression(column, filter) {
   const expressions = [];
@@ -14849,7 +15251,7 @@ function caseInsensitiveLike(column, pattern) {
     right: { type: "Literal", value: pattern.toLowerCase() }
   };
 }
-function applyFilter(qb, tableOrEntity, where) {
+function applyFilter(qb, tableOrEntity, where, _options) {
   if (!where) {
     return qb;
   }
@@ -14863,12 +15265,15 @@ function applyFilter(qb, tableOrEntity, where) {
       continue;
     }
     const column = table.columns[fieldName];
-    if (!column) {
-      continue;
-    }
-    const expr = buildFieldExpression(column, fieldFilter);
-    if (expr) {
-      expressions.push(expr);
+    if (column) {
+      const expr = buildFieldExpression(column, fieldFilter);
+      if (expr) {
+        expressions.push(expr);
+      }
+    } else if (table.relations && fieldName in table.relations) {
+      const relationFilter = fieldFilter;
+      const relationName = fieldName;
+      qb = applyRelationFilter(qb, table, relationName, relationFilter);
     }
   }
   if (expressions.length === 0) {
@@ -14879,6 +15284,199 @@ function applyFilter(qb, tableOrEntity, where) {
   }
   return qb.where(and(...expressions));
 }
+function applyRelationFilter(qb, table, relationName, filter) {
+  const relation = table.relations[relationName];
+  if (!relation) {
+    return qb;
+  }
+  if (filter.some) {
+    const predicate = buildFilterExpression(relation.target, filter.some);
+    if (predicate) {
+      qb = updateInclude(qb, relationName, (opts) => ({
+        ...opts,
+        joinKind: JOIN_KINDS.INNER,
+        filter: opts.filter ? and(opts.filter, predicate) : predicate
+      }));
+      const pk = findPrimaryKey(table);
+      const pkColumn = table.columns[pk];
+      qb = pkColumn ? qb.distinct(pkColumn) : qb.distinct({ type: "Column", table: table.name, name: pk });
+    }
+  }
+  if (filter.none) {
+    const predicate = buildFilterExpression(relation.target, filter.none);
+    if (predicate) {
+      qb = qb.whereHasNot(relationName, (subQb) => subQb.where(predicate));
+    }
+  }
+  if (filter.every) {
+    const predicate = buildFilterExpression(relation.target, filter.every);
+    if (predicate) {
+      const pk = findPrimaryKey(table);
+      qb = qb.joinRelation(relationName);
+      qb = qb.groupBy({ type: "Column", table: table.name, name: pk });
+      qb = qb.having(buildEveryHavingClause(relationName, predicate, relation.target));
+    }
+  }
+  if (filter.isEmpty !== void 0) {
+    if (filter.isEmpty) {
+      qb = qb.whereHasNot(relationName);
+    } else {
+      qb = qb.whereHas(relationName);
+    }
+  }
+  if (filter.isNotEmpty !== void 0) {
+    if (filter.isNotEmpty) {
+      qb = qb.whereHas(relationName);
+    } else {
+      qb = qb.whereHasNot(relationName);
+    }
+  }
+  return qb;
+}
+var buildRelationSubqueryBase = (table, relation) => {
+  const target = relation.target;
+  if (relation.type === RelationKinds.BelongsToMany) {
+    const many = relation;
+    const localKey = many.localKey || findPrimaryKey(table);
+    const targetKey = many.targetKey || findPrimaryKey(target);
+    const pivot = many.pivotTable;
+    const from2 = {
+      type: "Table",
+      name: pivot.name,
+      schema: pivot.schema
+    };
+    const joins = [
+      createJoinNode(
+        JOIN_KINDS.INNER,
+        { type: "Table", name: target.name, schema: target.schema },
+        eq(
+          { type: "Column", table: target.name, name: targetKey },
+          { type: "Column", table: pivot.name, name: many.pivotForeignKeyToTarget }
+        )
+      )
+    ];
+    const correlation2 = eq(
+      { type: "Column", table: pivot.name, name: many.pivotForeignKeyToRoot },
+      { type: "Column", table: table.name, name: localKey }
+    );
+    const groupByColumn = {
+      type: "Column",
+      table: pivot.name,
+      name: many.pivotForeignKeyToRoot
+    };
+    return {
+      from: from2,
+      joins,
+      correlation: correlation2,
+      groupByColumn,
+      targetTable: target,
+      targetTableName: target.name
+    };
+  }
+  const from = {
+    type: "Table",
+    name: target.name,
+    schema: target.schema
+  };
+  const correlation = buildRelationCorrelation(table, relation);
+  const groupByColumnName = relation.type === RelationKinds.BelongsTo ? relation.localKey || findPrimaryKey(target) : relation.foreignKey;
+  return {
+    from,
+    joins: [],
+    correlation,
+    groupByColumn: { type: "Column", table: target.name, name: groupByColumnName },
+    targetTable: target,
+    targetTableName: target.name
+  };
+};
+function buildRelationFilterExpression(table, relationName, filter) {
+  const relation = table.relations[relationName];
+  if (!relation) {
+    return null;
+  }
+  const expressions = [];
+  const subqueryBase = buildRelationSubqueryBase(table, relation);
+  const buildSubquery = (predicate) => {
+    const where = predicate ? and(subqueryBase.correlation, predicate) : subqueryBase.correlation;
+    return {
+      type: "SelectQuery",
+      from: subqueryBase.from,
+      columns: [],
+      joins: subqueryBase.joins,
+      where
+    };
+  };
+  if (filter.some) {
+    const predicate = buildFilterExpression(relation.target, filter.some);
+    if (predicate) {
+      expressions.push(exists(buildSubquery(predicate)));
+    }
+  }
+  if (filter.none) {
+    const predicate = buildFilterExpression(relation.target, filter.none);
+    if (predicate) {
+      expressions.push(notExists(buildSubquery(predicate)));
+    }
+  }
+  if (filter.every) {
+    const predicate = buildFilterExpression(relation.target, filter.every);
+    if (predicate) {
+      const subquery = {
+        type: "SelectQuery",
+        from: subqueryBase.from,
+        columns: [],
+        joins: subqueryBase.joins,
+        where: subqueryBase.correlation,
+        groupBy: [subqueryBase.groupByColumn],
+        having: buildEveryHavingClause(subqueryBase.targetTableName, predicate, subqueryBase.targetTable)
+      };
+      expressions.push(exists(subquery));
+    }
+  }
+  if (filter.isEmpty !== void 0) {
+    const subquery = buildSubquery();
+    expressions.push(filter.isEmpty ? notExists(subquery) : exists(subquery));
+  }
+  if (filter.isNotEmpty !== void 0) {
+    const subquery = buildSubquery();
+    expressions.push(filter.isNotEmpty ? exists(subquery) : notExists(subquery));
+  }
+  if (expressions.length === 0) {
+    return null;
+  }
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+  return and(...expressions);
+}
+function buildEveryHavingClause(relationName, predicate, targetTable) {
+  const pk = findPrimaryKey(targetTable);
+  const whenClause = {
+    when: predicate,
+    then: { type: "Literal", value: 1 }
+  };
+  const caseExpr = {
+    type: "CaseExpression",
+    conditions: [whenClause],
+    else: { type: "Literal", value: null }
+  };
+  const countMatching = {
+    type: "Function",
+    name: "COUNT",
+    args: [caseExpr]
+  };
+  const countAll2 = {
+    type: "Function",
+    name: "COUNT",
+    args: [{ type: "Column", table: relationName, name: pk }]
+  };
+  return {
+    type: "BinaryExpression",
+    operator: "=",
+    left: countAll2,
+    right: countMatching
+  };
+}
 function isEntityConstructor(value) {
   return typeof value === "function" && value.prototype?.constructor === value;
 }
@@ -14896,12 +15494,20 @@ function buildFilterExpression(tableOrEntity, where) {
       continue;
     }
     const column = table.columns[fieldName];
-    if (!column) {
-      continue;
-    }
-    const expr = buildFieldExpression(column, fieldFilter);
-    if (expr) {
-      expressions.push(expr);
+    if (column) {
+      const expr = buildFieldExpression(column, fieldFilter);
+      if (expr) {
+        expressions.push(expr);
+      }
+    } else if (table.relations && fieldName in table.relations) {
+      const relationExpr = buildRelationFilterExpression(
+        table,
+        fieldName,
+        fieldFilter
+      );
+      if (relationExpr) {
+        expressions.push(relationExpr);
+      }
     }
   }
   if (expressions.length === 0) {