metal-orm 1.0.12 → 1.0.13

package/dist/index.js

@@ -550,6 +550,82 @@ var SelectQueryState = class _SelectQueryState {
       ctes: [...this.ast.ctes ?? [], cte]
     });
   }
+  /**
+   * 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) {
+    return this.clone({
+      ...this.ast,
+      setOps: [...this.ast.setOps ?? [], op]
+    });
+  }
+};
+
+// src/core/ast/join-node.ts
+var createJoinNode = (kind, tableName, condition, relationName) => ({
+  type: "Join",
+  kind,
+  table: { type: "Table", name: tableName },
+  condition,
+  relationName
+});
+
+// src/core/sql/sql.ts
+var SQL_OPERATORS = {
+  /** Equality operator */
+  EQUALS: "=",
+  /** Not equals operator */
+  NOT_EQUALS: "!=",
+  /** Greater than operator */
+  GREATER_THAN: ">",
+  /** Greater than or equal operator */
+  GREATER_OR_EQUAL: ">=",
+  /** Less than operator */
+  LESS_THAN: "<",
+  /** Less than or equal operator */
+  LESS_OR_EQUAL: "<=",
+  /** LIKE pattern matching operator */
+  LIKE: "LIKE",
+  /** NOT LIKE pattern matching operator */
+  NOT_LIKE: "NOT LIKE",
+  /** IN membership operator */
+  IN: "IN",
+  /** NOT IN membership operator */
+  NOT_IN: "NOT IN",
+  /** BETWEEN range operator */
+  BETWEEN: "BETWEEN",
+  /** NOT BETWEEN range operator */
+  NOT_BETWEEN: "NOT BETWEEN",
+  /** IS NULL null check operator */
+  IS_NULL: "IS NULL",
+  /** IS NOT NULL null check operator */
+  IS_NOT_NULL: "IS NOT NULL",
+  /** Logical AND operator */
+  AND: "AND",
+  /** Logical OR operator */
+  OR: "OR",
+  /** EXISTS operator */
+  EXISTS: "EXISTS",
+  /** NOT EXISTS operator */
+  NOT_EXISTS: "NOT EXISTS"
+};
+var JOIN_KINDS = {
+  /** INNER JOIN type */
+  INNER: "INNER",
+  /** LEFT JOIN type */
+  LEFT: "LEFT",
+  /** RIGHT JOIN type */
+  RIGHT: "RIGHT",
+  /** CROSS JOIN type */
+  CROSS: "CROSS"
+};
+var ORDER_DIRECTIONS = {
+  /** Ascending order */
+  ASC: "ASC",
+  /** Descending order */
+  DESC: "DESC"
 };
 
 // src/query-builder/hydration-manager.ts
