metal-orm 1.0.39 → 1.0.41

package/src/orm/orm.ts

@@ -6,29 +6,61 @@ import { InterceptorPipeline } from './interceptor-pipeline.js';
 import { DefaultNamingStrategy } from '../codegen/naming-strategy.js';
 import { OrmSession } from './orm-session.js';
 
+/**
+ * Options for creating an ORM instance.
+ * @template E - The domain event type
+ */
 export interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
+  /** The database dialect */
   dialect: Dialect;
+  /** The database executor factory */
   executorFactory: DbExecutorFactory;
+  /** Optional interceptors pipeline */
   interceptors?: InterceptorPipeline;
+  /** Optional naming strategy */
   namingStrategy?: NamingStrategy;
   // model registrations etc.
 }
 
+/**
+ * Database executor factory interface.
+ */
 export interface DbExecutorFactory {
-  createExecutor(options?: { tx?: ExternalTransaction }): DbExecutor;
+  /**
+   * Creates a database executor.
+   * @returns The database executor
+   */
+  createExecutor(): DbExecutor;
+
+  /**
+   * Creates a transactional database executor.
+   * @returns The transactional database executor
+   */
   createTransactionalExecutor(): DbExecutor;
-}
 
-export interface ExternalTransaction {
-  // Transaction-specific properties
+  /**
+   * Disposes any underlying resources (connection pools, background timers, etc).
+   */
+  dispose(): Promise<void>;
 }
 
+/**
+ * ORM (Object-Relational Mapping) main class.
+ * @template E - The domain event type
+ */
 export class Orm<E extends DomainEvent = OrmDomainEvent> {
+  /** The database dialect */
   readonly dialect: Dialect;
+  /** The interceptors pipeline */
   readonly interceptors: InterceptorPipeline;
+  /** The naming strategy */
   readonly namingStrategy: NamingStrategy;
   private readonly executorFactory: DbExecutorFactory;
 
+  /**
+   * Creates a new ORM instance.
+   * @param opts - ORM options
+   */
   constructor(opts: OrmOptions<E>) {
     this.dialect = opts.dialect;
     this.interceptors = opts.interceptors ?? new InterceptorPipeline();
@@ -36,23 +68,41 @@ export class Orm<E extends DomainEvent = OrmDomainEvent> {
     this.executorFactory = opts.executorFactory;
   }
 
-  createSession(options?: { tx?: ExternalTransaction }): OrmSession<E> {
-    const executor = this.executorFactory.createExecutor(options?.tx);
+  /**
+   * Creates a new ORM session.
+   * @param options - Optional session options
+   * @returns The ORM session
+   */
+  createSession(): OrmSession<E> {
+    // No implicit transaction binding; callers should use Orm.transaction() for transactional work.
+    const executor = this.executorFactory.createExecutor();
     return new OrmSession<E>({ orm: this, executor });
   }
 
+  /**
+   * Executes a function within a transaction.
+   * @template T - The return type
+   * @param fn - The function to execute
+   * @returns The result of the function
+   * @throws If the transaction fails
+   */
   async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
     const executor = this.executorFactory.createTransactionalExecutor();
     const session = new OrmSession<E>({ orm: this, executor });
     try {
-      const result = await fn(session);
-      await session.commit();
-      return result;
+      // A real transaction scope: begin before running user code, commit/rollback after.
+      return await session.transaction(() => fn(session));
     } catch (err) {
-      await session.rollback();
       throw err;
     } finally {
-      // executor cleanup if needed
+      await session.dispose();
     }
   }
+
+  /**
+   * Shuts down the ORM and releases underlying resources (pools, timers).
+   */
+  async dispose(): Promise<void> {
+    await this.executorFactory.dispose();
+  }
 }

package/src/orm/pooled-executor-factory.ts

@@ -0,0 +1,131 @@
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import { rowsToQueryResult } from '../core/execution/db-executor.js';
+import type { Pool } from '../core/execution/pooling/pool.js';
+import type { DbExecutorFactory } from './orm.js';
+
+export interface PooledConnectionAdapter<TConn> {
+    query(
+        conn: TConn,
+        sql: string,
+        params?: unknown[]
+    ): Promise<Array<Record<string, unknown>>>;
+
+    beginTransaction(conn: TConn): Promise<void>;
+    commitTransaction(conn: TConn): Promise<void>;
+    rollbackTransaction(conn: TConn): Promise<void>;
+}
+
+type PooledExecutorFactoryOptions<TConn> = {
+    pool: Pool<TConn>;
+    adapter: PooledConnectionAdapter<TConn>;
+};
+
+/**
+ * Creates a first-class DbExecutorFactory backed by MetalORM's Pool.
+ *
+ * Design goals:
+ * - No leaks by default: pool leases are always released in `finally`.
+ * - Correct transactions: one leased connection per transaction.
+ * - Session-friendly: createExecutor() supports transactions without permanently leasing a connection.
+ */
+export function createPooledExecutorFactory<TConn>(
+    opts: PooledExecutorFactoryOptions<TConn>
+): DbExecutorFactory {
+    const { pool, adapter } = opts;
+
+    const makeExecutor = (mode: 'session' | 'sticky'): DbExecutor => {
+        let lease: Awaited<ReturnType<typeof pool.acquire>> | null = null;
+
+        const getLease = async () => {
+            if (lease) return lease;
+            lease = await pool.acquire();
+            return lease;
+        };
+
+        const executeWithConn = async (
+            conn: TConn,
+            sql: string,
+            params?: unknown[]
+        ): Promise<QueryResult[]> => {
+            const rows = await adapter.query(conn, sql, params);
+            return [rowsToQueryResult(rows)];
+        };
+
+        return {
+            capabilities: { transactions: true },
+
+            async executeSql(sql, params) {
+                // Sticky mode: always reuse a leased connection.
+                if (mode === 'sticky') {
+                    const l = await getLease();
+                    return executeWithConn(l.resource, sql, params);
+                }
+
+                // Session mode: use the leased connection if we're currently in a transaction;
+                // otherwise acquire/release per call.
+                if (lease) {
+                    return executeWithConn(lease.resource, sql, params);
+                }
+
+                const l = await pool.acquire();
+                try {
+                    return await executeWithConn(l.resource, sql, params);
+                } finally {
+                    await l.release();
+                }
+            },
+
+            async beginTransaction() {
+                const l = await getLease();
+                await adapter.beginTransaction(l.resource);
+            },
+
+            async commitTransaction() {
+                if (!lease) {
+                    throw new Error('commitTransaction called without an active transaction');
+                }
+                const l = lease;
+                try {
+                    await adapter.commitTransaction(l.resource);
+                } finally {
+                    lease = null;
+                    await l.release();
+                }
+            },
+
+            async rollbackTransaction() {
+                if (!lease) {
+                    // Nothing to rollback; keep idempotent semantics.
+                    return;
+                }
+                const l = lease;
+                try {
+                    await adapter.rollbackTransaction(l.resource);
+                } finally {
+                    lease = null;
+                    await l.release();
+                }
+            },
+
+            async dispose() {
+                if (!lease) return;
+                const l = lease;
+                lease = null;
+                await l.release();
+            },
+        };
+    };
+
+    return {
+        createExecutor() {
+            return makeExecutor('session');
+        },
+        createTransactionalExecutor() {
+            return makeExecutor('sticky');
+        },
+        async dispose() {
+            await pool.destroy();
+        },
+    };
+}
+

package/src/orm/query-logger.ts

@@ -31,23 +31,17 @@ export const createQueryLoggingExecutor = (
   }
 
   const wrapped: DbExecutor = {
+    capabilities: executor.capabilities,
     async executeSql(sql, params) {
       logger({ sql, params });
       return executor.executeSql(sql, params);
     }
+    ,
+    beginTransaction: () => executor.beginTransaction(),
+    commitTransaction: () => executor.commitTransaction(),
+    rollbackTransaction: () => executor.rollbackTransaction(),
+    dispose: () => executor.dispose(),
   };
 
-  if (executor.beginTransaction) {
-    wrapped.beginTransaction = executor.beginTransaction.bind(executor);
-  }
-
-  if (executor.commitTransaction) {
-    wrapped.commitTransaction = executor.commitTransaction.bind(executor);
-  }
-
-  if (executor.rollbackTransaction) {
-    wrapped.rollbackTransaction = executor.rollbackTransaction.bind(executor);
-  }
-
   return wrapped;
 };

