metal-orm 1.0.39 → 1.0.41

package/dist/index.js

@@ -245,6 +245,7 @@ var belongsToMany = (target, pivotTable, options) => ({
 
 // src/core/ast/expression-nodes.ts
 var operandTypes = /* @__PURE__ */ new Set([
+  "AliasRef",
   "Column",
   "Literal",
   "Function",
@@ -286,11 +287,21 @@ var toOperand = (val) => {
   }
   return toNode(val);
 };
+var hasQueryAst = (value) => typeof value.getAST === "function";
+var resolveSelectQueryNode = (query) => hasQueryAst(query) ? query.getAST() : query;
+var toScalarSubqueryNode = (query) => ({
+  type: "ScalarSubquery",
+  query: resolveSelectQueryNode(query)
+});
 var columnOperand = (col2) => toNode(col2);
 var outerRef = (col2) => ({
   ...columnOperand(col2),
   scope: "outer"
 });
+var aliasRef = (name) => ({
+  type: "AliasRef",
+  name
+});
 var correlateBy = (table, column) => outerRef({ name: column, table });
 var createBinaryExpression = (operator, left2, right2, escape) => {
   const node = {
@@ -332,14 +343,16 @@ var isNotNull = (left2) => ({
   left: toNode(left2),
   operator: "IS NOT NULL"
 });
-var createInExpression = (operator, left2, values) => ({
+var createInExpression = (operator, left2, right2) => ({
   type: "InExpression",
   left: toNode(left2),
   operator,
-  right: values.map((v) => toOperand(v))
+  right: right2
 });
-var inList = (left2, values) => createInExpression("IN", left2, values);
-var notInList = (left2, values) => createInExpression("NOT IN", left2, values);
+var inList = (left2, values) => createInExpression("IN", left2, values.map((v) => toOperand(v)));
+var notInList = (left2, values) => createInExpression("NOT IN", left2, values.map((v) => toOperand(v)));
+var inSubquery = (left2, subquery) => createInExpression("IN", left2, toScalarSubqueryNode(subquery));
+var notInSubquery = (left2, subquery) => createInExpression("NOT IN", left2, toScalarSubqueryNode(subquery));
 var createBetweenExpression = (operator, left2, lower2, upper2) => ({
   type: "BetweenExpression",
   left: toNode(left2),
@@ -349,6 +362,16 @@ var createBetweenExpression = (operator, left2, lower2, upper2) => ({
 });
 var between = (left2, lower2, upper2) => createBetweenExpression("BETWEEN", left2, lower2, upper2);
 var notBetween = (left2, lower2, upper2) => createBetweenExpression("NOT BETWEEN", left2, lower2, upper2);
+var createArithmeticExpression = (operator, left2, right2) => ({
+  type: "ArithmeticExpression",
+  left: toOperand(left2),
+  operator,
+  right: toOperand(right2)
+});
+var add = (left2, right2) => createArithmeticExpression("+", left2, right2);
+var sub = (left2, right2) => createArithmeticExpression("-", left2, right2);
+var mul = (left2, right2) => createArithmeticExpression("*", left2, right2);
+var div = (left2, right2) => createArithmeticExpression("/", left2, right2);
 var jsonPath = (col2, path) => ({
   type: "JsonPath",
   column: columnOperand(col2),
@@ -427,7 +450,7 @@ var windowFunction = (name, args = [], partitionBy, orderBy) => {
   const partitionNodes = partitionBy?.map((col2) => columnOperand(col2)) ?? void 0;
   const orderNodes = orderBy?.map((o) => ({
     type: "OrderBy",
-    column: columnOperand(o.column),
+    term: columnOperand(o.column),
     direction: o.direction
   }));
   return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
@@ -502,7 +525,7 @@ var min = buildAggregate("MIN");
 var max = buildAggregate("MAX");
 var toOrderByNode = (order) => ({
   type: "OrderBy",
-  column: columnOperand(order.column),
+  term: columnOperand(order.column),
   direction: order.direction ?? ORDER_DIRECTIONS.ASC
 });
 var groupConcat = (col2, options) => ({
@@ -552,6 +575,9 @@ var visitExpression = (node, visitor) => {
     case "BetweenExpression":
       if (visitor.visitBetweenExpression) return visitor.visitBetweenExpression(node);
       break;
+    case "ArithmeticExpression":
+      if (visitor.visitArithmeticExpression) return visitor.visitArithmeticExpression(node);
+      break;
     default:
       break;
   }
@@ -583,6 +609,9 @@ var visitOperand = (node, visitor) => {
     case "WindowFunction":
       if (visitor.visitWindowFunction) return visitor.visitWindowFunction(node);
       break;
+    case "AliasRef":
+      if (visitor.visitAliasRef) return visitor.visitAliasRef(node);
+      break;
     default:
       break;
   }
@@ -699,7 +728,14 @@ var StandardFunctionStrategy = class _StandardFunctionStrategy {
     if (!orderBy || orderBy.length === 0) {
       return "";
     }
-    const parts = orderBy.map((order) => `${ctx.compileOperand(order.column)} ${order.direction}`);
+    const parts = orderBy.map((order) => {
+      const term = isOperandNode(order.term) ? ctx.compileOperand(order.term) : (() => {
+        throw new Error("ORDER BY expressions inside functions must be operands");
+      })();
+      const collation = order.collation ? ` COLLATE ${order.collation}` : "";
+      const nulls = order.nulls ? ` NULLS ${order.nulls}` : "";
+      return `${term} ${order.direction}${collation}${nulls}`;
+    });
     return `ORDER BY ${parts.join(", ")}`;
   }
   formatGroupConcatSeparator(ctx) {
@@ -964,6 +1000,16 @@ var Dialect = class _Dialect {
     }
     return compiler(node, ctx);
   }
+  /**
+   * Compiles an ordering term (operand, expression, or alias reference).
+   */
+  compileOrderingTerm(term, ctx) {
+    if (isOperandNode(term)) {
+      return this.compileOperand(term, ctx);
+    }
+    const expr = this.compileExpression(term, ctx);
+    return `(${expr})`;
+  }
   registerDefaultExpressionCompilers() {
     this.registerExpressionCompiler("BinaryExpression", (binary, ctx) => {
       const left2 = this.compileOperand(binary.left, ctx);
@@ -989,8 +1035,12 @@ var Dialect = class _Dialect {
     });
     this.registerExpressionCompiler("InExpression", (inExpr, ctx) => {
       const left2 = this.compileOperand(inExpr.left, ctx);
-      const values = inExpr.right.map((v) => this.compileOperand(v, ctx)).join(", ");
-      return `${left2} ${inExpr.operator} (${values})`;
+      if (Array.isArray(inExpr.right)) {
+        const values = inExpr.right.map((v) => this.compileOperand(v, ctx)).join(", ");
+        return `${left2} ${inExpr.operator} (${values})`;
+      }
+      const subquerySql = this.compileSelectAst(inExpr.right.query, ctx).trim().replace(/;$/, "");
+      return `${left2} ${inExpr.operator} (${subquerySql})`;
     });
     this.registerExpressionCompiler("ExistsExpression", (existsExpr, ctx) => {
       const subquerySql = this.compileSelectForExists(existsExpr.subquery, ctx);
@@ -1002,9 +1052,15 @@ var Dialect = class _Dialect {
       const upper2 = this.compileOperand(betweenExpr.upper, ctx);
       return `${left2} ${betweenExpr.operator} ${lower2} AND ${upper2}`;
     });
+    this.registerExpressionCompiler("ArithmeticExpression", (arith, ctx) => {
+      const left2 = this.compileOperand(arith.left, ctx);
+      const right2 = this.compileOperand(arith.right, ctx);
+      return `${left2} ${arith.operator} ${right2}`;
+    });
   }
   registerDefaultOperandCompilers() {
     this.registerOperandCompiler("Literal", (literal, ctx) => ctx.addParameter(literal.value));
+    this.registerOperandCompiler("AliasRef", (alias, _ctx) => this.quoteIdentifier(alias.name));
     this.registerOperandCompiler("Column", (column, _ctx) => {
       return `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`;
     });
@@ -1042,9 +1098,12 @@ var Dialect = class _Dialect {
         parts.push(partitionClause);
       }
       if (node.orderBy && node.orderBy.length > 0) {
-        const orderClause = "ORDER BY " + node.orderBy.map(
-          (o) => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`
-        ).join(", ");
+        const orderClause = "ORDER BY " + node.orderBy.map((o) => {
+          const term = this.compileOrderingTerm(o.term, ctx);
+          const collation = o.collation ? ` COLLATE ${o.collation}` : "";
+          const nulls = o.nulls ? ` NULLS ${o.nulls}` : "";
+          return `${term} ${o.direction}${collation}${nulls}`;
+        }).join(", ");
         parts.push(orderClause);
       }
       result += parts.join(" ");
@@ -1239,17 +1298,9 @@ var NoReturningStrategy = class {
 
 // src/core/dialect/base/join-compiler.ts
 var JoinCompiler = class {
-  /**
-   * Compiles all JOIN clauses from a SELECT query AST.
-   * @param ast - The SELECT query AST containing join definitions.
-   * @param ctx - The compiler context for expression compilation.
-   * @param compileFrom - Function to compile table sources (tables or subqueries).
-   * @param compileExpression - Function to compile join condition expressions.
-   * @returns SQL JOIN clauses (e.g., " LEFT JOIN table ON condition") or empty string if no joins.
-   */
-  static compileJoins(ast, ctx, compileFrom, compileExpression) {
-    if (!ast.joins || ast.joins.length === 0) return "";
-    const parts = ast.joins.map((j) => {
+  static compileJoins(joins, ctx, compileFrom, compileExpression) {
+    if (!joins || joins.length === 0) return "";
+    const parts = joins.map((j) => {
       const table = compileFrom(j.table, ctx);
       const cond = compileExpression(j.condition, ctx);
       return `${j.kind} JOIN ${table} ON ${cond}`;
@@ -1263,12 +1314,12 @@ var GroupByCompiler = class {
   /**
    * Compiles GROUP BY clause from a SELECT query AST.
    * @param ast - The SELECT query AST containing grouping columns.
-   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @param renderTerm - Function to render a grouping term.
    * @returns SQL GROUP BY clause (e.g., " GROUP BY table.col1, table.col2") or empty string if no grouping.
    */
-  static compileGroupBy(ast, quoteIdentifier) {
+  static compileGroupBy(ast, renderTerm) {
     if (!ast.groupBy || ast.groupBy.length === 0) return "";
-    const cols = ast.groupBy.map((c) => `${quoteIdentifier(c.table)}.${quoteIdentifier(c.name)}`).join(", ");
+    const cols = ast.groupBy.map(renderTerm).join(", ");
     return ` GROUP BY ${cols}`;
   }
 };
@@ -1278,12 +1329,19 @@ var OrderByCompiler = class {
   /**
    * Compiles ORDER BY clause from a SELECT query AST.
    * @param ast - The SELECT query AST containing sort specifications.
-   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @param renderTerm - Function to render an ordering term.
+   * @param renderNulls - Optional function to render NULLS FIRST/LAST.
+   * @param renderCollation - Optional function to render COLLATE clause.
    * @returns SQL ORDER BY clause (e.g., " ORDER BY table.col1 ASC, table.col2 DESC") or empty string if no ordering.
    */
-  static compileOrderBy(ast, quoteIdentifier) {
+  static compileOrderBy(ast, renderTerm, renderNulls, renderCollation) {
     if (!ast.orderBy || ast.orderBy.length === 0) return "";
-    const parts = ast.orderBy.map((o) => `${quoteIdentifier(o.column.table)}.${quoteIdentifier(o.column.name)} ${o.direction}`).join(", ");
+    const parts = ast.orderBy.map((o) => {
+      const term = renderTerm(o.term);
+      const collation = renderCollation ? renderCollation(o) : o.collation ? ` COLLATE ${o.collation}` : "";
+      const nulls = renderNulls ? renderNulls(o) : o.nulls ? ` NULLS ${o.nulls}` : "";
+      return `${term} ${o.direction}${collation}${nulls}`;
+    }).join(", ");
     return ` ORDER BY ${parts}`;
   }
 };
@@ -1314,58 +1372,96 @@ var SqlDialectBase = class extends Dialect {
   }
   compileSelectWithSetOps(ast, baseSelect, ctes, ctx) {
     const compound = ast.setOps.map((op) => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`).join(" ");
-    const orderBy = OrderByCompiler.compileOrderBy(ast, this.quoteIdentifier.bind(this));
+    const orderBy = OrderByCompiler.compileOrderBy(
+      ast,
+      (term) => this.compileOrderingTerm(term, ctx),
+      this.renderOrderByNulls.bind(this),
+      this.renderOrderByCollation.bind(this)
+    );
     const pagination = this.paginationStrategy.compilePagination(ast.limit, ast.offset);
     const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
     return `${ctes}${combined}${orderBy}${pagination}`;
   }
   compileInsertAst(ast, ctx) {
+    if (!ast.columns.length) {
+      throw new Error("INSERT queries must specify columns.");
+    }
     const table = this.compileTableName(ast.into);
     const columnList = this.compileInsertColumnList(ast.columns);
-    const values = this.compileInsertValues(ast.values, ctx);
+    const source = this.compileInsertSource(ast.source, ctx);
     const returning = this.compileReturning(ast.returning, ctx);
-    return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning}`;
+    return `INSERT INTO ${table} (${columnList}) ${source}${returning}`;
   }
   compileReturning(returning, ctx) {
     return this.returningStrategy.compileReturning(returning, ctx);
   }
+  compileInsertSource(source, ctx) {
+    if (source.type === "InsertValues") {
+      if (!source.rows.length) {
+        throw new Error("INSERT ... VALUES requires at least one row.");
+      }
+      const values = source.rows.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+      return `VALUES ${values}`;
+    }
+    const normalized = this.normalizeSelectAst(source.query);
+    return this.compileSelectAst(normalized, ctx).trim();
+  }
   compileInsertColumnList(columns) {
     return columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
   }
-  compileInsertValues(values, ctx) {
-    return values.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
-  }
   compileSelectCore(ast, ctx) {
     const columns = this.compileSelectColumns(ast, ctx);
     const from = this.compileFrom(ast.from, ctx);
-    const joins = JoinCompiler.compileJoins(ast, ctx, this.compileFrom.bind(this), this.compileExpression.bind(this));
+    const joins = JoinCompiler.compileJoins(
+      ast.joins,
+      ctx,
+      this.compileFrom.bind(this),
+      this.compileExpression.bind(this)
+    );
     const whereClause = this.compileWhere(ast.where, ctx);
-    const groupBy = GroupByCompiler.compileGroupBy(ast, this.quoteIdentifier.bind(this));
+    const groupBy = GroupByCompiler.compileGroupBy(ast, (term) => this.compileOrderingTerm(term, ctx));
     const having = this.compileHaving(ast, ctx);
-    const orderBy = OrderByCompiler.compileOrderBy(ast, this.quoteIdentifier.bind(this));
+    const orderBy = OrderByCompiler.compileOrderBy(
+      ast,
+      (term) => this.compileOrderingTerm(term, ctx),
+      this.renderOrderByNulls.bind(this),
+      this.renderOrderByCollation.bind(this)
+    );
     const pagination = this.paginationStrategy.compilePagination(ast.limit, ast.offset);
     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 = this.compileUpdateAssignments(ast.set, ctx);
+    const target = this.compileTableReference(ast.table);
+    const assignments = this.compileUpdateAssignments(ast.set, ast.table, ctx);
+    const fromClause = this.compileUpdateFromClause(ast, ctx);
     const whereClause = this.compileWhere(ast.where, ctx);
     const returning = this.compileReturning(ast.returning, ctx);
-    return `UPDATE ${table} SET ${assignments}${whereClause}${returning}`;
+    return `UPDATE ${target} SET ${assignments}${fromClause}${whereClause}${returning}`;
   }
-  compileUpdateAssignments(assignments, ctx) {
+  compileUpdateAssignments(assignments, table, ctx) {
     return assignments.map((assignment) => {
       const col2 = assignment.column;
-      const target = this.quoteIdentifier(col2.name);
+      const target = this.compileQualifiedColumn(col2, table);
       const value = this.compileOperand(assignment.value, ctx);
       return `${target} = ${value}`;
     }).join(", ");
   }
+  compileQualifiedColumn(column, table) {
+    const baseTableName = table.name;
+    const alias = table.alias;
+    const columnTable = column.table ?? alias ?? baseTableName;
+    const tableQualifier = alias && column.table === baseTableName ? alias : columnTable;
+    if (!tableQualifier) {
+      return this.quoteIdentifier(column.name);
+    }
+    return `${this.quoteIdentifier(tableQualifier)}.${this.quoteIdentifier(column.name)}`;
+  }
   compileDeleteAst(ast, ctx) {
-    const table = this.compileTableName(ast.from);
+    const target = this.compileTableReference(ast.from);
+    const usingClause = this.compileDeleteUsingClause(ast, ctx);
     const whereClause = this.compileWhere(ast.where, ctx);
     const returning = this.compileReturning(ast.returning, ctx);
-    return `DELETE FROM ${table}${whereClause}${returning}`;
+    return `DELETE FROM ${target}${usingClause}${whereClause}${returning}`;
   }
   formatReturningColumns(returning) {
     return this.returningStrategy.formatReturningColumns(returning, this.quoteIdentifier.bind(this));
@@ -1420,6 +1516,38 @@ var SqlDialectBase = class extends Dialect {
     }
     return this.quoteIdentifier(table.name);
   }
+  compileTableReference(table) {
+    const base = this.compileTableName(table);
+    return table.alias ? `${base} AS ${this.quoteIdentifier(table.alias)}` : base;
+  }
+  compileUpdateFromClause(ast, ctx) {
+    if (!ast.from && (!ast.joins || ast.joins.length === 0)) return "";
+    if (!ast.from) {
+      throw new Error("UPDATE with JOINs requires an explicit FROM clause.");
+    }
+    const from = this.compileFrom(ast.from, ctx);
+    const joins = JoinCompiler.compileJoins(
+      ast.joins,
+      ctx,
+      this.compileFrom.bind(this),
+      this.compileExpression.bind(this)
+    );
+    return ` FROM ${from}${joins}`;
+  }
+  compileDeleteUsingClause(ast, ctx) {
+    if (!ast.using && (!ast.joins || ast.joins.length === 0)) return "";
+    if (!ast.using) {
+      throw new Error("DELETE with JOINs requires a USING clause.");
+    }
+    const usingTable = this.compileFrom(ast.using, ctx);
+    const joins = JoinCompiler.compileJoins(
+      ast.joins,
+      ctx,
+      this.compileFrom.bind(this),
+      this.compileExpression.bind(this)
+    );
+    return ` USING ${usingTable}${joins}`;
+  }
   compileHaving(ast, ctx) {
     if (!ast.having) return "";
     return ` HAVING ${this.compileExpression(ast.having, ctx)}`;
@@ -1431,6 +1559,12 @@ var SqlDialectBase = class extends Dialect {
     const trimmed = this.stripTrailingSemicolon(sql);
     return `(${trimmed})`;
   }
+  renderOrderByNulls(order) {
+    return order.nulls ? ` NULLS ${order.nulls}` : "";
+  }
+  renderOrderByCollation(order) {
+    return order.collation ? ` COLLATE ${order.collation}` : "";
+  }
 };
 
 // src/core/dialect/postgres/functions.ts
@@ -1794,6 +1928,9 @@ var SqliteDialect = class extends SqlDialectBase {
     const col2 = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     return `json_extract(${col2}, '${node.path}')`;
   }
+  compileQualifiedColumn(column, _table) {
+    return this.quoteIdentifier(column.name);
+  }
   compileReturning(returning, ctx) {
     if (!returning || returning.length === 0) return "";
     const columns = this.formatReturningColumns(returning);
@@ -1899,7 +2036,7 @@ var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
 };
 
 // src/core/dialect/mssql/index.ts
-var SqlServerDialect = class extends Dialect {
+var SqlServerDialect = class extends SqlDialectBase {
   /**
    * Creates a new SqlServerDialect instance
    */
@@ -1942,43 +2079,37 @@ var SqlServerDialect = class extends Dialect {
     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);
+    const baseSelect = this.compileSelectCoreForMssql(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 orderBy = this.compileOrderBy(ast, ctx);
     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) {
+    if (ast.using) {
+      throw new Error("DELETE ... USING is not supported in the MSSQL dialect; use join() instead.");
+    }
     if (ast.from.type !== "Table") {
       throw new Error("DELETE only supports base tables in the MSSQL dialect.");
     }
-    const table = this.quoteIdentifier(ast.from.name);
+    const alias = ast.from.alias ?? ast.from.name;
+    const target = this.compileTableReference(ast.from);
+    const joins = JoinCompiler.compileJoins(
+      ast.joins,
+      ctx,
+      this.compileFrom.bind(this),
+      this.compileExpression.bind(this)
+    );
     const whereClause = this.compileWhere(ast.where, ctx);
-    return `DELETE FROM ${table}${whereClause};`;
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `DELETE ${this.quoteIdentifier(alias)} FROM ${target}${joins}${whereClause}${returning}`;
   }
-  compileSelectCore(ast, ctx) {
+  compileSelectCoreForMssql(ast, ctx) {
     const columns = ast.columns.map((c) => {
       let expr = "";
       if (c.type === "Function") {
@@ -1997,25 +2128,29 @@ var SqlServerDialect = class extends Dialect {
       return expr;
     }).join(", ");
     const distinct = ast.distinct ? "DISTINCT " : "";
-    const from = this.compileTableSource(ast.from, ctx);
+    const from = this.compileTableSource(ast.from);
     const joins = ast.joins.map((j) => {
-      const table = this.compileTableSource(j.table, ctx);
+      const table = this.compileTableSource(j.table);
       const cond = this.compileExpression(j.condition, ctx);
       return `${j.kind} JOIN ${table} ON ${cond}`;
     }).join(" ");
     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 groupBy = ast.groupBy && ast.groupBy.length > 0 ? " GROUP BY " + ast.groupBy.map((term) => this.compileOrderingTerm(term, ctx)).join(", ") : "";
     const having = ast.having ? ` HAVING ${this.compileExpression(ast.having, ctx)}` : "";
-    const orderBy = this.compileOrderBy(ast);
+    const orderBy = this.compileOrderBy(ast, ctx);
     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(", ");
+  compileOrderBy(ast, ctx) {
+    return OrderByCompiler.compileOrderBy(
+      ast,
+      (term) => this.compileOrderingTerm(term, ctx),
+      this.renderOrderByNulls.bind(this),
+      this.renderOrderByCollation.bind(this)
+    );
   }
   compilePagination(ast, orderBy) {
     const hasLimit = ast.limit !== void 0;
@@ -2029,21 +2164,6 @@ var SqlServerDialect = class extends Dialect {
     }
     return pagination;
   }
-  compileTableSource(table, ctx) {
-    if (table.type === "FunctionTable") {
-      return FunctionTableFormatter.format(table, ctx, this);
-    }
-    if (table.type === "DerivedTable") {
-      return this.compileDerivedTable(table, ctx);
-    }
-    const base = table.schema ? `${this.quoteIdentifier(table.schema)}.${this.quoteIdentifier(table.name)}` : this.quoteIdentifier(table.name);
-    return table.alias ? `${base} AS ${this.quoteIdentifier(table.alias)}` : base;
-  }
-  compileDerivedTable(table, ctx) {
-    const sub = this.compileSelectAst(this.normalizeSelectAst(table.query), ctx).trim().replace(/;$/, "");
-    const cols = table.columnAliases?.length ? ` (${table.columnAliases.map((c) => this.quoteIdentifier(c)).join(", ")})` : "";
-    return `(${sub}) AS ${this.quoteIdentifier(table.alias)}${cols}`;
-  }
   compileCtes(ast, ctx) {
     if (!ast.ctes || ast.ctes.length === 0) return "";
     const defs = ast.ctes.map((cte) => {
@@ -2054,10 +2174,6 @@ var SqlServerDialect = class extends Dialect {
     }).join(", ");
     return `WITH ${defs} `;
   }
-  wrapSetOperand(sql) {
-    const trimmed = sql.trim().replace(/;$/, "");
-    return `(${trimmed})`;
-  }
 };
 
 // src/core/dialect/dialect-factory.ts
@@ -2207,7 +2323,7 @@ var SelectQueryState = class _SelectQueryState {
   }
   /**
    * Adds GROUP BY columns to the query
-   * @param columns - Columns to group by
+   * @param columns - Terms to group by
    * @returns New SelectQueryState with GROUP BY clause
    */
   withGroupBy(columns) {
@@ -2490,31 +2606,38 @@ var HydrationManager = class _HydrationManager {
     }
     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
-      });
+      const mappedTerm = this.mapOrderingTerm(ob.term, plan, projectionAliases, baseAlias, availableColumns);
+      if (!mappedTerm) return null;
+      mapped.push({ ...ob, term: mappedTerm });
     }
     return mapped;
   }
+  mapOrderingTerm(term, plan, projectionAliases, baseAlias, availableColumns) {
+    if (term.type === "Column") {
+      const col2 = term;
+      if (col2.table !== plan.rootTable) return null;
+      const alias = projectionAliases.get(`${col2.table}.${col2.name}`) ?? col2.name;
+      if (!availableColumns.has(alias)) return null;
+      return { type: "Column", table: baseAlias, name: alias };
+    }
+    if (term.type === "AliasRef") {
+      const aliasName = term.name;
+      if (!availableColumns.has(aliasName)) return null;
+      return { type: "Column", table: baseAlias, name: aliasName };
+    }
+    return null;
+  }
   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)) {
+      const term = ob.term;
+      if (!columns.some((col2) => col2.name === term.name)) {
         columns.push({
           type: "Column",
           table: tableAlias,
-          name: ob.column.name,
-          alias: ob.column.name
+          name: term.name,
+          alias: term.name
         });
       }
     }
@@ -2820,10 +2943,8 @@ var QueryAstService = class {
    * @returns Updated query state with GROUP BY clause
    */
   withGroupBy(col2) {
-    const from = this.state.ast.from;
-    const tableRef = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
-    const node = buildColumnNode(tableRef, col2);
-    return this.state.withGroupBy([node]);
+    const term = this.normalizeOrderingTerm(col2);
+    return this.state.withGroupBy([term]);
   }
   /**
    * Adds a HAVING clause to the query
@@ -2840,11 +2961,9 @@ var QueryAstService = class {
    * @param direction - Order direction (ASC/DESC)
    * @returns Updated query state with ORDER BY clause
    */
-  withOrderBy(col2, direction) {
-    const from = this.state.ast.from;
-    const tableRef = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
-    const node = buildColumnNode(tableRef, col2);
-    return this.state.withOrderBy([{ type: "OrderBy", column: node, direction }]);
+  withOrderBy(term, direction, nulls, collation) {
+    const normalized = this.normalizeOrderingTerm(term);
+    return this.state.withOrderBy([{ type: "OrderBy", term: normalized, direction, nulls, collation }]);
   }
   /**
    * Adds a DISTINCT clause to the query
@@ -2879,6 +2998,24 @@ var QueryAstService = class {
   combineExpressions(existing, next) {
     return existing ? and(existing, next) : next;
   }
+  normalizeOrderingTerm(term) {
+    const from = this.state.ast.from;
+    const tableRef = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
+    const termType = term?.type;
+    if (termType === "Column") {
+      return term;
+    }
+    if (termType === "AliasRef") {
+      return term;
+    }
+    if (isOperandNode(term)) {
+      return term;
+    }
+    if (termType === "BinaryExpression" || termType === "LogicalExpression" || termType === "NullExpression" || termType === "InExpression" || termType === "ExistsExpression" || termType === "BetweenExpression" || termType === "ArithmeticExpression") {
+      return term;
+    }
+    return buildColumnNode(tableRef, term);
+  }
 };
 
 // src/query-builder/relation-projection-helper.ts
@@ -3831,8 +3968,10 @@ var DefaultManyToManyCollection = class {
   attach(target) {
     const entity = this.ensureEntity(target);
     const id = this.extractId(entity);
-    if (id == null) return;
-    if (this.items.some((item) => this.extractId(item) === id)) {
+    if (id != null && this.items.some((item) => this.extractId(item) === id)) {
+      return;
+    }
+    if (id == null && this.items.includes(entity)) {
       return;
     }
     this.items.push(entity);
@@ -4528,8 +4667,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
      * @returns New query builder instance with the subquery selection
   
      */
-  selectSubquery(alias, sub) {
-    const query = this.resolveQueryNode(sub);
+  selectSubquery(alias, sub2) {
+    const query = this.resolveQueryNode(sub2);
     return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
   }
   /**
@@ -4711,16 +4850,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a GROUP BY clause to the query
-  
-     * @param col - Column definition or column node to group by
-  
-     * @returns New query builder instance with the GROUP BY clause
-  
-     */
-  groupBy(col2) {
-    const nextContext = this.applyAst(this.context, (service) => service.withGroupBy(col2));
+   * Adds a GROUP BY clause to the query
+   * @param term - Column definition or ordering term to group by
+   * @returns New query builder instance with the GROUP BY clause
+   */
+  groupBy(term) {
+    const nextContext = this.applyAst(this.context, (service) => service.withGroupBy(term));
     return this.clone(nextContext);
   }
   /**
@@ -4737,18 +4872,18 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds an ORDER BY clause to the query
-  
-     * @param col - Column definition or column node to order by
-  
-     * @param direction - Order direction (defaults to ASC)
-  
-     * @returns New query builder instance with the ORDER BY clause
-  
-     */
-  orderBy(col2, direction = ORDER_DIRECTIONS.ASC) {
-    const nextContext = this.applyAst(this.context, (service) => service.withOrderBy(col2, direction));
+   * Adds an ORDER BY clause to the query
+   * @param term - Column definition or ordering term to order by
+   * @param directionOrOptions - Order direction or options (defaults to ASC)
+   * @returns New query builder instance with the ORDER BY clause
+   */
+  orderBy(term, directionOrOptions = ORDER_DIRECTIONS.ASC) {
+    const options = typeof directionOrOptions === "string" ? { direction: directionOrOptions } : directionOrOptions;
+    const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
+    const nextContext = this.applyAst(
+      this.context,
+      (service) => service.withOrderBy(term, dir, options.nulls, options.collation)
+    );
     return this.clone(nextContext);
   }
   /**
@@ -5159,15 +5294,36 @@ var InsertQueryState = class _InsertQueryState {
       type: "InsertQuery",
       into: createTableNode(table),
       columns: [],
-      values: []
+      source: {
+        type: "InsertValues",
+        rows: []
+      }
     };
   }
   clone(nextAst) {
     return new _InsertQueryState(this.table, nextAst);
   }
+  ensureColumnsFromRow(rows) {
+    if (this.ast.columns.length) return this.ast.columns;
+    return buildColumnNodes(this.table, Object.keys(rows[0]));
+  }
+  appendValues(rows) {
+    if (this.ast.source.type === "InsertValues") {
+      return [...this.ast.source.rows, ...rows];
+    }
+    return rows;
+  }
+  getTableColumns() {
+    const names = Object.keys(this.table.columns);
+    if (!names.length) return [];
+    return buildColumnNodes(this.table, names);
+  }
   withValues(rows) {
     if (!rows.length) return this;
-    const definedColumns = this.ast.columns.length ? this.ast.columns : buildColumnNodes(this.table, Object.keys(rows[0]));
+    if (this.ast.source.type === "InsertSelect") {
+      throw new Error("Cannot mix INSERT ... VALUES with INSERT ... SELECT source.");
+    }
+    const definedColumns = this.ensureColumnsFromRow(rows);
     const newRows = rows.map(
       (row, rowIndex) => definedColumns.map((column) => {
         const rawValue = row[column.name];
@@ -5182,7 +5338,34 @@ var InsertQueryState = class _InsertQueryState {
     return this.clone({
       ...this.ast,
       columns: definedColumns,
-      values: [...this.ast.values, ...newRows]
+      source: {
+        type: "InsertValues",
+        rows: this.appendValues(newRows)
+      }
+    });
+  }
+  withColumns(columns) {
+    if (!columns.length) return this;
+    return this.clone({
+      ...this.ast,
+      columns: [...columns]
+    });
+  }
+  withSelect(query, columns) {
+    const targetColumns = columns.length ? columns : this.ast.columns.length ? this.ast.columns : this.getTableColumns();
+    if (!targetColumns.length) {
+      throw new Error("INSERT ... SELECT requires specifying destination columns.");
+    }
+    if (this.ast.source.type === "InsertValues" && this.ast.source.rows.length) {
+      throw new Error("Cannot mix INSERT ... SELECT with INSERT ... VALUES source.");
+    }
+    return this.clone({
+      ...this.ast,
+      columns: [...targetColumns],
+      source: {
+        type: "InsertSelect",
+        query
+      }
     });
   }
   withReturning(columns) {
@@ -5207,11 +5390,27 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
     if (!rows.length) return this;
     return this.clone(this.state.withValues(rows));
   }
+  columns(...columns) {
+    if (!columns.length) return this;
+    return this.clone(this.state.withColumns(this.resolveColumnNodes(columns)));
+  }
+  fromSelect(query, columns = []) {
+    const ast = this.resolveSelectQuery(query);
+    const nodes = columns.length ? this.resolveColumnNodes(columns) : [];
+    return this.clone(this.state.withSelect(ast, nodes));
+  }
   returning(...columns) {
     if (!columns.length) return this;
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
     return this.clone(this.state.withReturning(nodes));
   }
+  // Helpers for column/AST resolution
+  resolveColumnNodes(columns) {
+    return columns.map((column) => buildColumnNode(this.table, column));
+  }
+  resolveSelectQuery(query) {
+    return typeof query.getAST === "function" ? query.getAST() : query;
+  }
   compile(arg) {
     if (typeof arg.compileInsert === "function") {
       return arg.compileInsert(this.state.ast);
@@ -5245,7 +5444,8 @@ var UpdateQueryState = class _UpdateQueryState {
     this.ast = ast ?? {
       type: "UpdateQuery",
       table: createTableNode(table),
-      set: []
+      set: [],
+      joins: []
     };
   }
   clone(nextAst) {
@@ -5284,6 +5484,27 @@ var UpdateQueryState = class _UpdateQueryState {
       returning: [...columns]
     });
   }
+  withFrom(from) {
+    return this.clone({
+      ...this.ast,
+      from
+    });
+  }
+  withJoin(join) {
+    return this.clone({
+      ...this.ast,
+      joins: [...this.ast.joins ?? [], join]
+    });
+  }
+  withTableAlias(alias) {
+    return this.clone({
+      ...this.ast,
+      table: {
+        ...this.ast.table,
+        alias
+      }
+    });
+  }
 };
 
 // src/query-builder/update.ts
@@ -5295,6 +5516,18 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
   clone(state) {
     return new _UpdateQueryBuilder(this.table, state);
   }
+  as(alias) {
+    return this.clone(this.state.withTableAlias(alias));
+  }
+  from(source) {
+    const tableSource = this.resolveTableSource(source);
+    return this.clone(this.state.withFrom(tableSource));
+  }
+  join(table, condition, kind = JOIN_KINDS.INNER, relationName) {
+    const joinTarget = this.resolveJoinTarget(table);
+    const joinNode = createJoinNode(kind, joinTarget, condition, relationName);
+    return this.clone(this.state.withJoin(joinNode));
+  }
   set(values) {
     return this.clone(this.state.withSet(values));
   }
@@ -5306,6 +5539,16 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
     return this.clone(this.state.withReturning(nodes));
   }
+  resolveTableSource(source) {
+    if (isTableSourceNode(source)) {
+      return source;
+    }
+    return { type: "Table", name: source.name, schema: source.schema };
+  }
+  resolveJoinTarget(table) {
+    if (typeof table === "string") return table;
+    return this.resolveTableSource(table);
+  }
   compile(arg) {
     if (typeof arg.compileUpdate === "function") {
       return arg.compileUpdate(this.state.ast);
@@ -5320,6 +5563,7 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
     return this.state.ast;
   }
 };
+var isTableSourceNode = (source) => typeof source.type === "string";
 
 // src/query-builder/delete-query-state.ts
 var DeleteQueryState = class _DeleteQueryState {
@@ -5327,7 +5571,8 @@ var DeleteQueryState = class _DeleteQueryState {
     this.table = table;
     this.ast = ast ?? {
       type: "DeleteQuery",
-      from: createTableNode(table)
+      from: createTableNode(table),
+      joins: []
     };
   }
   clone(nextAst) {
@@ -5345,6 +5590,27 @@ var DeleteQueryState = class _DeleteQueryState {
       returning: [...columns]
     });
   }
+  withUsing(source) {
+    return this.clone({
+      ...this.ast,
+      using: source
+    });
+  }
+  withJoin(join) {
+    return this.clone({
+      ...this.ast,
+      joins: [...this.ast.joins ?? [], join]
+    });
+  }
+  withTableAlias(alias) {
+    return this.clone({
+      ...this.ast,
+      from: {
+        ...this.ast.from,
+        alias
+      }
+    });
+  }
 };
 
 // src/query-builder/delete.ts
@@ -5359,11 +5625,32 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
   where(expr) {
     return this.clone(this.state.withWhere(expr));
   }
+  as(alias) {
+    return this.clone(this.state.withTableAlias(alias));
+  }
+  using(source) {
+    return this.clone(this.state.withUsing(this.resolveTableSource(source)));
+  }
+  join(table, condition, kind = JOIN_KINDS.INNER, relationName) {
+    const target = this.resolveJoinTarget(table);
+    const joinNode = createJoinNode(kind, target, condition, relationName);
+    return this.clone(this.state.withJoin(joinNode));
+  }
   returning(...columns) {
     if (!columns.length) return this;
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
     return this.clone(this.state.withReturning(nodes));
   }
+  resolveTableSource(source) {
+    if (isTableSourceNode2(source)) {
+      return source;
+    }
+    return { type: "Table", name: source.name, schema: source.schema };
+  }
+  resolveJoinTarget(table) {
+    if (typeof table === "string") return table;
+    return this.resolveTableSource(table);
+  }
   compile(arg) {
     if (typeof arg.compileDelete === "function") {
       return arg.compileDelete(this.state.ast);
@@ -5378,6 +5665,7 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
     return this.state.ast;
   }
 };
+var isTableSourceNode2 = (source) => typeof source.type === "string";
 
 // src/core/ddl/sql-writing.ts
 var resolvePrimaryKey = (table) => {
@@ -6576,7 +6864,7 @@ var TypeScriptGenerator = class {
       lines.push(`.where(${this.printExpression(ast.where)})`);
     }
     if (ast.groupBy && ast.groupBy.length) {
-      const cols = ast.groupBy.map((c) => `${this.namingStrategy.tableToSymbol(c.table)}.${c.name}`).join(", ");
+      const cols = ast.groupBy.map((term) => this.printOrderingTerm(term)).join(", ");
       lines.push(`.groupBy(${cols})`);
     }
     if (ast.having) {
@@ -6584,7 +6872,16 @@ var TypeScriptGenerator = class {
     }
     if (ast.orderBy && ast.orderBy.length) {
       ast.orderBy.forEach((o) => {
-        lines.push(`.orderBy(${this.namingStrategy.tableToSymbol(o.column.table)}.${o.column.name}, '${o.direction}')`);
+        const term = this.printOrderingTerm(o.term);
+        const opts = [`direction: '${o.direction}'`];
+        if (o.nulls) opts.push(`nulls: '${o.nulls}'`);
+        if (o.collation) opts.push(`collation: '${o.collation}'`);
+        const hasOpts = opts.length > 1;
+        if (hasOpts) {
+          lines.push(`.orderBy(${term}, { ${opts.join(", ")} })`);
+        } else {
+          lines.push(`.orderBy(${term}, '${o.direction}')`);
+        }
       });
     }
     if (ast.limit) lines.push(`.limit(${ast.limit})`);
@@ -6607,6 +6904,29 @@ var TypeScriptGenerator = class {
   printOperand(node) {
     return visitOperand(node, this);
   }
+  /**
+   * Prints an ordering term (operand/expression/alias) to TypeScript code.
+   */
+  printOrderingTerm(term) {
+    if (!term || !term.type) {
+      throw new Error("Unsupported ordering term");
+    }
+    switch (term.type) {
+      case "Column":
+        return `${this.namingStrategy.tableToSymbol(term.table)}.${term.name}`;
+      case "AliasRef":
+        return this.visitAliasRef(term);
+      case "Literal":
+      case "Function":
+      case "JsonPath":
+      case "ScalarSubquery":
+      case "CaseExpression":
+      case "WindowFunction":
+        return this.printOperand(term);
+      default:
+        return this.printExpression(term);
+    }
+  }
   visitBinaryExpression(binary) {
     return this.printBinaryExpression(binary);
   }
@@ -6625,6 +6945,9 @@ var TypeScriptGenerator = class {
   visitBetweenExpression(betweenExpr) {
     return this.printBetweenExpression(betweenExpr);
   }
+  visitArithmeticExpression(arithExpr) {
+    return this.printArithmeticExpression(arithExpr);
+  }
   visitColumn(node) {
     return this.printColumnOperand(node);
   }
@@ -6646,6 +6969,9 @@ var TypeScriptGenerator = class {
   visitWindowFunction(node) {
     return this.printWindowFunctionOperand(node);
   }
+  visitAliasRef(node) {
+    return `aliasRef('${node.name}')`;
+  }
   /**
    * Prints a binary expression to TypeScript code
    * @param binary - Binary expression node
@@ -6676,6 +7002,11 @@ var TypeScriptGenerator = class {
     ${parts.join(",\n    ")}
   )`;
   }
+  printArithmeticExpression(expr) {
+    const left2 = this.printOperand(expr.left);
+    const right2 = this.printOperand(expr.right);
+    return `${left2} ${expr.operator} ${right2}`;
+  }
   /**
    * Prints an IN expression to TypeScript code
    * @param inExpr - IN expression node
@@ -6683,9 +7014,13 @@ var TypeScriptGenerator = class {
    */
   printInExpression(inExpr) {
     const left2 = this.printOperand(inExpr.left);
-    const values = inExpr.right.map((v) => this.printOperand(v)).join(", ");
     const fn4 = this.mapOp(inExpr.operator);
-    return `${fn4}(${left2}, [${values}])`;
+    if (Array.isArray(inExpr.right)) {
+      const values = inExpr.right.map((v) => this.printOperand(v)).join(", ");
+      return `${fn4}(${left2}, [${values}])`;
+    }
+    const subquery = this.inlineChain(this.buildSelectLines(inExpr.right.query));
+    return `${fn4}(${left2}, (${subquery}))`;
   }
   /**
    * Prints a null expression to TypeScript code
@@ -6789,7 +7124,12 @@ var TypeScriptGenerator = class {
       parts.push(partitionClause);
     }
     if (node.orderBy && node.orderBy.length > 0) {
-      const orderClause = "ORDER BY " + node.orderBy.map((o) => `${this.namingStrategy.tableToSymbol(o.column.table)}.${o.column.name} ${o.direction}`).join(", ");
+      const orderClause = "ORDER BY " + node.orderBy.map((o) => {
+        const term = this.printOrderingTerm(o.term);
+        const collation = o.collation ? ` COLLATE ${o.collation}` : "";
+        const nulls = o.nulls ? ` NULLS ${o.nulls}` : "";
+        return `${term} ${o.direction}${collation}${nulls}`;
+      }).join(", ");
       parts.push(orderClause);
     }
     result += parts.join(" ");
@@ -6865,6 +7205,13 @@ var EntityStatus = /* @__PURE__ */ ((EntityStatus2) => {
 
 // src/orm/unit-of-work.ts
 var UnitOfWork = class {
+  /**
+   * Creates a new UnitOfWork instance.
+   * @param dialect - The database dialect
+   * @param executor - The database executor
+   * @param identityMap - The identity map
+   * @param hookContext - Function to get the hook context
+   */
   constructor(dialect, executor, identityMap, hookContext) {
     this.dialect = dialect;
     this.executor = executor;
@@ -6872,21 +7219,50 @@ var UnitOfWork = class {
     this.hookContext = hookContext;
     this.trackedEntities = /* @__PURE__ */ new Map();
   }
+  /**
+   * Gets the identity buckets map.
+   */
   get identityBuckets() {
     return this.identityMap.bucketsMap;
   }
+  /**
+   * Gets all tracked entities.
+   * @returns Array of tracked entities
+   */
   getTracked() {
     return Array.from(this.trackedEntities.values());
   }
+  /**
+   * Gets an entity by table and primary key.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @returns The entity or undefined if not found
+   */
   getEntity(table, pk) {
     return this.identityMap.getEntity(table, pk);
   }
+  /**
+   * Gets all tracked entities for a specific table.
+   * @param table - The table definition
+   * @returns Array of tracked entities
+   */
   getEntitiesForTable(table) {
     return this.identityMap.getEntitiesForTable(table);
   }
+  /**
+   * Finds a tracked entity.
+   * @param entity - The entity to find
+   * @returns The tracked entity or undefined if not found
+   */
   findTracked(entity) {
     return this.trackedEntities.get(entity);
   }
+  /**
+   * Sets an entity in the identity map.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @param entity - The entity instance
+   */
   setEntity(table, pk, entity) {
     if (pk === null || pk === void 0) return;
     let tracked = this.trackedEntities.get(entity);
@@ -6904,6 +7280,12 @@ var UnitOfWork = class {
     }
     this.registerIdentity(tracked);
   }
+  /**
+   * Tracks a new entity.
+   * @param table - The table definition
+   * @param entity - The entity instance
+   * @param pk - Optional primary key value
+   */
   trackNew(table, entity, pk) {
     const tracked = {
       table,
@@ -6917,6 +7299,12 @@ var UnitOfWork = class {
       this.registerIdentity(tracked);
     }
   }
+  /**
+   * Tracks a managed entity.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @param entity - The entity instance
+   */
   trackManaged(table, pk, entity) {
     const tracked = {
       table,
@@ -6928,17 +7316,28 @@ var UnitOfWork = class {
     this.trackedEntities.set(entity, tracked);
     this.registerIdentity(tracked);
   }
+  /**
+   * Marks an entity as dirty (modified).
+   * @param entity - The entity to mark as dirty
+   */
   markDirty(entity) {
     const tracked = this.trackedEntities.get(entity);
     if (!tracked) return;
     if (tracked.status === "new" /* New */ || tracked.status === "removed" /* Removed */) return;
     tracked.status = "dirty" /* Dirty */;
   }
+  /**
+   * Marks an entity as removed.
+   * @param entity - The entity to mark as removed
+   */
   markRemoved(entity) {
     const tracked = this.trackedEntities.get(entity);
     if (!tracked) return;
     tracked.status = "removed" /* Removed */;
   }
+  /**
+   * Flushes pending changes to the database.
+   */
   async flush() {
     const toFlush = Array.from(this.trackedEntities.values());
     for (const tracked of toFlush) {
@@ -6957,10 +7356,17 @@ var UnitOfWork = class {
       }
     }
   }
+  /**
+   * Resets the unit of work by clearing all tracked entities and identity map.
+   */
   reset() {
     this.trackedEntities.clear();
     this.identityMap.clear();
   }
+  /**
+   * Flushes an insert operation for a new entity.
+   * @param tracked - The tracked entity to insert
+   */
   async flushInsert(tracked) {
     await this.runHook(tracked.table.hooks?.beforeInsert, tracked);
     const payload = this.extractColumns(tracked.table, tracked.entity);
@@ -6977,6 +7383,10 @@ var UnitOfWork = class {
     this.registerIdentity(tracked);
     await this.runHook(tracked.table.hooks?.afterInsert, tracked);
   }
+  /**
+   * Flushes an update operation for a modified entity.
+   * @param tracked - The tracked entity to update
+   */
   async flushUpdate(tracked) {
     if (tracked.pk == null) return;
     const changes = this.computeChanges(tracked);
@@ -6999,6 +7409,10 @@ var UnitOfWork = class {
     this.registerIdentity(tracked);
     await this.runHook(tracked.table.hooks?.afterUpdate, tracked);
   }
+  /**
+   * Flushes a delete operation for a removed entity.
+   * @param tracked - The tracked entity to delete
+   */
   async flushDelete(tracked) {
     if (tracked.pk == null) return;
     await this.runHook(tracked.table.hooks?.beforeDelete, tracked);
@@ -7012,10 +7426,20 @@ var UnitOfWork = class {
     this.identityMap.remove(tracked);
     await this.runHook(tracked.table.hooks?.afterDelete, tracked);
   }
+  /**
+   * Runs a table hook if defined.
+   * @param hook - The hook function
+   * @param tracked - The tracked entity
+   */
   async runHook(hook, tracked) {
     if (!hook) return;
     await hook(this.hookContext(), tracked.entity);
   }
+  /**
+   * Computes changes between current entity state and original snapshot.
+   * @param tracked - The tracked entity
+   * @returns Object with changed column values
+   */
   computeChanges(tracked) {
     const snapshot = tracked.original ?? {};
     const changes = {};
@@ -7027,6 +7451,12 @@ var UnitOfWork = class {
     }
     return changes;
   }
+  /**
+   * Extracts column values from an entity.
+   * @param table - The table definition
+   * @param entity - The entity instance
+   * @returns Object with column values
+   */
   extractColumns(table, entity) {
     const payload = {};
     for (const column of Object.keys(table.columns)) {
@@ -7035,9 +7465,19 @@ var UnitOfWork = class {
     }
     return payload;
   }
+  /**
+   * Executes a compiled query.
+   * @param compiled - The compiled query
+   * @returns Query results
+   */
   async executeCompiled(compiled) {
     return this.executor.executeSql(compiled.sql, compiled.params);
   }
+  /**
+   * Gets columns for RETURNING clause.
+   * @param table - The table definition
+   * @returns Array of column nodes
+   */
   getReturningColumns(table) {
     return Object.values(table.columns).map((column) => ({
       type: "Column",
@@ -7046,6 +7486,11 @@ var UnitOfWork = class {
       alias: column.name
     }));
   }
+  /**
+   * Applies RETURNING clause results to the tracked entity.
+   * @param tracked - The tracked entity
+   * @param results - Query results
+   */
   applyReturningResults(tracked, results) {
     if (!this.dialect.supportsReturning()) return;
     const first = results[0];
@@ -7057,15 +7502,30 @@ var UnitOfWork = class {
       tracked.entity[columnName] = row[i];
     }
   }
+  /**
+   * Normalizes a column name by removing quotes and table prefixes.
+   * @param column - The column name to normalize
+   * @returns Normalized column name
+   */
   normalizeColumnName(column) {
     const parts = column.split(".");
     const candidate = parts[parts.length - 1];
     return candidate.replace(/^["`[\]]+|["`[\]]+$/g, "");
   }
+  /**
+   * Registers an entity in the identity map.
+   * @param tracked - The tracked entity to register
+   */
   registerIdentity(tracked) {
     if (tracked.pk == null) return;
     this.identityMap.register(tracked);
   }
+  /**
+   * Creates a snapshot of an entity's current state.
+   * @param table - The table definition
+   * @param entity - The entity instance
+   * @returns Object with entity state
+   */
   createSnapshot(table, entity) {
     const snapshot = {};
     for (const column of Object.keys(table.columns)) {
@@ -7073,6 +7533,11 @@ var UnitOfWork = class {
     }
     return snapshot;
   }
+  /**
+   * Gets the primary key value from a tracked entity.
+   * @param tracked - The tracked entity
+   * @returns Primary key value or null
+   */
   getPrimaryKeyValue(tracked) {
     const key = findPrimaryKey(tracked.table);
     const val = tracked.entity[key];
@@ -7083,6 +7548,10 @@ var UnitOfWork = class {
 
 // src/orm/domain-event-bus.ts
 var DomainEventBus = class {
+  /**
+   * Creates a new DomainEventBus instance.
+   * @param initialHandlers - Optional initial event handlers
+   */
   constructor(initialHandlers) {
     this.handlers = /* @__PURE__ */ new Map();
     if (initialHandlers) {
@@ -7093,15 +7562,32 @@ var DomainEventBus = class {
       }
     }
   }
+  /**
+   * Registers an event handler for a specific event type.
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   on(type, handler) {
     const key = type;
     const existing = this.handlers.get(key) ?? [];
     existing.push(handler);
     this.handlers.set(key, existing);
   }
+  /**
+   * Registers an event handler for a specific event type (alias for on).
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   register(type, handler) {
     this.on(type, handler);
   }
+  /**
+   * Dispatches domain events for tracked entities.
+   * @param trackedEntities - Iterable of tracked entities
+   * @param ctx - The context to pass to handlers
+   */
   async dispatch(trackedEntities, ctx) {
     for (const tracked of trackedEntities) {
       const entity = tracked.entity;
@@ -7126,18 +7612,34 @@ var addDomainEvent = (entity, event) => {
 
 // src/orm/relation-change-processor.ts
 var RelationChangeProcessor = class {
+  /**
+   * Creates a new RelationChangeProcessor instance.
+   * @param unitOfWork - The unit of work instance
+   * @param dialect - The database dialect
+   * @param executor - The database executor
+   */
   constructor(unitOfWork, dialect, executor) {
     this.unitOfWork = unitOfWork;
     this.dialect = dialect;
     this.executor = executor;
     this.relationChanges = [];
   }
+  /**
+   * Registers a relation change for processing.
+   * @param entry - The relation change entry
+   */
   registerChange(entry) {
     this.relationChanges.push(entry);
   }
+  /**
+   * Resets the relation change processor by clearing all pending changes.
+   */
   reset() {
     this.relationChanges.length = 0;
   }
+  /**
+   * Processes all pending relation changes.
+   */
   async process() {
     if (!this.relationChanges.length) return;
     const entries = [...this.relationChanges];
@@ -7159,6 +7661,10 @@ var RelationChangeProcessor = class {
       }
     }
   }
+  /**
+   * Handles changes for has-many relations.
+   * @param entry - The relation change entry
+   */
   async handleHasManyChange(entry) {
     const relation = entry.relation;
     const target = entry.change.entity;
@@ -7177,6 +7683,10 @@ var RelationChangeProcessor = class {
       this.detachHasManyChild(tracked.entity, relation);
     }
   }
+  /**
+   * Handles changes for has-one relations.
+   * @param entry - The relation change entry
+   */
   async handleHasOneChange(entry) {
     const relation = entry.relation;
     const target = entry.change.entity;
@@ -7195,8 +7705,16 @@ var RelationChangeProcessor = class {
       this.detachHasOneChild(tracked.entity, relation);
     }
   }
+  /**
+   * Handles changes for belongs-to relations.
+   * @param _entry - The relation change entry (reserved for future use)
+   */
   async handleBelongsToChange(_entry) {
   }
+  /**
+   * Handles changes for belongs-to-many relations.
+   * @param entry - The relation change entry
+   */
   async handleBelongsToManyChange(entry) {
     const relation = entry.relation;
     const rootKey = relation.localKey || findPrimaryKey(entry.rootTable);
@@ -7215,11 +7733,22 @@ var RelationChangeProcessor = class {
       }
     }
   }
+  /**
+   * Assigns a foreign key for has-many relations.
+   * @param child - The child entity
+   * @param relation - The has-many relation
+   * @param rootValue - The root entity's primary key value
+   */
   assignHasManyForeignKey(child, relation, rootValue) {
     const current = child[relation.foreignKey];
     if (current === rootValue) return;
     child[relation.foreignKey] = rootValue;
   }
+  /**
+   * Detaches a child entity from has-many relations.
+   * @param child - The child entity
+   * @param relation - The has-many relation
+   */
   detachHasManyChild(child, relation) {
     if (relation.cascade === "all" || relation.cascade === "remove") {
       this.unitOfWork.markRemoved(child);
@@ -7228,11 +7757,22 @@ var RelationChangeProcessor = class {
     child[relation.foreignKey] = null;
     this.unitOfWork.markDirty(child);
   }
+  /**
+   * Assigns a foreign key for has-one relations.
+   * @param child - The child entity
+   * @param relation - The has-one relation
+   * @param rootValue - The root entity's primary key value
+   */
   assignHasOneForeignKey(child, relation, rootValue) {
     const current = child[relation.foreignKey];
     if (current === rootValue) return;
     child[relation.foreignKey] = rootValue;
   }
+  /**
+   * Detaches a child entity from has-one relations.
+   * @param child - The child entity
+   * @param relation - The has-one relation
+   */
   detachHasOneChild(child, relation) {
     if (relation.cascade === "all" || relation.cascade === "remove") {
       this.unitOfWork.markRemoved(child);
@@ -7241,6 +7781,12 @@ var RelationChangeProcessor = class {
     child[relation.foreignKey] = null;
     this.unitOfWork.markDirty(child);
   }
+  /**
+   * Inserts a pivot row for belongs-to-many relations.
+   * @param relation - The belongs-to-many relation
+   * @param rootId - The root entity's primary key value
+   * @param targetId - The target entity's primary key value
+   */
   async insertPivotRow(relation, rootId, targetId) {
     const payload = {
       [relation.pivotForeignKeyToRoot]: rootId,
@@ -7250,6 +7796,12 @@ var RelationChangeProcessor = class {
     const compiled = builder.compile(this.dialect);
     await this.executor.executeSql(compiled.sql, compiled.params);
   }
+  /**
+   * Deletes a pivot row for belongs-to-many relations.
+   * @param relation - The belongs-to-many relation
+   * @param rootId - The root entity's primary key value
+   * @param targetId - The target entity's primary key value
+   */
   async deletePivotRow(relation, rootId, targetId) {
     const rootCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
     const targetCol = relation.pivotTable.columns[relation.pivotForeignKeyToTarget];
@@ -7260,6 +7812,12 @@ var RelationChangeProcessor = class {
     const compiled = builder.compile(this.dialect);
     await this.executor.executeSql(compiled.sql, compiled.params);
   }
+  /**
+   * Resolves the primary key value from an entity.
+   * @param entity - The entity
+   * @param table - The table definition
+   * @returns The primary key value or null
+   */
   resolvePrimaryKeyValue(entity, table) {
     if (!entity) return null;
     const key = findPrimaryKey(table);
@@ -7275,42 +7833,231 @@ var createQueryLoggingExecutor = (executor, logger) => {
     return executor;
   }
   const wrapped = {
+    capabilities: executor.capabilities,
     async executeSql(sql, params) {
       logger({ sql, params });
       return executor.executeSql(sql, params);
-    }
+    },
+    beginTransaction: () => executor.beginTransaction(),
+    commitTransaction: () => executor.commitTransaction(),
+    rollbackTransaction: () => executor.rollbackTransaction(),
+    dispose: () => executor.dispose()
   };
-  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/transaction-runner.ts
 var runInTransaction = async (executor, action) => {
-  if (!executor.beginTransaction) {
+  if (!executor.capabilities.transactions) {
     await action();
     return;
   }
   await executor.beginTransaction();
   try {
     await action();
-    await executor.commitTransaction?.();
+    await executor.commitTransaction();
   } catch (error) {
-    await executor.rollbackTransaction?.();
+    await executor.rollbackTransaction();
     throw error;
   }
 };
 
+// src/orm/save-graph.ts
+var toKey8 = (value) => value === null || value === void 0 ? "" : String(value);
+var pickColumns = (table, payload) => {
+  const columns = {};
+  for (const key of Object.keys(table.columns)) {
+    if (payload[key] !== void 0) {
+      columns[key] = payload[key];
+    }
+  }
+  return columns;
+};
+var ensureEntity = (session, table, payload) => {
+  const pk = findPrimaryKey(table);
+  const row = pickColumns(table, payload);
+  const pkValue = payload[pk];
+  if (pkValue !== void 0 && pkValue !== null) {
+    const tracked = session.getEntity(table, pkValue);
+    if (tracked) {
+      return tracked;
+    }
+    if (row[pk] === void 0) {
+      row[pk] = pkValue;
+    }
+  }
+  return createEntityFromRow(session, table, row);
+};
+var assignColumns = (table, entity, payload) => {
+  for (const key of Object.keys(table.columns)) {
+    if (payload[key] !== void 0) {
+      entity[key] = payload[key];
+    }
+  }
+};
+var isEntityInCollection = (items, pkName, entity) => {
+  if (items.includes(entity)) return true;
+  const entityPk = entity[pkName];
+  if (entityPk === void 0 || entityPk === null) return false;
+  return items.some((item) => toKey8(item[pkName]) === toKey8(entityPk));
+};
+var findInCollectionByPk = (items, pkName, pkValue) => {
+  if (pkValue === void 0 || pkValue === null) return void 0;
+  return items.find((item) => toKey8(item[pkName]) === toKey8(pkValue));
+};
+var handleHasMany = async (session, root, relationName, relation, payload, options) => {
+  if (!Array.isArray(payload)) return;
+  const collection = root[relationName];
+  await collection.load();
+  const targetTable = relation.target;
+  const targetPk = findPrimaryKey(targetTable);
+  const existing = collection.getItems();
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of payload) {
+    if (item === null || item === void 0) continue;
+    const asObj = typeof item === "object" ? item : { [targetPk]: item };
+    const pkValue = asObj[targetPk];
+    const current = findInCollectionByPk(existing, targetPk, pkValue) ?? (pkValue !== void 0 && pkValue !== null ? session.getEntity(targetTable, pkValue) : void 0);
+    const entity = current ?? ensureEntity(session, targetTable, asObj);
+    assignColumns(targetTable, entity, asObj);
+    await applyGraphToEntity(session, targetTable, entity, asObj, options);
+    if (!isEntityInCollection(collection.getItems(), targetPk, entity)) {
+      collection.attach(entity);
+    }
+    if (pkValue !== void 0 && pkValue !== null) {
+      seen.add(toKey8(pkValue));
+    }
+  }
+  if (options.pruneMissing) {
+    for (const item of [...collection.getItems()]) {
+      const pkValue = item[targetPk];
+      if (pkValue !== void 0 && pkValue !== null && !seen.has(toKey8(pkValue))) {
+        collection.remove(item);
+      }
+    }
+  }
+};
+var handleHasOne = async (session, root, relationName, relation, payload, options) => {
+  const ref = root[relationName];
+  if (payload === void 0) return;
+  if (payload === null) {
+    ref.set(null);
+    return;
+  }
+  const pk = findPrimaryKey(relation.target);
+  if (typeof payload === "number" || typeof payload === "string") {
+    const entity = ref.set({ [pk]: payload });
+    if (entity) {
+      await applyGraphToEntity(session, relation.target, entity, { [pk]: payload }, options);
+    }
+    return;
+  }
+  const attached = ref.set(payload);
+  if (attached) {
+    await applyGraphToEntity(session, relation.target, attached, payload, options);
+  }
+};
+var handleBelongsTo = async (session, root, relationName, relation, payload, options) => {
+  const ref = root[relationName];
+  if (payload === void 0) return;
+  if (payload === null) {
+    ref.set(null);
+    return;
+  }
+  const pk = relation.localKey || findPrimaryKey(relation.target);
+  if (typeof payload === "number" || typeof payload === "string") {
+    const entity = ref.set({ [pk]: payload });
+    if (entity) {
+      await applyGraphToEntity(session, relation.target, entity, { [pk]: payload }, options);
+    }
+    return;
+  }
+  const attached = ref.set(payload);
+  if (attached) {
+    await applyGraphToEntity(session, relation.target, attached, payload, options);
+  }
+};
+var handleBelongsToMany = async (session, root, relationName, relation, payload, options) => {
+  if (!Array.isArray(payload)) return;
+  const collection = root[relationName];
+  await collection.load();
+  const targetTable = relation.target;
+  const targetPk = relation.targetKey || findPrimaryKey(targetTable);
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of payload) {
+    if (item === null || item === void 0) continue;
+    if (typeof item === "number" || typeof item === "string") {
+      const id = item;
+      collection.attach(id);
+      seen.add(toKey8(id));
+      continue;
+    }
+    const asObj = item;
+    const pkValue = asObj[targetPk];
+    const entity = pkValue !== void 0 && pkValue !== null ? session.getEntity(targetTable, pkValue) ?? ensureEntity(session, targetTable, asObj) : ensureEntity(session, targetTable, asObj);
+    assignColumns(targetTable, entity, asObj);
+    await applyGraphToEntity(session, targetTable, entity, asObj, options);
+    if (!isEntityInCollection(collection.getItems(), targetPk, entity)) {
+      collection.attach(entity);
+    }
+    if (pkValue !== void 0 && pkValue !== null) {
+      seen.add(toKey8(pkValue));
+    }
+  }
+  if (options.pruneMissing) {
+    for (const item of [...collection.getItems()]) {
+      const pkValue = item[targetPk];
+      if (pkValue !== void 0 && pkValue !== null && !seen.has(toKey8(pkValue))) {
+        collection.detach(item);
+      }
+    }
+  }
+};
+var applyRelation = async (session, table, entity, relationName, relation, payload, options) => {
+  switch (relation.type) {
+    case RelationKinds.HasMany:
+      return handleHasMany(session, entity, relationName, relation, payload, options);
+    case RelationKinds.HasOne:
+      return handleHasOne(session, entity, relationName, relation, payload, options);
+    case RelationKinds.BelongsTo:
+      return handleBelongsTo(session, entity, relationName, relation, payload, options);
+    case RelationKinds.BelongsToMany:
+      return handleBelongsToMany(session, entity, relationName, relation, payload, options);
+  }
+};
+var applyGraphToEntity = async (session, table, entity, payload, options) => {
+  assignColumns(table, entity, payload);
+  for (const [relationName, relation] of Object.entries(table.relations)) {
+    if (!(relationName in payload)) continue;
+    await applyRelation(session, table, entity, relationName, relation, payload[relationName], options);
+  }
+};
+var saveGraphInternal = async (session, entityClass, payload, options = {}) => {
+  const table = getTableDefFromEntity(entityClass);
+  if (!table) {
+    throw new Error("Entity metadata has not been bootstrapped");
+  }
+  const root = ensureEntity(session, table, payload);
+  await applyGraphToEntity(session, table, root, payload, options);
+  return root;
+};
+
 // src/orm/orm-session.ts
 var OrmSession = class {
+  /**
+   * Creates a new OrmSession instance.
+   * @param opts - Session options
+   */
   constructor(opts) {
+    /**
+     * Registers a relation change.
+     * @param root - The root entity
+     * @param relationKey - The relation key
+     * @param rootTable - The root table definition
+     * @param relationName - The relation name
+     * @param relation - The relation definition
+     * @param change - The relation change
+     */
     this.registerRelationChange = (root, relationKey, rootTable, relationName, relation, change) => {
       this.relationChanges.registerChange(
         buildRelationChangeEntry(root, relationKey, rootTable, relationName, relation, change)
@@ -7324,42 +8071,117 @@ var OrmSession = class {
     this.relationChanges = new RelationChangeProcessor(this.unitOfWork, this.orm.dialect, this.executor);
     this.domainEvents = new DomainEventBus(opts.domainEventHandlers);
   }
+  /**
+   * Releases resources associated with this session (executor/pool leases) and resets tracking.
+   * Must be safe to call multiple times.
+   */
+  async dispose() {
+    try {
+      await this.executor.dispose();
+    } finally {
+      this.unitOfWork.reset();
+      this.relationChanges.reset();
+    }
+  }
+  /**
+   * Gets the database dialect.
+   */
   get dialect() {
     return this.orm.dialect;
   }
+  /**
+   * Gets the identity buckets map.
+   */
   get identityBuckets() {
     return this.unitOfWork.identityBuckets;
   }
+  /**
+   * Gets all tracked entities.
+   */
   get tracked() {
     return this.unitOfWork.getTracked();
   }
+  /**
+   * Gets an entity by table and primary key.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @returns The entity or undefined if not found
+   */
   getEntity(table, pk) {
     return this.unitOfWork.getEntity(table, pk);
   }
+  /**
+   * Sets an entity in the identity map.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @param entity - The entity instance
+   */
   setEntity(table, pk, entity) {
     this.unitOfWork.setEntity(table, pk, entity);
   }
+  /**
+   * Tracks a new entity.
+   * @param table - The table definition
+   * @param entity - The entity instance
+   * @param pk - Optional primary key value
+   */
   trackNew(table, entity, pk) {
     this.unitOfWork.trackNew(table, entity, pk);
   }
+  /**
+   * Tracks a managed entity.
+   * @param table - The table definition
+   * @param pk - The primary key value
+   * @param entity - The entity instance
+   */
   trackManaged(table, pk, entity) {
     this.unitOfWork.trackManaged(table, pk, entity);
   }
+  /**
+   * Marks an entity as dirty (modified).
+   * @param entity - The entity to mark as dirty
+   */
   markDirty(entity) {
     this.unitOfWork.markDirty(entity);
   }
+  /**
+   * Marks an entity as removed.
+   * @param entity - The entity to mark as removed
+   */
   markRemoved(entity) {
     this.unitOfWork.markRemoved(entity);
   }
+  /**
+   * Gets all tracked entities for a specific table.
+   * @param table - The table definition
+   * @returns Array of tracked entities
+   */
   getEntitiesForTable(table) {
     return this.unitOfWork.getEntitiesForTable(table);
   }
+  /**
+   * Registers an interceptor for flush lifecycle hooks.
+   * @param interceptor - The interceptor to register
+   */
   registerInterceptor(interceptor) {
     this.interceptors.push(interceptor);
   }
+  /**
+   * Registers a domain event handler.
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   registerDomainEventHandler(type, handler) {
     this.domainEvents.on(type, handler);
   }
+  /**
+   * Finds an entity by its primary key.
+   * @template TCtor - The entity constructor type
+   * @param entityClass - The entity constructor
+   * @param id - The primary key value
+   * @returns The entity instance or null if not found
+   * @throws If entity metadata is not bootstrapped or table has no primary key
+   */
   async find(entityClass, id) {
     const table = getTableDefFromEntity(entityClass);
     if (!table) {
@@ -7378,14 +8200,46 @@ var OrmSession = class {
     const rows = await executeHydrated(this, qb);
     return rows[0] ?? null;
   }
+  /**
+   * Finds a single entity using a query builder.
+   * @template TTable - The table type
+   * @param qb - The query builder
+   * @returns The first entity instance or null if not found
+   */
   async findOne(qb) {
     const limited = qb.limit(1);
     const rows = await executeHydrated(this, limited);
     return rows[0] ?? null;
   }
+  /**
+   * Finds multiple entities using a query builder.
+   * @template TTable - The table type
+   * @param qb - The query builder
+   * @returns Array of entity instances
+   */
   async findMany(qb) {
     return executeHydrated(this, qb);
   }
+  /**
+   * Saves an entity graph (root + nested relations) based on a DTO-like payload.
+   * @param entityClass - Root entity constructor
+   * @param payload - DTO payload containing column values and nested relations
+   * @param options - Graph save options
+   * @returns The root entity instance
+   */
+  async saveGraph(entityClass, payload, options) {
+    const { transactional = true, ...graphOptions } = options ?? {};
+    const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
+    if (!transactional) {
+      return execute();
+    }
+    return this.transaction(() => execute());
+  }
+  /**
+   * Persists an entity (either inserts or updates).
+   * @param entity - The entity to persist
+   * @throws If entity metadata is not bootstrapped
+   */
   async persist(entity) {
     if (this.unitOfWork.findTracked(entity)) {
       return;
@@ -7402,12 +8256,22 @@ var OrmSession = class {
       this.trackNew(table, entity);
     }
   }
+  /**
+   * Marks an entity for removal.
+   * @param entity - The entity to remove
+   */
   async remove(entity) {
     this.markRemoved(entity);
   }
+  /**
+   * Flushes pending changes to the database.
+   */
   async flush() {
     await this.unitOfWork.flush();
   }
+  /**
+   * Flushes pending changes with interceptors and relation processing.
+   */
   async flushWithHooks() {
     for (const interceptor of this.interceptors) {
       await interceptor.beforeFlush?.(this);
@@ -7419,14 +8283,24 @@ var OrmSession = class {
       await interceptor.afterFlush?.(this);
     }
   }
+  /**
+   * Commits the current transaction.
+   */
   async commit() {
     await runInTransaction(this.executor, async () => {
       await this.flushWithHooks();
     });
     await this.domainEvents.dispatch(this.unitOfWork.getTracked(), this);
   }
+  /**
+   * Executes a function within a transaction.
+   * @template T - The return type
+   * @param fn - The function to execute
+   * @returns The result of the function
+   * @throws If the transaction fails
+   */
   async transaction(fn4) {
-    if (!this.executor.beginTransaction) {
+    if (!this.executor.capabilities.transactions) {
       const result = await fn4(this);
       await this.commit();
       return result;
@@ -7435,7 +8309,7 @@ var OrmSession = class {
     try {
       const result = await fn4(this);
       await this.flushWithHooks();
-      await this.executor.commitTransaction?.();
+      await this.executor.commitTransaction();
       await this.domainEvents.dispatch(this.unitOfWork.getTracked(), this);
       return result;
     } catch (err) {
@@ -7443,11 +8317,20 @@ var OrmSession = class {
       throw err;
     }
   }
+  /**
+   * Rolls back the current transaction.
+   */
   async rollback() {
-    await this.executor.rollbackTransaction?.();
+    if (this.executor.capabilities.transactions) {
+      await this.executor.rollbackTransaction();
+    }
     this.unitOfWork.reset();
     this.relationChanges.reset();
   }
+  /**
+   * Gets the execution context.
+   * @returns The execution context
+   */
   getExecutionContext() {
     return {
       dialect: this.orm.dialect,
@@ -7455,6 +8338,10 @@ var OrmSession = class {
       interceptors: this.orm.interceptors
     };
   }
+  /**
+   * Gets the hydration context.
+   * @returns The hydration context
+   */
   getHydrationContext() {
     return {
       identityMap: this.identityMap,
@@ -7497,29 +8384,49 @@ var InterceptorPipeline = class {
 
 // src/orm/orm.ts
 var Orm = class {
+  /**
+   * Creates a new ORM instance.
+   * @param opts - ORM options
+   */
   constructor(opts) {
     this.dialect = opts.dialect;
     this.interceptors = opts.interceptors ?? new InterceptorPipeline();
     this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
     this.executorFactory = opts.executorFactory;
   }
-  createSession(options) {
-    const executor = this.executorFactory.createExecutor(options?.tx);
+  /**
+   * Creates a new ORM session.
+   * @param options - Optional session options
+   * @returns The ORM session
+   */
+  createSession() {
+    const executor = this.executorFactory.createExecutor();
     return new OrmSession({ orm: this, executor });
   }
+  /**
+   * Executes a function within a transaction.
+   * @template T - The return type
+   * @param fn - The function to execute
+   * @returns The result of the function
+   * @throws If the transaction fails
+   */
   async transaction(fn4) {
     const executor = this.executorFactory.createTransactionalExecutor();
     const session = new OrmSession({ orm: this, executor });
     try {
-      const result = await fn4(session);
-      await session.commit();
-      return result;
+      return await session.transaction(() => fn4(session));
     } catch (err) {
-      await session.rollback();
       throw err;
     } finally {
+      await session.dispose();
     }
   }
+  /**
+   * Shuts down the ORM and releases underlying resources (pools, timers).
+   */
+  async dispose() {
+    await this.executorFactory.dispose();
+  }
 };
 
 // src/decorators/decorator-metadata.ts
@@ -7778,18 +8685,245 @@ function rowsToQueryResult(rows) {
   return { columns, values };
 }
 function createExecutorFromQueryRunner(runner) {
+  const supportsTransactions = typeof runner.beginTransaction === "function" && typeof runner.commitTransaction === "function" && typeof runner.rollbackTransaction === "function";
   return {
+    capabilities: {
+      transactions: supportsTransactions
+    },
     async executeSql(sql, params) {
       const rows = await runner.query(sql, params);
       const result = rowsToQueryResult(rows);
       return [result];
     },
-    beginTransaction: runner.beginTransaction?.bind(runner),
-    commitTransaction: runner.commitTransaction?.bind(runner),
-    rollbackTransaction: runner.rollbackTransaction?.bind(runner)
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.beginTransaction.call(runner);
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.commitTransaction.call(runner);
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.rollbackTransaction.call(runner);
+    },
+    async dispose() {
+      await runner.dispose?.call(runner);
+    }
   };
 }
 
+// src/core/execution/pooling/pool.ts
+var deferred = () => {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+var Pool = class {
+  constructor(adapter, options) {
+    this.destroyed = false;
+    this.creating = 0;
+    this.leased = 0;
+    this.idle = [];
+    this.waiters = [];
+    this.reapTimer = null;
+    if (!Number.isFinite(options.max) || options.max <= 0) {
+      throw new Error("Pool options.max must be a positive number");
+    }
+    this.adapter = adapter;
+    this.options = { max: options.max, ...options };
+    const idleTimeout = this.options.idleTimeoutMillis;
+    if (idleTimeout && idleTimeout > 0) {
+      const interval = this.options.reapIntervalMillis ?? Math.max(1e3, Math.floor(idleTimeout / 2));
+      this.reapTimer = setInterval(() => {
+        void this.reapIdle();
+      }, interval);
+      this.reapTimer.unref?.();
+    }
+    const min2 = this.options.min ?? 0;
+    if (min2 > 0) {
+      void this.warm(min2);
+    }
+  }
+  /**
+   * Acquire a resource lease.
+   * The returned lease MUST be released or destroyed.
+   */
+  async acquire() {
+    if (this.destroyed) {
+      throw new Error("Pool is destroyed");
+    }
+    const idle = await this.takeIdleValidated();
+    if (idle) {
+      this.leased++;
+      return this.makeLease(idle);
+    }
+    if (this.totalLive() < this.options.max) {
+      this.creating++;
+      try {
+        const created = await this.adapter.create();
+        this.leased++;
+        return this.makeLease(created);
+      } finally {
+        this.creating--;
+      }
+    }
+    const waiter = deferred();
+    this.waiters.push(waiter);
+    const timeout = this.options.acquireTimeoutMillis;
+    let timer = null;
+    if (timeout && timeout > 0) {
+      timer = setTimeout(() => {
+        const idx = this.waiters.indexOf(waiter);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+        waiter.reject(new Error("Pool acquire timeout"));
+      }, timeout);
+      timer.unref?.();
+    }
+    try {
+      return await waiter.promise;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  /** Destroy pool and all idle resources; waits for in-flight creations to settle. */
+  async destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.reapTimer) {
+      clearInterval(this.reapTimer);
+      this.reapTimer = null;
+    }
+    while (this.waiters.length) {
+      this.waiters.shift().reject(new Error("Pool destroyed"));
+    }
+    while (this.idle.length) {
+      const entry = this.idle.shift();
+      await this.adapter.destroy(entry.resource);
+    }
+  }
+  totalLive() {
+    return this.idle.length + this.leased + this.creating;
+  }
+  makeLease(resource) {
+    let done = false;
+    return {
+      resource,
+      release: async () => {
+        if (done) return;
+        done = true;
+        await this.releaseResource(resource);
+      },
+      destroy: async () => {
+        if (done) return;
+        done = true;
+        await this.destroyResource(resource);
+      }
+    };
+  }
+  async releaseResource(resource) {
+    this.leased = Math.max(0, this.leased - 1);
+    if (this.destroyed) {
+      await this.adapter.destroy(resource);
+      return;
+    }
+    const next = this.waiters.shift();
+    if (next) {
+      this.leased++;
+      next.resolve(this.makeLease(resource));
+      return;
+    }
+    this.idle.push({ resource, lastUsedAt: Date.now() });
+    await this.trimToMinMax();
+  }
+  async destroyResource(resource) {
+    this.leased = Math.max(0, this.leased - 1);
+    await this.adapter.destroy(resource);
+    if (!this.destroyed && this.waiters.length && this.totalLive() < this.options.max) {
+      const waiter = this.waiters.shift();
+      this.creating++;
+      try {
+        const created = await this.adapter.create();
+        this.leased++;
+        waiter.resolve(this.makeLease(created));
+      } catch (err) {
+        waiter.reject(err);
+      } finally {
+        this.creating--;
+      }
+    }
+  }
+  async takeIdleValidated() {
+    while (this.idle.length) {
+      const entry = this.idle.pop();
+      if (!this.adapter.validate) {
+        return entry.resource;
+      }
+      const ok = await this.adapter.validate(entry.resource);
+      if (ok) {
+        return entry.resource;
+      }
+      await this.adapter.destroy(entry.resource);
+    }
+    return null;
+  }
+  async reapIdle() {
+    if (this.destroyed) return;
+    const idleTimeout = this.options.idleTimeoutMillis;
+    if (!idleTimeout || idleTimeout <= 0) return;
+    const now2 = Date.now();
+    const min2 = this.options.min ?? 0;
+    const keep = [];
+    const kill = [];
+    for (const entry of this.idle) {
+      const expired = now2 - entry.lastUsedAt >= idleTimeout;
+      if (expired) kill.push(entry);
+      else keep.push(entry);
+    }
+    while (keep.length < min2 && kill.length) {
+      keep.push(kill.pop());
+    }
+    this.idle.length = 0;
+    this.idle.push(...keep);
+    for (const entry of kill) {
+      await this.adapter.destroy(entry.resource);
+    }
+  }
+  async warm(targetMin) {
+    const min2 = Math.max(0, targetMin);
+    while (!this.destroyed && this.idle.length < min2 && this.totalLive() < this.options.max) {
+      this.creating++;
+      try {
+        const created = await this.adapter.create();
+        this.idle.push({ resource: created, lastUsedAt: Date.now() });
+      } catch {
+        break;
+      } finally {
+        this.creating--;
+      }
+    }
+  }
+  async trimToMinMax() {
+    const max2 = this.options.max;
+    const min2 = this.options.min ?? 0;
+    while (this.totalLive() > max2 && this.idle.length > min2) {
+      const entry = this.idle.shift();
+      if (!entry) break;
+      await this.adapter.destroy(entry.resource);
+    }
+  }
+};
+
 // src/core/execution/executors/postgres-executor.ts
 function createPostgresExecutor(client) {
   return createExecutorFromQueryRunner({
@@ -7811,7 +8945,11 @@ function createPostgresExecutor(client) {
 
 // src/core/execution/executors/mysql-executor.ts
 function createMysqlExecutor(client) {
+  const supportsTransactions = typeof client.beginTransaction === "function" && typeof client.commit === "function" && typeof client.rollback === "function";
   return {
+    capabilities: {
+      transactions: supportsTransactions
+    },
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params);
       if (!Array.isArray(rows)) {
@@ -7823,53 +8961,94 @@ function createMysqlExecutor(client) {
       return [result];
     },
     async beginTransaction() {
-      if (!client.beginTransaction) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.beginTransaction();
     },
     async commitTransaction() {
-      if (!client.commit) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.commit();
     },
     async rollbackTransaction() {
-      if (!client.rollback) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.rollback();
+    },
+    async dispose() {
     }
   };
 }
 
 // src/core/execution/executors/sqlite-executor.ts
 function createSqliteExecutor(client) {
+  const supportsTransactions = typeof client.beginTransaction === "function" && typeof client.commitTransaction === "function" && typeof client.rollbackTransaction === "function";
   return {
+    capabilities: {
+      transactions: supportsTransactions
+    },
     async executeSql(sql, params) {
       const rows = await client.all(sql, params);
       const result = rowsToQueryResult(rows);
       return [result];
     },
-    beginTransaction: client.beginTransaction?.bind(client),
-    commitTransaction: client.commitTransaction?.bind(client),
-    rollbackTransaction: client.rollbackTransaction?.bind(client)
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await client.beginTransaction();
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await client.commitTransaction();
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await client.rollbackTransaction();
+    },
+    async dispose() {
+    }
   };
 }
 
 // src/core/execution/executors/mssql-executor.ts
 function createMssqlExecutor(client) {
+  const supportsTransactions = typeof client.beginTransaction === "function" && typeof client.commit === "function" && typeof client.rollback === "function";
   return {
+    capabilities: {
+      transactions: supportsTransactions
+    },
     async executeSql(sql, params) {
       const { recordset } = await client.query(sql, params);
       const result = rowsToQueryResult(recordset ?? []);
       return [result];
     },
     async beginTransaction() {
-      if (!client.beginTransaction) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.beginTransaction();
     },
     async commitTransaction() {
-      if (!client.commit) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.commit();
     },
     async rollbackTransaction() {
-      if (!client.rollback) return;
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
       await client.rollback();
+    },
+    async dispose() {
     }
   };
 }
@@ -7938,6 +9117,86 @@ function createTediousExecutor(connection, module, options) {
   const client = createTediousMssqlClient(connection, module, options);
   return createMssqlExecutor(client);
 }
+
+// src/orm/pooled-executor-factory.ts
+function createPooledExecutorFactory(opts) {
+  const { pool, adapter } = opts;
+  const makeExecutor = (mode) => {
+    let lease = null;
+    const getLease = async () => {
+      if (lease) return lease;
+      lease = await pool.acquire();
+      return lease;
+    };
+    const executeWithConn = async (conn, sql, params) => {
+      const rows = await adapter.query(conn, sql, params);
+      return [rowsToQueryResult(rows)];
+    };
+    return {
+      capabilities: { transactions: true },
+      async executeSql(sql, params) {
+        if (mode === "sticky") {
+          const l2 = await getLease();
+          return executeWithConn(l2.resource, sql, params);
+        }
+        if (lease) {
+          return executeWithConn(lease.resource, sql, params);
+        }
+        const l = await pool.acquire();
+        try {
+          return await executeWithConn(l.resource, sql, params);
+        } finally {
+          await l.release();
+        }
+      },
+      async beginTransaction() {
+        const l = await getLease();
+        await adapter.beginTransaction(l.resource);
+      },
+      async commitTransaction() {
+        if (!lease) {
+          throw new Error("commitTransaction called without an active transaction");
+        }
+        const l = lease;
+        try {
+          await adapter.commitTransaction(l.resource);
+        } finally {
+          lease = null;
+          await l.release();
+        }
+      },
+      async rollbackTransaction() {
+        if (!lease) {
+          return;
+        }
+        const l = lease;
+        try {
+          await adapter.rollbackTransaction(l.resource);
+        } finally {
+          lease = null;
+          await l.release();
+        }
+      },
+      async dispose() {
+        if (!lease) return;
+        const l = lease;
+        lease = null;
+        await l.release();
+      }
+    };
+  };
+  return {
+    createExecutor() {
+      return makeExecutor("session");
+    },
+    createTransactionalExecutor() {
+      return makeExecutor("sticky");
+    },
+    async dispose() {
+      await pool.destroy();
+    }
+  };
+}
 export {
   AsyncLocalStorage,
   BelongsTo,
@@ -7956,6 +9215,7 @@ export {
   MySqlDialect,
   Orm,
   OrmSession,
+  Pool,
   PostgresDialect,
   PrimaryKey,
   RelationKinds,
@@ -7966,7 +9226,9 @@ export {
   UpdateQueryBuilder,
   abs,
   acos,
+  add,
   addDomainEvent,
+  aliasRef,
   and,
   ascii,
   asin,
@@ -7999,6 +9261,7 @@ export {
   createLiteral,
   createMssqlExecutor,
   createMysqlExecutor,
+  createPooledExecutorFactory,
   createPostgresExecutor,
   createQueryLoggingExecutor,
   createSqliteExecutor,
@@ -8017,6 +9280,7 @@ export {
   degrees,
   denseRank,
   diffSchema,
+  div,
   endOfMonth,
   eq,
   esel,
@@ -8039,6 +9303,7 @@ export {
   hasOne,
   hydrateRows,
   inList,
+  inSubquery,
   instr,
   introspectSchema,
   isCaseExpressionNode,
@@ -8074,10 +9339,12 @@ export {
   min,
   mod,
   month,
+  mul,
   neq,
   notBetween,
   notExists,
   notInList,
+  notInSubquery,
   notLike,
   now,
   ntile,
@@ -8109,6 +9376,7 @@ export {
   sin,
   space,
   sqrt,
+  sub,
   substr,
   sum,
   synchronizeSchema,