metal-orm 1.0.39 → 1.0.41

package/src/core/execution/executors/mysql-executor.ts

@@ -17,7 +17,15 @@ export interface MysqlClientLike {
 export function createMysqlExecutor(
   client: MysqlClientLike
 ): DbExecutor {
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commit === 'function' &&
+    typeof client.rollback === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params as any[]);
 
@@ -32,16 +40,25 @@ export function createMysqlExecutor(
       return [result];
     },
     async beginTransaction() {
-      if (!client.beginTransaction) return;
-      await client.beginTransaction();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.beginTransaction!();
     },
     async commitTransaction() {
-      if (!client.commit) return;
-      await client.commit();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.commit!();
     },
     async rollbackTransaction() {
-      if (!client.rollback) return;
-      await client.rollback();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollback!();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
     },
   };
 }

package/src/core/execution/executors/sqlite-executor.ts

@@ -18,14 +18,40 @@ export interface SqliteClientLike {
 export function createSqliteExecutor(
   client: SqliteClientLike
 ): DbExecutor {
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commitTransaction === 'function' &&
+    typeof client.rollbackTransaction === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const rows = await client.all(sql, params);
       const result = rowsToQueryResult(rows);
       return [result];
     },
-    beginTransaction: client.beginTransaction?.bind(client),
-    commitTransaction: client.commitTransaction?.bind(client),
-    rollbackTransaction: client.rollbackTransaction?.bind(client),
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.beginTransaction!();
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.commitTransaction!();
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollbackTransaction!();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
+    },
   };
 }

package/src/core/execution/pooling/pool-types.ts

@@ -0,0 +1,30 @@
+export type PoolOptions = {
+    /** Maximum number of live resources (idle + leased). */
+    max: number;
+    /** Minimum number of idle resources to keep warm (best-effort). */
+    min?: number;
+
+    /** How long an idle resource can sit before being destroyed. */
+    idleTimeoutMillis?: number;
+    /** How often to reap idle resources. Defaults to idleTimeoutMillis / 2 (min 1s). */
+    reapIntervalMillis?: number;
+
+    /** How long callers wait for a resource before acquire() rejects. */
+    acquireTimeoutMillis?: number;
+};
+
+export interface PoolAdapter<TResource> {
+    create(): Promise<TResource>;
+    destroy(resource: TResource): Promise<void>;
+    validate?(resource: TResource): Promise<boolean>;
+}
+
+export interface PoolLease<TResource> {
+    readonly resource: TResource;
+
+    /** Returns the resource to the pool. Idempotent. */
+    release(): Promise<void>;
+    /** Permanently removes the resource from the pool. Idempotent. */
+    destroy(): Promise<void>;
+}
+

package/src/core/execution/pooling/pool.ts

