metal-orm 1.0.16 → 1.0.18

package/src/core/dialect/mssql/functions.ts

@@ -84,18 +84,27 @@ export class MssqlFunctionStrategy extends StandardFunctionStrategy {
             return `DATEPART(dw, ${compiledArgs[0]})`;
         });
 
-        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
-            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
-            return `DATEPART(wk, ${compiledArgs[0]})`;
-        });
-
-        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
-            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
-            const [, date] = compiledArgs;
-            const partArg = node.args[0] as LiteralNode;
-            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
-            // SQL Server 2022+ has DATETRUNC
-            return `DATETRUNC(${partClean}, ${date})`;
-        });
-    }
-}
+        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
+            return `DATEPART(wk, ${compiledArgs[0]})`;
+        });
+
+        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
+            const [, date] = compiledArgs;
+            const partArg = node.args[0] as LiteralNode;
+            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
+            // SQL Server 2022+ has DATETRUNC
+            return `DATETRUNC(${partClean}, ${date})`;
+        });
+
+        this.add('GROUP_CONCAT', ctx => {
+            const arg = ctx.compiledArgs[0];
+            const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+            const separator = ctx.compileOperand(separatorOperand);
+            const orderClause = this.buildOrderByExpression(ctx);
+            const withinGroup = orderClause ? ` WITHIN GROUP (${orderClause})` : '';
+            return `STRING_AGG(${arg}, ${separator})${withinGroup}`;
+        });
+    }
+}

package/src/core/dialect/mssql/index.ts