package/src/orm/relation-change-processor.ts

@@ -10,23 +10,42 @@ import type { DbExecutor } from '../core/execution/db-executor.js';
 import type { RelationChangeEntry } from './runtime-types.js';
 import { UnitOfWork } from './unit-of-work.js';
 
+/**
+ * Processes relation changes for entity relationships.
+ */
 export class RelationChangeProcessor {
   private readonly relationChanges: RelationChangeEntry[] = [];
 
+  /**
+   * Creates a new RelationChangeProcessor instance.
+   * @param unitOfWork - The unit of work instance
+   * @param dialect - The database dialect
+   * @param executor - The database executor
+   */
   constructor(
     private readonly unitOfWork: UnitOfWork,
     private readonly dialect: Dialect,
     private readonly executor: DbExecutor
   ) { }
 
+  /**
+   * Registers a relation change for processing.
+   * @param entry - The relation change entry
+   */
   registerChange(entry: RelationChangeEntry): void {
     this.relationChanges.push(entry);
   }
 
+  /**
+   * Resets the relation change processor by clearing all pending changes.
+   */
   reset(): void {
     this.relationChanges.length = 0;
   }
 
+  /**
+   * Processes all pending relation changes.
+   */
   async process(): Promise<void> {
     if (!this.relationChanges.length) return;
     const entries = [...this.relationChanges];
@@ -50,6 +69,10 @@ export class RelationChangeProcessor {
     }
   }
 
+  /**
+   * Handles changes for has-many relations.
+   * @param entry - The relation change entry
+   */
   private async handleHasManyChange(entry: RelationChangeEntry): Promise<void> {
     const relation = entry.relation as HasManyRelation;
     const target = entry.change.entity;
@@ -73,6 +96,10 @@ export class RelationChangeProcessor {
     }
   }
 
+  /**
+   * Handles changes for has-one relations.
+   * @param entry - The relation change entry
+   */
   private async handleHasOneChange(entry: RelationChangeEntry): Promise<void> {
     const relation = entry.relation as HasOneRelation;
     const target = entry.change.entity;
@@ -96,10 +123,18 @@ export class RelationChangeProcessor {
     }
   }
 
+  /**
+   * Handles changes for belongs-to relations.
+   * @param _entry - The relation change entry (reserved for future use)
+   */
   private async handleBelongsToChange(_entry: RelationChangeEntry): Promise<void> {
     // Reserved for future cascade/persist behaviors for belongs-to relations.
   }
 
+  /**
+   * Handles changes for belongs-to-many relations.
+   * @param entry - The relation change entry
+   */
   private async handleBelongsToManyChange(entry: RelationChangeEntry): Promise<void> {
     const relation = entry.relation as BelongsToManyRelation;
     const rootKey = relation.localKey || findPrimaryKey(entry.rootTable);
@@ -123,12 +158,23 @@ export class RelationChangeProcessor {
     }
   }
 
+  /**
+   * Assigns a foreign key for has-many relations.
+   * @param child - The child entity
+   * @param relation - The has-many relation
+   * @param rootValue - The root entity's primary key value
+   */
   private assignHasManyForeignKey(child: any, relation: HasManyRelation, rootValue: unknown): void {
     const current = child[relation.foreignKey];
     if (current === rootValue) return;
     child[relation.foreignKey] = rootValue;
   }
 
+  /**
+   * Detaches a child entity from has-many relations.
+   * @param child - The child entity
+   * @param relation - The has-many relation
+   */
   private detachHasManyChild(child: any, relation: HasManyRelation): void {
     if (relation.cascade === 'all' || relation.cascade === 'remove') {
       this.unitOfWork.markRemoved(child);
@@ -138,12 +184,23 @@ export class RelationChangeProcessor {
     this.unitOfWork.markDirty(child);
   }
 
+  /**
+   * Assigns a foreign key for has-one relations.
+   * @param child - The child entity
+   * @param relation - The has-one relation
+   * @param rootValue - The root entity's primary key value
+   */
   private assignHasOneForeignKey(child: any, relation: HasOneRelation, rootValue: unknown): void {
     const current = child[relation.foreignKey];
     if (current === rootValue) return;
     child[relation.foreignKey] = rootValue;
   }
 
+  /**
+   * Detaches a child entity from has-one relations.
+   * @param child - The child entity
+   * @param relation - The has-one relation
+   */
   private detachHasOneChild(child: any, relation: HasOneRelation): void {
     if (relation.cascade === 'all' || relation.cascade === 'remove') {
       this.unitOfWork.markRemoved(child);
@@ -153,6 +210,12 @@ export class RelationChangeProcessor {
     this.unitOfWork.markDirty(child);
   }
 
+  /**
+   * Inserts a pivot row for belongs-to-many relations.
+   * @param relation - The belongs-to-many relation
+   * @param rootId - The root entity's primary key value
+   * @param targetId - The target entity's primary key value
+   */
   private async insertPivotRow(relation: BelongsToManyRelation, rootId: string | number, targetId: string | number): Promise<void> {
     const payload = {
       [relation.pivotForeignKeyToRoot]: rootId,
@@ -163,6 +226,12 @@ export class RelationChangeProcessor {
     await this.executor.executeSql(compiled.sql, compiled.params);
   }
 
+  /**
+   * Deletes a pivot row for belongs-to-many relations.
+   * @param relation - The belongs-to-many relation
+   * @param rootId - The root entity's primary key value
+   * @param targetId - The target entity's primary key value
+   */
   private async deletePivotRow(relation: BelongsToManyRelation, rootId: string | number, targetId: string | number): Promise<void> {
     const rootCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
     const targetCol = relation.pivotTable.columns[relation.pivotForeignKeyToTarget];
@@ -175,6 +244,12 @@ export class RelationChangeProcessor {
     await this.executor.executeSql(compiled.sql, compiled.params);
   }
 
+  /**
+   * Resolves the primary key value from an entity.
+   * @param entity - The entity
+   * @param table - The table definition
+   * @returns The primary key value or null
+   */
   private resolvePrimaryKeyValue(entity: any, table: TableDef): string | number | null {
     if (!entity) return null;
     const key = findPrimaryKey(table);

package/src/orm/relations/many-to-many.ts

@@ -63,8 +63,10 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
   attach(target: TTarget | number | string): void {
     const entity = this.ensureEntity(target);
     const id = this.extractId(entity);
-    if (id == null) return;
-    if (this.items.some(item => this.extractId(item) === id)) {
+    if (id != null && this.items.some(item => this.extractId(item) === id)) {
+      return;
+    }
+    if (id == null && this.items.includes(entity)) {
       return;
     }
     this.items.push(entity);