@@ -0,0 +1,268 @@
+import type { PoolAdapter, PoolLease, PoolOptions } from './pool-types.js';
+
+type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (err: unknown) => void;
+};
+
+const deferred = <T>(): Deferred<T> => {
+    let resolve!: (value: T) => void;
+    let reject!: (err: unknown) => void;
+    const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+};
+
+type IdleEntry<T> = {
+    resource: T;
+    lastUsedAt: number;
+};
+
+export class Pool<TResource> {
+    private readonly adapter: PoolAdapter<TResource>;
+    private readonly options: Required<Pick<PoolOptions, 'max'>> & PoolOptions;
+
+    private destroyed = false;
+    private creating = 0;
+    private leased = 0;
+    private readonly idle: IdleEntry<TResource>[] = [];
+    private readonly waiters: Array<Deferred<PoolLease<TResource>>> = [];
+    private reapTimer: ReturnType<typeof setInterval> | null = null;
+
+    constructor(adapter: PoolAdapter<TResource>, options: PoolOptions) {
+        if (!Number.isFinite(options.max) || options.max <= 0) {
+            throw new Error('Pool options.max must be a positive number');
+        }
+
+        this.adapter = adapter;
+        this.options = { max: options.max, ...options };
+
+        const idleTimeout = this.options.idleTimeoutMillis;
+        if (idleTimeout && idleTimeout > 0) {
+            const interval =
+                this.options.reapIntervalMillis ?? Math.max(1_000, Math.floor(idleTimeout / 2));
+            this.reapTimer = setInterval(() => {
+                void this.reapIdle();
+            }, interval);
+
+            // Best-effort: avoid keeping the event loop alive.
+            (this.reapTimer as any).unref?.();
+        }
+
+        // Best-effort warmup.
+        const min = this.options.min ?? 0;
+        if (min > 0) {
+            void this.warm(min);
+        }
+    }
+
+    /**
+     * Acquire a resource lease.
+     * The returned lease MUST be released or destroyed.
+     */
+    async acquire(): Promise<PoolLease<TResource>> {
+        if (this.destroyed) {
+            throw new Error('Pool is destroyed');
+        }
+
+        // 1) Prefer idle.
+        const idle = await this.takeIdleValidated();
+        if (idle) {
+            this.leased++;
+            return this.makeLease(idle);
+        }
+
+        // 2) Create if capacity allows.
+        if (this.totalLive() < this.options.max) {
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.leased++;
+                return this.makeLease(created);
+            } finally {
+                this.creating--;
+            }
+        }
+
+        // 3) Wait.
+        const waiter = deferred<PoolLease<TResource>>();
+        this.waiters.push(waiter);
+
+        const timeout = this.options.acquireTimeoutMillis;
+        let timer: ReturnType<typeof setTimeout> | null = null;
+        if (timeout && timeout > 0) {
+            timer = setTimeout(() => {
+                // Remove from queue if still waiting.
+                const idx = this.waiters.indexOf(waiter);
+                if (idx >= 0) this.waiters.splice(idx, 1);
+                waiter.reject(new Error('Pool acquire timeout'));
+            }, timeout);
+            (timer as any).unref?.();
+        }
+
+        try {
+            return await waiter.promise;
+        } finally {
+            if (timer) clearTimeout(timer);
+        }
+    }
+
+    /** Destroy pool and all idle resources; waits for in-flight creations to settle. */
+    async destroy(): Promise<void> {
+        if (this.destroyed) return;
+        this.destroyed = true;
+
+        if (this.reapTimer) {
+            clearInterval(this.reapTimer);
+            this.reapTimer = null;
+        }
+
+        // Reject all waiters.
+        while (this.waiters.length) {
+            this.waiters.shift()!.reject(new Error('Pool destroyed'));
+        }
+
+        // Destroy idle resources.
+        while (this.idle.length) {
+            const entry = this.idle.shift()!;
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+
+    private totalLive(): number {
+        return this.idle.length + this.leased + this.creating;
+    }
+
+    private makeLease(resource: TResource): PoolLease<TResource> {
+        let done = false;
+        return {
+            resource,
+            release: async () => {
+                if (done) return;
+                done = true;
+                await this.releaseResource(resource);
+            },
+            destroy: async () => {
+                if (done) return;
+                done = true;
+                await this.destroyResource(resource);
+            },
+        };
+    }
+
+    private async releaseResource(resource: TResource): Promise<void> {
+        this.leased = Math.max(0, this.leased - 1);
+        if (this.destroyed) {
+            await this.adapter.destroy(resource);
+            return;
+        }
+
+        // Prefer handing directly to waiters.
+        const next = this.waiters.shift();
+        if (next) {
+            this.leased++;
+            next.resolve(this.makeLease(resource));
+            return;
+        }
+
+        this.idle.push({ resource, lastUsedAt: Date.now() });
+        await this.trimToMinMax();
+    }
+
+    private async destroyResource(resource: TResource): Promise<void> {
+        this.leased = Math.max(0, this.leased - 1);
+        await this.adapter.destroy(resource);
+
+        // If there are waiters and we have capacity, create a replacement.
+        if (!this.destroyed && this.waiters.length && this.totalLive() < this.options.max) {
+            const waiter = this.waiters.shift()!;
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.leased++;
+                waiter.resolve(this.makeLease(created));
+            } catch (err) {
+                waiter.reject(err);
+            } finally {
+                this.creating--;
+            }
+        }
+    }
+
+    private async takeIdleValidated(): Promise<TResource | null> {
+        while (this.idle.length) {
+            const entry = this.idle.pop()!;
+            if (!this.adapter.validate) {
+                return entry.resource;
+            }
+            const ok = await this.adapter.validate(entry.resource);
+            if (ok) {
+                return entry.resource;
+            }
+            await this.adapter.destroy(entry.resource);
+        }
+        return null;
+    }
+
+    private async reapIdle(): Promise<void> {
+        if (this.destroyed) return;
+        const idleTimeout = this.options.idleTimeoutMillis;
+        if (!idleTimeout || idleTimeout <= 0) return;
+
+        const now = Date.now();
+        const min = this.options.min ?? 0;
+
+        // Remove expired resources beyond min.
+        const keep: IdleEntry<TResource>[] = [];
+        const kill: IdleEntry<TResource>[] = [];
+        for (const entry of this.idle) {
+            const expired = now - entry.lastUsedAt >= idleTimeout;
+            if (expired) kill.push(entry);
+            else keep.push(entry);
+        }
+
+        // Keep at least `min`.
+        while (keep.length < min && kill.length) {
+            keep.push(kill.pop()!);
+        }
+
+        this.idle.length = 0;
+        this.idle.push(...keep);
+
+        for (const entry of kill) {
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+
+    private async warm(targetMin: number): Promise<void> {
+        const min = Math.max(0, targetMin);
+        while (!this.destroyed && this.idle.length < min && this.totalLive() < this.options.max) {
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.idle.push({ resource: created, lastUsedAt: Date.now() });
+            } catch {
+                // If warmup fails, stop trying.
+                break;
+            } finally {
+                this.creating--;
+            }
+        }
+    }
+
+    private async trimToMinMax(): Promise<void> {
+        const max = this.options.max;
+        const min = this.options.min ?? 0;
+
+        // Ensure we don't exceed max in idle (best-effort; leased/creating already counted elsewhere).
+        while (this.totalLive() > max && this.idle.length > min) {
+            const entry = this.idle.shift();
+            if (!entry) break;
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+}
+

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

@@ -1,13 +1,13 @@
 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();
-
-    constructor() {
-        this.registerStandard();
-    }
-
+import { LiteralNode, OperandNode, isOperandNode } from '../ast/expression.js';
+
+export class StandardFunctionStrategy implements FunctionStrategy {
+    protected renderers: Map<string, FunctionRenderer> = new Map();
+
+    constructor() {
+        this.registerStandard();
+    }
+
     protected registerStandard() {
         // Register ANSI standard implementations
         this.add('COUNT', ({ compiledArgs }) => `COUNT(${compiledArgs.join(', ')})`);
@@ -18,36 +18,36 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         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]})`);
-        this.add('RTRIM', ({ compiledArgs }) => `RTRIM(${compiledArgs[0]})`);
-        this.add('SUBSTRING', ({ compiledArgs }) => `SUBSTRING(${compiledArgs.join(', ')})`);
-        this.add('CONCAT', ({ compiledArgs }) => `CONCAT(${compiledArgs.join(', ')})`);
-        this.add('NOW', () => `NOW()`);
-        this.add('CURRENT_DATE', () => `CURRENT_DATE`);
-        this.add('CURRENT_TIME', () => `CURRENT_TIME`);
-        this.add('EXTRACT', ({ compiledArgs }) => `EXTRACT(${compiledArgs[0]} FROM ${compiledArgs[1]})`);
-        this.add('YEAR', ({ compiledArgs }) => `EXTRACT(YEAR FROM ${compiledArgs[0]})`);
-        this.add('MONTH', ({ compiledArgs }) => `EXTRACT(MONTH FROM ${compiledArgs[0]})`);
-        this.add('DAY', ({ compiledArgs }) => `EXTRACT(DAY FROM ${compiledArgs[0]})`);
-        this.add('DATE_ADD', ({ compiledArgs }) => `(${compiledArgs[0]} + INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
-        this.add('DATE_SUB', ({ compiledArgs }) => `(${compiledArgs[0]} - INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
-        this.add('DATE_DIFF', ({ compiledArgs }) => `DATEDIFF(${compiledArgs[0]}, ${compiledArgs[1]})`);
-        this.add('DATE_FORMAT', ({ compiledArgs }) => `DATE_FORMAT(${compiledArgs[0]}, ${compiledArgs[1]})`);
-        this.add('UNIX_TIMESTAMP', () => `UNIX_TIMESTAMP()`);
-        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('LENGTH', ({ compiledArgs }) => `LENGTH(${compiledArgs[0]})`);
+        this.add('TRIM', ({ compiledArgs }) => `TRIM(${compiledArgs[0]})`);
+        this.add('LTRIM', ({ compiledArgs }) => `LTRIM(${compiledArgs[0]})`);
+        this.add('RTRIM', ({ compiledArgs }) => `RTRIM(${compiledArgs[0]})`);
+        this.add('SUBSTRING', ({ compiledArgs }) => `SUBSTRING(${compiledArgs.join(', ')})`);
+        this.add('CONCAT', ({ compiledArgs }) => `CONCAT(${compiledArgs.join(', ')})`);
+        this.add('NOW', () => `NOW()`);
+        this.add('CURRENT_DATE', () => `CURRENT_DATE`);
+        this.add('CURRENT_TIME', () => `CURRENT_TIME`);
+        this.add('EXTRACT', ({ compiledArgs }) => `EXTRACT(${compiledArgs[0]} FROM ${compiledArgs[1]})`);
+        this.add('YEAR', ({ compiledArgs }) => `EXTRACT(YEAR FROM ${compiledArgs[0]})`);
+        this.add('MONTH', ({ compiledArgs }) => `EXTRACT(MONTH FROM ${compiledArgs[0]})`);
+        this.add('DAY', ({ compiledArgs }) => `EXTRACT(DAY FROM ${compiledArgs[0]})`);
+        this.add('DATE_ADD', ({ compiledArgs }) => `(${compiledArgs[0]} + INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+        this.add('DATE_SUB', ({ compiledArgs }) => `(${compiledArgs[0]} - INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+        this.add('DATE_DIFF', ({ compiledArgs }) => `DATEDIFF(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('DATE_FORMAT', ({ compiledArgs }) => `DATE_FORMAT(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('UNIX_TIMESTAMP', () => `UNIX_TIMESTAMP()`);
+        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('GROUP_CONCAT', ctx => this.renderGroupConcat(ctx));
-    }
-
-    protected add(name: string, renderer: FunctionRenderer) {
-        this.renderers.set(name, renderer);
-    }
-
+    }
+
+    protected add(name: string, renderer: FunctionRenderer) {
+        this.renderers.set(name, renderer);
+    }
+
     getRenderer(name: string): FunctionRenderer | undefined {
         return this.renderers.get(name);
     }
@@ -65,7 +65,16 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         if (!orderBy || orderBy.length === 0) {
             return '';
         }
-        const parts = orderBy.map(order => `${ctx.compileOperand(order.column)} ${order.direction}`);
+        const parts = orderBy.map(order => {
+            const term = isOperandNode(order.term)
+                ? ctx.compileOperand(order.term)
+                : (() => {
+                    throw new Error('ORDER BY expressions inside functions must be operands');
+                })();
+            const collation = order.collation ? ` COLLATE ${order.collation}` : '';
+            const nulls = order.nulls ? ` NULLS ${order.nulls}` : '';
+            return `${term} ${order.direction}${collation}${nulls}`;
+        });
         return `ORDER BY ${parts.join(', ')}`;
     }
 

package/src/decorators/bootstrap.ts

@@ -31,22 +31,22 @@ const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget
 
 const resolveTableTarget = (
   target: EntityOrTableTargetResolver,
-  tableMap: Map<EntityConstructor, TableDef>
+  tableMap: Map<EntityConstructor<any>, TableDef>
 ): TableDef => {
   const resolved = unwrapTarget(target);
   if (isTableDef(resolved)) {
     return resolved;
   }
-  const table = tableMap.get(resolved as EntityConstructor);
+  const table = tableMap.get(resolved as EntityConstructor<any>);
   if (!table) {
-    throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
+    throw new Error(`Entity '${(resolved as EntityConstructor<any>).name}' is not registered with decorators`);
   }
   return table;
 };
 
 const buildRelationDefinitions = (
   meta: { relations: Record<string, RelationMetadata> },
-  tableMap: Map<EntityConstructor, TableDef>
+  tableMap: Map<EntityConstructor<any>, TableDef>
 ): Record<string, RelationDef> => {
   const relations: Record<string, RelationDef> = {};
 
@@ -103,7 +103,7 @@ const buildRelationDefinitions = (
 
 export const bootstrapEntities = (): TableDef[] => {
   const metas = getAllEntityMetadata();
-  const tableMap = new Map<EntityConstructor, TableDef>();
+  const tableMap = new Map<EntityConstructor<any>, TableDef>();
 
   for (const meta of metas) {
     const table = buildTableDef(meta);
@@ -119,7 +119,7 @@ export const bootstrapEntities = (): TableDef[] => {
   return metas.map(meta => meta.table!) as TableDef[];
 };
 
-export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor): TTable | undefined => {
+export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>): TTable | undefined => {
   const meta = getEntityMetadata(ctor);
   if (!meta) return undefined;
   if (!meta.table) {
@@ -129,7 +129,7 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
 };
 
 export const selectFromEntity = <TTable extends TableDef = TableDef>(
-  ctor: EntityConstructor
+  ctor: EntityConstructor<any>
 ): SelectQueryBuilder<any, TTable> => {
   const table = getTableDefFromEntity(ctor);
   if (!table) {

package/src/index.ts

@@ -8,6 +8,7 @@ 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/ast/window-functions.js';
 export * from './core/hydration/types.js';
 export * from './core/dialect/mysql/index.js';
 export * from './core/dialect/mssql/index.js';
@@ -42,7 +43,12 @@ export * from './decorators/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';
+export * from './core/execution/pooling/pool-types.js';
+export * from './core/execution/pooling/pool.js';
 export * from './core/execution/executors/postgres-executor.js';
 export * from './core/execution/executors/mysql-executor.js';
 export * from './core/execution/executors/sqlite-executor.js';
 export * from './core/execution/executors/mssql-executor.js';
+
+// NEW: first-class pooling integration
+export * from './orm/pooled-executor-factory.js';

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

@@ -1,18 +1,44 @@
 import type { DomainEvent, HasDomainEvents, TrackedEntity } from './runtime-types.js';
 
+/**
+ * Extracts domain events of a specific type.
+ * @template E - The domain event type
+ * @template TType - The specific event type
+ */
 type EventOfType<E extends DomainEvent, TType extends E['type']> =
   Extract<E, { type: TType }>;
 
+/**
+ * Domain event handler function.
+ * @template E - The domain event type
+ * @template Context - The context type
+ * @param event - The domain event
+ * @param ctx - The context
+ */
 export type DomainEventHandler<E extends DomainEvent, Context> =
   (event: E, ctx: Context) => Promise<void> | void;
 
+/**
+ * Initial handlers for domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 export type InitialHandlers<E extends DomainEvent, Context> = {
   [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
 };
 
+/**
+ * Domain event bus for managing and dispatching domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 export class DomainEventBus<E extends DomainEvent, Context> {
   private readonly handlers = new Map<E['type'], DomainEventHandler<E, Context>[]>();
 
+  /**
+   * Creates a new DomainEventBus instance.
+   * @param initialHandlers - Optional initial event handlers
+   */
   constructor(initialHandlers?: InitialHandlers<E, Context>) {
     if (initialHandlers) {
       for (const key in initialHandlers) {
@@ -23,6 +49,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     }
   }
 
+  /**
+   * Registers an event handler for a specific event type.
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   on<TType extends E['type']>(
     type: TType,
     handler: DomainEventHandler<EventOfType<E, TType>, Context>
@@ -33,6 +65,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     this.handlers.set(key, existing);
   }
 
+  /**
+   * Registers an event handler for a specific event type (alias for on).
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   register<TType extends E['type']>(
     type: TType,
     handler: DomainEventHandler<EventOfType<E, TType>, Context>
@@ -40,6 +78,11 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     this.on(type, handler);
   }
 
+  /**
+   * Dispatches domain events for tracked entities.
+   * @param trackedEntities - Iterable of tracked entities
+   * @param ctx - The context to pass to handlers
+   */
   async dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void> {
     for (const tracked of trackedEntities) {
       const entity = tracked.entity as HasDomainEvents<E>;
@@ -59,6 +102,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
   }
 }
 
+/**
+ * Adds a domain event to an entity.
+ * @template E - The domain event type
+ * @param entity - The entity to add the event to
+ * @param event - The domain event to add
+ */
 export const addDomainEvent = <E extends DomainEvent>(
   entity: HasDomainEvents<E>,
   event: E