metal-orm 1.0.57 → 1.0.59

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

@@ -1,35 +1,30 @@
 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 { SelectQueryState } from './select-query-state.js';
-import { HydrationManager } from './hydration-manager.js';
-import { QueryAstService } from './query-ast-service.js';
-import { findPrimaryKey } from './hydration-planner.js';
-import { RelationProjectionHelper } from './relation-projection-helper.js';
-import type { RelationResult } from './relation-projection-helper.js';
-import {
-  buildRelationJoinCondition,
-  buildRelationCorrelation,
-  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';
+import { RelationDef } from '../schema/relation.js';
+import { SelectQueryNode, TableSourceNode, TableNode } from '../core/ast/query.js';
+import { ColumnNode, ExpressionNode, and } 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';
+import { findPrimaryKey } from './hydration-planner.js';
+import { RelationProjectionHelper } from './relation-projection-helper.js';
+import type { RelationResult } from './relation-projection-helper.js';
+import { buildRelationCorrelation } from './relation-conditions.js';
+import { JoinKind, JOIN_KINDS } from '../core/sql/sql.js';
+import { RelationIncludeOptions } from './relation-types.js';
+import { getJoinRelationName } from '../core/ast/join-metadata.js';
+import { splitFilterExpressions } from './relation-filter-utils.js';
+import { RelationJoinPlanner } from './relation-join-planner.js';
+import { RelationCteBuilder } from './relation-cte-builder.js';
+import { relationIncludeStrategies } from './relation-include-strategies.js';
 
 /**
  * Service for handling relation operations (joins, includes, etc.)
  */
-export class RelationService {
-  private readonly projectionHelper: RelationProjectionHelper;
+export class RelationService {
+  private readonly projectionHelper: RelationProjectionHelper;
+  private readonly joinPlanner: RelationJoinPlanner;
+  private readonly cteBuilder: RelationCteBuilder;
 
   /**
    * Creates a new RelationService instance
@@ -42,11 +37,13 @@ export class RelationService {
     private readonly state: SelectQueryState,
     private readonly hydration: HydrationManager,
     private readonly createQueryAstService: (table: TableDef, state: SelectQueryState) => QueryAstService
-  ) {
-    this.projectionHelper = new RelationProjectionHelper(table, (state, hydration, columns) =>
-      this.selectColumns(state, hydration, columns)
-    );
-  }
+  ) {
+    this.projectionHelper = new RelationProjectionHelper(table, (state, hydration, columns) =>
+      this.selectColumns(state, hydration, columns)
+    );
+    this.joinPlanner = new RelationJoinPlanner(table, createQueryAstService);
+    this.cteBuilder = new RelationCteBuilder(table, createQueryAstService);
+  }
 
   /**
    * Joins a relation to the query
@@ -58,11 +55,20 @@ export class RelationService {
   joinRelation(
     relationName: string,
     joinKind: JoinKind,
-    extraCondition?: ExpressionNode
-  ): RelationResult {
-    const nextState = this.withJoin(this.state, relationName, joinKind, extraCondition);
-    return { state: nextState, hydration: this.hydration };
-  }
+    extraCondition?: ExpressionNode,
+    tableSource?: TableSourceNode
+  ): RelationResult {
+    const relation = this.getRelation(relationName);
+    const nextState = this.joinPlanner.withJoin(
+      this.state,
+      relationName,
+      relation,
+      joinKind,
+      extraCondition,
+      tableSource
+    );
+    return { state: nextState, hydration: this.hydration };
+  }
 
   /**
    * Matches records based on a relation with an optional predicate
@@ -95,94 +101,60 @@ export class RelationService {
     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 { selfFilters, crossFilters } = 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 predicate = this.combineWithAnd(selfFilters);
+      const cteInfo = this.cteBuilder.createFilteredRelationCte(
+        state,
+        relationName,
+        relation,
+        predicate
+      );
+      state = cteInfo.state;
+      tableSourceOverride = cteInfo.table;
+    }
+
+    if (!alreadyJoined) {
+      state = this.joinPlanner.withJoin(
+        state,
+        relationName,
+        relation,
+        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);
-
-    const buildTypedSelection = (
-      columns: Record<string, ColumnDef>,
-      prefix: string,
-      keys: string[],
-      missingMsg: (col: string) => string
-    ): Record<string, ColumnDef> => {
-      return keys.reduce((acc, key) => {
-        const def = columns[key];
-        if (!def) {
-          throw new Error(missingMsg(key));
-        }
-        acc[makeRelationAlias(prefix, key)] = def;
-        return acc;
-      }, {} as Record<string, ColumnDef>);
-    };
-
-    const targetSelection = buildTypedSelection(
-      relation.target.columns as Record<string, ColumnDef>,
-      aliasPrefix,
-      targetColumns,
-      key => `Column '${key}' not found on relation '${relationName}'`
-    );
-
-    if (relation.type !== RelationKinds.BelongsToMany) {
-      const relationSelectionResult = this.selectColumns(state, hydration, targetSelection);
-      state = relationSelectionResult.state;
-      hydration = relationSelectionResult.hydration;
-
-      hydration = hydration.onRelationIncluded(
-        state,
-        relation,
-        relationName,
-        aliasPrefix,
-        targetColumns
-      );
-
-      return { state, hydration };
-    }
-
-    const many = relation as BelongsToManyRelation;
-    const pivotAliasPrefix = options?.pivot?.aliasPrefix ?? `${aliasPrefix}_pivot`;
-    const pivotPk = many.pivotPrimaryKey || findPrimaryKey(many.pivotTable);
-    const pivotColumns =
-      options?.pivot?.columns ??
-      many.defaultPivotColumns ??
-      buildDefaultPivotColumns(many, pivotPk);
-
-    const pivotSelection = buildTypedSelection(
-      many.pivotTable.columns as Record<string, ColumnDef>,
-      pivotAliasPrefix,
-      pivotColumns,
-      key => `Column '${key}' not found on pivot table '${many.pivotTable.name}'`
-    );
-
-    const combinedSelection = {
-      ...targetSelection,
-      ...pivotSelection
-    };
-
-    const relationSelectionResult = this.selectColumns(state, hydration, combinedSelection);
-    state = relationSelectionResult.state;
-    hydration = relationSelectionResult.hydration;
-
-    hydration = hydration.onRelationIncluded(
-      state,
-      relation,
-      relationName,
-      aliasPrefix,
-      targetColumns,
-      { aliasPrefix: pivotAliasPrefix, columns: pivotColumns }
-    );
-
-    return { state, hydration };
-  }
+    const strategy = relationIncludeStrategies[relation.type];
+    const result = strategy({
+      rootTable: this.table,
+      state,
+      hydration,
+      relation,
+      relationName,
+      aliasPrefix,
+      options,
+      selectColumns: (nextState, nextHydration, columns) =>
+        this.selectColumns(nextState, nextHydration, columns)
+    });
+
+    return { state: result.state, hydration: result.hydration };
+  }
 
   /**
    * Applies relation correlation to a query AST
@@ -211,47 +183,8 @@ export class RelationService {
     };
   }
 
-  /**
-   * Creates a join node for a relation
-   * @param state - Current query state
-   * @param relationName - Name of the relation
-   * @param joinKind - Type of join to use
-   * @param extraCondition - Additional join condition
-   * @returns Updated query state with join
-   */
-  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);
-  }
-
-  /**
-   * Selects columns for a relation
+  /**
+   * Selects columns for a relation
    * @param state - Current query state
    * @param hydration - Hydration manager
    * @param columns - Columns to select
@@ -269,6 +202,17 @@ export class RelationService {
     };
   }
 
+
+  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
+    };
+  }
+
   /**
    * Gets a relation definition by name
    * @param relationName - Name of the relation

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

@@ -1,5 +1,8 @@
-import { ExpressionNode } from '../core/ast/expression.js';
-import { JOIN_KINDS } from '../core/sql/sql.js';
+import { ExpressionNode } from '../core/ast/expression.js';
+import { JOIN_KINDS } from '../core/sql/sql.js';
+import { TableDef } from '../schema/table.js';
+import { BelongsToManyRelation, RelationDef } from '../schema/relation.js';
+import { RelationTargetTable } from '../schema/types.js';
 
 /**
  * Join kinds allowed when including a relation using `.include(...)`.
@@ -9,13 +12,41 @@ export type RelationIncludeJoinKind = typeof JOIN_KINDS.LEFT | typeof JOIN_KINDS
 /**
  * Options for including a relation in a query
  */
-export interface RelationIncludeOptions {
-  columns?: string[];
-  aliasPrefix?: string;
-  filter?: ExpressionNode;
-  joinKind?: RelationIncludeJoinKind;
-  pivot?: {
-    columns?: string[];
-    aliasPrefix?: string;
-  };
-}
+export interface RelationIncludeOptions {
+  columns?: readonly string[];
+  aliasPrefix?: string;
+  filter?: ExpressionNode;
+  joinKind?: RelationIncludeJoinKind;
+  pivot?: {
+    columns?: readonly string[];
+    aliasPrefix?: string;
+  };
+}
+
+type ColumnKeys<T> =
+  T extends { columns: infer Columns }
+    ? keyof Columns & string
+    : string;
+
+type PivotColumnKeys<TPivot> = ColumnKeys<TPivot> extends never ? string : ColumnKeys<TPivot>;
+
+export type RelationTargetColumns<TRel extends RelationDef> =
+  ColumnKeys<RelationTargetTable<TRel>>;
+
+export type BelongsToManyPivotColumns<TRel extends RelationDef> =
+  TRel extends BelongsToManyRelation<TableDef, infer TPivot>
+    ? PivotColumnKeys<TPivot>
+    : never;
+
+export type TypedRelationIncludeOptions<TRel extends RelationDef> =
+  TRel extends BelongsToManyRelation
+    ? Omit<RelationIncludeOptions, 'columns' | 'pivot'> & {
+        columns?: readonly RelationTargetColumns<TRel>[];
+        pivot?: {
+          columns?: readonly BelongsToManyPivotColumns<TRel>[];
+          aliasPrefix?: string;
+        };
+      }
+    : Omit<RelationIncludeOptions, 'columns' | 'pivot'> & {
+        columns?: readonly RelationTargetColumns<TRel>[];
+      };

package/src/query-builder/select/projection-facet.ts

@@ -22,12 +22,12 @@ export class SelectProjectionFacet {
      * @param columns - Columns to select
      * @returns Updated query context with selected columns
      */
-    select(
-        context: SelectQueryBuilderContext,
-        columns: Record<string, ColumnSelectionValue>
-    ): SelectQueryBuilderContext {
-        return { ...context, state: this.columnSelector.select(context, columns).state };
-    }
+    select(
+        context: SelectQueryBuilderContext,
+        columns: Record<string, ColumnSelectionValue>
+    ): SelectQueryBuilderContext {
+        return this.columnSelector.select(context, columns);
+    }
 
     /**
      * Selects raw column expressions
@@ -35,9 +35,9 @@ export class SelectProjectionFacet {
      * @param cols - Raw column expressions
      * @returns Updated query context with raw column selections
      */
-    selectRaw(context: SelectQueryBuilderContext, cols: string[]): SelectQueryBuilderContext {
-        return { ...context, state: this.columnSelector.selectRaw(context, cols).state };
-    }
+    selectRaw(context: SelectQueryBuilderContext, cols: string[]): SelectQueryBuilderContext {
+        return this.columnSelector.selectRaw(context, cols);
+    }
 
     /**
      * Selects a subquery as a column
@@ -46,13 +46,13 @@ export class SelectProjectionFacet {
      * @param query - Subquery to select
      * @returns Updated query context with subquery selection
      */
-    selectSubquery(
-        context: SelectQueryBuilderContext,
-        alias: string,
-        query: SelectQueryNode
-    ): SelectQueryBuilderContext {
-        return { ...context, state: this.columnSelector.selectSubquery(context, alias, query).state };
-    }
+    selectSubquery(
+        context: SelectQueryBuilderContext,
+        alias: string,
+        query: SelectQueryNode
+    ): SelectQueryBuilderContext {
+        return this.columnSelector.selectSubquery(context, alias, query);
+    }
 
     /**
      * Adds DISTINCT clause to the query
@@ -60,11 +60,11 @@ export class SelectProjectionFacet {
      * @param cols - Columns to make distinct
      * @returns Updated query context with DISTINCT clause
      */
-    distinct(
-        context: SelectQueryBuilderContext,
-        cols: (ColumnDef | ColumnNode)[]
-    ): SelectQueryBuilderContext {
-        return { ...context, state: this.columnSelector.distinct(context, cols).state };
-    }
-}
+    distinct(
+        context: SelectQueryBuilderContext,
+        cols: (ColumnDef | ColumnNode)[]
+    ): SelectQueryBuilderContext {
+        return this.columnSelector.distinct(context, cols);
+    }
+}
 

