metal-orm 1.1.8 → 1.1.10

package/src/orm/orm-session.ts

@@ -32,11 +32,16 @@ import { runInTransaction } from './transaction-runner.js';
 import { saveGraphInternal, patchGraphInternal, SaveGraphOptions } from './save-graph.js';
 import type { SaveGraphInputPayload, PatchGraphInputPayload } from './save-graph-types.js';
 import type { QueryCacheManager } from '../cache/query-cache-manager.js';
-
-/**
- * Interface for ORM interceptors that allow hooking into the flush lifecycle.
- */
-export interface OrmInterceptor {
+
+const NESTED_TRANSACTIONS_REQUIRE_SAVEPOINTS =
+  'Nested session.transaction calls require savepoint support in this executor';
+const ROLLBACK_ONLY_TRANSACTION =
+  'Cannot commit transaction because an inner transaction failed';
+
+/**
+ * Interface for ORM interceptors that allow hooking into the flush lifecycle.
+ */
+export interface OrmInterceptor {
   /**
    * Called before the flush operation begins.
    * @param ctx - The entity context
@@ -54,22 +59,22 @@ export interface OrmInterceptor {
  * Options for creating an OrmSession instance.
  * @template E - The domain event type
  */
-export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
-  /** The ORM instance */
-  orm: Orm<E>;
-  /** The database executor */
-  executor: DbExecutor;
-  /** Optional query logger for debugging */
-  queryLogger?: QueryLogger;
-  /** Optional interceptors for flush lifecycle hooks */
-  interceptors?: OrmInterceptor[];
-  /** Optional domain event handlers */
-  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
-  /** Optional cache manager for query caching */
-  cacheManager?: QueryCacheManager;
-  /** Optional tenant ID for multi-tenancy */
-  tenantId?: string | number;
-}
+export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+  /** The ORM instance */
+  orm: Orm<E>;
+  /** The database executor */
+  executor: DbExecutor;
+  /** Optional query logger for debugging */
+  queryLogger?: QueryLogger;
+  /** Optional interceptors for flush lifecycle hooks */
+  interceptors?: OrmInterceptor[];
+  /** Optional domain event handlers */
+  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
+  /** Optional cache manager for query caching */
+  cacheManager?: QueryCacheManager;
+  /** Optional tenant ID for multi-tenancy */
+  tenantId?: string | number;
+}
 
 export interface SaveGraphSessionOptions extends SaveGraphOptions {
   /** Wrap the save operation in a transaction (default: true). */
@@ -93,15 +98,18 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
   readonly unitOfWork: UnitOfWork;
   /** The domain event bus */
   readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
-  /** The relation change processor */
-  readonly relationChanges: RelationChangeProcessor;
-  /** The cache manager for query caching */
-  readonly cacheManager?: QueryCacheManager;
-  /** The tenant ID for multi-tenancy support */
-  readonly tenantId?: string | number;
-
+  /** The relation change processor */
+  readonly relationChanges: RelationChangeProcessor;
+  /** The cache manager for query caching */
+  readonly cacheManager?: QueryCacheManager;
+  /** The tenant ID for multi-tenancy support */
+  readonly tenantId?: string | number;
+
   private readonly interceptors: OrmInterceptor[];
   private saveGraphDefaults?: SaveGraphSessionOptions;
+  private transactionDepth = 0;
+  private savepointCounter = 0;
+  private rollbackOnly = false;
 
   /**
    * Creates a new OrmSession instance.
@@ -112,13 +120,13 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     this.executor = createQueryLoggingExecutor(opts.executor, opts.queryLogger);
     this.interceptors = [...(opts.interceptors ?? [])];
 
-    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<E, OrmSession<E>>(opts.domainEventHandlers);
-    this.cacheManager = opts.cacheManager;
-    this.tenantId = opts.tenantId;
-  }
+    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<E, OrmSession<E>>(opts.domainEventHandlers);
+    this.cacheManager = opts.cacheManager;
+    this.tenantId = opts.tenantId;
+  }
 
   /**
    * Releases resources associated with this session (executor/pool leases) and resets tracking.
@@ -533,37 +541,71 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @returns The result of the function
    * @throws If the transaction fails
    */
-  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
-    // If the executor can't do transactions, just run and commit once.
-    if (!this.executor.capabilities.transactions) {
-      const result = await fn(this);
-      await this.commit();
-      return result;
-    }
-
-    await this.executor.beginTransaction();
-    try {
-      const result = await fn(this);
-      await this.flushWithHooks();
-      await this.executor.commitTransaction();
-      await this.domainEvents.dispatch(this.unitOfWork.getTracked(), this);
-      return result;
-    } catch (err) {
-      await this.rollback();
-      throw err;
-    }
-  }
+  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
+    // If the executor can't do transactions, just run and commit once.
+    if (!this.executor.capabilities.transactions) {
+      const result = await fn(this);
+      await this.commit();
+      return result;
+    }
+
+    const isOutermost = this.transactionDepth === 0;
+    let savepointName: string | null = null;
+
+    if (isOutermost) {
+      this.rollbackOnly = false;
+      await this.executor.beginTransaction();
+    } else {
+      this.assertSavepointSupport();
+      savepointName = this.nextSavepointName();
+      await this.executor.savepoint!(savepointName);
+    }
+
+    this.transactionDepth += 1;
+    try {
+      const result = await fn(this);
+      this.throwIfRollbackOnly();
+      await this.flushWithHooks();
+      this.throwIfRollbackOnly();
+
+      if (isOutermost) {
+        await this.executor.commitTransaction();
+        await this.domainEvents.dispatch(this.unitOfWork.getTracked(), this);
+      } else {
+        await this.executor.releaseSavepoint!(savepointName!);
+      }
+
+      return result;
+    } catch (err) {
+      if (isOutermost) {
+        await this.rollback();
+      } else {
+        this.rollbackOnly = true;
+        await this.executor.rollbackToSavepoint!(savepointName!);
+      }
+      throw err;
+    } finally {
+      this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+      if (this.transactionDepth === 0) {
+        this.rollbackOnly = false;
+        this.savepointCounter = 0;
+      }
+    }
+  }
 
   /**
    * Rolls back the current transaction.
    */
