metal-orm 1.0.42 → 1.0.44

package/dist/index.js

@@ -32,7 +32,8 @@ var init_schema_plan_executor = __esm({
 // src/schema/table.ts
 var defineTable = (name, columns, relations = {}, hooks, options = {}) => {
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
-    acc[key] = { ...def, name: key, table: name };
+    const colDef = { ...def, name: key, table: name };
+    acc[key] = colDef;
     return acc;
   }, {});
   return {
@@ -56,17 +57,20 @@ var withColumnProps = (table) => {
   if (cached) return cached;
   const proxy = new Proxy(table, {
     get(target, prop, receiver) {
-      if (prop === "$") return target.columns;
+      const t = target;
+      if (prop === "$") return t.columns;
       if (Reflect.has(target, prop)) return Reflect.get(target, prop, receiver);
-      if (typeof prop === "string" && prop in target.columns) return target.columns[prop];
+      if (typeof prop === "string" && prop in t.columns) return t.columns[prop];
       return void 0;
     },
     has(target, prop) {
-      return prop === "$" || Reflect.has(target, prop) || typeof prop === "string" && prop in target.columns;
+      const t = target;
+      return prop === "$" || Reflect.has(target, prop) || typeof prop === "string" && prop in t.columns;
     },
     ownKeys(target) {
+      const t = target;
       const base = Reflect.ownKeys(target);
-      const cols = Object.keys(target.columns);
+      const cols = Object.keys(t.columns);
       for (const k of cols) {
         if (!base.includes(k)) base.push(k);
       }
@@ -98,6 +102,14 @@ var withColumnProps = (table) => {
   return proxy;
 };
 var tableRef = (table) => withColumnProps(table);
+function getColumn(table, key) {
+  const col2 = table.columns[key];
+  if (!col2) {
+    const tableName = table.name || "<unknown>";
+    throw new Error(`Column '${key}' does not exist on table '${tableName}'`);
+  }
+  return col2;
+}
 
 // src/schema/column.ts
 var col = {
@@ -302,46 +314,59 @@ var operandTypes = /* @__PURE__ */ new Set([
   "CaseExpression",
   "WindowFunction"
 ]);
-var isOperandNode = (node) => node && operandTypes.has(node.type);
-var isFunctionNode = (node) => node?.type === "Function";
-var isCaseExpressionNode = (node) => node?.type === "CaseExpression";
-var isWindowFunctionNode = (node) => node?.type === "WindowFunction";
+var hasTypeProperty = (value) => typeof value === "object" && value !== null && "type" in value;
+var isOperandNode = (node) => {
+  if (!hasTypeProperty(node)) return false;
+  return operandTypes.has(node.type);
+};
+var isFunctionNode = (node) => isOperandNode(node) && node.type === "Function";
+var isCaseExpressionNode = (node) => isOperandNode(node) && node.type === "CaseExpression";
+var isWindowFunctionNode = (node) => isOperandNode(node) && node.type === "WindowFunction";
 var isExpressionSelectionNode = (node) => isFunctionNode(node) || isCaseExpressionNode(node) || isWindowFunctionNode(node);
 
 // src/core/ast/expression-builders.ts
-var valueToOperand = (value) => {
-  if (isOperandNode(value)) {
-    return value;
-  }
-  return {
-    type: "Literal",
-    value
-  };
-};
-var toNode = (col2) => {
-  if (isOperandNode(col2)) return col2;
-  const def = col2;
-  return { type: "Column", table: def.table || "unknown", name: def.name };
-};
+var isLiteralValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 var toLiteralNode = (value) => ({
   type: "Literal",
   value
 });
-var isLiteralValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
-var isValueOperandInput = (value) => isOperandNode(value) || isLiteralValue(value);
-var toOperand = (val) => {
-  if (isLiteralValue(val)) {
-    return valueToOperand(val);
+var columnRefToNode = (col2) => {
+  if (!col2.table) {
+    throw new Error(
+      `Column "${col2.name}" requires a table reference. Use columnOperand with a fully qualified ColumnRef or ColumnNode.`
+    );
   }
-  return toNode(val);
+  return { type: "Column", table: col2.table, name: col2.name };
 };
+var toOperandNode = (value) => {
+  if (isOperandNode(value)) {
+    return value;
+  }
+  if (isLiteralValue(value)) {
+    return toLiteralNode(value);
+  }
+  return columnRefToNode(value);
+};
+var valueToOperand = (value) => {
+  if (isOperandNode(value)) {
+    return value;
+  }
+  return toLiteralNode(value);
+};
+var toOperand = (val) => toOperandNode(val);
+var isValueOperandInput = (value) => isOperandNode(value) || isLiteralValue(value);
 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 columnOperand = (col2) => {
+  if (isOperandNode(col2) && col2.type === "Column") {
+    return col2;
+  }
+  return columnRefToNode(col2);
+};
 var outerRef = (col2) => ({
   ...columnOperand(col2),
   scope: "outer"
@@ -354,7 +379,7 @@ var correlateBy = (table, column) => outerRef({ name: column, table });
 var createBinaryExpression = (operator, left2, right2, escape) => {
   const node = {
     type: "BinaryExpression",
-    left: toNode(left2),
+    left: toOperandNode(left2),
     operator,
     right: toOperand(right2)
   };
@@ -383,17 +408,17 @@ var or = (...operands) => ({
 });
 var isNull = (left2) => ({
   type: "NullExpression",
-  left: toNode(left2),
+  left: toOperandNode(left2),
   operator: "IS NULL"
 });
 var isNotNull = (left2) => ({
   type: "NullExpression",
-  left: toNode(left2),
+  left: toOperandNode(left2),
   operator: "IS NOT NULL"
 });
 var createInExpression = (operator, left2, right2) => ({
   type: "InExpression",
-  left: toNode(left2),
+  left: toOperandNode(left2),
   operator,
   right: right2
 });
@@ -403,7 +428,7 @@ var inSubquery = (left2, subquery) => createInExpression("IN", left2, toScalarSu
 var notInSubquery = (left2, subquery) => createInExpression("NOT IN", left2, toScalarSubqueryNode(subquery));
 var createBetweenExpression = (operator, left2, lower2, upper2) => ({
   type: "BetweenExpression",
-  left: toNode(left2),
+  left: toOperandNode(left2),
   operator,
   lower: toOperand(lower2),
   upper: toOperand(upper2)
@@ -585,24 +610,54 @@ var groupConcat = (col2, options) => ({
 });
 
 // src/core/ast/expression-visitor.ts
-var expressionDispatchers = /* @__PURE__ */ new Map();
-var operandDispatchers = /* @__PURE__ */ new Map();
+var DispatcherRegistry = class _DispatcherRegistry {
+  constructor(dispatchers = /* @__PURE__ */ new Map()) {
+    this.dispatchers = dispatchers;
+  }
+  /**
+   * Registers a new dispatcher and returns a new registry instance
+   */
+  register(type, dispatcher) {
+    const newMap = new Map(this.dispatchers);
+    newMap.set(type, dispatcher);
+    return new _DispatcherRegistry(newMap);
+  }
+  /**
+   * Gets a dispatcher for the given type
+   */
+  get(type) {
+    return this.dispatchers.get(type);
+  }
+  /**
+   * Returns a new empty registry
+   */
+  clear() {
+    return new _DispatcherRegistry();
+  }
+};
+var expressionRegistry = new DispatcherRegistry();
+var operandRegistry = new DispatcherRegistry();
 var registerExpressionDispatcher = (type, dispatcher) => {
-  expressionDispatchers.set(type, dispatcher);
+  expressionRegistry = expressionRegistry.register(type, dispatcher);
 };
 var registerOperandDispatcher = (type, dispatcher) => {
-  operandDispatchers.set(type, dispatcher);
+  operandRegistry = operandRegistry.register(type, dispatcher);
 };
-var clearExpressionDispatchers = () => expressionDispatchers.clear();
-var clearOperandDispatchers = () => operandDispatchers.clear();
+var clearExpressionDispatchers = () => {
+  expressionRegistry = expressionRegistry.clear();
+};
+var clearOperandDispatchers = () => {
+  operandRegistry = operandRegistry.clear();
+};
+var getNodeType = (node) => typeof node === "object" && node !== null && typeof node.type === "string" ? node.type : void 0;
 var unsupportedExpression = (node) => {
-  throw new Error(`Unsupported expression type "${node?.type ?? "unknown"}"`);
+  throw new Error(`Unsupported expression type "${getNodeType(node) ?? "unknown"}"`);
 };
 var unsupportedOperand = (node) => {
-  throw new Error(`Unsupported operand type "${node?.type ?? "unknown"}"`);
+  throw new Error(`Unsupported operand type "${getNodeType(node) ?? "unknown"}"`);
 };
 var visitExpression = (node, visitor) => {
-  const dynamic = expressionDispatchers.get(node?.type);
+  const dynamic = expressionRegistry.get(node.type);
   if (dynamic) return dynamic(node, visitor);
   switch (node.type) {
     case "BinaryExpression":
@@ -633,7 +688,7 @@ var visitExpression = (node, visitor) => {
   return unsupportedExpression(node);
 };
 var visitOperand = (node, visitor) => {
-  const dynamic = operandDispatchers.get(node?.type);
+  const dynamic = operandRegistry.get(node.type);
   if (dynamic) return dynamic(node, visitor);
   switch (node.type) {
     case "Column":
@@ -668,24 +723,35 @@ var visitOperand = (node, visitor) => {
 };
 
 // src/core/ast/adapters.ts
+var hasAlias = (obj) => typeof obj === "object" && obj !== null && "alias" in obj;
 var toColumnRef = (col2) => ({
   name: col2.name,
   table: col2.table,
-  alias: col2.alias
+  alias: hasAlias(col2) ? col2.alias : void 0
 });
 var toTableRef = (table) => ({
   name: table.name,
   schema: table.schema,
-  alias: table.alias
+  alias: hasAlias(table) ? table.alias : void 0
 });
 
 // src/core/ast/builders.ts
+var isColumnNode = (col2) => "type" in col2 && col2.type === "Column";
+var resolveTableName = (def, table) => {
+  if (!def.table) {
+    return table.alias || table.name;
+  }
+  if (table.alias && def.table === table.name) {
+    return table.alias;
+  }
+  return def.table;
+};
 var buildColumnNode = (table, column) => {
-  if (column.type === "Column") {
+  if (isColumnNode(column)) {
     return column;
   }
   const def = column;
-  const baseTable = def.table ? table.alias && def.table === table.name ? table.alias : def.table : table.alias || table.name;
+  const baseTable = resolveTableName(def, table);
   return {
     type: "Column",
     table: baseTable,
@@ -699,7 +765,8 @@ var buildColumnNodes = (table, names) => names.map((name) => ({
 }));
 var createTableNode = (table) => ({
   type: "Table",
-  name: table.name
+  name: table.name,
+  schema: table.schema
 });
 var fnTable = (name, args = [], alias, opts) => ({
   type: "FunctionTable",
@@ -720,6 +787,9 @@ var derivedTable = (query, alias, columnAliases) => ({
 
 // src/core/functions/standard-strategy.ts
 var StandardFunctionStrategy = class _StandardFunctionStrategy {
+  /**
+   * Creates a new StandardFunctionStrategy and registers standard functions.
+   */
   constructor() {
     this.renderers = /* @__PURE__ */ new Map();
     this.registerStandard();
@@ -758,12 +828,25 @@ var StandardFunctionStrategy = class _StandardFunctionStrategy {
     this.add("DATE_TRUNC", ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
     this.add("GROUP_CONCAT", (ctx) => this.renderGroupConcat(ctx));
   }
+  /**
+   * Registers a renderer for a function name.
+   * @param name - The function name.
+   * @param renderer - The renderer function.
+   */
   add(name, renderer) {
     this.renderers.set(name, renderer);
   }
+  /**
+   * @inheritDoc
+   */
   getRenderer(name) {
     return this.renderers.get(name);
   }
+  /**
+   * Renders the GROUP_CONCAT function with optional ORDER BY and SEPARATOR.
+   * @param ctx - The function render context.
+   * @returns The rendered SQL string.
+   */
   renderGroupConcat(ctx) {
     const arg = ctx.compiledArgs[0];
     const orderClause = this.buildOrderByExpression(ctx);
@@ -771,6 +854,11 @@ var StandardFunctionStrategy = class _StandardFunctionStrategy {
     const separatorClause = this.formatGroupConcatSeparator(ctx);
     return `GROUP_CONCAT(${arg}${orderSegment}${separatorClause})`;
   }
+  /**
+   * Builds the ORDER BY clause for functions like GROUP_CONCAT.
+   * @param ctx - The function render context.
+   * @returns The ORDER BY SQL clause or empty string.
+   */
   buildOrderByExpression(ctx) {
     const orderBy = ctx.node.orderBy;
     if (!orderBy || orderBy.length === 0) {
@@ -786,16 +874,27 @@ var StandardFunctionStrategy = class _StandardFunctionStrategy {
     });
     return `ORDER BY ${parts.join(", ")}`;
   }
+  /**
+   * Formats the SEPARATOR clause for GROUP_CONCAT.
+   * @param ctx - The function render context.
+   * @returns The SEPARATOR SQL clause or empty string.
+   */
   formatGroupConcatSeparator(ctx) {
     if (!ctx.node.separator) {
       return "";
     }
     return ` SEPARATOR ${ctx.compileOperand(ctx.node.separator)}`;
   }
+  /**
+   * Gets the separator operand for GROUP_CONCAT, defaulting to comma.
+   * @param ctx - The function render context.
+   * @returns The separator operand.
+   */
   getGroupConcatSeparatorOperand(ctx) {
     return ctx.node.separator ?? _StandardFunctionStrategy.DEFAULT_GROUP_CONCAT_SEPARATOR;
   }
   static {
+    /** Default separator for GROUP_CONCAT, a comma. */
     this.DEFAULT_GROUP_CONCAT_SEPARATOR = {
       type: "Literal",
       value: ","
@@ -860,7 +959,8 @@ var Dialect = class _Dialect {
     if (!where) return "";
     return ` WHERE ${this.compileExpression(where, ctx)}`;
   }
-  compileReturning(returning, ctx) {
+  compileReturning(returning, _ctx) {
+    void _ctx;
     if (!returning || returning.length === 0) return "";
     throw new Error("RETURNING is not supported by this dialect.");
   }
@@ -908,14 +1008,16 @@ var Dialect = class _Dialect {
    * @param index - Parameter index
    * @returns Formatted placeholder string
    */
-  formatPlaceholder(index) {
+  formatPlaceholder(_index) {
+    void _index;
     return "?";
   }
   /**
    * Whether the current dialect supports a given set operation.
    * Override in concrete dialects to restrict support.
    */
-  supportsSetOperation(kind) {
+  supportsSetOperation(_kind) {
+    void _kind;
     return true;
   }
   /**
@@ -1108,15 +1210,22 @@ var Dialect = class _Dialect {
   }
   registerDefaultOperandCompilers() {
     this.registerOperandCompiler("Literal", (literal, ctx) => ctx.addParameter(literal.value));
-    this.registerOperandCompiler("AliasRef", (alias, _ctx) => this.quoteIdentifier(alias.name));
+    this.registerOperandCompiler("AliasRef", (alias, _ctx) => {
+      void _ctx;
+      return this.quoteIdentifier(alias.name);
+    });
     this.registerOperandCompiler("Column", (column, _ctx) => {
+      void _ctx;
       return `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`;
     });
     this.registerOperandCompiler(
       "Function",
       (fnNode, ctx) => this.compileFunctionOperand(fnNode, ctx)
     );
-    this.registerOperandCompiler("JsonPath", (path, _ctx) => this.compileJsonPath(path));
+    this.registerOperandCompiler("JsonPath", (path, _ctx) => {
+      void _ctx;
+      return this.compileJsonPath(path);
+    });
     this.registerOperandCompiler("ScalarSubquery", (node, ctx) => {
       const sql = this.compileSelectAst(node.query, ctx).trim().replace(/;$/, "");
       return `(${sql})`;
@@ -1160,7 +1269,8 @@ var Dialect = class _Dialect {
     });
   }
   // Default fallback, should be overridden by dialects if supported
-  compileJsonPath(node) {
+  compileJsonPath(_node) {
+    void _node;
     throw new Error("JSON Path not supported by this dialect");
   }
   /**
@@ -1326,6 +1436,7 @@ var NoReturningStrategy = class {
    * @throws Error indicating RETURNING is not supported.
    */
   compileReturning(returning, _ctx) {
+    void _ctx;
     if (!returning || returning.length === 0) return "";
     throw new Error("RETURNING is not supported by this dialect.");
   }
@@ -1727,6 +1838,7 @@ var PostgresDialect = class extends SqlDialectBase {
     return `${col2}->>'${node.path}'`;
   }
   compileReturning(returning, ctx) {
+    void ctx;
     if (!returning || returning.length === 0) return "";
     const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
@@ -1977,9 +2089,11 @@ var SqliteDialect = class extends SqlDialectBase {
     return `json_extract(${col2}, '${node.path}')`;
   }
   compileQualifiedColumn(column, _table) {
+    void _table;
     return this.quoteIdentifier(column.name);
   }
   compileReturning(returning, ctx) {
+    void ctx;
     if (!returning || returning.length === 0) return "";
     const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
@@ -2301,7 +2415,7 @@ var SelectQueryState = class _SelectQueryState {
     this.table = table;
     this.ast = ast ?? {
       type: "SelectQuery",
-      from: { type: "Table", name: table.name },
+      from: createTableNode(table),
       columns: [],
       joins: []
     };
@@ -2452,10 +2566,18 @@ var SelectQueryState = class _SelectQueryState {
 var createJoinNode = (kind, tableName, condition, relationName) => ({
   type: "Join",
   kind,
-  table: typeof tableName === "string" ? { type: "Table", name: tableName } : tableName,
+  table: typeof tableName === "string" ? parseQualifiedTableRef(tableName) : tableName,
   condition,
   meta: relationName ? { relationName } : void 0
 });
+var parseQualifiedTableRef = (ref) => {
+  const parts = ref.split(".");
+  if (parts.length === 2) {
+    const [schema, name] = parts;
+    return { type: "Table", schema, name };
+  }
+  return { type: "Table", name: ref };
+};
 
 // src/query-builder/hydration-manager.ts
 var HydrationManager = class _HydrationManager {
@@ -2542,6 +2664,11 @@ var HydrationManager = class _HydrationManager {
     const hasPagination = ast.limit !== void 0 || ast.offset !== void 0;
     return hasPagination && this.hasMultiplyingRelations(plan);
   }
+  /**
+   * Checks if the hydration plan contains relations that multiply rows
+   * @param plan - Hydration plan to check
+   * @returns True if plan has HasMany or BelongsToMany relations
+   */
   hasMultiplyingRelations(plan) {
     return plan.relations.some(
       (rel) => rel.type === RelationKinds.HasMany || rel.type === RelationKinds.BelongsToMany
@@ -2619,6 +2746,12 @@ var HydrationManager = class _HydrationManager {
       ctes: [...ast.ctes ?? [], baseCte, pageCte]
     };
   }
+  /**
+   * Generates a unique CTE name by appending a suffix if needed
+   * @param existing - Existing CTE nodes
+   * @param baseName - Base name for the CTE
+   * @returns Unique CTE name
+   */
   nextCteName(existing, baseName) {
     const names = new Set((existing ?? []).map((cte) => cte.name));
     let candidate = baseName;
@@ -2629,15 +2762,26 @@ var HydrationManager = class _HydrationManager {
     }
     return candidate;
   }
+  /**
+   * Extracts projection names from column nodes
+   * @param columns - Projection nodes
+   * @returns Array of names or undefined if any column lacks name/alias
+   */
   getProjectionNames(columns) {
     const names = [];
     for (const col2 of columns) {
-      const alias = col2.alias ?? col2.name;
+      const node = col2;
+      const alias = node.alias ?? node.name;
       if (!alias) return void 0;
       names.push(alias);
     }
     return names;
   }
+  /**
+   * Builds a map of column keys to their aliases from projection nodes
+   * @param columns - Projection nodes
+   * @returns Map of 'table.name' to alias
+   */
   buildProjectionAliasMap(columns) {
     const map = /* @__PURE__ */ new Map();
     for (const col2 of columns) {
@@ -2648,6 +2792,15 @@ var HydrationManager = class _HydrationManager {
     }
     return map;
   }
+  /**
+   * Maps order by nodes to use base CTE alias
+   * @param orderBy - Original order by nodes
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped order by nodes, null if cannot map
+   */
   mapOrderBy(orderBy, plan, projectionAliases, baseAlias, availableColumns) {
     if (!orderBy || orderBy.length === 0) {
       return void 0;
@@ -2660,6 +2813,15 @@ var HydrationManager = class _HydrationManager {
     }
     return mapped;
   }
+  /**
+   * Maps a single ordering term to use base CTE alias
+   * @param term - Ordering term to map
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped term or null if cannot map
+   */
   mapOrderingTerm(term, plan, projectionAliases, baseAlias, availableColumns) {
     if (term.type === "Column") {
       const col2 = term;
@@ -2675,6 +2837,13 @@ var HydrationManager = class _HydrationManager {
     }
     return null;
   }
+  /**
+   * Builds column nodes for paging CTE
+   * @param primaryKey - Primary key name
+   * @param orderBy - Order by nodes
+   * @param tableAlias - Table alias for columns
+   * @returns Array of column nodes for paging
+   */
   buildPagingColumns(primaryKey, orderBy, tableAlias) {
     const columns = [{ type: "Column", table: tableAlias, name: primaryKey, alias: primaryKey }];
     if (!orderBy) return columns;
@@ -2849,7 +3018,8 @@ var buildDefaultHydrationPlan = (table) => ({
 // src/query-builder/raw-column-parser.ts
 var parseRawColumn = (col2, tableName, ctes) => {
   if (col2.includes("(")) {
-    const [fn4, rest] = col2.split("(");
+    const [_fn, rest] = col2.split("(");
+    void _fn;
     const colName = rest.replace(")", "");
     const [table, name] = colName.includes(".") ? colName.split(".") : [tableName, colName];
     return { type: "Column", table, name, alias: col2 };
@@ -3046,10 +3216,15 @@ var QueryAstService = class {
   combineExpressions(existing, next) {
     return existing ? and(existing, next) : next;
   }
+  /**
+   * Normalizes an ordering term to a standard OrderingTerm
+   * @param term - Column definition or ordering term to normalize
+   * @returns Normalized ordering term
+   */
   normalizeOrderingTerm(term) {
     const from = this.state.ast.from;
     const tableRef2 = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
-    const termType = term?.type;
+    const termType = term.type;
     if (termType === "Column") {
       return term;
     }
@@ -3162,7 +3337,11 @@ var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, ro
     { type: "Column", table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
     { type: "Column", table: rootTable, name: rootKey }
   );
-  const pivotJoin = createJoinNode(joinKind, relation.pivotTable.name, pivotCondition);
+  const pivotJoin = createJoinNode(
+    joinKind,
+    { type: "Table", name: relation.pivotTable.name, schema: relation.pivotTable.schema },
+    pivotCondition
+  );
   let targetCondition = eq(
     { type: "Column", table: relation.target.name, name: targetKey },
     { type: "Column", table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
@@ -3172,7 +3351,7 @@ var buildBelongsToManyJoins = (root, relationName, relation, joinKind, extra, ro
   }
   const targetJoin = createJoinNode(
     joinKind,
-    relation.target.name,
+    { type: "Table", name: relation.target.name, schema: relation.target.schema },
     targetCondition,
     relationName
   );
@@ -3350,7 +3529,12 @@ var RelationService = class {
       return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
     }
     const condition = buildRelationJoinCondition(this.table, relation, extraCondition, rootAlias);
-    const joinNode = createJoinNode(joinKind, relation.target.name, condition, relationName);
+    const joinNode = createJoinNode(
+      joinKind,
+      { type: "Table", name: relation.target.name, schema: relation.target.schema },
+      condition,
+      relationName
+    );
     return this.astService(state).withJoin(joinNode);
   }
   /**
@@ -3395,25 +3579,6 @@ var RelationService = class {
   }
 };
 
-// src/query-builder/select-query-builder-deps.ts
-var defaultCreateQueryAstService = (table, state) => new QueryAstService(table, state);
-var defaultCreateHydrationPlanner = (table) => new HydrationPlanner(table);
-var defaultCreateHydration = (table, plannerFactory) => new HydrationManager(table, plannerFactory(table));
-var resolveSelectQueryBuilderDependencies = (overrides = {}) => {
-  const createQueryAstService = overrides.createQueryAstService ?? defaultCreateQueryAstService;
-  const createHydrationPlanner = overrides.createHydrationPlanner ?? defaultCreateHydrationPlanner;
-  const createHydration = overrides.createHydration ?? ((table) => defaultCreateHydration(table, createHydrationPlanner));
-  const createRelationService = overrides.createRelationService ?? ((table, state, hydration) => new RelationService(table, state, hydration, createQueryAstService));
-  return {
-    createState: overrides.createState ?? ((table) => new SelectQueryState(table)),
-    createHydration,
-    createHydrationPlanner,
-    createQueryAstService,
-    createRelationService
-  };
-};
-var defaultSelectQueryBuilderDependencies = resolveSelectQueryBuilderDependencies();
-
 // src/query-builder/column-selector.ts
 var ColumnSelector = class {
   /**
@@ -3539,6 +3704,29 @@ var RelationManager = class {
   }
 };
 
+// src/query-builder/select-query-builder-deps.ts
+var defaultCreateQueryAstService = (table, state) => new QueryAstService(table, state);
+var defaultCreateHydrationPlanner = (table) => new HydrationPlanner(table);
+var defaultCreateHydration = (table, plannerFactory) => new HydrationManager(table, plannerFactory(table));
+var resolveSelectQueryBuilderDependencies = (overrides = {}) => {
+  const createQueryAstService = overrides.createQueryAstService ?? defaultCreateQueryAstService;
+  const createHydrationPlanner = overrides.createHydrationPlanner ?? defaultCreateHydrationPlanner;
+  const createHydration = overrides.createHydration ?? ((table) => defaultCreateHydration(table, createHydrationPlanner));
+  const createRelationService = overrides.createRelationService ?? ((table, state, hydration) => new RelationService(table, state, hydration, createQueryAstService));
+  const createColumnSelector = overrides.createColumnSelector ?? ((env) => new ColumnSelector(env));
+  const createRelationManager = overrides.createRelationManager ?? ((env) => new RelationManager(env));
+  return {
+    createState: overrides.createState ?? ((table) => new SelectQueryState(table)),
+    createHydration,
+    createHydrationPlanner,
+    createQueryAstService,
+    createRelationService,
+    createColumnSelector,
+    createRelationManager
+  };
+};
+var defaultSelectQueryBuilderDependencies = resolveSelectQueryBuilderDependencies();
+
 // src/orm/hydration.ts
 var hydrateRows = (rows, plan) => {
   if (!plan || !rows.length) return rows;
@@ -3664,6 +3852,18 @@ var hideInternal = (obj, keys) => {
   }
 };
 var DefaultHasManyCollection = class {
+  /**
+   * Creates a new DefaultHasManyCollection instance.
+   * @param ctx - The entity context
+   * @param meta - The entity metadata
+   * @param root - The root entity
+   * @param relationName - The relation name
+   * @param relation - The relation definition
+   * @param rootTable - The root table definition
+   * @param loader - The loader function for lazy loading
+   * @param createEntity - Function to create entities from rows
+   * @param localKey - The local key for the relation
+   */
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
     this.ctx = ctx;
     this.meta = meta;
@@ -3681,6 +3881,10 @@ var DefaultHasManyCollection = class {
     hideInternal(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
+  /**
+   * Loads the related entities if not already loaded.
+   * @returns Promise resolving to the array of child entities
+   */
   async load() {
     if (this.loaded) return this.items;
     const map = await this.loader();
@@ -3690,9 +3894,18 @@ var DefaultHasManyCollection = class {
     this.loaded = true;
     return this.items;
   }
+  /**
+   * Gets the current items in the collection.
+   * @returns Array of child entities
+   */
   getItems() {
     return this.items;
   }
+  /**
+   * Adds a new child entity to the collection.
+   * @param data - Partial data for the new entity
+   * @returns The created entity
+   */
   add(data) {
     const keyValue = this.root[this.localKey];
     const childRow = {
@@ -3712,6 +3925,10 @@ var DefaultHasManyCollection = class {
     );
     return entity;
   }
+  /**
+   * Attaches an existing entity to the collection.
+   * @param entity - The entity to attach
+   */
   attach(entity) {
     const keyValue = this.root[this.localKey];
     entity[this.relation.foreignKey] = keyValue;
@@ -3726,6 +3943,10 @@ var DefaultHasManyCollection = class {
       { kind: "attach", entity }
     );
   }
+  /**
+   * Removes an entity from the collection.
+   * @param entity - The entity to remove
+   */
   remove(entity) {
     this.items = this.items.filter((item) => item !== entity);
     this.removed.add(entity);
@@ -3738,6 +3959,9 @@ var DefaultHasManyCollection = class {
       { kind: "remove", entity }
     );
   }
+  /**
+   * Clears all entities from the collection.
+   */
   clear() {
     for (const entity of [...this.items]) {
       this.remove(entity);
@@ -3754,6 +3978,10 @@ var DefaultHasManyCollection = class {
     this.items = rows.map((row) => this.createEntity(row));
     this.loaded = true;
   }
+  /**
+   * Returns the items for JSON serialization.
+   * @returns Array of child entities
+   */
   toJSON() {
     return this.items;
   }
@@ -4049,7 +4277,6 @@ var DefaultManyToManyCollection = class {
   }
   async syncByIds(ids) {
     await this.load();
-    const targetKey = this.relation.targetKey || findPrimaryKey(this.relation.target);
     const normalized = new Set(ids.map((id) => toKey5(id)));
     const currentIds = new Set(this.items.map((item) => toKey5(this.extractId(item))));
     for (const id of normalized) {
@@ -4130,112 +4357,92 @@ var executeQuery = async (ctx, qb) => {
   return rowsFromResults(results);
 };
 var toKey6 = (value) => value === null || value === void 0 ? "" : String(value);
-var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
-  const localKey = relation.localKey || findPrimaryKey(rootTable);
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = /* @__PURE__ */ new Set();
+var collectKeysFromRoots = (roots, key) => {
+  const collected = /* @__PURE__ */ new Set();
   for (const tracked of roots) {
-    const value = tracked.entity[localKey];
+    const value = tracked.entity[key];
     if (value !== null && value !== void 0) {
-      keys.add(value);
+      collected.add(value);
     }
   }
-  if (!keys.size) {
-    return /* @__PURE__ */ new Map();
-  }
-  const selectMap = selectAllColumns(relation.target);
-  const fb = new SelectQueryBuilder(relation.target).select(selectMap);
-  const fkColumn = relation.target.columns[relation.foreignKey];
-  if (!fkColumn) return /* @__PURE__ */ new Map();
-  fb.where(inList(fkColumn, Array.from(keys)));
-  const rows = await executeQuery(ctx, fb);
+  return collected;
+};
+var buildInListValues = (keys) => Array.from(keys);
+var fetchRowsForKeys = async (ctx, table, column, keys) => {
+  const qb = new SelectQueryBuilder(table).select(selectAllColumns(table));
+  qb.where(inList(column, buildInListValues(keys)));
+  return executeQuery(ctx, qb);
+};
+var groupRowsByMany = (rows, keyColumn) => {
   const grouped = /* @__PURE__ */ new Map();
   for (const row of rows) {
-    const fkValue = row[relation.foreignKey];
-    if (fkValue === null || fkValue === void 0) continue;
-    const key = toKey6(fkValue);
+    const value = row[keyColumn];
+    if (value === null || value === void 0) continue;
+    const key = toKey6(value);
     const bucket = grouped.get(key) ?? [];
     bucket.push(row);
     grouped.set(key, bucket);
   }
   return grouped;
 };
-var loadHasOneRelation = async (ctx, rootTable, _relationName, relation) => {
-  const localKey = relation.localKey || findPrimaryKey(rootTable);
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = /* @__PURE__ */ new Set();
-  for (const tracked of roots) {
-    const value = tracked.entity[localKey];
-    if (value !== null && value !== void 0) {
-      keys.add(value);
+var groupRowsByUnique = (rows, keyColumn) => {
+  const lookup = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const value = row[keyColumn];
+    if (value === null || value === void 0) continue;
+    const key = toKey6(value);
+    if (!lookup.has(key)) {
+      lookup.set(key, row);
     }
   }
+  return lookup;
+};
+var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
+  const localKey = relation.localKey || findPrimaryKey(rootTable);
+  const roots = ctx.getEntitiesForTable(rootTable);
+  const keys = collectKeysFromRoots(roots, localKey);
   if (!keys.size) {
     return /* @__PURE__ */ new Map();
   }
-  const selectMap = selectAllColumns(relation.target);
-  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return /* @__PURE__ */ new Map();
-  qb.where(inList(fkColumn, Array.from(keys)));
-  const rows = await executeQuery(ctx, qb);
-  const lookup = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    const fkValue = row[relation.foreignKey];
-    if (fkValue === null || fkValue === void 0) continue;
-    const key = toKey6(fkValue);
-    if (!lookup.has(key)) {
-      lookup.set(key, row);
-    }
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
+  return groupRowsByMany(rows, relation.foreignKey);
+};
+var loadHasOneRelation = async (ctx, rootTable, _relationName, relation) => {
+  const localKey = relation.localKey || findPrimaryKey(rootTable);
+  const roots = ctx.getEntitiesForTable(rootTable);
+  const keys = collectKeysFromRoots(roots, localKey);
+  if (!keys.size) {
+    return /* @__PURE__ */ new Map();
   }
-  return lookup;
+  const fkColumn = relation.target.columns[relation.foreignKey];
+  if (!fkColumn) return /* @__PURE__ */ new Map();
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
+  return groupRowsByUnique(rows, relation.foreignKey);
 };
 var loadBelongsToRelation = async (ctx, rootTable, _relationName, relation) => {
   const roots = ctx.getEntitiesForTable(rootTable);
-  const foreignKeys = /* @__PURE__ */ new Set();
-  for (const tracked of roots) {
-    const value = tracked.entity[relation.foreignKey];
-    if (value !== null && value !== void 0) {
-      foreignKeys.add(value);
-    }
-  }
+  const foreignKeys = collectKeysFromRoots(roots, relation.foreignKey);
   if (!foreignKeys.size) {
     return /* @__PURE__ */ new Map();
   }
-  const selectMap = selectAllColumns(relation.target);
-  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
   const targetKey = relation.localKey || findPrimaryKey(relation.target);
   const pkColumn = relation.target.columns[targetKey];
   if (!pkColumn) return /* @__PURE__ */ new Map();
-  qb.where(inList(pkColumn, Array.from(foreignKeys)));
-  const rows = await executeQuery(ctx, qb);
-  const map = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    const keyValue = row[targetKey];
-    if (keyValue === null || keyValue === void 0) continue;
-    map.set(toKey6(keyValue), row);
-  }
-  return map;
+  const rows = await fetchRowsForKeys(ctx, relation.target, pkColumn, foreignKeys);
+  return groupRowsByUnique(rows, targetKey);
 };
 var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation) => {
   const rootKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
-  const rootIds = /* @__PURE__ */ new Set();
-  for (const tracked of roots) {
-    const value = tracked.entity[rootKey];
-    if (value !== null && value !== void 0) {
-      rootIds.add(value);
-    }
-  }
+  const rootIds = collectKeysFromRoots(roots, rootKey);
   if (!rootIds.size) {
     return /* @__PURE__ */ new Map();
   }
-  const pivotSelect = selectAllColumns(relation.pivotTable);
-  const pivotQb = new SelectQueryBuilder(relation.pivotTable).select(pivotSelect);
-  const pivotFkCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
-  if (!pivotFkCol) return /* @__PURE__ */ new Map();
-  pivotQb.where(inList(pivotFkCol, Array.from(rootIds)));
-  const pivotRows = await executeQuery(ctx, pivotQb);
+  const pivotColumn = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
+  if (!pivotColumn) return /* @__PURE__ */ new Map();
+  const pivotRows = await fetchRowsForKeys(ctx, relation.pivotTable, pivotColumn, rootIds);
   const rootLookup = /* @__PURE__ */ new Map();
   const targetIds = /* @__PURE__ */ new Set();
   for (const pivot of pivotRows) {
@@ -4255,19 +4462,11 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
   if (!targetIds.size) {
     return /* @__PURE__ */ new Map();
   }
-  const targetSelect = selectAllColumns(relation.target);
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const targetPkColumn = relation.target.columns[targetKey];
   if (!targetPkColumn) return /* @__PURE__ */ new Map();
-  const targetQb = new SelectQueryBuilder(relation.target).select(targetSelect);
-  targetQb.where(inList(targetPkColumn, Array.from(targetIds)));
-  const targetRows = await executeQuery(ctx, targetQb);
-  const targetMap = /* @__PURE__ */ new Map();
-  for (const row of targetRows) {
-    const pkValue = row[targetKey];
-    if (pkValue === null || pkValue === void 0) continue;
-    targetMap.set(toKey6(pkValue), row);
-  }
+  const targetRows = await fetchRowsForKeys(ctx, relation.target, targetPkColumn, targetIds);
+  const targetMap = groupRowsByUnique(targetRows, targetKey);
   const result = /* @__PURE__ */ new Map();
   for (const [rootId, entries] of rootLookup.entries()) {
     const bucket = [];
@@ -4320,7 +4519,6 @@ var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
     enumerable: false,
     writable: false
   });
-  let proxy;
   const handler = {
     get(targetObj, prop, receiver) {
       if (prop === ENTITY_META) {
@@ -4328,7 +4526,7 @@ var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
       }
       if (prop === "$load") {
         return async (relationName) => {
-          const wrapper = getRelationWrapper(meta, relationName, proxy);
+          const wrapper = getRelationWrapper(meta, relationName, receiver);
           if (wrapper && typeof wrapper.load === "function") {
             return wrapper.load();
           }
@@ -4336,19 +4534,19 @@ var createEntityProxy = (ctx, table, row, lazyRelations = []) => {
         };
       }
       if (typeof prop === "string" && table.relations[prop]) {
-        return getRelationWrapper(meta, prop, proxy);
+        return getRelationWrapper(meta, prop, receiver);
       }
       return Reflect.get(targetObj, prop, receiver);
     },
     set(targetObj, prop, value, receiver) {
       const result = Reflect.set(targetObj, prop, value, receiver);
       if (typeof prop === "string" && table.columns[prop]) {
-        ctx.markDirty(proxy);
+        ctx.markDirty(receiver);
       }
       return result;
     }
   };
-  proxy = new Proxy(target, handler);
+  const proxy = new Proxy(target, handler);
   populateHydrationCache(proxy, row, meta);
   return proxy;
 };
@@ -4545,21 +4743,21 @@ async function executeHydratedWithContexts(_execCtx, hydCtx, qb) {
   return executeWithEntityContext(entityCtx, qb);
 }
 
+// src/query-builder/query-resolution.ts
+function resolveSelectQuery(query) {
+  const candidate = query;
+  return typeof candidate.getAST === "function" && candidate.getAST ? candidate.getAST() : query;
+}
+
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
-  
-     * Creates a new SelectQueryBuilder instance
-  
-     * @param table - Table definition to query
-  
-     * @param state - Optional initial query state
-  
-     * @param hydration - Optional hydration manager
-  
-     * @param dependencies - Optional query builder dependencies
-  
-     */
+   * Creates a new SelectQueryBuilder instance
+   * @param table - Table definition to query
+   * @param state - Optional initial query state
+   * @param hydration - Optional hydration manager
+   * @param dependencies - Optional query builder dependencies
+   */
   constructor(table, state, hydration, dependencies, lazyRelations) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
@@ -4570,9 +4768,15 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       hydration: initialHydration
     };
     this.lazyRelations = new Set(lazyRelations ?? []);
-    this.columnSelector = new ColumnSelector(this.env);
-    this.relationManager = new RelationManager(this.env);
+    this.columnSelector = deps.createColumnSelector(this.env);
+    this.relationManager = deps.createRelationManager(this.env);
   }
+  /**
+   * Creates a new SelectQueryBuilder instance with updated context and lazy relations
+   * @param context - Updated query context
+   * @param lazyRelations - Updated lazy relations set
+   * @returns New SelectQueryBuilder instance
+   */
   clone(context = this.context, lazyRelations = new Set(this.lazyRelations)) {
     return new _SelectQueryBuilder(this.env.table, context.state, context.hydration, this.env.deps, lazyRelations);
   }
@@ -4589,9 +4793,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const nextContext = this.applyAst(this.context, (service) => service.withFrom(nextFrom));
     return this.clone(nextContext);
   }
-  resolveQueryNode(query) {
-    return typeof query.getAST === "function" ? query.getAST() : query;
-  }
+  /**
+   * Applies correlation expression to the query AST
+   * @param ast - Query AST to modify
+   * @param correlation - Correlation expression
+   * @returns Modified AST with correlation applied
+   */
   applyCorrelation(ast, correlation) {
     if (!correlation) return ast;
     const combinedWhere = ast.where ? and(correlation, ast.where) : correlation;
@@ -4600,39 +4807,53 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       where: combinedWhere
     };
   }
+  /**
+   * Creates a new child query builder for a related table
+   * @param table - Table definition for the child builder
+   * @returns New SelectQueryBuilder instance for the child table
+   */
   createChildBuilder(table) {
     return new _SelectQueryBuilder(table, void 0, void 0, this.env.deps);
   }
+  /**
+   * Applies an AST mutation using the query AST service
+   * @param context - Current query context
+   * @param mutator - Function that mutates the AST
+   * @returns Updated query context
+   */
   applyAst(context, mutator) {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = mutator(astService);
     return { state: nextState, hydration: context.hydration };
   }
+  /**
+   * Applies a join to the query context
+   * @param context - Current query context
+   * @param table - Table to join
+   * @param condition - Join condition
+   * @param kind - Join kind
+   * @returns Updated query context with join applied
+   */
   applyJoin(context, table, condition, kind) {
-    const joinNode = createJoinNode(kind, table.name, condition);
+    const joinNode = createJoinNode(kind, { type: "Table", name: table.name, schema: table.schema }, condition);
     return this.applyAst(context, (service) => service.withJoin(joinNode));
   }
+  /**
+   * Applies a set operation to the query
+   * @param operator - Set operation kind
+   * @param query - Query to combine with
+   * @returns Updated query context with set operation
+   */
   applySetOperation(operator, query) {
-    const subAst = this.resolveQueryNode(query);
+    const subAst = resolveSelectQuery(query);
     return this.applyAst(this.context, (service) => service.withSetOperation(operator, subAst));
   }
-  /**
-  
-     * Selects specific columns for the query
-  
-     * @param columns - Record of column definitions, function nodes, case expressions, or window functions
-  
-     * @returns New query builder instance with selected columns
-  
-     */
-  select(columns) {
-    return this.clone(this.columnSelector.select(this.context, columns));
-  }
-  /**
-   * Selects columns from the root table by name (typed).
-   * @param cols - Column names on the root table
-   */
-  selectColumns(...cols) {
+  select(...args) {
+    if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && typeof args[0] !== "string") {
+      const columns = args[0];
+      return this.clone(this.columnSelector.select(this.context, columns));
+    }
+    const cols = args;
     const selection = {};
     for (const key of cols) {
       const col2 = this.env.table.columns[key];
@@ -4641,53 +4862,37 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       }
       selection[key] = col2;
     }
-    return this.select(selection);
+    return this.clone(this.columnSelector.select(this.context, selection));
   }
   /**
-  
-     * Selects raw column expressions
-  
-     * @param cols - Column expressions as strings
-  
-     * @returns New query builder instance with raw column selections
-  
-     */
+   * Selects raw column expressions
+   * @param cols - Column expressions as strings
+   * @returns New query builder instance with raw column selections
+   */
   selectRaw(...cols) {
     return this.clone(this.columnSelector.selectRaw(this.context, cols));
   }
   /**
-  
-     * Adds a Common Table Expression (CTE) to the query
-  
-     * @param name - Name of the CTE
-  
-     * @param query - Query builder or query node for the CTE
-  
-     * @param columns - Optional column names for the CTE
-  
-     * @returns New query builder instance with the CTE
-  
-     */
+   * Adds a Common Table Expression (CTE) to the query
+   * @param name - Name of the CTE
+   * @param query - Query builder or query node for the CTE
+   * @param columns - Optional column names for the CTE
+   * @returns New query builder instance with the CTE
+   */
   with(name, query, columns) {
-    const subAst = this.resolveQueryNode(query);
+    const subAst = resolveSelectQuery(query);
     const nextContext = this.applyAst(this.context, (service) => service.withCte(name, subAst, columns, false));
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a recursive Common Table Expression (CTE) to the query
-  
-     * @param name - Name of the CTE
-  
-     * @param query - Query builder or query node for the CTE
-  
-     * @param columns - Optional column names for the CTE
-  
-     * @returns New query builder instance with the recursive CTE
-  
-     */
+   * Adds a recursive Common Table Expression (CTE) to the query
+   * @param name - Name of the CTE
+   * @param query - Query builder or query node for the CTE
+   * @param columns - Optional column names for the CTE
+   * @returns New query builder instance with the recursive CTE
+   */
   withRecursive(name, query, columns) {
-    const subAst = this.resolveQueryNode(query);
+    const subAst = resolveSelectQuery(query);
     const nextContext = this.applyAst(this.context, (service) => service.withCte(name, subAst, columns, true));
     return this.clone(nextContext);
   }
@@ -4699,24 +4904,31 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with updated FROM
    */
   fromSubquery(subquery, alias, columnAliases) {
-    const subAst = this.resolveQueryNode(subquery);
+    const subAst = resolveSelectQuery(subquery);
     const fromNode = derivedTable(subAst, alias, columnAliases);
     const nextContext = this.applyAst(this.context, (service) => service.withFrom(fromNode));
     return this.clone(nextContext);
   }
   /**
-  
-     * Selects a subquery as a column
-  
-     * @param alias - Alias for the subquery column
-  
-     * @param sub - Query builder or query node for the subquery
-  
-     * @returns New query builder instance with the subquery selection
-  
-     */
+   * Replaces the FROM clause with a function table expression.
+   * @param name - Function name
+   * @param args - Optional function arguments
+   * @param alias - Optional alias for the function table
+   * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
+   */
+  fromFunctionTable(name, args = [], alias, options) {
+    const functionTable = fnTable(name, args, alias, options);
+    const nextContext = this.applyAst(this.context, (service) => service.withFrom(functionTable));
+    return this.clone(nextContext);
+  }
+  /**
+   * Selects a subquery as a column
+   * @param alias - Alias for the subquery column
+   * @param sub - Query builder or query node for the subquery
+   * @returns New query builder instance with the subquery selection
+   */
   selectSubquery(alias, sub2) {
-    const query = this.resolveQueryNode(sub2);
+    const query = resolveSelectQuery(sub2);
     return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
   }
   /**
@@ -4729,103 +4941,92 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @returns New query builder instance with the derived-table join
    */
   joinSubquery(subquery, alias, condition, joinKind = JOIN_KINDS.INNER, columnAliases) {
-    const subAst = this.resolveQueryNode(subquery);
+    const subAst = resolveSelectQuery(subquery);
     const joinNode = createJoinNode(joinKind, derivedTable(subAst, alias, columnAliases), condition);
     const nextContext = this.applyAst(this.context, (service) => service.withJoin(joinNode));
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds an INNER JOIN to the query
-  
-     * @param table - Table to join
-  
-     * @param condition - Join condition expression
-  
-     * @returns New query builder instance with the INNER JOIN
-  
-     */
+   * Adds a join against a function table (e.g., `generate_series`) using `fnTable` internally.
+   * @param name - Function name
+   * @param args - Optional arguments passed to the function
+   * @param alias - Alias for the function table so columns can be referenced
+   * @param condition - Join condition expression
+   * @param joinKind - Kind of join (defaults to INNER)
+   * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
+   */
+  joinFunctionTable(name, args = [], alias, condition, joinKind = JOIN_KINDS.INNER, options) {
+    const functionTable = fnTable(name, args, alias, options);
+    const joinNode = createJoinNode(joinKind, functionTable, condition);
+    const nextContext = this.applyAst(this.context, (service) => service.withJoin(joinNode));
+    return this.clone(nextContext);
+  }
+  /**
+   * Adds an INNER JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the INNER JOIN
+   */
   innerJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a LEFT JOIN to the query
-  
-     * @param table - Table to join
-  
-     * @param condition - Join condition expression
-  
-     * @returns New query builder instance with the LEFT JOIN
-  
-     */
+   * Adds a LEFT JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the LEFT JOIN
+   */
   leftJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a RIGHT JOIN to the query
-  
-     * @param table - Table to join
-  
-     * @param condition - Join condition expression
-  
-     * @returns New query builder instance with the RIGHT JOIN
-  
-     */
+   * Adds a RIGHT JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the RIGHT JOIN
+   */
   rightJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
     return this.clone(nextContext);
   }
   /**
-  
-     * Matches records based on a relationship
-  
-     * @param relationName - Name of the relationship to match
-  
-     * @param predicate - Optional predicate expression
-  
-     * @returns New query builder instance with the relationship match
-  
-     */
+   * Matches records based on a relationship
+   * @param relationName - Name of the relationship to match
+   * @param predicate - Optional predicate expression
+   * @returns New query builder instance with the relationship match
+   */
   match(relationName, predicate) {
     const nextContext = this.relationManager.match(this.context, relationName, predicate);
     return this.clone(nextContext);
   }
   /**
-  
-     * Joins a related table
-  
-     * @param relationName - Name of the relationship to join
-  
-     * @param joinKind - Type of join (defaults to INNER)
-  
-     * @param extraCondition - Optional additional join condition
-  
-     * @returns New query builder instance with the relationship join
-  
-     */
+   * Joins a related table
+   * @param relationName - Name of the relationship to join
+   * @param joinKind - Type of join (defaults to INNER)
+   * @param extraCondition - Optional additional join condition
+   * @returns New query builder instance with the relationship join
+   */
   joinRelation(relationName, joinKind = JOIN_KINDS.INNER, extraCondition) {
     const nextContext = this.relationManager.joinRelation(this.context, relationName, joinKind, extraCondition);
     return this.clone(nextContext);
   }
   /**
-  
-     * Includes related data in the query results
-  
-     * @param relationName - Name of the relationship to include
-  
-     * @param options - Optional include options
-  
-     * @returns New query builder instance with the relationship inclusion
-  
-     */
+   * Includes related data in the query results
+   * @param relationName - Name of the relationship to include
+   * @param options - Optional include options
+   * @returns New query builder instance with the relationship inclusion
+   */
   include(relationName, options) {
     const nextContext = this.relationManager.include(this.context, relationName, options);
     return this.clone(nextContext);
   }
+  /**
+   * Includes a relation lazily in the query results
+   * @param relationName - Name of the relation to include lazily
+   * @returns New query builder instance with lazy relation inclusion
+   */
   includeLazy(relationName) {
     const nextLazy = new Set(this.lazyRelations);
     nextLazy.add(relationName);
@@ -4856,43 +5057,57 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.selectRelationColumns(relationName, ...cols);
   }
   /**
-   * Selects columns for the root table and relations from a single config object.
+   * Selects columns for the root table and relations from an array of entries
+   * @param config - Configuration array for deep column selection
+   * @returns New query builder instance with deep column selections
    */
   selectColumnsDeep(config) {
-    let qb = this;
-    if (config.root?.length) {
-      qb = qb.selectColumns(...config.root);
-    }
-    for (const key of Object.keys(config)) {
-      if (key === "root") continue;
-      const relName = key;
-      const cols = config[relName];
-      if (!cols || !cols.length) continue;
-      qb = qb.selectRelationColumns(relName, ...cols);
+    let currBuilder = this;
+    for (const entry of config) {
+      if (entry.type === "root") {
+        currBuilder = currBuilder.select(...entry.columns);
+      } else {
+        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...entry.columns);
+      }
     }
-    return qb;
+    return currBuilder;
   }
+  /**
+   * Gets the list of lazy relations
+   * @returns Array of lazy relation names
+   */
   getLazyRelations() {
     return Array.from(this.lazyRelations);
   }
+  /**
+   * Gets the table definition for this query builder
+   * @returns Table definition
+   */
   getTable() {
     return this.env.table;
   }
+  /**
+   * Executes the query and returns hydrated results
+   * @param ctx - ORM session context
+   * @returns Promise of entity instances
+   */
   async execute(ctx) {
     return executeHydrated(ctx, this);
   }
+  /**
+   * Executes the query with provided execution and hydration contexts
+   * @param execCtx - Execution context
+   * @param hydCtx - Hydration context
+   * @returns Promise of entity instances
+   */
   async executeWithContexts(execCtx, hydCtx) {
     return executeHydratedWithContexts(execCtx, hydCtx, this);
   }
   /**
-  
-     * Adds a WHERE condition to the query
-  
-     * @param expr - Expression for the WHERE clause
-  
-     * @returns New query builder instance with the WHERE condition
-  
-     */
+   * Adds a WHERE condition to the query
+   * @param expr - Expression for the WHERE clause
+   * @returns New query builder instance with the WHERE condition
+   */
   where(expr) {
     const nextContext = this.applyAst(this.context, (service) => service.withWhere(expr));
     return this.clone(nextContext);
@@ -4907,14 +5122,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a HAVING condition to the query
-  
-     * @param expr - Expression for the HAVING clause
-  
-     * @returns New query builder instance with the HAVING condition
-  
-     */
+   * Adds a HAVING condition to the query
+   * @param expr - Expression for the HAVING clause
+   * @returns New query builder instance with the HAVING condition
+   */
   having(expr) {
     const nextContext = this.applyAst(this.context, (service) => service.withHaving(expr));
     return this.clone(nextContext);
@@ -4935,130 +5146,89 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds a DISTINCT clause to the query
-  
-     * @param cols - Columns to make distinct
-  
-     * @returns New query builder instance with the DISTINCT clause
-  
-     */
+   * Adds a DISTINCT clause to the query
+   * @param cols - Columns to make distinct
+   * @returns New query builder instance with the DISTINCT clause
+   */
   distinct(...cols) {
     return this.clone(this.columnSelector.distinct(this.context, cols));
   }
   /**
-  
-     * Adds a LIMIT clause to the query
-  
-     * @param n - Maximum number of rows to return
-  
-     * @returns New query builder instance with the LIMIT clause
-  
-     */
+   * Adds a LIMIT clause to the query
+   * @param n - Maximum number of rows to return
+   * @returns New query builder instance with the LIMIT clause
+   */
   limit(n) {
     const nextContext = this.applyAst(this.context, (service) => service.withLimit(n));
     return this.clone(nextContext);
   }
   /**
-  
-     * Adds an OFFSET clause to the query
-  
-     * @param n - Number of rows to skip
-  
-     * @returns New query builder instance with the OFFSET clause
-  
-     */
+   * Adds an OFFSET clause to the query
+   * @param n - Number of rows to skip
+   * @returns New query builder instance with the OFFSET clause
+   */
   offset(n) {
     const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
     return this.clone(nextContext);
   }
   /**
-  
-     * Combines this query with another using UNION
-  
-     * @param query - Query to union with
-  
-     * @returns New query builder instance with the set operation
-  
-     */
+   * Combines this query with another using UNION
+   * @param query - Query to union with
+   * @returns New query builder instance with the set operation
+   */
   union(query) {
     return this.clone(this.applySetOperation("UNION", query));
   }
   /**
-  
-     * Combines this query with another using UNION ALL
-  
-     * @param query - Query to union with
-  
-     * @returns New query builder instance with the set operation
-  
-     */
+   * Combines this query with another using UNION ALL
+   * @param query - Query to union with
+   * @returns New query builder instance with the set operation
+   */
   unionAll(query) {
     return this.clone(this.applySetOperation("UNION ALL", query));
   }
   /**
-  
-     * Combines this query with another using INTERSECT
-  
-     * @param query - Query to intersect with
-  
-     * @returns New query builder instance with the set operation
-  
-     */
+   * Combines this query with another using INTERSECT
+   * @param query - Query to intersect with
+   * @returns New query builder instance with the set operation
+   */
   intersect(query) {
     return this.clone(this.applySetOperation("INTERSECT", query));
   }
   /**
-  
-     * Combines this query with another using EXCEPT
-  
-     * @param query - Query to subtract
-  
-     * @returns New query builder instance with the set operation
-  
-     */
+   * Combines this query with another using EXCEPT
+   * @param query - Query to subtract
+   * @returns New query builder instance with the set operation
+   */
   except(query) {
     return this.clone(this.applySetOperation("EXCEPT", query));
   }
   /**
-  
-     * Adds a WHERE EXISTS condition to the query
-  
-     * @param subquery - Subquery to check for existence
-  
-     * @returns New query builder instance with the WHERE EXISTS condition
-  
-     */
+   * Adds a WHERE EXISTS condition to the query
+   * @param subquery - Subquery to check for existence
+   * @returns New query builder instance with the WHERE EXISTS condition
+   */
   whereExists(subquery, correlate) {
-    const subAst = this.resolveQueryNode(subquery);
+    const subAst = resolveSelectQuery(subquery);
     const correlated = this.applyCorrelation(subAst, correlate);
     return this.where(exists(correlated));
   }
   /**
-  
-     * Adds a WHERE NOT EXISTS condition to the query
-  
-     * @param subquery - Subquery to check for non-existence
-  
-     * @returns New query builder instance with the WHERE NOT EXISTS condition
-  
-     */
+   * Adds a WHERE NOT EXISTS condition to the query
+   * @param subquery - Subquery to check for non-existence
+   * @returns New query builder instance with the WHERE NOT EXISTS condition
+   */
   whereNotExists(subquery, correlate) {
-    const subAst = this.resolveQueryNode(subquery);
+    const subAst = resolveSelectQuery(subquery);
     const correlated = this.applyCorrelation(subAst, correlate);
     return this.where(notExists(correlated));
   }
   /**
-  
-     * Adds a WHERE EXISTS condition based on a relationship
-  
-     * @param relationName - Name of the relationship to check
-  
-     * @param callback - Optional callback to modify the relationship query
-  
-     * @returns New query builder instance with the relationship existence check
-  
-     */
+   * Adds a WHERE EXISTS condition based on a relationship
+   * @param relationName - Name of the relationship to check
+   * @param callback - Optional callback to modify the relationship query
+   * @returns New query builder instance with the relationship existence check
+   */
   whereHas(relationName, callbackOrOptions, maybeOptions) {
     const relation = this.env.table.relations[relationName];
     if (!relation) {
@@ -5075,16 +5245,11 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.where(exists(finalSubAst));
   }
   /**
-  
-     * Adds a WHERE NOT EXISTS condition based on a relationship
-  
-     * @param relationName - Name of the relationship to check
-  
-     * @param callback - Optional callback to modify the relationship query
-  
-     * @returns New query builder instance with the relationship non-existence check
-  
-     */
+   * Adds a WHERE NOT EXISTS condition based on a relationship
+   * @param relationName - Name of the relationship to check
+   * @param callback - Optional callback to modify the relationship query
+   * @returns New query builder instance with the relationship non-existence check
+   */
   whereHasNot(relationName, callbackOrOptions, maybeOptions) {
     const relation = this.env.table.relations[relationName];
     if (!relation) {
@@ -5101,53 +5266,61 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.where(notExists(finalSubAst));
   }
   /**
-  
-     * Compiles the query to SQL for a specific dialect
-  
-     * @param dialect - Database dialect to compile for
-  
-     * @returns Compiled query with SQL and parameters
-  
-     */
+   * Compiles the query to SQL for a specific dialect
+   * @param dialect - Database dialect to compile for
+   * @returns Compiled query with SQL and parameters
+   */
   compile(dialect) {
     const resolved = resolveDialectInput(dialect);
-    return resolved.compileSelect(this.context.state.ast);
+    return resolved.compileSelect(this.getAST());
   }
   /**
-  
-     * Converts the query to SQL string for a specific dialect
-  
-     * @param dialect - Database dialect to generate SQL for
-  
-     * @returns SQL string representation of the query
-  
-     */
+   * Converts the query to SQL string for a specific dialect
+   * @param dialect - Database dialect to generate SQL for
+   * @returns SQL string representation of the query
+   */
   toSql(dialect) {
     return this.compile(dialect).sql;
   }
   /**
-  
-     * Gets the hydration plan for the query
-  
-     * @returns Hydration plan or undefined if none exists
-  
-     */
+   * Gets the hydration plan for the query
+   * @returns Hydration plan or undefined if none exists
+   */
   getHydrationPlan() {
     return this.context.hydration.getPlan();
   }
   /**
-  
-     * Gets the Abstract Syntax Tree (AST) representation of the query
-  
-     * @returns Query AST with hydration applied
-  
-     */
+   * Gets the Abstract Syntax Tree (AST) representation of the query
+   * @returns Query AST with hydration applied
+   */
   getAST() {
     return this.context.hydration.applyToAst(this.context.state.ast);
   }
 };
-var createColumn = (table, name) => ({ type: "Column", table, name });
-var createLiteral = (val) => ({ type: "Literal", value: val });
+
+// src/schema/table-guards.ts
+var isColumnsRecord = (columns) => {
+  return typeof columns === "object" && columns !== null;
+};
+var isRelationsRecord = (relations) => {
+  return typeof relations === "object" && relations !== null;
+};
+var isTableDef = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  if (typeof candidate.name !== "string") {
+    return false;
+  }
+  if (!isColumnsRecord(candidate.columns)) {
+    return false;
+  }
+  if (!isRelationsRecord(candidate.relations)) {
+    return false;
+  }
+  return true;
+};
 
 // src/orm/entity-metadata.ts
 var metadataMap = /* @__PURE__ */ new Map();
@@ -5191,23 +5364,20 @@ var buildTableDef = (meta) => {
   if (meta.table) {
     return meta.table;
   }
-  const columns = Object.entries(meta.columns).reduce((acc, [key, def]) => {
-    acc[key] = {
+  const columns = {};
+  for (const [key, def] of Object.entries(meta.columns)) {
+    columns[key] = {
       ...def,
       name: key,
       table: meta.tableName
     };
-    return acc;
-  }, {});
+  }
   const table = defineTable(meta.tableName, columns, {}, meta.hooks);
   meta.table = table;
   return table;
 };
 
 // src/decorators/bootstrap.ts
-var isTableDef = (value) => {
-  return typeof value === "object" && value !== null && "columns" in value;
-};
 var unwrapTarget = (target) => {
   if (typeof target === "function" && target.prototype === void 0) {
     return target();
@@ -5305,6 +5475,13 @@ var selectFromEntity = (ctor) => {
   }
   return new SelectQueryBuilder(table);
 };
+var entityRef = (ctor) => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+  }
+  return tableRef(table);
+};
 
 // src/query-builder/select-helpers.ts
 function sel(table, ...cols) {
@@ -5336,6 +5513,11 @@ function esel(entity, ...props) {
 
 // src/query-builder/insert-query-state.ts
 var InsertQueryState = class _InsertQueryState {
+  /**
+   * Creates a new InsertQueryState instance
+   * @param table - The table definition for the INSERT query
+   * @param ast - Optional initial AST node, defaults to a basic INSERT query
+   */
   constructor(table, ast) {
     this.table = table;
     this.ast = ast ?? {
@@ -5366,6 +5548,13 @@ var InsertQueryState = class _InsertQueryState {
     if (!names.length) return [];
     return buildColumnNodes(this.table, names);
   }
+  /**
+   * Adds VALUES clause to the INSERT query
+   * @param rows - Array of row objects to insert
+   * @returns A new InsertQueryState with the VALUES clause added
+   * @throws Error if mixing VALUES with SELECT source
+   * @throws Error if invalid values are provided
+   */
   withValues(rows) {
     if (!rows.length) return this;
     if (this.ast.source.type === "InsertSelect") {
@@ -5392,6 +5581,11 @@ var InsertQueryState = class _InsertQueryState {
       }
     });
   }
+  /**
+   * Sets the columns for the INSERT query
+   * @param columns - Column nodes to insert into
+   * @returns A new InsertQueryState with the specified columns
+   */
   withColumns(columns) {
     if (!columns.length) return this;
     return this.clone({
@@ -5399,6 +5593,14 @@ var InsertQueryState = class _InsertQueryState {
       columns: [...columns]
     });
   }
+  /**
+   * Adds SELECT source to the INSERT query
+   * @param query - The SELECT query to use as source
+   * @param columns - Target columns for the INSERT
+   * @returns A new InsertQueryState with the SELECT source
+   * @throws Error if mixing SELECT with VALUES source
+   * @throws Error if no destination columns specified
+   */
   withSelect(query, columns) {
     const targetColumns = columns.length ? columns : this.ast.columns.length ? this.ast.columns : this.getTableColumns();
     if (!targetColumns.length) {
@@ -5416,6 +5618,11 @@ var InsertQueryState = class _InsertQueryState {
       }
     });
   }
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryState with the RETURNING clause added
+   */
   withReturning(columns) {
     return this.clone({
       ...this.ast,
@@ -5426,6 +5633,11 @@ var InsertQueryState = class _InsertQueryState {
 
 // src/query-builder/insert.ts
 var InsertQueryBuilder = class _InsertQueryBuilder {
+  /**
+   * Creates a new InsertQueryBuilder instance
+   * @param table - The table definition for the INSERT query
+   * @param state - Optional initial query state, defaults to a new InsertQueryState
+   */
   constructor(table, state) {
     this.table = table;
     this.state = state ?? new InsertQueryState(table);
@@ -5433,20 +5645,42 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
   clone(state) {
     return new _InsertQueryBuilder(this.table, state);
   }
+  /**
+   * Adds VALUES to the INSERT query
+   * @param rowOrRows - Single row object or array of row objects to insert
+   * @returns A new InsertQueryBuilder with the VALUES clause added
+   */
   values(rowOrRows) {
     const rows = Array.isArray(rowOrRows) ? rowOrRows : [rowOrRows];
     if (!rows.length) return this;
     return this.clone(this.state.withValues(rows));
   }
+  /**
+   * Specifies the columns for the INSERT query
+   * @param columns - Column definitions or nodes to insert into
+   * @returns A new InsertQueryBuilder with the specified columns
+   */
   columns(...columns) {
     if (!columns.length) return this;
     return this.clone(this.state.withColumns(this.resolveColumnNodes(columns)));
   }
+  /**
+   * Sets the source of the INSERT query to a SELECT query
+   * @template TSource - The source table type
+   * @param query - The SELECT query or query builder to use as source
+   * @param columns - Optional target columns for the INSERT
+   * @returns A new InsertQueryBuilder with the SELECT source
+   */
   fromSelect(query, columns = []) {
     const ast = this.resolveSelectQuery(query);
     const nodes = columns.length ? this.resolveColumnNodes(columns) : [];
     return this.clone(this.state.withSelect(ast, nodes));
   }
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryBuilder with the RETURNING clause added
+   */
   returning(...columns) {
     if (!columns.length) return this;
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
@@ -5457,18 +5691,29 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
     return columns.map((column) => buildColumnNode(this.table, column));
   }
   resolveSelectQuery(query) {
-    return typeof query.getAST === "function" ? query.getAST() : query;
+    const candidate = query;
+    return typeof candidate.getAST === "function" && candidate.getAST ? candidate.getAST() : query;
   }
   compile(arg) {
-    if (typeof arg.compileInsert === "function") {
-      return arg.compileInsert(this.state.ast);
+    const candidate = arg;
+    if (typeof candidate.compileInsert === "function") {
+      return candidate.compileInsert(this.state.ast);
     }
     const dialect = resolveDialectInput(arg);
     return dialect.compileInsert(this.state.ast);
   }
+  /**
+   * Returns the SQL string for the INSERT query
+   * @param arg - The compiler or dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
   toSql(arg) {
     return this.compile(arg).sql;
   }
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the INSERT query
+   */
   getAST() {
     return this.state.ast;
   }
@@ -5487,6 +5732,11 @@ var isUpdateValue = (value) => {
   }
 };
 var UpdateQueryState = class _UpdateQueryState {
+  /**
+   * Creates a new UpdateQueryState instance
+   * @param table - Table definition for the update
+   * @param ast - Optional existing AST
+   */
   constructor(table, ast) {
     this.table = table;
     this.ast = ast ?? {
@@ -5496,9 +5746,19 @@ var UpdateQueryState = class _UpdateQueryState {
       joins: []
     };
   }
+  /**
+   * Creates a new UpdateQueryState with updated AST
+   * @param nextAst - Updated AST
+   * @returns New UpdateQueryState instance
+   */
   clone(nextAst) {
     return new _UpdateQueryState(this.table, nextAst);
   }
+  /**
+   * Sets the columns to update with their new values
+   * @param values - Record of column names to values
+   * @returns New UpdateQueryState with SET clause
+   */
   withSet(values) {
     const assignments = Object.entries(values).map(([column, rawValue]) => {
       if (!isUpdateValue(rawValue)) {
@@ -5520,30 +5780,55 @@ var UpdateQueryState = class _UpdateQueryState {
       set: assignments
     });
   }
+  /**
+   * Adds a WHERE condition to the update query
+   * @param expr - WHERE expression
+   * @returns New UpdateQueryState with WHERE clause
+   */
   withWhere(expr) {
     return this.clone({
       ...this.ast,
       where: expr
     });
   }
+  /**
+   * Adds a RETURNING clause to the update query
+   * @param columns - Columns to return
+   * @returns New UpdateQueryState with RETURNING clause
+   */
   withReturning(columns) {
     return this.clone({
       ...this.ast,
       returning: [...columns]
     });
   }
+  /**
+   * Sets the FROM clause for the update query
+   * @param from - Table source for FROM
+   * @returns New UpdateQueryState with FROM clause
+   */
   withFrom(from) {
     return this.clone({
       ...this.ast,
       from
     });
   }
+  /**
+   * Adds a JOIN to the update query
+   * @param join - Join node to add
+   * @returns New UpdateQueryState with JOIN
+   */
   withJoin(join) {
     return this.clone({
       ...this.ast,
       joins: [...this.ast.joins ?? [], join]
     });
   }
+  /**
+   * Applies an alias to the table being updated
+   * @param alias - Alias for the table
+   * @returns New UpdateQueryState with table alias
+   */
   withTableAlias(alias) {
     return this.clone({
       ...this.ast,
@@ -5557,6 +5842,11 @@ var UpdateQueryState = class _UpdateQueryState {
 
 // src/query-builder/update.ts
 var UpdateQueryBuilder = class _UpdateQueryBuilder {
+  /**
+   * Creates a new UpdateQueryBuilder instance
+   * @param table - The table definition for the UPDATE query
+   * @param state - Optional initial query state, defaults to a new UpdateQueryState
+   */
   constructor(table, state) {
     this.table = table;
     this.state = state ?? new UpdateQueryState(table);
@@ -5564,24 +5854,57 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
   clone(state) {
     return new _UpdateQueryBuilder(this.table, state);
   }
+  /**
+   * Sets an alias for the table in the UPDATE query
+   * @param alias - The alias to assign to the table
+   * @returns A new UpdateQueryBuilder with the table alias set
+   */
   as(alias) {
     return this.clone(this.state.withTableAlias(alias));
   }
+  /**
+   * Adds a FROM clause to the UPDATE query
+   * @param source - The table source to use in the FROM clause
+   * @returns A new UpdateQueryBuilder with the FROM clause added
+   */
   from(source) {
     const tableSource = this.resolveTableSource(source);
     return this.clone(this.state.withFrom(tableSource));
   }
+  /**
+   * Adds a JOIN clause to the UPDATE query
+   * @param table - The table to join with
+   * @param condition - The join condition expression
+   * @param kind - The type of join (defaults to INNER)
+   * @param relationName - Optional name for the relation
+   * @returns A new UpdateQueryBuilder with the JOIN clause added
+   */
   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));
   }
+  /**
+   * Adds a SET clause to the UPDATE query
+   * @param values - The column-value pairs to update
+   * @returns A new UpdateQueryBuilder with the SET clause added
+   */
   set(values) {
     return this.clone(this.state.withSet(values));
   }
+  /**
+   * Adds a WHERE clause to the UPDATE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new UpdateQueryBuilder with the WHERE clause added
+   */
   where(expr) {
     return this.clone(this.state.withWhere(expr));
   }
+  /**
+   * Adds a RETURNING clause to the UPDATE query
+   * @param columns - Columns to return after update
+   * @returns A new UpdateQueryBuilder with the RETURNING clause added
+   */
   returning(...columns) {
     if (!columns.length) return this;
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
@@ -5597,16 +5920,36 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
     if (typeof table === "string") return table;
     return this.resolveTableSource(table);
   }
-  compile(arg) {
-    if (typeof arg.compileUpdate === "function") {
-      return arg.compileUpdate(this.state.ast);
-    }
-    const dialect = resolveDialectInput(arg);
-    return dialect.compileUpdate(this.state.ast);
+  /**
+   * Compiles the UPDATE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect) {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileUpdate(this.state.ast);
   }
-  toSql(arg) {
-    return this.compile(arg).sql;
+  /**
+   * Returns the SQL string for the UPDATE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect) {
+    return this.compile(dialect).sql;
   }
+  /**
+   * Executes the UPDATE query using the provided session
+   * @param session - The ORM session to execute the query with
+   * @returns A promise that resolves to the query results
+   */
+  async execute(session) {
+    const compiled = this.compile(session.dialect);
+    return session.executor.executeSql(compiled.sql, compiled.params);
+  }
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the UPDATE query
+   */
   getAST() {
     return this.state.ast;
   }
@@ -5615,6 +5958,11 @@ var isTableSourceNode = (source) => typeof source.type === "string";
 
 // src/query-builder/delete-query-state.ts
 var DeleteQueryState = class _DeleteQueryState {
+  /**
+   * Creates a new DeleteQueryState instance
+   * @param table - The table definition for the DELETE query
+   * @param ast - Optional initial AST node, defaults to a basic DELETE query
+   */
   constructor(table, ast) {
     this.table = table;
     this.ast = ast ?? {
@@ -5626,30 +5974,55 @@ var DeleteQueryState = class _DeleteQueryState {
   clone(nextAst) {
     return new _DeleteQueryState(this.table, nextAst);
   }
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryState with the WHERE clause added
+   */
   withWhere(expr) {
     return this.clone({
       ...this.ast,
       where: expr
     });
   }
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryState with the RETURNING clause added
+   */
   withReturning(columns) {
     return this.clone({
       ...this.ast,
       returning: [...columns]
     });
   }
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryState with the USING clause added
+   */
   withUsing(source) {
     return this.clone({
       ...this.ast,
       using: source
     });
   }
+  /**
+   * Adds a JOIN clause to the DELETE query
+   * @param join - The join node to add
+   * @returns A new DeleteQueryState with the JOIN clause added
+   */
   withJoin(join) {
     return this.clone({
       ...this.ast,
       joins: [...this.ast.joins ?? [], join]
     });
   }
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryState with the table alias set
+   */
   withTableAlias(alias) {
     return this.clone({
       ...this.ast,
@@ -5663,6 +6036,11 @@ var DeleteQueryState = class _DeleteQueryState {
 
 // src/query-builder/delete.ts
 var DeleteQueryBuilder = class _DeleteQueryBuilder {
+  /**
+   * Creates a new DeleteQueryBuilder instance
+   * @param table - The table definition for the DELETE query
+   * @param state - Optional initial query state, defaults to a new DeleteQueryState
+   */
   constructor(table, state) {
     this.table = table;
     this.state = state ?? new DeleteQueryState(table);
@@ -5670,20 +6048,48 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
   clone(state) {
     return new _DeleteQueryBuilder(this.table, state);
   }
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryBuilder with the WHERE clause added
+   */
   where(expr) {
     return this.clone(this.state.withWhere(expr));
   }
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryBuilder with the table alias set
+   */
   as(alias) {
     return this.clone(this.state.withTableAlias(alias));
   }
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryBuilder with the USING clause added
+   */
   using(source) {
     return this.clone(this.state.withUsing(this.resolveTableSource(source)));
   }
+  /**
+   * Adds a JOIN clause to the DELETE query
+   * @param table - The table to join with
+   * @param condition - The join condition expression
+   * @param kind - The type of join (defaults to INNER)
+   * @param relationName - Optional name for the relation
+   * @returns A new DeleteQueryBuilder with the JOIN clause added
+   */
   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));
   }
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryBuilder with the RETURNING clause added
+   */
   returning(...columns) {
     if (!columns.length) return this;
     const nodes = columns.map((column) => buildColumnNode(this.table, column));
@@ -5699,16 +6105,36 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
     if (typeof table === "string") return table;
     return this.resolveTableSource(table);
   }
-  compile(arg) {
-    if (typeof arg.compileDelete === "function") {
-      return arg.compileDelete(this.state.ast);
-    }
-    const dialect = resolveDialectInput(arg);
-    return dialect.compileDelete(this.state.ast);
+  /**
+   * Compiles the DELETE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect) {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileDelete(this.state.ast);
   }
-  toSql(arg) {
-    return this.compile(arg).sql;
+  /**
+   * Returns the SQL string for the DELETE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect) {
+    return this.compile(dialect).sql;
+  }
+  /**
+   * Executes the DELETE query using the provided session
+   * @param session - The ORM session to execute the query with
+   * @returns A promise that resolves to the query results
+   */
+  async execute(session) {
+    const compiled = this.compile(session.dialect);
+    return session.executor.executeSql(compiled.sql, compiled.params);
   }
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the DELETE query
+   */
   getAST() {
     return this.state.ast;
   }
@@ -5751,7 +6177,7 @@ var generateCreateTableSql = (table, dialect) => {
   const pk = resolvePrimaryKey(table);
   const inlinePkColumns = /* @__PURE__ */ new Set();
   const columnLines = Object.values(table.columns).map((col2) => {
-    const includePk = dialect.preferInlinePkAutoincrement?.(col2, table, pk) && pk.includes(col2.name);
+    const includePk = dialect.preferInlinePkAutoincrement(col2, table, pk) && pk.includes(col2.name);
     if (includePk) {
       inlinePkColumns.add(col2.name);
     }
@@ -6143,6 +6569,13 @@ async function runSelectNode(ast, ctx) {
 
 // src/core/ddl/introspect/postgres.ts
 var postgresIntrospector = {
+  /**
+   * Introspects the PostgreSQL database schema by querying information_schema and pg_catalog.
+   * Builds tables with columns, primary keys, foreign keys, and indexes.
+   * @param ctx - The introspection context with database executor.
+   * @param options - Options for schema selection and table filtering.
+   * @returns A promise resolving to the complete database schema.
+   */
   async introspect(ctx, options) {
     const schema = options.schema || "public";
     const tables = [];
@@ -6256,7 +6689,7 @@ var postgresIntrospector = {
       ],
       where: and(
         eq({ table: "ns", name: "nspname" }, schema),
-        eq({ table: "i", name: "indisprimary" }, { type: "Literal", value: false })
+        eq({ table: "i", name: "indisprimary" }, false)
       )
     };
     const indexQueryRows = await runSelectNode(indexQuery, ctx);
@@ -6420,8 +6853,22 @@ var mysqlIntrospector = {
 };
 
 // src/core/ddl/introspect/sqlite.ts
+var toReferentialAction = (value) => {
+  if (!value) return void 0;
+  const normalized = value.toUpperCase();
+  if (normalized === "NO ACTION" || normalized === "RESTRICT" || normalized === "CASCADE" || normalized === "SET NULL" || normalized === "SET DEFAULT") {
+    return normalized;
+  }
+  return void 0;
+};
 var escapeSingleQuotes = (name) => name.replace(/'/g, "''");
 var sqliteIntrospector = {
+  /**
+   * Introspects the SQLite database schema by querying sqlite_master and various PRAGMAs.
+   * @param ctx - The database execution context containing the DbExecutor.
+   * @param options - Options controlling which tables and schemas to include.
+   * @returns A promise that resolves to the introspected DatabaseSchema.
+   */
   async introspect(ctx, options) {
     const tables = [];
     const tableRows = await queryRows(
@@ -6453,8 +6900,8 @@ var sqliteIntrospector = {
           col2.references = {
             table: fk.table,
             column: fk.to,
-            onDelete: fk.on_delete?.toUpperCase(),
-            onUpdate: fk.on_update?.toUpperCase()
+            onDelete: toReferentialAction(fk.on_delete),
+            onUpdate: toReferentialAction(fk.on_update)
           };
         }
       });
@@ -6477,6 +6924,12 @@ var sqliteIntrospector = {
 
 // src/core/ddl/introspect/mssql.ts
 var mssqlIntrospector = {
+  /**
+   * Introspects the MSSQL database schema.
+   * @param ctx - The introspection context containing the database executor.
+   * @param options - Options for introspection, such as schema filter.
+   * @returns A promise that resolves to the introspected database schema.
+   */
   async introspect(ctx, options) {
     const schema = options.schema;
     const filterSchema = schema ? "sch.name = @p1" : "1=1";
@@ -6759,10 +7212,21 @@ var dateTrunc = (part, date) => fn3("DATE_TRUNC", [part, date]);
 // src/orm/als.ts
 var AsyncLocalStorage = class {
   /**
-   * Executes a callback with the specified store value
-   * @param store - Value to store during callback execution
-   * @param callback - Function to execute with the store value
-   * @returns Result of the callback function
+   * Executes a callback function within a context containing the specified store value.
+   * The store value is only available during the callback's execution and is automatically
+   * cleared afterward.
+   * 
+   * @param store - The context value to make available during callback execution
+   * @param callback - Function to execute with the store value available
+   * @returns Result of the callback function execution
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<number>();
+   * als.run(42, () => {
+   *   console.log(als.getStore()); // Outputs: 42
+   * });
+   * ```
    */
   run(store, callback) {
     this.store = store;
@@ -6773,8 +7237,20 @@ var AsyncLocalStorage = class {
     }
   }
   /**
-   * Gets the currently stored value
-   * @returns Current store value or undefined if none exists
+   * Retrieves the current store value from the async context.
+   * Returns undefined if called outside of a `run()` callback execution.
+   * 
+   * @returns Current store value or undefined if no context exists
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<string>();
+   * console.log(als.getStore()); // Outputs: undefined
+   * 
+   * als.run('hello', () => {
+   *   console.log(als.getStore()); // Outputs: 'hello'
+   * });
+   * ```
    */
   getStore() {
     return this.store;
@@ -6864,11 +7340,7 @@ var TypeScriptGenerator = class {
     const lines = [];
     const hydration = ast.meta?.hydration;
     const hydratedRelations = new Set(hydration?.relations?.map((r) => r.name) ?? []);
-    const selections = ast.columns.filter((col2) => !(hydration && isRelationAlias(col2.alias))).map((col2) => {
-      const key = col2.alias || col2.name;
-      const operand = col2;
-      return `${key}: ${this.printOperand(operand)}`;
-    });
+    const selections = ast.columns.filter((col2) => !(hydration && isRelationAlias(col2.alias))).map((col2, index) => `${this.getSelectionKey(col2, index)}: ${this.printOperand(col2)}`);
     lines.push(`db.select({`);
     selections.forEach((sel2, index) => {
       lines.push(`  ${sel2}${index < selections.length - 1 ? "," : ""}`);
@@ -6956,7 +7428,7 @@ var TypeScriptGenerator = class {
    * Prints an ordering term (operand/expression/alias) to TypeScript code.
    */
   printOrderingTerm(term) {
-    if (!term || !term.type) {
+    if (!term || !("type" in term)) {
       throw new Error("Unsupported ordering term");
     }
     switch (term.type) {
@@ -6975,6 +7447,18 @@ var TypeScriptGenerator = class {
         return this.printExpression(term);
     }
   }
+  getSelectionKey(selection, index) {
+    if (selection.alias) {
+      return selection.alias;
+    }
+    if (this.isNamedSelection(selection)) {
+      return selection.name;
+    }
+    return `selection${index + 1}`;
+  }
+  isNamedSelection(selection) {
+    return "name" in selection;
+  }
   visitBinaryExpression(binary) {
     return this.printBinaryExpression(binary);
   }
@@ -7758,6 +8242,7 @@ var RelationChangeProcessor = class {
    * @param _entry - The relation change entry (reserved for future use)
    */
   async handleBelongsToChange(_entry) {
+    void _entry;
   }
   /**
    * Handles changes for belongs-to-many relations.
@@ -7871,7 +8356,7 @@ var RelationChangeProcessor = class {
     const key = findPrimaryKey(table);
     const value = entity[key];
     if (value === void 0 || value === null) return null;
-    return value;
+    return value ?? null;
   }
 };
 
@@ -8463,8 +8948,6 @@ var Orm = class {
     const session = new OrmSession({ orm: this, executor });
     try {
       return await session.transaction(() => fn4(session));
-    } catch (err) {
-      throw err;
     } finally {
       await session.dispose();
     }
@@ -8495,9 +8978,6 @@ var getOrCreateMetadataBag = (context) => {
 var readMetadataBag = (context) => {
   return context.metadata?.[METADATA_KEY];
 };
-var registerInitializer = (context, initializer) => {
-  context.addInitializer?.(initializer);
-};
 
 // src/decorators/entity.ts
 var toSnakeCase = (value) => {
@@ -8527,14 +9007,24 @@ function Entity(options = {}) {
       if (bag) {
         const meta = ensureEntityMetadata(ctor);
         for (const entry of bag.columns) {
-          if (!meta.columns[entry.propertyName]) {
-            addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+          if (meta.columns[entry.propertyName]) {
+            throw new Error(
+              `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+            );
           }
+          addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
         }
         for (const entry of bag.relations) {
-          if (!meta.relations[entry.propertyName]) {
-            addRelationMetadata(ctor, entry.propertyName, entry.relation);
+          if (meta.relations[entry.propertyName]) {
+            throw new Error(
+              `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+            );
           }
+          const relationCopy = entry.relation.kind === RelationKinds.BelongsToMany ? {
+            ...entry.relation,
+            defaultPivotColumns: entry.relation.defaultPivotColumns ? [...entry.relation.defaultPivotColumns] : void 0
+          } : { ...entry.relation };
+          addRelationMetadata(ctor, entry.propertyName, relationCopy);
         }
       }
     }
@@ -8597,13 +9087,6 @@ var registerColumnFromContext = (context, column) => {
   if (!bag.columns.some((entry) => entry.propertyName === propertyName)) {
     bag.columns.push({ propertyName, column: { ...column } });
   }
-  registerInitializer(context, function() {
-    const ctor = resolveConstructor(this);
-    if (!ctor) {
-      return;
-    }
-    registerColumn(ctor, propertyName, column);
-  });
 };
 function Column(definition) {
   const normalized = normalizeColumnInput(definition);
@@ -8659,13 +9142,6 @@ var createFieldDecorator = (metadataFactory) => {
       if (!bag.relations.some((entry) => entry.propertyName === propertyName2)) {
         bag.relations.push({ propertyName: propertyName2, relation: relationMetadata });
       }
-      registerInitializer(ctx, function() {
-        const ctor2 = resolveConstructor2(this);
-        if (!ctor2) {
-          return;
-        }
-        registerRelation(ctor2, propertyName2, relationMetadata);
-      });
       return;
     }
     const propertyName = normalizePropertyName2(propertyKeyOrContext);
@@ -9302,11 +9778,9 @@ export {
   cos,
   cot,
   count,
-  createColumn,
   createEntityFromRow,
   createEntityProxy,
   createExecutorFromQueryRunner,
-  createLiteral,
   createMssqlExecutor,
   createMysqlExecutor,
   createPooledExecutorFactory,
@@ -9330,6 +9804,7 @@ export {
   diffSchema,
   div,
   endOfMonth,
+  entityRef,
   eq,
   esel,
   executeHydrated,
@@ -9342,6 +9817,7 @@ export {
   fromUnixTime,
   generateCreateTableSql,
   generateSchemaSql,
+  getColumn,
   getSchemaIntrospector,
   getTableDefFromEntity,
   groupConcat,