metal-orm 1.0.16 → 1.0.18

package/src/orm/hydration-context.ts

@@ -1,13 +1,15 @@
 import { IdentityMap } from './identity-map.js';
 import { UnitOfWork } from './unit-of-work.js';
-import { DomainEventBus } from './domain-event-bus.js';
+import type { DomainEventBus } from './domain-event-bus.js';
 import { RelationChangeProcessor } from './relation-change-processor.js';
-import { EntityContext } from './entity-context.js';
+import type { EntityContext } from './entity-context.js';
+import type { AnyDomainEvent, DomainEvent } from './runtime-types.js';
+import type { OrmSession } from './orm-session.js';
 
-export interface HydrationContext {
+export interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
   identityMap: IdentityMap;
   unitOfWork: UnitOfWork;
-  domainEvents: DomainEventBus<any>;
+  domainEvents: DomainEventBus<E, OrmSession<E>>;
   relationChanges: RelationChangeProcessor;
   entityContext: EntityContext;
   // maybe mapping registry, converters, etc.

package/src/orm/orm-session.ts

@@ -1,9 +1,10 @@
 import { Dialect } from '../core/dialect/abstract.js';
 import { eq } from '../core/ast/expression.js';
 import type { DbExecutor } from '../core/execution/db-executor.js';
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import type { TableDef } from '../schema/table.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import type { ColumnDef } from '../schema/column.js';
+import type { TableDef } from '../schema/table.js';
 import { Entity } from '../schema/types.js';
 import { RelationDef } from '../schema/relation.js';
 
@@ -12,13 +13,15 @@ import type { EntityConstructor } from './entity-metadata.js';
 import { Orm } from './orm.js';
 import { IdentityMap } from './identity-map.js';
 import { UnitOfWork } from './unit-of-work.js';
-import { DomainEventBus, DomainEventHandler } from './domain-event-bus.js';
+import { DomainEventBus, DomainEventHandler, InitialHandlers } from './domain-event-bus.js';
 import { RelationChangeProcessor } from './relation-change-processor.js';
 import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
 import { ExecutionContext } from './execution-context.js';
-import { HydrationContext } from './hydration-context.js';
-import { EntityContext } from './entity-context.js';
+import type { HydrationContext } from './hydration-context.js';
+import type { EntityContext } from './entity-context.js';
 import {
+  DomainEvent,
+  OrmDomainEvent,
   RelationChange,
   RelationChangeEntry,
   RelationKey,
@@ -32,25 +35,25 @@ export interface OrmInterceptor {
   afterFlush?(ctx: EntityContext): Promise<void> | void;
 }
 
-export interface OrmSessionOptions {
-  orm: Orm;
+export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+  orm: Orm<E>;
   executor: DbExecutor;
   queryLogger?: QueryLogger;
   interceptors?: OrmInterceptor[];
-  domainEventHandlers?: Record<string, DomainEventHandler<OrmSession>[]>;
+  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
 
-export class OrmSession implements EntityContext {
-  readonly orm: Orm;
+export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+  readonly orm: Orm<E>;
   readonly executor: DbExecutor;
   readonly identityMap: IdentityMap;
   readonly unitOfWork: UnitOfWork;
-  readonly domainEvents: DomainEventBus<OrmSession>;
+  readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
   readonly relationChanges: RelationChangeProcessor;
 
   private readonly interceptors: OrmInterceptor[];
 
-  constructor(opts: OrmSessionOptions) {
+  constructor(opts: OrmSessionOptions<E>) {
     this.orm = opts.orm;
     this.executor = createQueryLoggingExecutor(opts.executor, opts.queryLogger);
     this.interceptors = [...(opts.interceptors ?? [])];
@@ -58,7 +61,7 @@ export class OrmSession implements EntityContext {
     this.identityMap = new IdentityMap();
     this.unitOfWork = new UnitOfWork(this.orm.dialect, this.executor, this.identityMap, () => this);
     this.relationChanges = new RelationChangeProcessor(this.unitOfWork, this.orm.dialect, this.executor);
-    this.domainEvents = new DomainEventBus<OrmSession>(opts.domainEventHandlers);
+    this.domainEvents = new DomainEventBus<E, OrmSession<E>>(opts.domainEventHandlers);
   }
 
   get dialect(): Dialect {
@@ -118,8 +121,11 @@ export class OrmSession implements EntityContext {
     this.interceptors.push(interceptor);
   }
 
-  registerDomainEventHandler(name: string, handler: DomainEventHandler<OrmSession>): void {
-    this.domainEvents.register(name, handler);
+  registerDomainEventHandler<TType extends E['type']>(
+    type: TType,
+    handler: DomainEventHandler<Extract<E, { type: TType }>, OrmSession<E>>
+  ): void {
+    this.domainEvents.on(type, handler);
   }
 
   async find<TTable extends TableDef>(entityClass: EntityConstructor, id: any): Promise<Entity<TTable> | null> {
@@ -128,13 +134,18 @@ export class OrmSession implements EntityContext {
       throw new Error('Entity metadata has not been bootstrapped');
     }
     const primaryKey = findPrimaryKey(table);
-    const column = table.columns[primaryKey];
-    if (!column) {
-      throw new Error('Entity table does not expose a primary key');
-    }
-    const qb = selectFromEntity<TTable>(entityClass)
-      .where(eq(column, id))
-      .limit(1);
+    const column = table.columns[primaryKey];
+    if (!column) {
+      throw new Error('Entity table does not expose a primary key');
+    }
+    const columnSelections = Object.values(table.columns).reduce<Record<string, ColumnDef>>((acc, col) => {
+      acc[col.name] = col;
+      return acc;
+    }, {});
+    const qb = selectFromEntity<TTable>(entityClass)
+      .select(columnSelections)
+      .where(eq(column, id))
+      .limit(1);
     const rows = await executeHydrated(this, qb);
     return rows[0] ?? null;
   }
@@ -206,7 +217,7 @@ export class OrmSession implements EntityContext {
     };
   }
 
-  getHydrationContext(): HydrationContext {
+  getHydrationContext(): HydrationContext<E> {
     return {
       identityMap: this.identityMap,
       unitOfWork: this.unitOfWork,

package/src/orm/orm.ts

@@ -1,11 +1,12 @@
+import type { DomainEvent, OrmDomainEvent } from './runtime-types.js';
 import type { Dialect } from '../core/dialect/abstract.js';
-import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
 import type { NamingStrategy } from '../codegen/naming-strategy.js';
 import { InterceptorPipeline } from './interceptor-pipeline.js';
 import { DefaultNamingStrategy } from '../codegen/naming-strategy.js';
-import { OrmSession } from './orm-session.ts';
+import { OrmSession } from './orm-session.js';
 
-export interface OrmOptions {
+export interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
   dialect: Dialect;
   executorFactory: DbExecutorFactory;
   interceptors?: InterceptorPipeline;
@@ -22,28 +23,27 @@ export interface ExternalTransaction {
   // Transaction-specific properties
 }
 
-export class Orm {
+export class Orm<E extends DomainEvent = OrmDomainEvent> {
   readonly dialect: Dialect;
   readonly interceptors: InterceptorPipeline;
   readonly namingStrategy: NamingStrategy;
   private readonly executorFactory: DbExecutorFactory;
 
-  constructor(opts: OrmOptions) {
+  constructor(opts: OrmOptions<E>) {
     this.dialect = opts.dialect;
     this.interceptors = opts.interceptors ?? new InterceptorPipeline();
     this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
     this.executorFactory = opts.executorFactory;
   }
 
-  createSession(options?: { tx?: ExternalTransaction }): OrmSession {
+  createSession(options?: { tx?: ExternalTransaction }): OrmSession<E> {
     const executor = this.executorFactory.createExecutor(options?.tx);
-    return new OrmSession({ orm: this, executor });
+    return new OrmSession<E>({ orm: this, executor });
   }
 
-  // Nice convenience:
-  async transaction<T>(fn: (session: OrmSession) => Promise<T>): Promise<T> {
+  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
     const executor = this.executorFactory.createTransactionalExecutor();
-    const session = new OrmSession({ orm: this, executor });
+    const session = new OrmSession<E>({ orm: this, executor });
     try {
       const result = await fn(session);
       await session.commit();

package/src/orm/query-logger.ts

@@ -1,12 +1,27 @@
 import type { DbExecutor } from '../core/execution/db-executor.js';
 
+/**
+ * Represents a single SQL query log entry
+ */
 export interface QueryLogEntry {
+  /** The SQL query that was executed */
   sql: string;
+  /** Parameters used in the query */
   params?: unknown[];
 }
 
+/**
+ * Function type for query logging callbacks
+ * @param entry - The query log entry to process
+ */
 export type QueryLogger = (entry: QueryLogEntry) => void;
 
+/**
+ * Creates a wrapped database executor that logs all SQL queries
+ * @param executor - Original database executor to wrap
+ * @param logger - Optional logger function to receive query log entries
+ * @returns Wrapped executor that logs queries before execution
+ */
 export const createQueryLoggingExecutor = (
   executor: DbExecutor,
   logger?: QueryLogger

package/src/orm/runtime-types.ts

@@ -1,39 +1,97 @@
 import { RelationDef } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
 
+/**
+ * Entity status enum representing the lifecycle state of an entity
+ */
 export enum EntityStatus {
+  /** Entity is newly created and not yet persisted */
   New = 'new',
+  /** Entity is managed by the ORM and synchronized with the database */
   Managed = 'managed',
+  /** Entity has been modified but not yet persisted */
   Dirty = 'dirty',
+  /** Entity has been marked for removal */
   Removed = 'removed',
+  /** Entity is detached from the ORM context */
   Detached = 'detached'
 }
 
+/**
+ * Represents an entity being tracked by the ORM
+ */
 export interface TrackedEntity {
+  /** The table definition this entity belongs to */
   table: TableDef;
+  /** The actual entity instance */
   entity: any;
+  /** Primary key value of the entity */
   pk: string | number | null;
+  /** Current status of the entity */
   status: EntityStatus;
+  /** Original values of the entity when it was loaded */
   original: Record<string, any> | null;
 }
 
+/**
+ * Type representing a key for relation navigation
+ */
 export type RelationKey = string;
 
+/**
+ * Represents a change operation on a relation
+ * @typeParam T - Type of the related entity
+ */
 export type RelationChange<T> =
   | { kind: 'add'; entity: T }
   | { kind: 'attach'; entity: T }
   | { kind: 'remove'; entity: T }
   | { kind: 'detach'; entity: T };
 
+/**
+ * Represents a relation change entry in the unit of work
+ */
 export interface RelationChangeEntry {
+  /** Root entity that owns the relation */
   root: any;
+  /** Key of the relation being changed */
   relationKey: RelationKey;
+  /** Table definition of the root entity */
   rootTable: TableDef;
+  /** Name of the relation */
   relationName: string;
+  /** Relation definition */
   relation: RelationDef;
+  /** The change being applied */
   change: RelationChange<any>;
 }
 
-export interface HasDomainEvents {
-  domainEvents?: any[];
+/**
+ * Represents a domain event that can be emitted by entities
+ * @typeParam TType - Type of the event (string literal)
+ */
+export interface DomainEvent<TType extends string = string> {
+  /** Type identifier for the event */
+  readonly type: TType;
+  /** Timestamp when the event occurred */
+  readonly occurredAt?: Date;
+}
+
+/**
+ * Type representing any domain event
+ */
+export type AnyDomainEvent = DomainEvent<string>;
+
+/**
+ * Type representing ORM-specific domain events
+ */
+export type OrmDomainEvent = AnyDomainEvent;
+
+/**
+ * Interface for entities that can emit domain events
+ * @typeParam E - Type of domain events this entity can emit
+ */
+export interface HasDomainEvents<E extends DomainEvent = AnyDomainEvent> {
+  /** Array of domain events emitted by this entity */
+  domainEvents?: E[];
 }

package/src/orm/transaction-runner.ts

@@ -1,5 +1,12 @@
 import type { DbExecutor } from '../core/execution/db-executor.js';
 
+/**
+ * Executes a function within a database transaction
+ * @param executor - Database executor to use for transaction operations
+ * @param action - Function to execute within the transaction
+ * @returns Promise that resolves when the transaction is complete
+ * @throws Re-throws any errors that occur during the transaction (after rolling back)
+ */
 export const runInTransaction = async (executor: DbExecutor, action: () => Promise<void>): Promise<void> => {
   if (!executor.beginTransaction) {
     await action();

package/src/orm/unit-of-work.ts

@@ -215,6 +215,7 @@ export class UnitOfWork {
   private extractColumns(table: TableDef, entity: any): Record<string, unknown> {
     const payload: Record<string, unknown> = {};
     for (const column of Object.keys(table.columns)) {
+      if (entity[column] === undefined) continue;
       payload[column] = entity[column];
     }
     return payload;

package/src/query-builder/column-selector.ts

@@ -69,10 +69,12 @@ export class ColumnSelector {
    * @param columns - Columns to make distinct
    * @returns Updated query context with DISTINCT clause
    */
-  distinct(context: SelectQueryBuilderContext, columns: (ColumnDef | ColumnNode)[]): SelectQueryBuilderContext {
-    const nodes = columns.map(col => buildColumnNode(this.env.table, col));
-    const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
-    const nextState = astService.withDistinct(nodes);
-    return { state: nextState, hydration: context.hydration };
-  }
-}
+  distinct(context: SelectQueryBuilderContext, columns: (ColumnDef | ColumnNode)[]): SelectQueryBuilderContext {
+    const from = context.state.ast.from;
+    const tableRef = from.type === 'Table' && from.alias ? { ...this.env.table, alias: from.alias } : this.env.table;
+    const nodes = columns.map(col => buildColumnNode(tableRef, col));
+    const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
+    const nextState = astService.withDistinct(nodes);
+    return { state: nextState, hydration: context.hydration };
+  }
+}

package/src/query-builder/insert-query-state.ts

@@ -1,6 +1,6 @@
 import { TableDef } from '../schema/table.js';
 import { InsertQueryNode, TableNode } from '../core/ast/query.js';
-import { ColumnNode, OperandNode, valueToOperand } from '../core/ast/expression.js';
+import { ColumnNode, OperandNode, isValueOperandInput, valueToOperand } from '../core/ast/expression.js';
 import { buildColumnNodes, createTableNode } from '../core/ast/builders.js';
 
 /**
@@ -31,8 +31,18 @@ export class InsertQueryState {
       ? this.ast.columns
       : buildColumnNodes(this.table, Object.keys(rows[0]));
 
-    const newRows: OperandNode[][] = rows.map(row =>
-      definedColumns.map(column => valueToOperand(row[column.name]))
+    const newRows: OperandNode[][] = rows.map((row, rowIndex) =>
+      definedColumns.map(column => {
+        const rawValue = row[column.name];
+
+        if (!isValueOperandInput(rawValue)) {
+          throw new Error(
+            `Invalid insert value for column "${column.name}" in row ${rowIndex}: only primitives, null, or OperandNodes are allowed`
+          );
+        }
+
+        return valueToOperand(rawValue);
+      })
     );
 
     return this.clone({

package/src/query-builder/query-ast-service.ts

@@ -1,6 +1,6 @@
 import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column.js';
-import { SelectQueryNode, CommonTableExpressionNode, SetOperationKind, SetOperationNode } from '../core/ast/query.js';
+import { SelectQueryNode, CommonTableExpressionNode, SetOperationKind, SetOperationNode, TableSourceNode } from '../core/ast/query.js';
 import { buildColumnNode } from '../core/ast/builders.js';
 import {
   ColumnNode,
@@ -47,30 +47,36 @@ export class QueryAstService {
    * @param columns - Columns to select (key: alias, value: column definition or expression)
    * @returns Column selection result with updated state and added columns
    */
-  select(
-    columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>
-  ): ColumnSelectionResult {
-    const existingAliases = new Set(
-      this.state.ast.columns.map(c => (c as ColumnNode).alias || (c as ColumnNode).name)
-    );
-
-    const newCols = Object.entries(columns).reduce<ProjectionNode[]>((acc, [alias, val]) => {
-      if (existingAliases.has(alias)) return acc;
-
-      if (isExpressionSelectionNode(val)) {
-        acc.push({ ...(val as FunctionNode | CaseExpressionNode | WindowFunctionNode), alias } as ProjectionNode);
-        return acc;
-      }
-
-      const colDef = val as ColumnDef;
-      acc.push({
-        type: 'Column',
-        table: colDef.table || this.table.name,
-        name: colDef.name,
-        alias
-      } as ColumnNode);
-      return acc;
-    }, []);
+  select(
+    columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>
+  ): ColumnSelectionResult {
+    const existingAliases = new Set(
+      this.state.ast.columns.map(c => (c as ColumnNode).alias || (c as ColumnNode).name)
+    );
+    const from = this.state.ast.from;
+    const rootTableName = from.type === 'Table' && from.alias ? from.alias : this.table.name;
+
+    const newCols = Object.entries(columns).reduce<ProjectionNode[]>((acc, [alias, val]) => {
+      if (existingAliases.has(alias)) return acc;
+
+      if (isExpressionSelectionNode(val)) {
+        acc.push({ ...(val as FunctionNode | CaseExpressionNode | WindowFunctionNode), alias } as ProjectionNode);
+        return acc;
+      }
+
+      const colDef = val as ColumnDef;
+      const resolvedTable =
+        colDef.table && colDef.table === this.table.name && from.type === 'Table' && from.alias
+          ? from.alias
+          : colDef.table || rootTableName;
+      acc.push({
+        type: 'Column',
+        table: resolvedTable,
+        name: colDef.name,
+        alias
+      } as ColumnNode);
+      return acc;
+    }, []);
 
     const nextState = this.state.withColumns(newCols);
     return { state: nextState, addedColumns: newCols };
@@ -81,11 +87,13 @@ export class QueryAstService {
    * @param cols - Raw column expressions
    * @returns Column selection result with updated state and added columns
    */
-  selectRaw(cols: string[]): ColumnSelectionResult {
-    const newCols = cols.map(col => parseRawColumn(col, this.table.name, this.state.ast.ctes));
-    const nextState = this.state.withColumns(newCols);
-    return { state: nextState, addedColumns: newCols };
-  }
+  selectRaw(cols: string[]): ColumnSelectionResult {
+    const from = this.state.ast.from;
+    const defaultTable = from.type === 'Table' && from.alias ? from.alias : this.table.name;
+    const newCols = cols.map(col => parseRawColumn(col, defaultTable, this.state.ast.ctes));
+    const nextState = this.state.withColumns(newCols);
+    return { state: nextState, addedColumns: newCols };
+  }
 
   /**
    * Adds a Common Table Expression (CTE) to the query
@@ -121,6 +129,15 @@ export class QueryAstService {
     };
     return this.state.withSetOperation(op);
   }
+
+  /**
+   * Replaces the FROM clause for the current query.
+   * @param from - Table source to use in the FROM clause
+   * @returns Updated query state with new FROM
+   */
+  withFrom(from: TableSourceNode): SelectQueryState {
+    return this.state.withFrom(from);
+  }
 
   /**
    * Selects a subquery as a column
@@ -157,10 +174,12 @@ export class QueryAstService {
    * @param col - Column to group by
    * @returns Updated query state with GROUP BY clause
    */
-  withGroupBy(col: ColumnDef | ColumnNode): SelectQueryState {
-    const node = buildColumnNode(this.table, col);
-    return this.state.withGroupBy([node]);
-  }
+  withGroupBy(col: ColumnDef | ColumnNode): SelectQueryState {
+    const from = this.state.ast.from;
+    const tableRef = from.type === 'Table' && from.alias ? { ...this.table, alias: from.alias } : this.table;
+    const node = buildColumnNode(tableRef, col);
+    return this.state.withGroupBy([node]);
+  }
 
   /**
    * Adds a HAVING clause to the query
@@ -178,10 +197,12 @@ export class QueryAstService {
    * @param direction - Order direction (ASC/DESC)
    * @returns Updated query state with ORDER BY clause
    */
-  withOrderBy(col: ColumnDef | ColumnNode, direction: OrderDirection): SelectQueryState {
-    const node = buildColumnNode(this.table, col);
-    return this.state.withOrderBy([{ type: 'OrderBy', column: node, direction }]);
-  }
+  withOrderBy(col: ColumnDef | ColumnNode, direction: OrderDirection): SelectQueryState {
+    const from = this.state.ast.from;
+    const tableRef = from.type === 'Table' && from.alias ? { ...this.table, alias: from.alias } : this.table;
+    const node = buildColumnNode(tableRef, col);
+    return this.state.withOrderBy([{ type: 'OrderBy', column: node, direction }]);
+  }
 
   /**
    * Adds a DISTINCT clause to the query

package/src/query-builder/relation-conditions.ts

@@ -21,25 +21,26 @@ const assertNever = (value: never): never => {
  * @param relation - Relation definition
  * @returns Expression node representing the join condition
  */
-const baseRelationCondition = (root: TableDef, relation: RelationDef): ExpressionNode => {
-  const defaultLocalKey =
+const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
+  const rootTable = rootAlias || root.name;
+  const defaultLocalKey =
   relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne
     ? findPrimaryKey(root)
     : findPrimaryKey(relation.target);
-  const localKey = relation.localKey || defaultLocalKey;
+  const localKey = relation.localKey || defaultLocalKey;
 
   switch (relation.type) {
     case RelationKinds.HasMany:
     case RelationKinds.HasOne:
       return eq(
         { type: 'Column', table: relation.target.name, name: relation.foreignKey },
-        { type: 'Column', table: root.name, name: localKey }
+        { type: 'Column', table: rootTable, name: localKey }
+      );
+    case RelationKinds.BelongsTo:
+      return eq(
+        { type: 'Column', table: relation.target.name, name: localKey },
+        { type: 'Column', table: rootTable, name: relation.foreignKey }
       );
-    case RelationKinds.BelongsTo:
-      return eq(
-        { type: 'Column', table: relation.target.name, name: localKey },
-        { type: 'Column', table: root.name, name: relation.foreignKey }
-      );
     case RelationKinds.BelongsToMany:
       throw new Error('BelongsToMany relations do not support the standard join condition builder');
     default:
@@ -50,20 +51,22 @@ const baseRelationCondition = (root: TableDef, relation: RelationDef): Expressio
 /**
  * Builds the join nodes required to include a BelongsToMany relation.
  */
-export const buildBelongsToManyJoins = (
-  root: TableDef,
-  relationName: string,
-  relation: BelongsToManyRelation,
-  joinKind: JoinKind,
-  extra?: ExpressionNode
-): JoinNode[] => {
-  const rootKey = relation.localKey || findPrimaryKey(root);
-  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
-
-  const pivotCondition = eq(
-    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
-    { type: 'Column', table: root.name, name: rootKey }
-  );
+export const buildBelongsToManyJoins = (
+  root: TableDef,
+  relationName: string,
+  relation: BelongsToManyRelation,
+  joinKind: JoinKind,
+  extra?: ExpressionNode,
+  rootAlias?: string
+): JoinNode[] => {
+  const rootKey = relation.localKey || findPrimaryKey(root);
+  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
+  const rootTable = rootAlias || root.name;
+
+  const pivotCondition = eq(
+    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
+    { type: 'Column', table: rootTable, name: rootKey }
+  );
 
   const pivotJoin = createJoinNode(joinKind, relation.pivotTable.name, pivotCondition);
 
@@ -93,14 +96,15 @@ export const buildBelongsToManyJoins = (
  * @param extra - Optional additional expression to combine with AND
  * @returns Expression node representing the complete join condition
  */
-export const buildRelationJoinCondition = (
-  root: TableDef,
-  relation: RelationDef,
-  extra?: ExpressionNode
-): ExpressionNode => {
-  const base = baseRelationCondition(root, relation);
-  return extra ? and(base, extra) : base;
-};
+export const buildRelationJoinCondition = (
+  root: TableDef,
+  relation: RelationDef,
+  extra?: ExpressionNode,
+  rootAlias?: string
+): ExpressionNode => {
+  const base = baseRelationCondition(root, relation, rootAlias);
+  return extra ? and(base, extra) : base;
+};
 
 /**
  * Builds a relation correlation condition for subqueries
@@ -108,6 +112,6 @@ export const buildRelationJoinCondition = (
  * @param relation - Relation definition
  * @returns Expression node representing the correlation condition
  */
-export const buildRelationCorrelation = (root: TableDef, relation: RelationDef): ExpressionNode => {
-  return baseRelationCondition(root, relation);
-};
+export const buildRelationCorrelation = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
+  return baseRelationCondition(root, relation, rootAlias);
+};

package/src/query-builder/relation-manager.ts

@@ -67,9 +67,14 @@ export class RelationManager {
    * @param ast - Query AST to modify
    * @returns Modified query AST with relation correlation
    */
-  applyRelationCorrelation(context: SelectQueryBuilderContext, relationName: string, ast: SelectQueryNode): SelectQueryNode {
-    return this.createService(context).applyRelationCorrelation(relationName, ast);
-  }
+  applyRelationCorrelation(
+    context: SelectQueryBuilderContext,
+    relationName: string,
+    ast: SelectQueryNode,
+    additionalCorrelation?: ExpressionNode
+  ): SelectQueryNode {
+    return this.createService(context).applyRelationCorrelation(relationName, ast, additionalCorrelation);
+  }
 
   /**
    * Creates a relation service instance