-  async rollback(): Promise<void> {
-    if (this.executor.capabilities.transactions) {
-      await this.executor.rollbackTransaction();
-    }
-    this.unitOfWork.reset();
-    this.relationChanges.reset();
-  }
+  async rollback(): Promise<void> {
+    if (this.executor.capabilities.transactions) {
+      await this.executor.rollbackTransaction();
+    }
+    this.transactionDepth = 0;
+    this.savepointCounter = 0;
+    this.rollbackOnly = false;
+    this.unitOfWork.reset();
+    this.relationChanges.reset();
+  }
 
   /**
    * Gets the execution context.
@@ -591,55 +633,79 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     };
   }
 
-  /**
-   * Invalidates cache by specific tags.
-   * @param tags - Tags to invalidate
-   * @throws Error if no cache manager is configured
-   * @example
-   * await session.invalidateCacheTags(['users', 'dashboard']);
-   */
-  async invalidateCacheTags(tags: string[]): Promise<void> {
-    if (!this.cacheManager) {
-      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
-    }
-    await this.cacheManager.invalidateTags(tags);
+  /**
+   * Invalidates cache by specific tags.
+   * @param tags - Tags to invalidate
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCacheTags(['users', 'dashboard']);
+   */
+  async invalidateCacheTags(tags: string[]): Promise<void> {
+    if (!this.cacheManager) {
+      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
+    }
+    await this.cacheManager.invalidateTags(tags);
+  }
+
+  /**
+   * Invalidates cache by key prefix (useful for multi-tenancy).
+   * @param prefix - Prefix to match cache keys
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCachePrefix('tenant:123:');
+   */
+  async invalidateCachePrefix(prefix: string): Promise<void> {
+    if (!this.cacheManager) {
+      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
+    }
+    await this.cacheManager.invalidatePrefix(prefix);
+  }
+
+  /**
+   * Invalidates a specific cache key.
+   * @param key - Cache key to invalidate
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCacheKey('active_users');
+   */
+  async invalidateCacheKey(key: string): Promise<void> {
+    if (!this.cacheManager) {
+      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
+    }
+    await this.cacheManager.invalidateKey(key, this.tenantId);
+  }
+
+  /**
+   * Merges session defaults with per-call saveGraph options.
+   * @param options - Per-call saveGraph options
+   * @returns Combined options with per-call values taking precedence
+   */
+  private resolveSaveGraphOptions(options?: SaveGraphSessionOptions): SaveGraphSessionOptions {
+    return { ...(this.saveGraphDefaults ?? {}), ...(options ?? {}) };
   }
 
-  /**
-   * Invalidates cache by key prefix (useful for multi-tenancy).
-   * @param prefix - Prefix to match cache keys
-   * @throws Error if no cache manager is configured
-   * @example
-   * await session.invalidateCachePrefix('tenant:123:');
-   */
-  async invalidateCachePrefix(prefix: string): Promise<void> {
-    if (!this.cacheManager) {
-      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
+  private assertSavepointSupport(): void {
+    if (!this.executor.capabilities.savepoints) {
+      throw new Error(NESTED_TRANSACTIONS_REQUIRE_SAVEPOINTS);
+    }
+    if (
+      typeof this.executor.savepoint !== 'function' ||
+      typeof this.executor.releaseSavepoint !== 'function' ||
+      typeof this.executor.rollbackToSavepoint !== 'function'
+    ) {
+      throw new Error(NESTED_TRANSACTIONS_REQUIRE_SAVEPOINTS);
     }
-    await this.cacheManager.invalidatePrefix(prefix);
   }
 
-  /**
-   * Invalidates a specific cache key.
-   * @param key - Cache key to invalidate
-   * @throws Error if no cache manager is configured
-   * @example
-   * await session.invalidateCacheKey('active_users');
-   */
-  async invalidateCacheKey(key: string): Promise<void> {
-    if (!this.cacheManager) {
-      throw new Error('No cache manager configured. Please provide cacheManager when creating the session.');
-    }
-    await this.cacheManager.invalidateKey(key, this.tenantId);
+  private nextSavepointName(): string {
+    this.savepointCounter += 1;
+    return `metalorm_sp_${this.savepointCounter}`;
   }
 
-  /**
-   * Merges session defaults with per-call saveGraph options.
-   * @param options - Per-call saveGraph options
-   * @returns Combined options with per-call values taking precedence
-   */
-  private resolveSaveGraphOptions(options?: SaveGraphSessionOptions): SaveGraphSessionOptions {
-    return { ...(this.saveGraphDefaults ?? {}), ...(options ?? {}) };
+  private throwIfRollbackOnly(): void {
+    if (this.rollbackOnly) {
+      throw new Error(ROLLBACK_ONLY_TRANSACTION);
+    }
   }
 }
 

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

@@ -1,39 +1,42 @@
-import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
-import { toExecutionPayload } from '../core/execution/db-executor.js';
-import { rowsToQueryResult } from '../core/execution/db-executor.js';
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import { toExecutionPayload } 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>>
-      | Array<Array<Record<string, unknown>>>
-      | QueryResult[]
-    >;
-
-    beginTransaction(conn: TConn): Promise<void>;
-    commitTransaction(conn: TConn): Promise<void>;
-    rollbackTransaction(conn: TConn): Promise<void>;
-}
-
-type PooledExecutorFactoryOptions<TConn> = {
-    pool: Pool<TConn>;
-    adapter: PooledConnectionAdapter<TConn>;
-};
-
-const isQueryResult = (value: unknown): value is QueryResult =>
-  typeof value === 'object' &&
-  value !== null &&
-  Array.isArray((value as QueryResult).columns) &&
-  Array.isArray((value as QueryResult).values);
-
-const isRowArray = (value: unknown): value is Array<Record<string, unknown>> =>
-  Array.isArray(value) &&
-  value.every(item => typeof item === 'object' && item !== null && !Array.isArray(item));
+    query(
+        conn: TConn,
+        sql: string,
+        params?: unknown[]
+    ): Promise<
+      | Array<Record<string, unknown>>
+      | Array<Array<Record<string, unknown>>>
+      | QueryResult[]
+    >;
+
+    beginTransaction(conn: TConn): Promise<void>;
+    commitTransaction(conn: TConn): Promise<void>;
+    rollbackTransaction(conn: TConn): Promise<void>;
+    savepoint?(conn: TConn, name: string): Promise<void>;
+    releaseSavepoint?(conn: TConn, name: string): Promise<void>;
+    rollbackToSavepoint?(conn: TConn, name: string): Promise<void>;
+}
+
+type PooledExecutorFactoryOptions<TConn> = {
+    pool: Pool<TConn>;
+    adapter: PooledConnectionAdapter<TConn>;
+};
+
+const isQueryResult = (value: unknown): value is QueryResult =>
+  typeof value === 'object' &&
+  value !== null &&
+  Array.isArray((value as QueryResult).columns) &&
+  Array.isArray((value as QueryResult).values);
+
+const isRowArray = (value: unknown): value is Array<Record<string, unknown>> =>
+  Array.isArray(value) &&
+  value.every(item => typeof item === 'object' && item !== null && !Array.isArray(item));
 
 /**
  * Creates a first-class DbExecutorFactory backed by MetalORM's Pool.
@@ -45,11 +48,15 @@ const isRowArray = (value: unknown): value is Array<Record<string, unknown>> =>
  */
 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;
+): DbExecutorFactory {
+    const { pool, adapter } = opts;
+    const supportsSavepoints =
+      typeof adapter.savepoint === 'function' &&
+      typeof adapter.releaseSavepoint === 'function' &&
+      typeof adapter.rollbackToSavepoint === 'function';
+
+    const makeExecutor = (mode: 'session' | 'sticky'): DbExecutor => {
+        let lease: Awaited<ReturnType<typeof pool.acquire>> | null = null;
 
         const getLease = async () => {
             if (lease) return lease;
@@ -61,19 +68,29 @@ export function createPooledExecutorFactory<TConn>(
             conn: TConn,
             sql: string,
             params?: unknown[]
-        ) => {
-            const rows = await adapter.query(conn, sql, params);
-            if (Array.isArray(rows) && rows.length > 0 && rows.every(isQueryResult)) {
-              return toExecutionPayload(rows);
-            }
-            if (Array.isArray(rows) && rows.length > 0 && rows.every(isRowArray)) {
-              return toExecutionPayload(rows.map(set => rowsToQueryResult(set)));
+        ) => {
+            const rows = await adapter.query(conn, sql, params);
+            if (Array.isArray(rows) && rows.length > 0 && rows.every(isQueryResult)) {
+              return toExecutionPayload(rows);
+            }
+            if (Array.isArray(rows) && rows.length > 0 && rows.every(isRowArray)) {
+              return toExecutionPayload(rows.map(set => rowsToQueryResult(set)));
             }
             return toExecutionPayload([rowsToQueryResult(rows as Array<Record<string, unknown>>)]);
         };
-
-        return {
-            capabilities: { transactions: true },
+
+        const requireActiveTransactionLease = () => {
+            if (!lease) {
+                throw new Error('savepoint operation called without an active transaction');
+            }
+            return lease;
+        };
+
+        return {
+            capabilities: {
+                transactions: true,
+                ...(supportsSavepoints ? { savepoints: true } : {}),
+            },
 
             async executeSql(sql, params) {
                 // Sticky mode: always reuse a leased connection.
@@ -114,22 +131,46 @@ export function createPooledExecutorFactory<TConn>(
                 }
             },
 
-            async rollbackTransaction() {
-                if (!lease) {
-                    // Nothing to rollback; keep idempotent semantics.
-                    return;
-                }
+            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;
+                    await l.release();
+                }
+            },
+
+            async savepoint(name: string) {
+                if (!supportsSavepoints) {
+                    throw new Error('Savepoints are not supported by this executor');
+                }
+                const l = requireActiveTransactionLease();
+                await adapter.savepoint!(l.resource, name);
+            },
+
+            async releaseSavepoint(name: string) {
+                if (!supportsSavepoints) {
+                    throw new Error('Savepoints are not supported by this executor');
+                }
+                const l = requireActiveTransactionLease();
+                await adapter.releaseSavepoint!(l.resource, name);
+            },
+
+            async rollbackToSavepoint(name: string) {
+                if (!supportsSavepoints) {
+                    throw new Error('Savepoints are not supported by this executor');
+                }
+                const l = requireActiveTransactionLease();
+                await adapter.rollbackToSavepoint!(l.resource, name);
+            },
+
+            async dispose() {
+                if (!lease) return;
                 const l = lease;
                 lease = null;
                 await l.release();

package/src/orm/query-logger.ts

@@ -1,47 +1,56 @@
-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
-): DbExecutor => {
-  if (!logger) {
-    return executor;
-  }
-
-  const wrapped: DbExecutor = {
-    capabilities: executor.capabilities,
-    async executeSql(sql, params) {
-      logger({ sql, params });
-      return executor.executeSql(sql, params);
+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
+): DbExecutor => {
+  if (!logger) {
+    return executor;
+  }
+
+  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(),
+    savepoint: executor.savepoint
+      ? (name: string) => executor.savepoint!(name)
+      : undefined,
+    releaseSavepoint: executor.releaseSavepoint
+      ? (name: string) => executor.releaseSavepoint!(name)
+      : undefined,
+    rollbackToSavepoint: executor.rollbackToSavepoint
+      ? (name: string) => executor.rollbackToSavepoint!(name)
+      : undefined,
     dispose: () => executor.dispose(),
   };
-
-  return wrapped;
-};
+
+  return wrapped;
+};