metal-orm 1.0.57 → 1.0.58

package/src/query-builder/relation-service.ts

@@ -1,12 +1,21 @@
 import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column-types.js';
-import { RelationDef, RelationKinds, BelongsToManyRelation } from '../schema/relation.js';
-import { SelectQueryNode } from '../core/ast/query.js';
-import {
-  ColumnNode,
-  ExpressionNode,
-  and
-} from '../core/ast/expression.js';
+import {
+  RelationDef,
+  RelationKinds,
+  BelongsToManyRelation,
+  HasManyRelation,
+  HasOneRelation,
+  BelongsToRelation
+} from '../schema/relation.js';
+import { SelectQueryNode, TableSourceNode, TableNode, OrderingTerm } from '../core/ast/query.js';
+import {
+  ColumnNode,
+  ExpressionNode,
+  OperandNode,
+  and,
+  isOperandNode
+} from '../core/ast/expression.js';
 import { SelectQueryState } from './select-query-state.js';
 import { HydrationManager } from './hydration-manager.js';
 import { QueryAstService } from './query-ast-service.js';
@@ -19,16 +28,29 @@ import {
   buildBelongsToManyJoins
 } from './relation-conditions.js';
 import { JoinKind, JOIN_KINDS } from '../core/sql/sql.js';
-import { RelationIncludeOptions } from './relation-types.js';
-import { createJoinNode } from '../core/ast/join-node.js';
-import { getJoinRelationName } from '../core/ast/join-metadata.js';
-import { makeRelationAlias } from './relation-alias.js';
-import { buildDefaultPivotColumns } from './relation-utils.js';
-
-/**
- * Service for handling relation operations (joins, includes, etc.)
- */
-export class RelationService {
+import { RelationIncludeOptions } from './relation-types.js';
+import { createJoinNode } from '../core/ast/join-node.js';
+import { getJoinRelationName } from '../core/ast/join-metadata.js';
+import { makeRelationAlias } from './relation-alias.js';
+import { buildDefaultPivotColumns } from './relation-utils.js';
+
+type FilterTableCollector = {
+  tables: Set<string>;
+  hasSubquery: boolean;
+};
+
+type RelationWithForeignKey =
+  | HasManyRelation
+  | HasOneRelation
+  | BelongsToRelation;
+
+const hasRelationForeignKey = (relation: RelationDef): relation is RelationWithForeignKey =>
+  relation.type !== RelationKinds.BelongsToMany;
+
+/**
+ * Service for handling relation operations (joins, includes, etc.)
+ */
+export class RelationService {
   private readonly projectionHelper: RelationProjectionHelper;
 
   /**
@@ -55,14 +77,15 @@ export class RelationService {
    * @param extraCondition - Additional join condition
    * @returns Relation result with updated state and hydration
    */
-  joinRelation(
-    relationName: string,
-    joinKind: JoinKind,
-    extraCondition?: ExpressionNode
-  ): RelationResult {
-    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition);
-    return { state: nextState, hydration: this.hydration };
-  }
+  joinRelation(
+    relationName: string,
+    joinKind: JoinKind,
+    extraCondition?: ExpressionNode,
+    tableSource?: TableSourceNode
+  ): RelationResult {
+    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition, tableSource);
+    return { state: nextState, hydration: this.hydration };
+  }
 
   /**
    * Matches records based on a relation with an optional predicate
@@ -88,26 +111,73 @@ export class RelationService {
    * @param options - Options for relation inclusion
    * @returns Relation result with updated state and hydration
    */