package/src/query-builder/select/select-operations.ts

@@ -0,0 +1,145 @@
+import { TableDef } from '../../schema/table.js';
+import { ColumnDef } from '../../schema/column-types.js';
+import { OrderingTerm, SelectQueryNode } from '../../core/ast/query.js';
+import { FunctionNode, ExpressionNode, exists, notExists } from '../../core/ast/expression.js';
+import { derivedTable } from '../../core/ast/builders.js';
+import { SelectQueryState } from '../select-query-state.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { SelectPredicateFacet } from './predicate-facet.js';
+import { SelectRelationFacet } from './relation-facet.js';
+import { ORDER_DIRECTIONS, OrderDirection } from '../../core/sql/sql.js';
+import { OrmSession } from '../../orm/orm-session.js';
+import { EntityInstance } from '../../schema/types.js';
+import type { SelectQueryBuilder } from '../select.js';
+
+export type WhereHasOptions = {
+  correlate?: ExpressionNode;
+};
+
+export type RelationCallback = <TChildTable extends TableDef>(
+  qb: SelectQueryBuilder<unknown, TChildTable>
+) => SelectQueryBuilder<unknown, TChildTable>;
+
+type ChildBuilderFactory = <R, TChild extends TableDef>(table: TChild) => SelectQueryBuilder<R, TChild>;
+
+/**
+ * Builds a new query context with an ORDER BY clause applied.
+ */
+export function applyOrderBy(
+  context: SelectQueryBuilderContext,
+  predicateFacet: SelectPredicateFacet,
+  term: ColumnDef | OrderingTerm,
+  directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string }
+): SelectQueryBuilderContext {
+  const options =
+    typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
+  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
+  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
+}
+
+/**
+ * Runs the count query for the provided context and session.
+ */
+export async function executeCount(
+  context: SelectQueryBuilderContext,
+  env: SelectQueryBuilderEnvironment,
+  session: OrmSession
+): Promise<number> {
+  const unpagedAst: SelectQueryNode = {
+    ...context.state.ast,
+    orderBy: undefined,
+    limit: undefined,
+    offset: undefined
+  };
+
+  const nextState = new SelectQueryState(env.table as TableDef, unpagedAst);
+  const nextContext: SelectQueryBuilderContext = {
+    ...context,
+    state: nextState
+  };
+
+  const subAst = nextContext.hydration.applyToAst(nextState.ast);
+  const countQuery: SelectQueryNode = {
+    type: 'SelectQuery',
+    from: derivedTable(subAst, '__metal_count'),
+    columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
+    joins: []
+  };
+
+  const execCtx = session.getExecutionContext();
+  const compiled = execCtx.dialect.compileSelect(countQuery);
+  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const value = results[0]?.values?.[0]?.[0];
+
+  if (typeof value === 'number') return value;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'string') return Number(value);
+  return value === null || value === undefined ? 0 : Number(value);
+}
+
+/**
+ * Executes paged queries using the provided builder helpers.
+ */
+export async function executePagedQuery<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  session: OrmSession,
+  options: { page: number; pageSize: number },
+  countCallback: (session: OrmSession) => Promise<number>
+): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
+  const { page, pageSize } = options;
+
+  if (!Number.isInteger(page) || page < 1) {
+    throw new Error('executePaged: page must be an integer >= 1');
+  }
+  if (!Number.isInteger(pageSize) || pageSize < 1) {
+    throw new Error('executePaged: pageSize must be an integer >= 1');
+  }
+
+  const offset = (page - 1) * pageSize;
+
+  const [items, totalItems] = await Promise.all([
+    builder.limit(pageSize).offset(offset).execute(session),
+    countCallback(session)
+  ]);
+
+  return { items, totalItems };
+}
+
+/**
+ * Builds an EXISTS or NOT EXISTS predicate for a related table.
+ */
+export function buildWhereHasPredicate<TTable extends TableDef>(
+  env: SelectQueryBuilderEnvironment,
+  context: SelectQueryBuilderContext,
+  relationFacet: SelectRelationFacet,
+  createChildBuilder: ChildBuilderFactory,
+  relationName: keyof TTable['relations'] & string,
+  callbackOrOptions?: RelationCallback | WhereHasOptions,
+  maybeOptions?: WhereHasOptions,
+  negate = false
+): ExpressionNode {
+  const relation = env.table.relations[relationName as string];
+  if (!relation) {
+    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
+  }
+
+  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
+  const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as
+    | WhereHasOptions
+    | undefined;
+
+  let subQb = createChildBuilder<unknown, TableDef>(relation.target);
+  if (callback) {
+    subQb = callback(subQb);
+  }
+
+  const subAst = subQb.getAST();
+  const finalSubAst = relationFacet.applyRelationCorrelation(
+    context,
+    relationName,
+    subAst,
+    options?.correlate
+  );
+
+  return negate ? notExists(finalSubAst) : exists(finalSubAst);
+}