metal-orm 1.0.43 → 1.0.45

package/dist/index.js

@@ -325,39 +325,48 @@ var isWindowFunctionNode = (node) => isOperandNode(node) && node.type === "Windo
 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"
@@ -370,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)
   };
@@ -399,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
 });
@@ -419,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)
@@ -601,16 +610,45 @@ 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 = () => {
+  expressionRegistry = expressionRegistry.clear();
+};
+var clearOperandDispatchers = () => {
+  operandRegistry = operandRegistry.clear();
 };
-var clearExpressionDispatchers = () => expressionDispatchers.clear();
-var clearOperandDispatchers = () => operandDispatchers.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 "${getNodeType(node) ?? "unknown"}"`);
@@ -619,7 +657,7 @@ var unsupportedOperand = (node) => {
   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":
@@ -650,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":
@@ -685,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,
@@ -716,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",
@@ -737,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();
@@ -775,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);
@@ -788,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) {
@@ -803,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: ","
@@ -2333,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: []
     };
@@ -2484,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 {
@@ -2574,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
@@ -2651,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;
@@ -2661,6 +2762,11 @@ 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) {
@@ -2671,6 +2777,11 @@ var HydrationManager = class _HydrationManager {
     }
     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) {
@@ -2681,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;
@@ -2693,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;
@@ -2708,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;
@@ -3080,6 +3216,11 @@ 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;
@@ -3196,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 }
@@ -3206,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
   );
@@ -3384,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);
   }
   /**
@@ -3429,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 {
   /**
@@ -3573,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;
@@ -3698,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;
@@ -3715,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();
@@ -3724,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 = {
@@ -3746,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;
@@ -3760,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);
@@ -3772,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);
@@ -3788,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;
   }
@@ -4163,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) {
@@ -4288,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 = [];
@@ -4577,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 };
@@ -4602,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);
   }
@@ -4621,10 +4793,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const nextContext = this.applyAst(this.context, (service) => service.withFrom(nextFrom));
     return this.clone(nextContext);
   }
-  resolveQueryNode(query) {
-    const candidate = query;
-    return typeof candidate.getAST === "function" && candidate.getAST ? candidate.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;
@@ -4633,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];
@@ -4674,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);
   }
@@ -4732,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));
   }
   /**
@@ -4762,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);
@@ -4889,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 currBuilder = this;
-    if (config.root?.length) {
-      currBuilder = currBuilder.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;
-      currBuilder = currBuilder.selectRelationColumns(relName, ...cols);
+    for (const entry of config) {
+      if (entry.type === "root") {
+        currBuilder = currBuilder.select(...entry.columns);
+      } else {
+        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...entry.columns);
+      }
     }
     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);
@@ -4940,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);
@@ -4968,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) {
@@ -5108,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) {
@@ -5134,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();
@@ -5224,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();
@@ -5376,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 ?? {
@@ -5406,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") {
@@ -5432,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({
@@ -5439,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) {
@@ -5456,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,
@@ -5466,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);
@@ -5473,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));
@@ -5508,9 +5702,18 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
     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;
   }
@@ -5529,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 ?? {
@@ -5538,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)) {
@@ -5562,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,
@@ -5599,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);
@@ -5606,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));
@@ -5639,17 +5920,36 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
     if (typeof table === "string") return table;
     return this.resolveTableSource(table);
   }
-  compile(arg) {
-    const candidate = arg;
-    if (typeof candidate.compileUpdate === "function") {
-      return candidate.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;
   }
@@ -5658,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 ?? {
@@ -5669,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,
@@ -5706,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);
@@ -5713,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));
@@ -5742,17 +6105,36 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
     if (typeof table === "string") return table;
     return this.resolveTableSource(table);
   }
-  compile(arg) {
-    const candidate = arg;
-    if (typeof candidate.compileDelete === "function") {
-      return candidate.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;
   }
@@ -6187,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 = [];
@@ -6474,6 +6863,12 @@ var toReferentialAction = (value) => {
 };
 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(
@@ -6529,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";
@@ -6811,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;
@@ -6825,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;
@@ -9354,11 +9778,9 @@ export {
   cos,
   cot,
   count,
-  createColumn,
   createEntityFromRow,
   createEntityProxy,
   createExecutorFromQueryRunner,
-  createLiteral,
   createMssqlExecutor,
   createMysqlExecutor,
   createPooledExecutorFactory,