@@ -1,7 +1,8 @@
 import { CompilerContext, Dialect } from '../abstract.js';
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
-import { JsonPathNode } from '../../ast/expression.js';
-import { MssqlFunctionStrategy } from './functions.js';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode, TableSourceNode, DerivedTableNode } from '../../ast/query.js';
+import { JsonPathNode } from '../../ast/expression.js';
+import { MssqlFunctionStrategy } from './functions.js';
+import { FunctionTableFormatter } from '../base/function-table-formatter.js';
 
 /**
  * Microsoft SQL Server dialect implementation
@@ -94,13 +95,16 @@ export class SqlServerDialect extends Dialect {
     return `UPDATE ${table} SET ${assignments}${whereClause};`;
   }
 
-  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.from.name);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    return `DELETE FROM ${table}${whereClause};`;
-  }
-
-  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
+  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
+    if (ast.from.type !== 'Table') {
+      throw new Error('DELETE only supports base tables in the MSSQL dialect.');
+    }
+    const table = this.quoteIdentifier(ast.from.name);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `DELETE FROM ${table}${whereClause};`;
+  }
+
+  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';
       if (c.type === 'Function') {
@@ -119,15 +123,15 @@ export class SqlServerDialect extends Dialect {
       }
       return expr;
     }).join(', ');
-
-    const distinct = ast.distinct ? 'DISTINCT ' : '';
-    const from = `${this.quoteIdentifier(ast.from.name)}`;
-
-    const joins = ast.joins.map(j => {
-      const table = this.quoteIdentifier(j.table.name);
-      const cond = this.compileExpression(j.condition, ctx);
-      return `${j.kind} JOIN ${table} ON ${cond}`;
-    }).join(' ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = this.compileTableSource(ast.from, ctx);
+
+    const joins = ast.joins.map(j => {
+      const table = this.compileTableSource(j.table, ctx);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
     const whereClause = this.compileWhere(ast.where, ctx);
 
     const groupBy = ast.groupBy && ast.groupBy.length > 0
@@ -155,19 +159,40 @@ export class SqlServerDialect extends Dialect {
       .join(', ');
   }
 
-  private compilePagination(ast: SelectQueryNode, orderBy: string): string {
-    const hasLimit = ast.limit !== undefined;
-    const hasOffset = ast.offset !== undefined;
-    if (!hasLimit && !hasOffset) return '';
+  private compilePagination(ast: SelectQueryNode, orderBy: string): string {
+    const hasLimit = ast.limit !== undefined;
+    const hasOffset = ast.offset !== undefined;
+    if (!hasLimit && !hasOffset) return '';
 
     const off = ast.offset ?? 0;
     const orderClause = orderBy || ' ORDER BY (SELECT NULL)';
     let pagination = `${orderClause} OFFSET ${off} ROWS`;
-    if (hasLimit) {
-      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
-    }
-    return pagination;
-  }
+    if (hasLimit) {
+      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
+    }
+    return pagination;
+  }
+
+  private compileTableSource(table: TableSourceNode, ctx: CompilerContext): string {
+    if (table.type === 'FunctionTable') {
+      return FunctionTableFormatter.format(table, ctx, this as any);
+    }
+    if (table.type === 'DerivedTable') {
+      return this.compileDerivedTable(table, ctx);
+    }
+    const base = table.schema
+      ? `${this.quoteIdentifier(table.schema)}.${this.quoteIdentifier(table.name)}`
+      : this.quoteIdentifier(table.name);
+    return table.alias ? `${base} AS ${this.quoteIdentifier(table.alias)}` : base;
+  }
+
+  private compileDerivedTable(table: DerivedTableNode, ctx: CompilerContext): string {
+    const sub = this.compileSelectAst(this.normalizeSelectAst(table.query), ctx).trim().replace(/;$/, '');
+    const cols = table.columnAliases?.length
+      ? ` (${table.columnAliases.map(c => this.quoteIdentifier(c)).join(', ')})`
+      : '';
+    return `(${sub}) AS ${this.quoteIdentifier(table.alias)}${cols}`;
+  }
 
   private compileCtes(ast: SelectQueryNode, ctx: CompilerContext): string {
     if (!ast.ctes || ast.ctes.length === 0) return '';

package/src/core/dialect/postgres/functions.ts

@@ -69,27 +69,36 @@ export class PostgresFunctionStrategy extends StandardFunctionStrategy {
             return `TO_CHAR(${date}, ${format})`;
         });
 
-        this.add('END_OF_MONTH', ({ compiledArgs }) => {
-            if (compiledArgs.length !== 1) throw new Error('END_OF_MONTH expects 1 argument');
-            return `(date_trunc('month', ${compiledArgs[0]}) + interval '1 month' - interval '1 day')::DATE`;
-        });
-
-        this.add('DAY_OF_WEEK', ({ compiledArgs }) => {
-            if (compiledArgs.length !== 1) throw new Error('DAY_OF_WEEK expects 1 argument');
-            return `EXTRACT(DOW FROM ${compiledArgs[0]})`;
-        });
-
-        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
-            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
-            return `EXTRACT(WEEK FROM ${compiledArgs[0]})`;
-        });
-
-        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
-            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
-            const [, date] = compiledArgs;
-            const partArg = node.args[0] as LiteralNode;
-            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
-            return `DATE_TRUNC('${partClean}', ${date})`;
-        });
-    }
-}
+        this.add('END_OF_MONTH', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('END_OF_MONTH expects 1 argument');
+            return `(date_trunc('month', ${compiledArgs[0]}) + interval '1 month' - interval '1 day')::DATE`;
+        });
+
+        this.add('DAY_OF_WEEK', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('DAY_OF_WEEK expects 1 argument');
+            return `EXTRACT(DOW FROM ${compiledArgs[0]})`;
+        });
+
+        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
+            return `EXTRACT(WEEK FROM ${compiledArgs[0]})`;
+        });
+
+        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
+            const [, date] = compiledArgs;
+            const partArg = node.args[0] as LiteralNode;
+            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
+            return `DATE_TRUNC('${partClean}', ${date})`;
+        });
+
+        this.add('GROUP_CONCAT', ctx => {
+            const arg = ctx.compiledArgs[0];
+            const orderClause = this.buildOrderByExpression(ctx);
+            const orderSegment = orderClause ? ` ${orderClause}` : '';
+            const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+            const separator = ctx.compileOperand(separatorOperand);
+            return `STRING_AGG(${arg}, ${separator}${orderSegment})`;
+        });
+    }
+}

package/src/core/dialect/sqlite/functions.ts

@@ -1,12 +1,12 @@
-import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
-import { FunctionRenderContext } from '../../functions/types.js';
-import { LiteralNode } from '../../ast/expression.js';
-
-export class SqliteFunctionStrategy extends StandardFunctionStrategy {
-    constructor() {
-        super();
-        this.registerOverrides();
-    }
+import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
+import { FunctionRenderContext } from '../../functions/types.js';
+import { LiteralNode } from '../../ast/expression.js';
+
+export class SqliteFunctionStrategy extends StandardFunctionStrategy {
+    constructor() {
+        super();
+        this.registerOverrides();
+    }
 
     private registerOverrides() {
         // Override Standard/Abstract definitions with SQLite specifics
@@ -110,6 +110,13 @@ export class SqliteFunctionStrategy extends StandardFunctionStrategy {
                 return `date(${date})`;
             }
             return `date(${date}, 'start of ${partClean}')`;
-        });
-    }
-}
+        });
+
+        this.add('GROUP_CONCAT', ctx => {
+            const arg = ctx.compiledArgs[0];
+            const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+            const separator = ctx.compileOperand(separatorOperand);
+            return `GROUP_CONCAT(${arg}, ${separator})`;
+        });
+    }
+}

package/src/core/dialect/sqlite/index.ts

@@ -6,14 +6,14 @@ import { SqliteFunctionStrategy } from './functions.js';
 /**
  * SQLite dialect implementation
  */