@@ -601,8 +677,26 @@ var HydrationManager = class _HydrationManager {
    * @returns AST with hydration metadata
    */
   applyToAst(ast) {
+    if (ast.setOps && ast.setOps.length > 0) {
+      return ast;
+    }
     const plan = this.planner.getPlan();
     if (!plan) return ast;
+    const needsPaginationGuard = this.requiresParentPagination(ast, plan);
+    const rewritten = needsPaginationGuard ? this.wrapForParentPagination(ast, plan) : ast;
+    return this.attachHydrationMeta(rewritten, plan);
+  }
+  /**
+   * Gets the current hydration plan
+   * @returns Hydration plan or undefined if none exists
+   */
+  getPlan() {
+    return this.planner.getPlan();
+  }
+  /**
+   * Attaches hydration metadata to a query AST node.
+   */
+  attachHydrationMeta(ast, plan) {
     return {
       ...ast,
       meta: {
@@ -612,11 +706,154 @@ var HydrationManager = class _HydrationManager {
     };
   }
   /**
-   * Gets the current hydration plan
-   * @returns Hydration plan or undefined if none exists
+   * Determines whether the query needs pagination rewriting to keep LIMIT/OFFSET
+   * applied to parent rows when eager-loading multiplicative relations.
    */
-  getPlan() {
-    return this.planner.getPlan();
+  requiresParentPagination(ast, plan) {
+    const hasPagination = ast.limit !== void 0 || ast.offset !== void 0;
+    return hasPagination && this.hasMultiplyingRelations(plan);
+  }
+  hasMultiplyingRelations(plan) {
+    return plan.relations.some(
+      (rel) => rel.type === RelationKinds.HasMany || rel.type === RelationKinds.BelongsToMany
+    );
+  }
+  /**
+   * 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.
+   */
+  wrapForParentPagination(ast, plan) {
+    const projectionNames = this.getProjectionNames(ast.columns);
+    if (!projectionNames) {
+      return ast;
+    }
+    const projectionAliases = this.buildProjectionAliasMap(ast.columns);
+    const projectionSet = new Set(projectionNames);
+    const rootPkAlias = projectionAliases.get(`${plan.rootTable}.${plan.rootPrimaryKey}`) ?? plan.rootPrimaryKey;
+    const baseCteName = this.nextCteName(ast.ctes, "__metal_pagination_base");
+    const baseQuery = {
+      ...ast,
+      ctes: void 0,
+      limit: void 0,
+      offset: void 0,
+      orderBy: void 0,
+      meta: void 0
+    };
+    const baseCte = {
+      type: "CommonTableExpression",
+      name: baseCteName,
+      query: baseQuery,
+      recursive: false
+    };
+    const orderBy = this.mapOrderBy(ast.orderBy, plan, projectionAliases, baseCteName, projectionSet);
+    if (orderBy === null) {
+      return ast;
+    }
+    const pageCteName = this.nextCteName([...ast.ctes ?? [], baseCte], "__metal_pagination_page");
+    const pagingColumns = this.buildPagingColumns(rootPkAlias, orderBy, baseCteName);
+    const pageCte = {
+      type: "CommonTableExpression",
+      name: pageCteName,
+      query: {
+        type: "SelectQuery",
+        from: { type: "Table", name: baseCteName },
+        columns: pagingColumns,
+        joins: [],
+        distinct: [{ type: "Column", table: baseCteName, name: rootPkAlias }],
+        orderBy,
+        limit: ast.limit,
+        offset: ast.offset
+      },
+      recursive: false
+    };
+    const joinCondition = eq(
+      { type: "Column", table: baseCteName, name: rootPkAlias },
+      { type: "Column", table: pageCteName, name: rootPkAlias }
+    );
+    const outerColumns = projectionNames.map((name) => ({
+      type: "Column",
+      table: baseCteName,
+      name,
+      alias: name
+    }));
+    return {
+      type: "SelectQuery",
+      from: { type: "Table", name: baseCteName },
+      columns: outerColumns,
+      joins: [createJoinNode(JOIN_KINDS.INNER, pageCteName, joinCondition)],
+      orderBy,
+      ctes: [...ast.ctes ?? [], baseCte, pageCte]
+    };
+  }
+  nextCteName(existing, baseName) {
+    const names = new Set((existing ?? []).map((cte) => cte.name));
+    let candidate = baseName;
+    let suffix = 1;
+    while (names.has(candidate)) {
+      suffix += 1;
+      candidate = `${baseName}_${suffix}`;
+    }
+    return candidate;
+  }
+  getProjectionNames(columns) {
+    const names = [];
+    for (const col2 of columns) {
+      const alias = col2.alias ?? col2.name;
+      if (!alias) return void 0;
+      names.push(alias);
+    }
+    return names;
+  }
+  buildProjectionAliasMap(columns) {
+    const map = /* @__PURE__ */ new Map();
+    for (const col2 of columns) {
+      if (col2.type !== "Column") continue;
+      const node = col2;
+      const key = `${node.table}.${node.name}`;
+      map.set(key, node.alias ?? node.name);
+    }
+    return map;
+  }
+  mapOrderBy(orderBy, plan, projectionAliases, baseAlias, availableColumns) {
+    if (!orderBy || orderBy.length === 0) {
+      return void 0;
+    }
+    const mapped = [];
+    for (const ob of orderBy) {
+      if (ob.column.table !== plan.rootTable) {
+        return null;
+      }
+      const alias = projectionAliases.get(`${ob.column.table}.${ob.column.name}`) ?? ob.column.name;
+      if (!availableColumns.has(alias)) {
+        return null;
+      }
+      mapped.push({
+        type: "OrderBy",
+        column: { type: "Column", table: baseAlias, name: alias },
+        direction: ob.direction
+      });
+    }
+    return mapped;
+  }
+  buildPagingColumns(primaryKey, orderBy, tableAlias) {
+    const columns = [{ type: "Column", table: tableAlias, name: primaryKey, alias: primaryKey }];
+    if (!orderBy) return columns;
+    for (const ob of orderBy) {
+      if (!columns.some((col2) => col2.name === ob.column.name)) {
+        columns.push({
+          type: "Column",
+          table: tableAlias,
+          name: ob.column.name,
+          alias: ob.column.name
+        });
+      }
+    }
+    return columns;
   }
 };
 
@@ -879,6 +1116,20 @@ var QueryAstService = class {
     };
     return this.state.withCte(cte);
   }
+  /**
+   * 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, query) {
+    const op = {
+      type: "SetOperation",
+      operator,
+      query
+    };
+    return this.state.withSetOperation(op);
+  }
   /**
    * Selects a subquery as a column
    * @param alias - Alias for the subquery
@@ -1031,15 +1282,6 @@ var RelationProjectionHelper = class {
   }
 };
 
-// src/core/ast/join-node.ts
-var createJoinNode = (kind, tableName, condition, relationName) => ({
-  type: "Join",
-  kind,
-  table: { type: "Table", name: tableName },
-  condition,
-  relationName
-});
-
 // src/query-builder/relation-conditions.ts
 var assertNever = (value) => {
   throw new Error(`Unhandled relation type: ${JSON.stringify(value)}`);
@@ -1095,62 +1337,6 @@ var buildRelationCorrelation = (root, relation) => {
   return baseRelationCondition(root, relation);
 };
 
-// src/core/sql/sql.ts
-var SQL_OPERATORS = {
-  /** Equality operator */
-  EQUALS: "=",
-  /** Not equals operator */
-  NOT_EQUALS: "!=",
-  /** Greater than operator */
-  GREATER_THAN: ">",
-  /** Greater than or equal operator */
-  GREATER_OR_EQUAL: ">=",
-  /** Less than operator */
-  LESS_THAN: "<",
-  /** Less than or equal operator */
-  LESS_OR_EQUAL: "<=",
-  /** LIKE pattern matching operator */
-  LIKE: "LIKE",
-  /** NOT LIKE pattern matching operator */
-  NOT_LIKE: "NOT LIKE",
-  /** IN membership operator */
-  IN: "IN",
-  /** NOT IN membership operator */
-  NOT_IN: "NOT IN",
-  /** BETWEEN range operator */
-  BETWEEN: "BETWEEN",
-  /** NOT BETWEEN range operator */
-  NOT_BETWEEN: "NOT BETWEEN",
-  /** IS NULL null check operator */
-  IS_NULL: "IS NULL",
-  /** IS NOT NULL null check operator */
-  IS_NOT_NULL: "IS NOT NULL",
-  /** Logical AND operator */
-  AND: "AND",
-  /** Logical OR operator */
-  OR: "OR",
-  /** EXISTS operator */
-  EXISTS: "EXISTS",
-  /** NOT EXISTS operator */
-  NOT_EXISTS: "NOT EXISTS"
-};
-var JOIN_KINDS = {
-  /** INNER JOIN type */
-  INNER: "INNER",
-  /** LEFT JOIN type */
-  LEFT: "LEFT",
-  /** RIGHT JOIN type */
-  RIGHT: "RIGHT",
-  /** CROSS JOIN type */
-  CROSS: "CROSS"
-};
-var ORDER_DIRECTIONS = {
-  /** Ascending order */
-  ASC: "ASC",
-  /** Descending order */
-  DESC: "DESC"
-};
-
 // src/query-builder/relation-service.ts
 var RelationService = class {
   /**
@@ -1596,6 +1782,16 @@ var hasEntityMeta = (entity) => {
 
 // src/orm/relations/has-many.ts
 var toKey2 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultHasManyCollection = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
     this.ctx = ctx;
@@ -1611,6 +1807,7 @@ var DefaultHasManyCollection = class {
     this.items = [];
     this.added = /* @__PURE__ */ new Set();
     this.removed = /* @__PURE__ */ new Set();
+    hideInternal(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
   async load() {
@@ -1686,10 +1883,23 @@ var DefaultHasManyCollection = class {
     this.items = rows.map((row) => this.createEntity(row));
     this.loaded = true;
   }
+  toJSON() {
+    return this.items;
+  }
 };
 
 // src/orm/relations/belongs-to.ts
 var toKey3 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal2 = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultBelongsToReference = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, targetKey) {
     this.ctx = ctx;
@@ -1703,6 +1913,7 @@ var DefaultBelongsToReference = class {
     this.targetKey = targetKey;
     this.loaded = false;
     this.current = null;
+    hideInternal2(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "targetKey"]);
     this.populateFromHydrationCache();
   }
   async load() {
@@ -1763,10 +1974,23 @@ var DefaultBelongsToReference = class {
     this.current = this.createEntity(row);
     this.loaded = true;
   }
+  toJSON() {
+    return this.current;
+  }
 };
 
 // src/orm/relations/many-to-many.ts
 var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal3 = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultManyToManyCollection = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
     this.ctx = ctx;
@@ -1780,6 +2004,7 @@ var DefaultManyToManyCollection = class {
     this.localKey = localKey;
     this.loaded = false;
     this.items = [];
+    hideInternal3(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
   async load() {
@@ -1885,6 +2110,9 @@ var DefaultManyToManyCollection = class {
     });
     this.loaded = true;
   }
+  toJSON() {
+    return this.items;
+  }
 };
 
 // src/orm/lazy-batch.ts
@@ -2245,9 +2473,15 @@ var flattenResults = (results) => {
   return rows;
 };
 async function executeHydrated(ctx, qb) {
-  const compiled = ctx.dialect.compileSelect(qb.getAST());
+  const ast = qb.getAST();
+  const compiled = ctx.dialect.compileSelect(ast);
   const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
   const rows = flattenResults(executed);
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows.map(
+      (row) => createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
+    );
+  }
   const hydrated = hydrateRows(rows, qb.getHydrationPlan());
   return hydrated.map(
     (row) => createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
@@ -2294,6 +2528,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const joinNode = createJoinNode(kind, table.name, condition);
     return this.applyAst(context, (service) => service.withJoin(joinNode));
   }
+  applySetOperation(operator, query) {
+    const subAst = this.resolveQueryNode(query);
+    return this.applyAst(this.context, (service) => service.withSetOperation(operator, subAst));
+  }
   /**
    * Selects specific columns for the query
    * @param columns - Record of column definitions, function nodes, case expressions, or window functions
@@ -2482,6 +2720,38 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
     return this.clone(nextContext);
   }
+  /**
+   * Combines this query with another using UNION
+   * @param query - Query to union with
+   * @returns New query builder instance with the set operation
+   */
+  union(query) {
+    return this.clone(this.applySetOperation("UNION", query));
+  }
+  /**
+   * 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) {
+    return this.clone(this.applySetOperation("UNION ALL", query));
+  }
+  /**
+   * Combines this query with another using INTERSECT
+   * @param query - Query to intersect with
+   * @returns New query builder instance with the set operation
+   */
+  intersect(query) {
+    return this.clone(this.applySetOperation("INTERSECT", query));
+  }
+  /**
+   * Combines this query with another using EXCEPT
+   * @param query - Query to subtract
+   * @returns New query builder instance with the set operation
+   */
+  except(query) {
+    return this.clone(this.applySetOperation("EXCEPT", query));
+  }
   /**
    * Adds a WHERE EXISTS condition to the query
    * @param subquery - Subquery to check for existence
@@ -2771,7 +3041,8 @@ var Dialect = class {
    */
   compileSelect(ast) {
     const ctx = this.createCompilerContext();
-    const rawSql = this.compileSelectAst(ast, ctx).trim();
+    const normalized = this.normalizeSelectAst(ast);
+    const rawSql = this.compileSelectAst(normalized, ctx).trim();
     const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
     return {
       sql,
@@ -2805,6 +3076,9 @@ var Dialect = class {
       params: [...ctx.params]
     };
   }
+  supportsReturning() {
+    return false;
+  }
   /**
    * Compiles a WHERE clause
    * @param where - WHERE expression
@@ -2829,7 +3103,11 @@ var Dialect = class {
    * @returns SQL for EXISTS subquery
    */
   compileSelectForExists(ast, ctx) {
-    const full = this.compileSelectAst(ast, ctx).trim().replace(/;$/, "");
+    const normalized = this.normalizeSelectAst(ast);
+    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, "");
+    if (normalized.setOps && normalized.setOps.length > 0) {
+      return `SELECT 1 FROM (${full}) AS _exists`;
+    }
     const upper = full.toUpperCase();
     const fromIndex = upper.indexOf(" FROM ");
     if (fromIndex === -1) {
@@ -2862,6 +3140,65 @@ var Dialect = class {
   formatPlaceholder(index) {
     return "?";
   }
+  /**
+   * Whether the current dialect supports a given set operation.
+   * Override in concrete dialects to restrict support.
+   */
+  supportsSetOperation(kind) {
+    return true;
+  }
+  /**
+   * 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
+   */
+  validateSetOperations(ast, isOutermost = true) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    if (!isOutermost && (ast.orderBy || ast.limit !== void 0 || ast.offset !== void 0)) {
+      throw new Error("ORDER BY / LIMIT / OFFSET are only allowed on the outermost compound query.");
+    }
+    if (hasSetOps) {
+      for (const op of ast.setOps) {
+        if (!this.supportsSetOperation(op.operator)) {
+          throw new Error(`Set operation ${op.operator} is not supported by this dialect.`);
+        }
+        this.validateSetOperations(op.query, false);
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  hoistCtes(ast) {
+    let hoisted = [];
+    const normalizedSetOps = ast.setOps?.map((op) => {
+      const { normalized: child, hoistedCtes: childHoisted } = this.hoistCtes(op.query);
+      const childCtes = child.ctes ?? [];
+      if (childCtes.length) {
+        hoisted = hoisted.concat(childCtes);
+      }
+      hoisted = hoisted.concat(childHoisted);
+      const queryWithoutCtes = childCtes.length ? { ...child, ctes: void 0 } : child;
+      return { ...op, query: queryWithoutCtes };
+    });
+    const normalized = normalizedSetOps ? { ...ast, setOps: normalizedSetOps } : ast;
+    return { normalized, hoistedCtes: hoisted };
+  }
+  /**
+   * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+   * @param ast - Query AST
+   * @returns Normalized query AST
+   */
+  normalizeSelectAst(ast) {
+    this.validateSetOperations(ast, true);
+    const { normalized, hoistedCtes } = this.hoistCtes(ast);
+    const combinedCtes = [...normalized.ctes ?? [], ...hoistedCtes];
+    return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
+  }
   constructor() {
     this.expressionCompilers = /* @__PURE__ */ new Map();
     this.operandCompilers = /* @__PURE__ */ new Map();
@@ -3010,16 +3347,18 @@ var SqlDialectBase = class extends Dialect {
    * Compiles SELECT query AST to SQL using common rules.
    */
   compileSelectAst(ast, ctx) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
     const ctes = this.compileCtes(ast, ctx);
-    const columns = this.compileSelectColumns(ast, ctx);
-    const from = this.compileFrom(ast.from);
-    const joins = this.compileJoins(ast, ctx);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    const groupBy = this.compileGroupBy(ast);
-    const having = this.compileHaving(ast, ctx);
+    const baseAst = hasSetOps ? { ...ast, setOps: void 0, orderBy: void 0, limit: void 0, offset: void 0 } : ast;
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+    const compound = ast.setOps.map((op) => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`).join(" ");
     const orderBy = this.compileOrderBy(ast);
     const pagination = this.compilePagination(ast, orderBy);
-    return `${ctes}SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    return `${ctes}${combined}${orderBy}${pagination}`;
   }
   compileInsertAst(ast, ctx) {
     const table = this.compileTableName(ast.into);
@@ -3028,6 +3367,20 @@ var SqlDialectBase = class extends Dialect {
     const returning = this.compileReturning(ast.returning, ctx);
     return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning}`;
   }
+  /**
+   * Compiles a single SELECT (no set operations, no CTE prefix).
+   */
+  compileSelectCore(ast, ctx) {
+    const columns = this.compileSelectColumns(ast, ctx);
+    const from = this.compileFrom(ast.from);
+    const joins = this.compileJoins(ast, ctx);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const groupBy = this.compileGroupBy(ast);
+    const having = this.compileHaving(ast, ctx);
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    return `SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+  }
   compileUpdateAst(ast, ctx) {
     const table = this.compileTableName(ast.table);
     const assignments = ast.set.map((assignment) => {
@@ -3053,6 +3406,13 @@ var SqlDialectBase = class extends Dialect {
     if (!returning || returning.length === 0) return "";
     throw new Error("RETURNING is not supported by this dialect.");
   }
+  formatReturningColumns(returning) {
+    return returning.map((column) => {
+      const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : "";
+      const aliasPart = column.alias ? ` AS ${this.quoteIdentifier(column.alias)}` : "";
+      return `${tablePart}${this.quoteIdentifier(column.name)}${aliasPart}`;
+    }).join(", ");
+  }
   /**
    * DISTINCT clause. Override for DISTINCT ON support.
    */
@@ -3118,7 +3478,7 @@ var SqlDialectBase = class extends Dialect {
     const cteDefs = ast.ctes.map((cte) => {
       const name = this.quoteIdentifier(cte.name);
       const cols = cte.columns && cte.columns.length ? `(${cte.columns.map((c) => this.quoteIdentifier(c)).join(", ")})` : "";
-      const query = this.stripTrailingSemicolon(this.compileSelectAst(cte.query, ctx));
+      const query = this.stripTrailingSemicolon(this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx));
       return `${name}${cols} AS (${query})`;
     }).join(", ");
     return `${prefix}${cteDefs} `;
@@ -3126,6 +3486,10 @@ var SqlDialectBase = class extends Dialect {
   stripTrailingSemicolon(sql) {
     return sql.trim().replace(/;$/, "");
   }
+  wrapSetOperand(sql) {
+    const trimmed = this.stripTrailingSemicolon(sql);
+    return `(${trimmed})`;
+  }
 };
 
 // src/core/dialect/mysql/index.ts
@@ -3195,6 +3559,43 @@ var SqlServerDialect = class extends Dialect {
    * @returns SQL Server SQL string
    */
   compileSelectAst(ast, ctx) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    const ctes = this.compileCtes(ast, ctx);
+    const baseAst = hasSetOps ? { ...ast, setOps: void 0, orderBy: void 0, limit: void 0, offset: void 0 } : ast;
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+    const compound = ast.setOps.map((op) => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`).join(" ");
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    const tail = pagination || orderBy;
+    return `${ctes}${combined}${tail}`;
+  }
+  compileInsertAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.into.name);
+    const columnList = ast.columns.map((column) => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`).join(", ");
+    const values = ast.values.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+    return `INSERT INTO ${table} (${columnList}) VALUES ${values};`;
+  }
+  compileUpdateAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.table.name);
+    const assignments = ast.set.map((assignment) => {
+      const col2 = assignment.column;
+      const target = `${this.quoteIdentifier(col2.table)}.${this.quoteIdentifier(col2.name)}`;
+      const value = this.compileOperand(assignment.value, ctx);
+      return `${target} = ${value}`;
+    }).join(", ");
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `UPDATE ${table} SET ${assignments}${whereClause};`;
+  }
+  compileDeleteAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.from.name);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `DELETE FROM ${table}${whereClause};`;
+  }
+  compileSelectCore(ast, ctx) {
     const columns = ast.columns.map((c) => {
       let expr = "";
       if (c.type === "Function") {
@@ -3222,46 +3623,42 @@ var SqlServerDialect = class extends Dialect {
     const whereClause = this.compileWhere(ast.where, ctx);
     const groupBy = ast.groupBy && ast.groupBy.length > 0 ? " GROUP BY " + ast.groupBy.map((c) => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(", ") : "";
     const having = ast.having ? ` HAVING ${this.compileExpression(ast.having, ctx)}` : "";
-    const orderBy = ast.orderBy && ast.orderBy.length > 0 ? " ORDER BY " + ast.orderBy.map((o) => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(", ") : "";
-    let pagination = "";
-    if (ast.limit || ast.offset) {
-      const off = ast.offset || 0;
-      const orderClause = orderBy || " ORDER BY (SELECT NULL)";
-      pagination = `${orderClause} OFFSET ${off} ROWS`;
-      if (ast.limit) {
-        pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
-      }
-      return `SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${pagination};`;
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    if (pagination) {
+      return `SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${pagination}`;
+    }
+    return `SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${orderBy}`;
+  }
+  compileOrderBy(ast) {
+    if (!ast.orderBy || ast.orderBy.length === 0) return "";
+    return " ORDER BY " + ast.orderBy.map((o) => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(", ");
+  }
+  compilePagination(ast, orderBy) {
+    const hasLimit = ast.limit !== void 0;
+    const hasOffset = ast.offset !== void 0;
+    if (!hasLimit && !hasOffset) return "";
+    const off = ast.offset ?? 0;
+    const orderClause = orderBy || " ORDER BY (SELECT NULL)";
+    let pagination = `${orderClause} OFFSET ${off} ROWS`;
+    if (hasLimit) {
+      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
     }
-    const ctes = ast.ctes && ast.ctes.length > 0 ? "WITH " + ast.ctes.map((cte) => {
+    return pagination;
+  }
+  compileCtes(ast, ctx) {
+    if (!ast.ctes || ast.ctes.length === 0) return "";
+    const defs = ast.ctes.map((cte) => {
       const name = this.quoteIdentifier(cte.name);
       const cols = cte.columns ? `(${cte.columns.map((c) => this.quoteIdentifier(c)).join(", ")})` : "";
-      const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, "");
+      const query = this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx).trim().replace(/;$/, "");
       return `${name}${cols} AS (${query})`;
-    }).join(", ") + " " : "";
-    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${orderBy};`;
-  }
-  compileInsertAst(ast, ctx) {
-    const table = this.quoteIdentifier(ast.into.name);
-    const columnList = ast.columns.map((column) => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`).join(", ");
-    const values = ast.values.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
-    return `INSERT INTO ${table} (${columnList}) VALUES ${values};`;
-  }
-  compileUpdateAst(ast, ctx) {
-    const table = this.quoteIdentifier(ast.table.name);
-    const assignments = ast.set.map((assignment) => {
-      const col2 = assignment.column;
-      const target = `${this.quoteIdentifier(col2.table)}.${this.quoteIdentifier(col2.name)}`;
-      const value = this.compileOperand(assignment.value, ctx);
-      return `${target} = ${value}`;
     }).join(", ");
-    const whereClause = this.compileWhere(ast.where, ctx);
-    return `UPDATE ${table} SET ${assignments}${whereClause};`;
+    return `WITH ${defs} `;
   }
-  compileDeleteAst(ast, ctx) {
-    const table = this.quoteIdentifier(ast.from.name);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    return `DELETE FROM ${table}${whereClause};`;
+  wrapSetOperand(sql) {
+    const trimmed = sql.trim().replace(/;$/, "");
+    return `(${trimmed})`;
   }
 };
 
@@ -3292,12 +3689,12 @@ var SqliteDialect = class extends SqlDialectBase {
   }
   compileReturning(returning, ctx) {
     if (!returning || returning.length === 0) return "";
-    const columns = returning.map((column) => {
-      const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : "";
-      return `${tablePart}${this.quoteIdentifier(column.name)}`;
-    }).join(", ");
+    const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
+  supportsReturning() {
+    return true;
+  }
 };
 
 // src/core/dialect/postgres/index.ts
@@ -3327,12 +3724,12 @@ var PostgresDialect = class extends SqlDialectBase {
   }
   compileReturning(returning, ctx) {
     if (!returning || returning.length === 0) return "";
-    const columns = returning.map((column) => {
-      const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : "";
-      return `${tablePart}${this.quoteIdentifier(column.name)}`;
-    }).join(", ");
+    const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
+  supportsReturning() {
+    return true;
+  }
 };
 
 // src/core/ddl/dialects/base-schema-dialect.ts
@@ -5096,9 +5493,13 @@ var UnitOfWork = class {
   async flushInsert(tracked) {
     await this.runHook(tracked.table.hooks?.beforeInsert, tracked);
     const payload = this.extractColumns(tracked.table, tracked.entity);
-    const builder = new InsertQueryBuilder(tracked.table).values(payload);
+    let builder = new InsertQueryBuilder(tracked.table).values(payload);
+    if (this.dialect.supportsReturning()) {
+      builder = builder.returning(...this.getReturningColumns(tracked.table));
+    }
     const compiled = builder.compile(this.dialect);
-    await this.executeCompiled(compiled);
+    const results = await this.executeCompiled(compiled);
+    this.applyReturningResults(tracked, results);
     tracked.status = "managed" /* Managed */;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity);
     tracked.pk = this.getPrimaryKeyValue(tracked);
@@ -5115,9 +5516,13 @@ var UnitOfWork = class {
     await this.runHook(tracked.table.hooks?.beforeUpdate, tracked);
     const pkColumn = tracked.table.columns[findPrimaryKey(tracked.table)];
     if (!pkColumn) return;
-    const builder = new UpdateQueryBuilder(tracked.table).set(changes).where(eq(pkColumn, tracked.pk));
+    let builder = new UpdateQueryBuilder(tracked.table).set(changes).where(eq(pkColumn, tracked.pk));
+    if (this.dialect.supportsReturning()) {
+      builder = builder.returning(...this.getReturningColumns(tracked.table));
+    }
     const compiled = builder.compile(this.dialect);
-    await this.executeCompiled(compiled);
+    const results = await this.executeCompiled(compiled);
+    this.applyReturningResults(tracked, results);
     tracked.status = "managed" /* Managed */;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity);
     this.registerIdentity(tracked);
@@ -5159,7 +5564,31 @@ var UnitOfWork = class {
     return payload;
   }
   async executeCompiled(compiled) {
-    await this.executor.executeSql(compiled.sql, compiled.params);
+    return this.executor.executeSql(compiled.sql, compiled.params);
+  }
+  getReturningColumns(table) {
+    return Object.values(table.columns).map((column) => ({
+      type: "Column",
+      table: table.name,
+      name: column.name,
+      alias: column.name
+    }));
+  }
+  applyReturningResults(tracked, results) {
+    if (!this.dialect.supportsReturning()) return;
+    const first = results[0];
+    if (!first || first.values.length === 0) return;
+    const row = first.values[0];
+    for (let i = 0; i < first.columns.length; i++) {
+      const columnName = this.normalizeColumnName(first.columns[i]);
+      if (!(columnName in tracked.table.columns)) continue;
+      tracked.entity[columnName] = row[i];
+    }
+  }
+  normalizeColumnName(column) {
+    const parts = column.split(".");
+    const candidate = parts[parts.length - 1];
+    return candidate.replace(/^["`[\]]+|["`[\]]+$/g, "");
   }
   registerIdentity(tracked) {
     if (tracked.pk == null) return;
@@ -5180,22 +5609,46 @@ var UnitOfWork = class {
   }
 };
 
+// src/orm/query-logger.ts
+var createQueryLoggingExecutor = (executor, logger) => {
+  if (!logger) {
+    return executor;
+  }
+  const wrapped = {
+    async executeSql(sql, params) {
+      logger({ sql, params });
+      return executor.executeSql(sql, params);
+    }
+  };
+  if (executor.beginTransaction) {
+    wrapped.beginTransaction = executor.beginTransaction.bind(executor);
+  }
+  if (executor.commitTransaction) {
+    wrapped.commitTransaction = executor.commitTransaction.bind(executor);
+  }
+  if (executor.rollbackTransaction) {
+    wrapped.rollbackTransaction = executor.rollbackTransaction.bind(executor);
+  }
+  return wrapped;
+};
+
 // src/orm/orm-context.ts
 var OrmContext = class {
   constructor(options) {
     this.options = options;
     this.identityMap = new IdentityMap();
     this.interceptors = [...options.interceptors ?? []];
+    this.executorWithLogging = createQueryLoggingExecutor(options.executor, options.queryLogger);
     this.unitOfWork = new UnitOfWork(
       options.dialect,
-      options.executor,
+      this.executorWithLogging,
       this.identityMap,
       () => this
     );
     this.relationChanges = new RelationChangeProcessor(
       this.unitOfWork,
       options.dialect,
-      options.executor
+      this.executorWithLogging
     );
     this.domainEvents = new DomainEventBus(options.domainEventHandlers);
   }
@@ -5203,7 +5656,7 @@ var OrmContext = class {
     return this.options.dialect;
   }
   get executor() {
-    return this.options.executor;
+    return this.executorWithLogging;
   }
   get identityBuckets() {
     return this.unitOfWork.identityBuckets;