metal-orm 1.0.12 → 1.0.13

package/dist/{select-BKlr2ivY.d.cts → select-CCp1oz9p.d.cts}

@@ -721,6 +721,20 @@ interface CommonTableExpressionNode {
     /** Whether the CTE is recursive */
     recursive: boolean;
 }
+/**
+ * Supported set operation kinds for compound SELECT queries
+ */
+type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
+/**
+ * AST node representing a set operation (UNION, INTERSECT, etc.)
+ */
+interface SetOperationNode {
+    type: 'SetOperation';
+    /** Operator to combine queries */
+    operator: SetOperationKind;
+    /** Right-hand query in the compound expression */
+    query: SelectQueryNode;
+}
 /**
  * AST node representing a complete SELECT query
  */
@@ -750,6 +764,8 @@ interface SelectQueryNode {
     meta?: QueryMetadata;
     /** Optional DISTINCT clause */
     distinct?: ColumnNode[];
+    /** Optional set operations chaining this query with others */
+    setOps?: SetOperationNode[];
 }
 interface InsertQueryNode {
     type: 'InsertQuery';
@@ -832,6 +848,7 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     compileInsert(ast: InsertQueryNode): CompiledQuery;
     compileUpdate(ast: UpdateQueryNode): CompiledQuery;
     compileDelete(ast: DeleteQueryNode): CompiledQuery;
+    supportsReturning(): boolean;
     /**
      * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
      * @param ast - Query AST
@@ -877,6 +894,31 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Formatted placeholder string
      */
     protected formatPlaceholder(index: number): string;
+    /**
+     * Whether the current dialect supports a given set operation.
+     * Override in concrete dialects to restrict support.
+     */
+    protected supportsSetOperation(kind: SetOperationKind): boolean;
+    /**
+     * Validates set-operation semantics:
+     * - Ensures the dialect supports requested operators.
+     * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
+     * @param ast - Query to validate
+     * @param isOutermost - Whether this node is the outermost compound query
+     */
+    protected validateSetOperations(ast: SelectQueryNode, isOutermost?: boolean): void;
+    /**
+     * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
+     * @param ast - Query AST
+     * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
+     */
+    private hoistCtes;
+    /**
+     * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+     * @param ast - Query AST
+     * @returns Normalized query AST
+     */
+    protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode;
     private readonly expressionCompilers;
     private readonly operandCompilers;
     protected constructor();
@@ -999,6 +1041,12 @@ declare class SelectQueryState {
      * @returns New SelectQueryState with CTE
      */
     withCte(cte: CommonTableExpressionNode): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/INTERSECT/EXCEPT) to the query
+     * @param op - Set operation node to add
+     * @returns New SelectQueryState with set operation
+     */
+    withSetOperation(op: SetOperationNode): SelectQueryState;
 }
 
 /**
@@ -1101,6 +1149,31 @@ declare class HydrationManager {
      * @returns Hydration plan or undefined if none exists
      */
     getPlan(): HydrationPlan | undefined;
+    /**
+     * Attaches hydration metadata to a query AST node.
+     */
+    private attachHydrationMeta;
+    /**
+     * Determines whether the query needs pagination rewriting to keep LIMIT/OFFSET
+     * applied to parent rows when eager-loading multiplicative relations.
+     */
+    private requiresParentPagination;
+    private hasMultiplyingRelations;
+    /**
+     * Rewrites the query using CTEs so LIMIT/OFFSET target distinct parent rows
+     * instead of the joined result set.
+     *
+     * The strategy:
+     * - Hoist the original query (minus limit/offset) into a base CTE.
+     * - Select distinct parent ids from that base CTE with the original ordering and pagination.
+     * - Join the base CTE against the paged ids to retrieve the joined rows for just that page.
+     */
+    private wrapForParentPagination;
+    private nextCteName;
+    private getProjectionNames;
+    private buildProjectionAliasMap;
+    private mapOrderBy;
+    private buildPagingColumns;
 }
 
 /**
@@ -1149,6 +1222,13 @@ declare class QueryAstService {
      * @returns Updated query state with CTE
      */
     withCte(name: string, query: SelectQueryNode, columns?: string[], recursive?: boolean): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/UNION ALL/INTERSECT/EXCEPT) to the query