-  include(relationName: string, options?: RelationIncludeOptions): RelationResult {
-    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;
-    }
-
-    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);
+  include(relationName: string, options?: RelationIncludeOptions): RelationResult {
+    let state = this.state;
+    let hydration = this.hydration;
+
+    const relation = this.getRelation(relationName);
+    const aliasPrefix = options?.aliasPrefix ?? relationName;
+    const alreadyJoined = state.ast.joins.some(j => getJoinRelationName(j) === relationName);
+    const { selfFilters, crossFilters } = this.splitFilterExpressions(
+      options?.filter,
+      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: TableNode | undefined;
+    if (canUseCte) {
+      const cteInfo = this.createFilteredRelationCte(state, relationName, relation, selfFilters);
+      state = cteInfo.state;
+      tableSourceOverride = cteInfo.table;
+    }
+
+    if (!alreadyJoined) {
+      state = this.withJoin(
+        state,
+        relationName,
+        options?.joinKind ?? JOIN_KINDS.LEFT,
+        joinCondition,
+        tableSourceOverride
+      );
+    }
+
+    const projectionResult = this.projectionHelper.ensureBaseProjection(state, hydration);
+    state = projectionResult.state;
+    hydration = projectionResult.hydration;
+
+    if (hasRelationForeignKey(relation)) {
+      const fkColumn = this.table.columns[relation.foreignKey];
+      if (fkColumn) {
+        const hasForeignKeySelected = state.ast.columns.some(col => {
+          if ((col as ColumnNode).type !== 'Column') return false;
+          const node = col as ColumnNode;
+          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: Record<string, ColumnDef>,
@@ -219,36 +289,52 @@ export class RelationService {
    * @param extraCondition - Additional join condition
    * @returns Updated query state with join
    */
-  private withJoin(
-    state: SelectQueryState,
-    relationName: string,
-    joinKind: JoinKind,
-    extraCondition?: ExpressionNode
-  ): SelectQueryState {
-    const relation = this.getRelation(relationName);
-    const rootAlias = state.ast.from.type === 'Table' ? state.ast.from.alias : undefined;
-    if (relation.type === RelationKinds.BelongsToMany) {
-      const joins = buildBelongsToManyJoins(
-        this.table,
-        relationName,
-        relation as BelongsToManyRelation,
-        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);
-  }
+  private withJoin(
+    state: SelectQueryState,
+    relationName: string,
+    joinKind: JoinKind,
+    extraCondition?: ExpressionNode,
+    tableSource?: TableSourceNode
+  ): SelectQueryState {
+    const relation = this.getRelation(relationName);
+    const rootAlias = state.ast.from.type === 'Table' ? state.ast.from.alias : undefined;
+    if (relation.type === RelationKinds.BelongsToMany) {
+      const targetTableSource: TableSourceNode = tableSource ?? {
+        type: 'Table',
+        name: relation.target.name,
+        schema: relation.target.schema
+      };
+      const targetName = this.resolveTargetTableName(targetTableSource, relation);
+      const joins = buildBelongsToManyJoins(
+        this.table,
+        relationName,
+        relation as BelongsToManyRelation,
+        joinKind,
+        extraCondition,
+        rootAlias,
+        targetTableSource,
+        targetName
+      );
+      return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
+    }
+
+    const targetTable: TableSourceNode = 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);
+  }
 
   /**
    * Selects columns for a relation
@@ -257,18 +343,236 @@ export class RelationService {
    * @param columns - Columns to select
    * @returns Relation result with updated state and hydration
    */
-  private selectColumns(
-    state: SelectQueryState,
-    hydration: HydrationManager,
-    columns: Record<string, ColumnDef>
-  ): RelationResult {
-    const { state: nextState, addedColumns } = this.astService(state).select(columns);
-    return {
-      state: nextState,
-      hydration: hydration.onColumnsSelected(nextState, addedColumns)
-    };
-  }
-
+  private selectColumns(
+    state: SelectQueryState,
+    hydration: HydrationManager,
+    columns: Record<string, ColumnDef>
+  ): RelationResult {
+    const { state: nextState, addedColumns } = this.astService(state).select(columns);
+    return {
+      state: nextState,
+      hydration: hydration.onColumnsSelected(nextState, addedColumns)
+    };
+  }
+
+
+  private combineWithAnd(expressions: ExpressionNode[]): ExpressionNode | undefined {
+    if (expressions.length === 0) return undefined;
+    if (expressions.length === 1) return expressions[0];
+    return {
+      type: 'LogicalExpression',
+      operator: 'AND',
+      operands: expressions
+    };
+  }
+
+  private splitFilterExpressions(
+    filter: ExpressionNode | undefined,
+    allowedTables: Set<string>
+  ): { selfFilters: ExpressionNode[]; crossFilters: ExpressionNode[] } {
+    const terms = this.flattenAnd(filter);
+    const selfFilters: ExpressionNode[] = [];
+    const crossFilters: ExpressionNode[] = [];
+
+    for (const term of terms) {
+      if (this.isExpressionSelfContained(term, allowedTables)) {
+        selfFilters.push(term);
+      } else {
+        crossFilters.push(term);
+      }
+    }
+
+    return { selfFilters, crossFilters };
+  }
+
+  private flattenAnd(node?: ExpressionNode): ExpressionNode[] {
+    if (!node) return [];
+    if (node.type === 'LogicalExpression' && node.operator === 'AND') {
+      return node.operands.flatMap(operand => this.flattenAnd(operand));
+    }
+    return [node];
+  }
+
+  private isExpressionSelfContained(expr: ExpressionNode, allowedTables: Set<string>): boolean {
+    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;
+  }
+
+  private collectReferencedTables(expr: ExpressionNode): FilterTableCollector {
+    const collector: FilterTableCollector = {
+      tables: new Set(),
+      hasSubquery: false
+    };
+    this.collectFromExpression(expr, collector);
+    return collector;
+  }
+
+  private collectFromExpression(expr: ExpressionNode, collector: FilterTableCollector): void {
+    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;
+    }
+  }
+
+  private collectFromOperand(node: OperandNode, collector: FilterTableCollector): void {
+    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;
+    }
+  }
+
+  private collectFromOrderingTerm(term: OrderingTerm, collector: FilterTableCollector): void {
+    if (isOperandNode(term)) {
+      this.collectFromOperand(term, collector);
+      return;
+    }
+    this.collectFromExpression(term, collector);
+  }
+
+  private createFilteredRelationCte(
+    state: SelectQueryState,
+    relationName: string,
+    relation: RelationDef,
+    filters: ExpressionNode[]
+  ): { state: SelectQueryState; table: TableNode } {
+    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: ColumnNode[] = Object.keys(relation.target.columns).map(name => ({
+      type: 'Column',
+      table: relation.target.name,
+      name
+    }));
+
+    const cteQuery: SelectQueryNode = {
+      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 tableNode: TableNode = {
+      type: 'Table',
+      name: cteName,
+      alias: relation.target.name
+    };
+
+    return { state: nextState, table: tableNode };
+  }
+
+  private generateUniqueCteName(state: SelectQueryState, relationName: string): string {
+    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;
+  }
+
+  private resolveTargetTableName(target: TableSourceNode, relation: RelationDef): string {
+    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
@@ -293,12 +597,12 @@ export class RelationService {
     return this.createQueryAstService(this.table, state);
   }
 
-  private rootTableName(): string {
-    const from = this.state.ast.from;
-    if (from.type === 'Table' && from.alias) return from.alias;
-    return this.table.name;
-  }
-}
-
-export type { RelationResult } from './relation-projection-helper.js';
+  private rootTableName(): string {
+    const from = this.state.ast.from;
+    if (from.type === 'Table' && from.alias) return from.alias;
+    return this.table.name;
+  }
+}
+
+export type { RelationResult } from './relation-projection-helper.js';
 

package/src/query-builder/relation-types.ts

@@ -9,8 +9,8 @@ export type RelationIncludeJoinKind = typeof JOIN_KINDS.LEFT | typeof JOIN_KINDS
 /**
  * Options for including a relation in a query
  */
-export interface RelationIncludeOptions {
-  columns?: string[];
+export interface RelationIncludeOptions {
+  columns?: readonly string[];
   aliasPrefix?: string;
   filter?: ExpressionNode;
   joinKind?: RelationIncludeJoinKind;