metal-orm 1.0.42 → 1.0.44

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

@@ -20,8 +20,8 @@ import {
 } 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 { 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';
 
@@ -70,17 +70,17 @@ export class RelationService {
    * @param predicate - Optional predicate expression
    * @returns Relation result with updated state and hydration
    */
-  match(
-    relationName: string,
-    predicate?: ExpressionNode
-  ): RelationResult {
-    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
-    const pk = findPrimaryKey(this.table);
-    const distinctCols: ColumnNode[] = [{ type: 'Column', table: this.rootTableName(), name: pk }];
-    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
-    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
-    return { state: nextState, hydration: joined.hydration };
-  }
+  match(
+    relationName: string,
+    predicate?: ExpressionNode
+  ): RelationResult {
+    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
+    const pk = findPrimaryKey(this.table);
+    const distinctCols: ColumnNode[] = [{ type: 'Column', table: this.rootTableName(), name: pk }];
+    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
+    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
+    return { state: nextState, hydration: joined.hydration };
+  }
 
   /**
    * Includes a relation in the query result
@@ -94,7 +94,7 @@ export class RelationService {
 
     const relation = this.getRelation(relationName);
     const aliasPrefix = options?.aliasPrefix ?? relationName;
-    const alreadyJoined = state.ast.joins.some(j => getJoinRelationName(j) === 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);
@@ -114,7 +114,7 @@ export class RelationService {
       prefix: string,
       keys: string[],
       missingMsg: (col: string) => string
-    ) : Record<string, ColumnDef> => {
+    ): Record<string, ColumnDef> => {
       return keys.reduce((acc, key) => {
         const def = columns[key];
         if (!def) {
@@ -190,22 +190,22 @@ export class RelationService {
    * @param ast - Query AST to modify
    * @returns Modified query AST with relation correlation
    */
-  applyRelationCorrelation(
-    relationName: string,
-    ast: SelectQueryNode,
-    additionalCorrelation?: ExpressionNode
-  ): SelectQueryNode {
-    const relation = this.getRelation(relationName);
-    const rootAlias = this.state.ast.from.type === 'Table' ? this.state.ast.from.alias : undefined;
-    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
-    if (additionalCorrelation) {
-      correlation = and(correlation, additionalCorrelation);
-    }
-    const whereInSubquery = ast.where
-      ? and(correlation, ast.where)
-      : correlation;
-
-    return {
+  applyRelationCorrelation(
+    relationName: string,
+    ast: SelectQueryNode,
+    additionalCorrelation?: ExpressionNode
+  ): SelectQueryNode {
+    const relation = this.getRelation(relationName);
+    const rootAlias = this.state.ast.from.type === 'Table' ? this.state.ast.from.alias : undefined;
+    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
+    if (additionalCorrelation) {
+      correlation = and(correlation, additionalCorrelation);
+    }
+    const whereInSubquery = ast.where
+      ? and(correlation, ast.where)
+      : correlation;
+
+    return {
       ...ast,
       where: whereInSubquery
     };
@@ -219,28 +219,33 @@ 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, relation.target.name, condition, relationName);
+  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);
   }
@@ -284,15 +289,15 @@ export class RelationService {
    * @param state - Current query state
    * @returns QueryAstService instance
    */
-  private astService(state: SelectQueryState = this.state): QueryAstService {
-    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;
-  }
-}
+  private astService(state: SelectQueryState = this.state): QueryAstService {
+    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';

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

@@ -2,6 +2,9 @@ import { BelongsToManyRelation } from '../schema/relation.js';
 
 /**
  * Builds a default set of pivot columns, excluding keys used for joins.
+ * @param rel - The BelongsToMany relation definition
+ * @param pivotPk - The primary key column name of the pivot table
+ * @returns Array of column names that can be included in pivot table selections
  */
 export const buildDefaultPivotColumns = (
   rel: BelongsToManyRelation,

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

@@ -0,0 +1,40 @@
+import { SelectQueryNode } from '../../core/ast/query.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for Common Table Expressions (WITH clauses)
+ */
+export class SelectCTEFacet {
+    /**
+     * Creates a new SelectCTEFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Adds a Common Table Expression to the query
+     * @param context - Current query context
+     * @param name - CTE name
+     * @param subAst - CTE query AST
+     * @param columns - Optional column names
+     * @param recursive - Whether the CTE is recursive
+     * @returns Updated query context with CTE
+     */
+    withCTE(
+        context: SelectQueryBuilderContext,
+        name: string,
+        subAst: SelectQueryNode,
+        columns: string[] | undefined,
+        recursive: boolean
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withCte(name, subAst, columns, recursive);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,80 @@
+import { SelectQueryNode } from '../../core/ast/query.js';
+import { OperandNode } from '../../core/ast/expression.js';
+import { derivedTable, fnTable } from '../../core/ast/builders.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for FROM clause operations
+ */
+export class SelectFromFacet {
+    /**
+     * Creates a new SelectFromFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Applies an alias to the FROM table
+     * @param context - Current query context
+     * @param alias - Alias to apply
+     * @returns Updated query context with aliased FROM
+     */
+    as(context: SelectQueryBuilderContext, alias: string): SelectQueryBuilderContext {
+        const from = context.state.ast.from;
+        if (from.type !== 'Table') {
+            throw new Error('Cannot alias non-table FROM sources');
+        }
+        const nextFrom = { ...from, alias };
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(nextFrom);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Sets the FROM clause to a subquery
+     * @param context - Current query context
+     * @param subAst - Subquery AST
+     * @param alias - Alias for the subquery
+     * @param columnAliases - Optional column aliases
+     * @returns Updated query context with subquery FROM
+     */
+    fromSubquery(
+        context: SelectQueryBuilderContext,
+        subAst: SelectQueryNode,
+        alias: string,
+        columnAliases?: string[]
+    ): SelectQueryBuilderContext {
+        const fromNode = derivedTable(subAst, alias, columnAliases);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(fromNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Sets the FROM clause to a function table
+     * @param context - Current query context
+     * @param name - Function name
+     * @param args - Function arguments
+     * @param alias - Optional alias for the function table
+     * @param options - Optional function table options
+     * @returns Updated query context with function table FROM
+     */
+    fromFunctionTable(
+        context: SelectQueryBuilderContext,
+        name: string,
+        args: OperandNode[],
+        alias?: string,
+        options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+    ): SelectQueryBuilderContext {
+        const functionTable = fnTable(name, args, alias, options);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(functionTable);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,62 @@
+import { TableDef } from '../../schema/table.js';
+import { BinaryExpressionNode } from '../../core/ast/expression.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+import { JoinKind } from '../../core/sql/sql.js';
+import { derivedTable, fnTable } from '../../core/ast/builders.js';
+import { createJoinNode } from '../../core/ast/join-node.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { OperandNode } from '../../core/ast/expression.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for JOIN operations
+ */
+export class SelectJoinFacet {
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    applyJoin(
+        context: SelectQueryBuilderContext,
+        table: TableDef,
+        condition: BinaryExpressionNode,
+        kind: JoinKind
+    ): SelectQueryBuilderContext {
+        const joinNode = createJoinNode(kind, { type: 'Table', name: table.name, schema: table.schema }, condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    joinSubquery(
+        context: SelectQueryBuilderContext,
+        subAst: SelectQueryNode,
+        alias: string,
+        condition: BinaryExpressionNode,
+        joinKind: JoinKind,
+        columnAliases?: string[]
+    ): SelectQueryBuilderContext {
+        const joinNode = createJoinNode(joinKind, derivedTable(subAst, alias, columnAliases), condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    joinFunctionTable(
+        context: SelectQueryBuilderContext,
+        name: string,
+        args: OperandNode[],
+        alias: string,
+        condition: BinaryExpressionNode,
+        joinKind: JoinKind,
+        options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+    ): SelectQueryBuilderContext {
+        const functionTable = fnTable(name, args, alias, options);
+        const joinNode = createJoinNode(joinKind, functionTable, condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,103 @@
+import { ColumnDef } from '../../schema/column.js';
+import { ExpressionNode } from '../../core/ast/expression.js';
+import { OrderingTerm } from '../../core/ast/query.js';
+import { OrderDirection } from '../../core/sql/sql.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for filtering and ordering operations
+ */
+export class SelectPredicateFacet {
+    /**
+     * Creates a new SelectPredicateFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Adds a WHERE condition to the query
+     * @param context - Current query context
+     * @param expr - WHERE expression
+     * @returns Updated query context with WHERE condition
+     */
+    where(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withWhere(expr);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds a GROUP BY clause to the query
+     * @param context - Current query context
+     * @param term - Column or ordering term to group by
+     * @returns Updated query context with GROUP BY clause
+     */
+    groupBy(context: SelectQueryBuilderContext, term: ColumnDef | OrderingTerm): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withGroupBy(term);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds a HAVING condition to the query
+     * @param context - Current query context
+     * @param expr - HAVING expression
+     * @returns Updated query context with HAVING condition
+     */
+    having(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withHaving(expr);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds an ORDER BY clause to the query
+     * @param context - Current query context
+     * @param term - Column or ordering term to order by
+     * @param direction - Order direction
+     * @param nulls - Nulls ordering
+     * @param collation - Collation
+     * @returns Updated query context with ORDER BY clause
+     */
+    orderBy(
+        context: SelectQueryBuilderContext,
+        term: ColumnDef | OrderingTerm,
+        direction: OrderDirection,
+        nulls?: 'FIRST' | 'LAST',
+        collation?: string
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withOrderBy(term, direction, nulls, collation);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds a LIMIT clause to the query
+     * @param context - Current query context
+     * @param n - Maximum number of rows
+     * @returns Updated query context with LIMIT clause
+     */
+    limit(context: SelectQueryBuilderContext, n: number): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withLimit(n);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds an OFFSET clause to the query
+     * @param context - Current query context
+     * @param n - Number of rows to skip
+     * @returns Updated query context with OFFSET clause
+     */
+    offset(context: SelectQueryBuilderContext, n: number): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withOffset(n);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,69 @@
+import { ColumnDef } from '../../schema/column.js';
+import { ColumnNode, FunctionNode, CaseExpressionNode, WindowFunctionNode } from '../../core/ast/expression.js';
+import { SelectQueryBuilderContext } from '../select-query-builder-deps.js';
+import { ColumnSelector } from '../column-selector.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+
+/**
+ * Facet responsible for projection operations (SELECT, DISTINCT, etc.)
+ */
+export class SelectProjectionFacet {
+    /**
+     * Creates a new SelectProjectionFacet instance
+     * @param columnSelector - Column selector dependency
+     */
+    constructor(private readonly columnSelector: ColumnSelector) { }
+
+    /**
+     * Selects columns for the query
+     * @param context - Current query context
+     * @param columns - Columns to select
+     * @returns Updated query context with selected columns
+     */
+    select(
+        context: SelectQueryBuilderContext,
+        columns: Record<string, ColumnSelectionValue>
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.select(context, columns).state };
+    }
+
+    /**
+     * Selects raw column expressions
+     * @param context - Current query context
+     * @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 };
+    }
+
+    /**
+     * Selects a subquery as a column
+     * @param context - Current query context
+     * @param alias - Alias for the subquery
+     * @param query - Subquery to select
+     * @returns Updated query context with subquery selection
+     */
+    selectSubquery(
+        context: SelectQueryBuilderContext,
+        alias: string,
+        query: SelectQueryNode
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.selectSubquery(context, alias, query).state };
+    }
+
+    /**
+     * Adds DISTINCT clause to the query
+     * @param context - Current query context
+     * @param cols - Columns to make distinct
+     * @returns Updated query context with DISTINCT clause
+     */
+    distinct(
+        context: SelectQueryBuilderContext,
+        cols: (ColumnDef | ColumnNode)[]
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.distinct(context, cols).state };
+    }
+}

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

@@ -0,0 +1,81 @@
+import { ExpressionNode } from '../../core/ast/expression.js';
+import { JoinKind } from '../../core/sql/sql.js';
+import { SelectQueryBuilderContext } from '../select-query-builder-deps.js';
+import { RelationManager } from '../relation-manager.js';
+import { RelationIncludeOptions } from '../relation-types.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+
+/**
+ * Facet responsible for relation operations (include, match, whereHas, etc.)
+ */
+export class SelectRelationFacet {
+    /**
+     * Creates a new SelectRelationFacet instance
+     * @param relationManager - Relation manager dependency
+     */
+    constructor(private readonly relationManager: RelationManager) { }
+
+    /**
+     * Matches records based on a relationship
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param predicate - Optional predicate
+     * @returns Updated query context with relation match
+     */
+    match(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        predicate?: ExpressionNode
+    ): SelectQueryBuilderContext {
+        return this.relationManager.match(context, relationName, predicate);
+    }
+
+    /**
+     * Joins a related table
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param joinKind - Type of join
+     * @param extraCondition - Optional additional condition
+     * @returns Updated query context with relation join
+     */
+    joinRelation(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        joinKind: JoinKind,
+        extraCondition?: ExpressionNode
+    ): SelectQueryBuilderContext {
+        return this.relationManager.joinRelation(context, relationName, joinKind, extraCondition);
+    }
+
+    /**
+     * Includes related data in the query results
+     * @param context - Current query context
+     * @param relationName - Name of the relationship to include
+     * @param options - Optional include options
+     * @returns Updated query context with relation inclusion
+     */
+    include(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        options?: RelationIncludeOptions
+    ): SelectQueryBuilderContext {
+        return this.relationManager.include(context, relationName, options);
+    }
+
+    /**
+     * Applies correlation for relation-based subqueries
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param subAst - Subquery AST
+     * @param extraCorrelate - Optional additional correlation
+     * @returns Modified subquery AST with correlation
+     */
+    applyRelationCorrelation(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        subAst: SelectQueryNode,
+        extraCorrelate?: ExpressionNode
+    ): SelectQueryNode {
+        return this.relationManager.applyRelationCorrelation(context, relationName, subAst, extraCorrelate);
+    }
+}

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

@@ -0,0 +1,36 @@
+import { SelectQueryNode, SetOperationKind } from '../../core/ast/query.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for set operations (UNION, INTERSECT, EXCEPT)
+ */
+export class SelectSetOpFacet {
+    /**
+     * Creates a new SelectSetOpFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Applies a set operation to the query
+     * @param context - Current query context
+     * @param operator - Set operation kind
+     * @param subAst - Subquery AST to combine
+     * @returns Updated query context with set operation
+     */
+    applySetOperation(
+        context: SelectQueryBuilderContext,
+        operator: SetOperationKind,
+        subAst: SelectQueryNode
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withSetOperation(operator, subAst);
+        return { state: nextState, hydration: context.hydration };
+    }
+}