-export class SqliteDialect extends SqlDialectBase {
-  protected readonly dialect = 'sqlite';
-  /**
-   * Creates a new SqliteDialect instance
-   */
-  public constructor() {
-    super(new SqliteFunctionStrategy());
-  }
+export class SqliteDialect extends SqlDialectBase {
+  protected readonly dialect = 'sqlite';
+  /**
+   * Creates a new SqliteDialect instance
+   */
+  public constructor() {
+    super(new SqliteFunctionStrategy());
+  }
 
   /**
    * Quotes an identifier using SQLite double-quote syntax
@@ -35,11 +35,20 @@ export class SqliteDialect extends SqlDialectBase {
     return `json_extract(${col}, '${node.path}')`;
   }
 
-  protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
-    if (!returning || returning.length === 0) return '';
-    const columns = this.formatReturningColumns(returning);
-    return ` RETURNING ${columns}`;
-  }
+  protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
+    if (!returning || returning.length === 0) return '';
+    const columns = this.formatReturningColumns(returning);
+    return ` RETURNING ${columns}`;
+  }
+
+  protected formatReturningColumns(returning: ColumnNode[]): string {
+    return returning
+      .map(column => {
+        const alias = column.alias ? ` AS ${this.quoteIdentifier(column.alias)}` : '';
+        return `${this.quoteIdentifier(column.name)}${alias}`;
+      })
+      .join(', ');
+  }
 
   supportsReturning(): boolean {
     return true;

package/src/core/functions/datetime.ts

@@ -11,7 +11,8 @@ const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'obj
 const toOperand = (input: OperandInput): OperandNode => {
     if (isOperandNode(input)) return input;
     if (isColumnDef(input)) return columnOperand(input);
-    return valueToOperand(input as any);
+
+    return valueToOperand(input);
 };
 
 const fn = (key: string, args: OperandInput[]): FunctionNode => ({

package/src/core/functions/numeric.ts

@@ -11,7 +11,8 @@ const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'obj
 const toOperand = (input: OperandInput): OperandNode => {
     if (isOperandNode(input)) return input;
     if (isColumnDef(input)) return columnOperand(input);
-    return valueToOperand(input as any);
+
+    return valueToOperand(input);
 };
 
 const fn = (key: string, args: OperandInput[]): FunctionNode => ({

package/src/core/functions/standard-strategy.ts

@@ -1,4 +1,5 @@
-import { FunctionStrategy, FunctionRenderer, FunctionRenderContext } from './types.js';
+import { FunctionStrategy, FunctionRenderer, FunctionRenderContext } from './types.js';
+import { LiteralNode, OperandNode } from '../ast/expression.js';
 
 export class StandardFunctionStrategy implements FunctionStrategy {
     protected renderers: Map<string, FunctionRenderer> = new Map();
@@ -7,11 +8,16 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         this.registerStandard();
     }
 
-    protected registerStandard() {
-        // Register ANSI standard implementations
-        this.add('ABS', ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
-        this.add('UPPER', ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
-        this.add('LOWER', ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
+    protected registerStandard() {
+        // Register ANSI standard implementations
+        this.add('COUNT', ({ compiledArgs }) => `COUNT(${compiledArgs.join(', ')})`);
+        this.add('SUM', ({ compiledArgs }) => `SUM(${compiledArgs[0]})`);
+        this.add('AVG', ({ compiledArgs }) => `AVG(${compiledArgs[0]})`);
+        this.add('MIN', ({ compiledArgs }) => `MIN(${compiledArgs[0]})`);
+        this.add('MAX', ({ compiledArgs }) => `MAX(${compiledArgs[0]})`);
+        this.add('ABS', ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
+        this.add('UPPER', ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
+        this.add('LOWER', ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
         this.add('LENGTH', ({ compiledArgs }) => `LENGTH(${compiledArgs[0]})`);
         this.add('TRIM', ({ compiledArgs }) => `TRIM(${compiledArgs[0]})`);
         this.add('LTRIM', ({ compiledArgs }) => `LTRIM(${compiledArgs[0]})`);
@@ -33,15 +39,49 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         this.add('FROM_UNIXTIME', ({ compiledArgs }) => `FROM_UNIXTIME(${compiledArgs[0]})`);
         this.add('END_OF_MONTH', ({ compiledArgs }) => `LAST_DAY(${compiledArgs[0]})`);
         this.add('DAY_OF_WEEK', ({ compiledArgs }) => `DAYOFWEEK(${compiledArgs[0]})`);
-        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
-        this.add('DATE_TRUNC', ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
+        this.add('DATE_TRUNC', ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('GROUP_CONCAT', ctx => this.renderGroupConcat(ctx));
     }
 
     protected add(name: string, renderer: FunctionRenderer) {
         this.renderers.set(name, renderer);
     }
 
-    getRenderer(name: string): FunctionRenderer | undefined {
-        return this.renderers.get(name);
-    }
-}
+    getRenderer(name: string): FunctionRenderer | undefined {
+        return this.renderers.get(name);
+    }
+
+    private renderGroupConcat(ctx: FunctionRenderContext): string {
+        const arg = ctx.compiledArgs[0];
+        const orderClause = this.buildOrderByExpression(ctx);
+        const orderSegment = orderClause ? ` ${orderClause}` : '';
+        const separatorClause = this.formatGroupConcatSeparator(ctx);
+        return `GROUP_CONCAT(${arg}${orderSegment}${separatorClause})`;
+    }
+
+    protected buildOrderByExpression(ctx: FunctionRenderContext): string {
+        const orderBy = ctx.node.orderBy;
+        if (!orderBy || orderBy.length === 0) {
+            return '';
+        }
+        const parts = orderBy.map(order => `${ctx.compileOperand(order.column)} ${order.direction}`);
+        return `ORDER BY ${parts.join(', ')}`;
+    }
+
+    protected formatGroupConcatSeparator(ctx: FunctionRenderContext): string {
+        if (!ctx.node.separator) {
+            return '';
+        }
+        return ` SEPARATOR ${ctx.compileOperand(ctx.node.separator)}`;
+    }
+
+    protected getGroupConcatSeparatorOperand(ctx: FunctionRenderContext): OperandNode {
+        return ctx.node.separator ?? StandardFunctionStrategy.DEFAULT_GROUP_CONCAT_SEPARATOR;
+    }
+
+    protected static readonly DEFAULT_GROUP_CONCAT_SEPARATOR: LiteralNode = {
+        type: 'Literal',
+        value: ','
+    };
+}

package/src/core/functions/text.ts

@@ -11,7 +11,8 @@ const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'obj
 const toOperand = (input: OperandInput): OperandNode => {
   if (isOperandNode(input)) return input;
   if (isColumnDef(input)) return columnOperand(input);
-  return valueToOperand(input as any);
+
+  return valueToOperand(input);
 };
 
 const fn = (key: string, args: OperandInput[]): FunctionNode => ({

package/src/core/functions/types.ts

@@ -1,11 +1,11 @@
-import { FunctionNode } from '../ast/expression.js';
-
-export interface FunctionRenderContext {
-    node: FunctionNode;
-    compiledArgs: string[];
-    // Helper to allow dialects to call back into the compiler if needed
-    // compileOperand: (node: OperandNode) => string;
-}
+import { FunctionNode, OperandNode } from '../ast/expression.js';
+
+export interface FunctionRenderContext {
+    node: FunctionNode;
+    compiledArgs: string[];
+    /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
+    compileOperand: (operand: OperandNode) => string;
+}
 
 export type FunctionRenderer = (ctx: FunctionRenderContext) => string;
 

package/src/index.ts

@@ -2,10 +2,11 @@ export * from './schema/table.js';
 export * from './schema/column.js';
 export * from './schema/relation.js';
 export * from './schema/types.js';
-export * from './query-builder/select.js';
-export * from './query-builder/insert.js';
-export * from './query-builder/update.js';
-export * from './query-builder/delete.js';
+export * from './query-builder/select.js';
+export * from './query-builder/select-helpers.js';
+export * from './query-builder/insert.js';
+export * from './query-builder/update.js';
+export * from './query-builder/delete.js';
 export * from './core/ast/expression.js';
 export * from './core/hydration/types.js';
 export * from './core/dialect/mysql/index.js';

package/src/orm/domain-event-bus.ts

@@ -1,32 +1,53 @@
-import type { HasDomainEvents, TrackedEntity } from './runtime-types.js';
+import type { DomainEvent, HasDomainEvents, TrackedEntity } from './runtime-types.js';
 
-export type DomainEventHandler<Context> = (event: any, ctx: Context) => Promise<void> | void;
+type EventOfType<E extends DomainEvent, TType extends E['type']> =
+  Extract<E, { type: TType }>;
 
-export class DomainEventBus<Context> {
-  private readonly handlers = new Map<string, DomainEventHandler<Context>[]>();
+export type DomainEventHandler<E extends DomainEvent, Context> =
+  (event: E, ctx: Context) => Promise<void> | void;
 
-  constructor(initialHandlers?: Record<string, DomainEventHandler<Context>[]>) {
-    const handlers = initialHandlers ?? {};
-    Object.entries(handlers).forEach(([name, list]) => {
-      this.handlers.set(name, [...list]);
-    });
+export type InitialHandlers<E extends DomainEvent, Context> = {
+  [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
+};
+
+export class DomainEventBus<E extends DomainEvent, Context> {
+  private readonly handlers = new Map<E['type'], DomainEventHandler<E, Context>[]>();
+
+  constructor(initialHandlers?: InitialHandlers<E, Context>) {
+    if (initialHandlers) {
+      for (const key in initialHandlers) {
+        const type = key as E['type'];
+        const list = initialHandlers[type] ?? [];
+        this.handlers.set(type, [...(list as DomainEventHandler<E, Context>[])]);
+      }
+    }
   }
 
-  register(name: string, handler: DomainEventHandler<Context>): void {
-    const existing = this.handlers.get(name) ?? [];
-    existing.push(handler);
-    this.handlers.set(name, existing);
+  on<TType extends E['type']>(
+    type: TType,
+    handler: DomainEventHandler<EventOfType<E, TType>, Context>
+  ): void {
+    const key = type as E['type'];
+    const existing = this.handlers.get(key) ?? [];
+    existing.push(handler as unknown as DomainEventHandler<E, Context>);
+    this.handlers.set(key, existing);
+  }
+
+  register<TType extends E['type']>(
+    type: TType,
+    handler: DomainEventHandler<EventOfType<E, TType>, Context>
+  ): void {
+    this.on(type, handler);
   }
 
   async dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void> {
     for (const tracked of trackedEntities) {
-      const entity = tracked.entity as HasDomainEvents;
-      if (!entity.domainEvents || !entity.domainEvents.length) continue;
+      const entity = tracked.entity as HasDomainEvents<E>;
+      if (!entity.domainEvents?.length) continue;
 
       for (const event of entity.domainEvents) {
-        const eventName = this.getEventName(event);
-        const handlers = this.handlers.get(eventName);
-        if (!handlers) continue;
+        const handlers = this.handlers.get(event.type as E['type']);
+        if (!handlers?.length) continue;
 
         for (const handler of handlers) {
           await handler(event, ctx);
@@ -36,15 +57,12 @@ export class DomainEventBus<Context> {
       entity.domainEvents = [];
     }
   }
-
-  private getEventName(event: any): string {
-    if (!event) return 'Unknown';
-    if (typeof event === 'string') return event;
-    return event.constructor?.name ?? 'Unknown';
-  }
 }
 
-export const addDomainEvent = (entity: HasDomainEvents, event: any): void => {
+export const addDomainEvent = <E extends DomainEvent>(
+  entity: HasDomainEvents<E>,
+  event: E
+): void => {
   if (!entity.domainEvents) {
     entity.domainEvents = [];
   }

package/src/orm/entity-meta.ts

@@ -2,19 +2,40 @@ import { TableDef } from '../schema/table.js';
 import { EntityContext } from './entity-context.js';
 import { RelationMap } from '../schema/types.js';
 
+/**
+ * Symbol used to store entity metadata on entity instances
+ */
 export const ENTITY_META = Symbol('EntityMeta');
 
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
+/**
+ * Metadata stored on entity instances for ORM internal use
+ * @typeParam TTable - Table definition type
+ */
 export interface EntityMeta<TTable extends TableDef> {
+  /** Entity context */
   ctx: EntityContext;
+  /** Table definition */
   table: TTable;
+  /** Relations that should be loaded lazily */
   lazyRelations: (keyof RelationMap<TTable>)[];
+  /** Cache for relation promises */
   relationCache: Map<string, Promise<any>>;
+  /** Hydration data for relations */
   relationHydration: Map<string, Map<string, any>>;
+  /** Relation wrapper instances */
   relationWrappers: Map<string, unknown>;
 }
 
+/**
+ * Gets hydration rows for a specific relation and key
+ * @param meta - Entity metadata
+ * @param relationName - Name of the relation
+ * @param key - Key to look up in the hydration map
+ * @returns Array of hydration rows or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
 export const getHydrationRows = <TTable extends TableDef>(
   meta: EntityMeta<TTable>,
   relationName: string,
@@ -27,6 +48,14 @@ export const getHydrationRows = <TTable extends TableDef>(
   return Array.isArray(rows) ? rows : undefined;
 };
 
+/**
+ * Gets a single hydration record for a specific relation and key
+ * @param meta - Entity metadata
+ * @param relationName - Name of the relation
+ * @param key - Key to look up in the hydration map
+ * @returns Single hydration record or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
 export const getHydrationRecord = <TTable extends TableDef>(
   meta: EntityMeta<TTable>,
   relationName: string,
@@ -42,11 +71,22 @@ export const getHydrationRecord = <TTable extends TableDef>(
   return value;
 };
 
+/**
+ * Gets entity metadata from an entity instance
+ * @param entity - Entity instance to get metadata from
+ * @returns Entity metadata or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
 export const getEntityMeta = <TTable extends TableDef>(entity: any): EntityMeta<TTable> | undefined => {
   if (!entity || typeof entity !== 'object') return undefined;
   return (entity as any)[ENTITY_META];
 };
 
+/**
+ * Checks if an entity has metadata attached
+ * @param entity - Entity instance to check
+ * @returns True if the entity has metadata, false otherwise
+ */
 export const hasEntityMeta = (entity: any): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
   return Boolean(getEntityMeta(entity));
 };

package/src/orm/execution-context.ts

@@ -2,9 +2,15 @@ import type { Dialect } from '../core/dialect/abstract.js';
 import type { DbExecutor } from '../core/execution/db-executor.js';
 import { InterceptorPipeline } from './interceptor-pipeline.js';
 
+/**
+ * Context for SQL query execution
+ */
 export interface ExecutionContext {
+  /** Database dialect to use for SQL generation */
   dialect: Dialect;
+  /** Database executor for running SQL queries */
   executor: DbExecutor;
+  /** Interceptor pipeline for query processing */
   interceptors: InterceptorPipeline;
   // plus anything *purely about executing SQL*:
   // - logging