+     * @param operator - Set operator
+     * @param query - Right-hand side query
+     * @returns Updated query state with set operation
+     */
+    withSetOperation(operator: SetOperationKind, query: SelectQueryNode): SelectQueryState;
     /**
      * Selects a subquery as a column
      * @param alias - Alias for the subquery
@@ -1408,6 +1488,12 @@ interface HasDomainEvents {
 type DomainEventHandler$1<Context> = (event: any, ctx: Context) => Promise<void> | void;
 declare const addDomainEvent: (entity: HasDomainEvents, event: any) => void;
 
+interface QueryLogEntry {
+    sql: string;
+    params?: unknown[];
+}
+type QueryLogger = (entry: QueryLogEntry) => void;
+
 interface OrmInterceptor {
     beforeFlush?(ctx: OrmContext): Promise<void> | void;
     afterFlush?(ctx: OrmContext): Promise<void> | void;
@@ -1418,10 +1504,12 @@ interface OrmContextOptions {
     executor: DbExecutor;
     interceptors?: OrmInterceptor[];
     domainEventHandlers?: Record<string, DomainEventHandler[]>;
+    queryLogger?: QueryLogger;
 }
 declare class OrmContext {
     private readonly options;
     private readonly identityMap;
+    private readonly executorWithLogging;
     private readonly unitOfWork;
     private readonly relationChanges;
     private readonly interceptors;
@@ -1468,6 +1556,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
     private createChildBuilder;
     private applyAst;
     private applyJoin;
+    private applySetOperation;
     /**
      * Selects specific columns for the query
      * @param columns - Record of column definitions, function nodes, case expressions, or window functions
@@ -1593,6 +1682,30 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the OFFSET clause
      */
     offset(n: number): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    union(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION ALL
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    unionAll(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using INTERSECT
+     * @param query - Query to intersect with
+     * @returns New query builder instance with the set operation
+     */
+    intersect(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using EXCEPT
+     * @param query - Query to subtract
+     * @returns New query builder instance with the set operation
+     */
+    except(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a WHERE EXISTS condition to the query
      * @param subquery - Subquery to check for existence
@@ -1656,4 +1769,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-export { type RelationType as $, type CheckConstraint as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type TableOptions as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type TableHooks as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, defineTable as P, type ColumnType as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, type ReferentialAction as V, type WindowFunctionNode as W, type RawDefaultValue as X, type DefaultValue as Y, col as Z, RelationKinds as _, type ColumnNode as a, type CascadeMode as a0, type RelationDef as a1, hasMany as a2, belongsTo as a3, belongsToMany as a4, type ColumnToTs as a5, type InferRow as a6, createColumn as a7, createLiteral as a8, isOperandNode as a9, isFunctionNode as aa, isCaseExpressionNode as ab, isWindowFunctionNode as ac, isExpressionSelectionNode as ad, addDomainEvent as ae, EntityStatus as af, type QueryResult as ag, type RelationKey as ah, type RelationChange as ai, type HasDomainEvents as aj, type OrmInterceptor as ak, type DomainEventHandler as al, type OrmContextOptions as am, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, type ForeignKeyReference as o, type IndexColumn as p, type IndexDef as q, type DbExecutor as r, OrmContext as s, type Entity as t, type HasManyRelation as u, type BelongsToRelation as v, type BelongsToManyRelation as w, type HasManyCollection as x, type BelongsToReference as y, SelectQueryBuilder as z };
+export { type RelationType as $, type CheckConstraint as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type TableOptions as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type TableHooks as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, defineTable as P, type ColumnType as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, type ReferentialAction as V, type WindowFunctionNode as W, type RawDefaultValue as X, type DefaultValue as Y, col as Z, RelationKinds as _, type ColumnNode as a, type CascadeMode as a0, type RelationDef as a1, hasMany as a2, belongsTo as a3, belongsToMany as a4, type ColumnToTs as a5, type InferRow as a6, createColumn as a7, createLiteral as a8, isOperandNode as a9, isFunctionNode as aa, isCaseExpressionNode as ab, isWindowFunctionNode as ac, isExpressionSelectionNode as ad, addDomainEvent as ae, EntityStatus as af, type QueryResult as ag, type RelationKey as ah, type RelationChange as ai, type HasDomainEvents as aj, type OrmInterceptor as ak, type DomainEventHandler as al, type OrmContextOptions as am, type QueryLogEntry as an, type QueryLogger as ao, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, type ForeignKeyReference as o, type IndexColumn as p, type IndexDef as q, type DbExecutor as r, OrmContext as s, type Entity as t, type HasManyRelation as u, type BelongsToRelation as v, type BelongsToManyRelation as w, type HasManyCollection as x, type BelongsToReference as y, SelectQueryBuilder as z };

package/dist/{select-BKlr2ivY.d.ts → select-CCp1oz9p.d.ts}

@@ -721,6 +721,20 @@ interface CommonTableExpressionNode {
     /** Whether the CTE is recursive */
     recursive: boolean;
 }
+/**
+ * Supported set operation kinds for compound SELECT queries
+ */
+type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
+/**
+ * AST node representing a set operation (UNION, INTERSECT, etc.)
+ */
+interface SetOperationNode {
+    type: 'SetOperation';
+    /** Operator to combine queries */
+    operator: SetOperationKind;
+    /** Right-hand query in the compound expression */
+    query: SelectQueryNode;
+}
 /**
  * AST node representing a complete SELECT query
  */
@@ -750,6 +764,8 @@ interface SelectQueryNode {
     meta?: QueryMetadata;
     /** Optional DISTINCT clause */
     distinct?: ColumnNode[];
+    /** Optional set operations chaining this query with others */
+    setOps?: SetOperationNode[];
 }
 interface InsertQueryNode {
     type: 'InsertQuery';
@@ -832,6 +848,7 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     compileInsert(ast: InsertQueryNode): CompiledQuery;
     compileUpdate(ast: UpdateQueryNode): CompiledQuery;
     compileDelete(ast: DeleteQueryNode): CompiledQuery;
+    supportsReturning(): boolean;
     /**
      * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
      * @param ast - Query AST
@@ -877,6 +894,31 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Formatted placeholder string
      */
     protected formatPlaceholder(index: number): string;
+    /**
+     * Whether the current dialect supports a given set operation.
+     * Override in concrete dialects to restrict support.
+     */
+    protected supportsSetOperation(kind: SetOperationKind): boolean;
+    /**
+     * Validates set-operation semantics:
+     * - Ensures the dialect supports requested operators.
+     * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
+     * @param ast - Query to validate
+     * @param isOutermost - Whether this node is the outermost compound query
+     */
+    protected validateSetOperations(ast: SelectQueryNode, isOutermost?: boolean): void;
+    /**
+     * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
+     * @param ast - Query AST
+     * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
+     */
+    private hoistCtes;
+    /**
+     * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+     * @param ast - Query AST
+     * @returns Normalized query AST
+     */
+    protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode;
     private readonly expressionCompilers;
     private readonly operandCompilers;
     protected constructor();
@@ -999,6 +1041,12 @@ declare class SelectQueryState {
      * @returns New SelectQueryState with CTE
      */
     withCte(cte: CommonTableExpressionNode): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/INTERSECT/EXCEPT) to the query
+     * @param op - Set operation node to add
+     * @returns New SelectQueryState with set operation
+     */
+    withSetOperation(op: SetOperationNode): SelectQueryState;
 }
 
 /**
@@ -1101,6 +1149,31 @@ declare class HydrationManager {
      * @returns Hydration plan or undefined if none exists
      */
     getPlan(): HydrationPlan | undefined;
+    /**
+     * Attaches hydration metadata to a query AST node.
+     */
+    private attachHydrationMeta;
+    /**
+     * Determines whether the query needs pagination rewriting to keep LIMIT/OFFSET
+     * applied to parent rows when eager-loading multiplicative relations.
+     */
+    private requiresParentPagination;
+    private hasMultiplyingRelations;
+    /**
+     * Rewrites the query using CTEs so LIMIT/OFFSET target distinct parent rows
+     * instead of the joined result set.
+     *
+     * The strategy:
+     * - Hoist the original query (minus limit/offset) into a base CTE.
+     * - Select distinct parent ids from that base CTE with the original ordering and pagination.
+     * - Join the base CTE against the paged ids to retrieve the joined rows for just that page.
+     */
+    private wrapForParentPagination;
+    private nextCteName;
+    private getProjectionNames;
+    private buildProjectionAliasMap;
+    private mapOrderBy;
+    private buildPagingColumns;
 }
 
 /**
@@ -1149,6 +1222,13 @@ declare class QueryAstService {
      * @returns Updated query state with CTE
      */
     withCte(name: string, query: SelectQueryNode, columns?: string[], recursive?: boolean): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/UNION ALL/INTERSECT/EXCEPT) to the query
+     * @param operator - Set operator
+     * @param query - Right-hand side query
+     * @returns Updated query state with set operation
+     */
+    withSetOperation(operator: SetOperationKind, query: SelectQueryNode): SelectQueryState;
     /**
      * Selects a subquery as a column
      * @param alias - Alias for the subquery
@@ -1408,6 +1488,12 @@ interface HasDomainEvents {
 type DomainEventHandler$1<Context> = (event: any, ctx: Context) => Promise<void> | void;
 declare const addDomainEvent: (entity: HasDomainEvents, event: any) => void;
 
+interface QueryLogEntry {
+    sql: string;
+    params?: unknown[];
+}
+type QueryLogger = (entry: QueryLogEntry) => void;
+
 interface OrmInterceptor {
     beforeFlush?(ctx: OrmContext): Promise<void> | void;
     afterFlush?(ctx: OrmContext): Promise<void> | void;
@@ -1418,10 +1504,12 @@ interface OrmContextOptions {
     executor: DbExecutor;
     interceptors?: OrmInterceptor[];
     domainEventHandlers?: Record<string, DomainEventHandler[]>;
+    queryLogger?: QueryLogger;
 }
 declare class OrmContext {
     private readonly options;
     private readonly identityMap;
+    private readonly executorWithLogging;
     private readonly unitOfWork;
     private readonly relationChanges;
     private readonly interceptors;
@@ -1468,6 +1556,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
     private createChildBuilder;
     private applyAst;
     private applyJoin;
+    private applySetOperation;
     /**
      * Selects specific columns for the query
      * @param columns - Record of column definitions, function nodes, case expressions, or window functions
@@ -1593,6 +1682,30 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the OFFSET clause
      */
     offset(n: number): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    union(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION ALL
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    unionAll(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using INTERSECT
+     * @param query - Query to intersect with
+     * @returns New query builder instance with the set operation
+     */
+    intersect(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using EXCEPT
+     * @param query - Query to subtract
+     * @returns New query builder instance with the set operation
+     */
+    except(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a WHERE EXISTS condition to the query
      * @param subquery - Subquery to check for existence
@@ -1656,4 +1769,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-export { type RelationType as $, type CheckConstraint as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type TableOptions as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type TableHooks as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, defineTable as P, type ColumnType as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, type ReferentialAction as V, type WindowFunctionNode as W, type RawDefaultValue as X, type DefaultValue as Y, col as Z, RelationKinds as _, type ColumnNode as a, type CascadeMode as a0, type RelationDef as a1, hasMany as a2, belongsTo as a3, belongsToMany as a4, type ColumnToTs as a5, type InferRow as a6, createColumn as a7, createLiteral as a8, isOperandNode as a9, isFunctionNode as aa, isCaseExpressionNode as ab, isWindowFunctionNode as ac, isExpressionSelectionNode as ad, addDomainEvent as ae, EntityStatus as af, type QueryResult as ag, type RelationKey as ah, type RelationChange as ai, type HasDomainEvents as aj, type OrmInterceptor as ak, type DomainEventHandler as al, type OrmContextOptions as am, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, type ForeignKeyReference as o, type IndexColumn as p, type IndexDef as q, type DbExecutor as r, OrmContext as s, type Entity as t, type HasManyRelation as u, type BelongsToRelation as v, type BelongsToManyRelation as w, type HasManyCollection as x, type BelongsToReference as y, SelectQueryBuilder as z };
+export { type RelationType as $, type CheckConstraint as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type TableOptions as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type TableHooks as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, defineTable as P, type ColumnType as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, type ReferentialAction as V, type WindowFunctionNode as W, type RawDefaultValue as X, type DefaultValue as Y, col as Z, RelationKinds as _, type ColumnNode as a, type CascadeMode as a0, type RelationDef as a1, hasMany as a2, belongsTo as a3, belongsToMany as a4, type ColumnToTs as a5, type InferRow as a6, createColumn as a7, createLiteral as a8, isOperandNode as a9, isFunctionNode as aa, isCaseExpressionNode as ab, isWindowFunctionNode as ac, isExpressionSelectionNode as ad, addDomainEvent as ae, EntityStatus as af, type QueryResult as ag, type RelationKey as ah, type RelationChange as ai, type HasDomainEvents as aj, type OrmInterceptor as ak, type DomainEventHandler as al, type OrmContextOptions as am, type QueryLogEntry as an, type QueryLogger as ao, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, type ForeignKeyReference as o, type IndexColumn as p, type IndexDef as q, type DbExecutor as r, OrmContext as s, type Entity as t, type HasManyRelation as u, type BelongsToRelation as v, type BelongsToManyRelation as w, type HasManyCollection as x, type BelongsToReference as y, SelectQueryBuilder as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,8 @@
     "build": "tsup",
     "check": "tsc --noEmit",
     "test": "vitest",
-    "test:ui": "vitest --ui"
+    "test:ui": "vitest --ui",
+    "show-sql": "node scripts/show-sql.mjs"
   },
   "peerDependencies": {
     "mysql2": "^3.9.0",

package/src/core/ast/query.ts

@@ -94,23 +94,39 @@ export interface QueryMetadata {
 /**
  * AST node representing a Common Table Expression (CTE)
  */
-export interface CommonTableExpressionNode {
-  type: 'CommonTableExpression';
-  /** CTE name */
-  name: string;
-  /** Optional column names */
-  columns?: string[];
-  /** CTE query */
-  query: SelectQueryNode;
-  /** Whether the CTE is recursive */
-  recursive: boolean;
-}
-
-/**
- * AST node representing a complete SELECT query
- */
-export interface SelectQueryNode {
-  type: 'SelectQuery';
+export interface CommonTableExpressionNode {
+  type: 'CommonTableExpression';
+  /** CTE name */
+  name: string;
+  /** Optional column names */
+  columns?: string[];
+  /** CTE query */
+  query: SelectQueryNode;
+  /** Whether the CTE is recursive */
+  recursive: boolean;
+}
+
+/**
+ * Supported set operation kinds for compound SELECT queries
+ */
+export type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
+
+/**
+ * AST node representing a set operation (UNION, INTERSECT, etc.)
+ */
+export interface SetOperationNode {
+  type: 'SetOperation';
+  /** Operator to combine queries */
+  operator: SetOperationKind;
+  /** Right-hand query in the compound expression */
+  query: SelectQueryNode;
+}
+
+/**
+ * AST node representing a complete SELECT query
+ */
+export interface SelectQueryNode {
+  type: 'SelectQuery';
   /** Optional CTEs (WITH clauses) */
   ctes?: CommonTableExpressionNode[];
   /** FROM clause table */
@@ -131,11 +147,13 @@ export interface SelectQueryNode {
   limit?: number;
   /** Optional OFFSET clause */
   offset?: number;
-  /** Optional query metadata */
-  meta?: QueryMetadata;
-  /** Optional DISTINCT clause */
-  distinct?: ColumnNode[];
-}
+  /** Optional query metadata */
+  meta?: QueryMetadata;
+  /** Optional DISTINCT clause */
+  distinct?: ColumnNode[];
+  /** Optional set operations chaining this query with others */
+  setOps?: SetOperationNode[];
+}
 
 export interface InsertQueryNode {
   type: 'InsertQuery';