@proteinjs/db 1.26.0 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -65,5 +65,6 @@
     "jest": "29.7.0",
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
-  }
+  },
+  "gitHead": "020e0d6b909cdd60925952aa05c23cfdecd8353d"
 }

package/src/Db.ts

@@ -24,6 +24,7 @@ import {
   DefaultTransactionContextFactory,
   PostCommitHook,
   getDefaultTransactionContextFactory,
+  TransactionContextData,
 } from './transaction/TransactionContextFactory';
 import { isInstanceOf } from '@proteinjs/util';
 import { Reference } from './reference/Reference';
@@ -76,7 +77,6 @@ export class Db<R extends Record = Record> implements DbService<R> {
   private statementConfigFactory: StatementConfigFactory;
   private auth = new TableAuth();
   private tableWatcherRunner = new TableWatcherRunner<R>();
-  private currentTransaction?: any;
   private transactionContextFactory: DefaultTransactionContextFactory;
   public serviceMetadata: Service['serviceMetadata'] = {
     auth: {
@@ -96,10 +96,6 @@ export class Db<R extends Record = Record> implements DbService<R> {
     this.transactionContextFactory = transactionContextFactory
       ? transactionContextFactory
       : this.getDefaultTransactionContextFactory();
-    const transactionContext = this.transactionContextFactory.getTransactionContext();
-    if (transactionContext.currentTransaction) {
-      this.currentTransaction = transactionContext.currentTransaction;
-    }
   }
 
   static getDefaultDbDriver(): DbDriver {
@@ -159,7 +155,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         serializedRecord as Partial<T>,
         this.statementConfigFactory.getStatementConfig(config)
       );
-    await this.dbDriver.runDml(generateInsert, this.currentTransaction);
+    await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
     await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
     return recordCopy as T;
   }
@@ -202,7 +198,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         qb,
         this.statementConfigFactory.getStatementConfig(config)
       );
-    const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.currentTransaction);
+    const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
     await this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb);
     return recordUpdateCount;
   }
@@ -219,7 +215,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * or the record no longer exists — a concurrently deleted record wins).
    */
   async updateArrayMembership<T extends R>(table: Table<T>, update: ArrayMembershipUpdate): Promise<number> {
-    if (!this.currentTransaction) {
+    if (!this.transactionContextFactory.getTransactionContext().currentTransaction) {
       const db = this.newSelfWrapDb();
       return await db.runTransaction(async () => await db.updateArrayMembership(table, update));
     }
@@ -261,7 +257,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * Self-wraps in a transaction when called outside one. Plain-JSON columns only.
    */
   async updatePreserving<T extends R>(table: Table<T>, record: Partial<T>, preserve: PreservedPath[]): Promise<number> {
-    if (!this.currentTransaction) {
+    if (!this.transactionContextFactory.getTransactionContext().currentTransaction) {
       const db = this.newSelfWrapDb();
       return await db.runTransaction(async () => await db.updatePreserving(table, record, preserve));
     }
@@ -316,7 +312,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
       new StatementFactory<T>().delete(table.name, deleteQb, this.statementConfigFactory.getStatementConfig(config));
     await this.runColumnBeforeDeletes(table, recordsToDelete);
     await this.tableWatcherRunner.runBeforeDeleteTableWatchers(table, recordsToDelete, qb, deleteQb);
-    const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.currentTransaction);
+    const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.transactionForDriver());
     await this.runCascadeDeletions(table, recordsToDelete);
     await this.runColumnReverseCascadeDeletions(table, recordsToDelete);
     await this.tableWatcherRunner.runAfterDeleteTableWatchers(table, recordDeleteCount, recordsToDelete, qb, deleteQb);
@@ -536,7 +532,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
 
     const generateQuery = (config: DbDriverQueryStatementConfig) =>
       qb.toSql(this.statementConfigFactory.getStatementConfig(config));
-    const serializedRecords = await this.dbDriver.runQuery(generateQuery, this.currentTransaction);
+    const serializedRecords = await this.dbDriver.runQuery(generateQuery, this.transactionForDriver());
     const recordSerializer = new RecordSerializer(table);
     const records = await Promise.all(
       serializedRecords.map(async (serializedRecord) => recordSerializer.deserialize(serializedRecord))
@@ -579,7 +575,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await this.addColumnQueries(table, qb);
     const generateQuery = (config: DbDriverQueryStatementConfig) =>
       qb.toSql(this.statementConfigFactory.getStatementConfig(config));
-    const result = await this.dbDriver.runQuery(generateQuery, this.currentTransaction);
+    const result = await this.dbDriver.runQuery(generateQuery, this.transactionForDriver());
     return result[0]['count'];
   }
 
@@ -608,13 +604,19 @@ export class Db<R extends Record = Record> implements DbService<R> {
   /**
    * Run a transaction.
    *
-   * Use this db instance for any operation you want to include in the transaction.
-   *
-   * Note: This method uses Db instance state. Usually it is best to create a new instance
-   * of Db to run a transaction.
+   * Db instances are STATELESS with respect to transactions: every operation resolves the
+   * ambient transaction (AsyncLocalStorage) at call time, so any Db instance used inside the
+   * transaction body — whenever it was constructed — rides the transaction. There is no way
+   * to issue an operation outside a transaction from inside its body, and no second session
+   * is ever acquired inside one (the historical pool-wedge class is unrepresentable —
+   * plans/DB_PERF_PLAN.md P2, in the consumer repo).
    *
    * Note: Nested transactions are not supported; will throw.
    *
+   * Note: work spawned inside the body but NOT awaited by it escapes the transaction's
+   * lifetime while still holding its context — such work fails loudly on its next db
+   * operation (see TransactionContextData.ended). Await everything inside the body, or run
+   * it outside the transaction.
    *
    * Example:
    *
@@ -630,8 +632,8 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * ```
    */
   async runTransaction<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.currentTransaction) {
-      throw new Error(`Nested transactions are not supported. A transaction is already running on this Db instance.`);
+    if (this.transactionContextFactory.getTransactionContext().currentTransaction) {
+      throw new Error(`Nested transactions are not supported. A transaction is already running in this context.`);
     }
 
     // Reassigned fresh per driver attempt: drivers may retry `fn` on transient aborts (Spanner's
@@ -639,19 +641,18 @@ export class Db<R extends Record = Record> implements DbService<R> {
     // the attempt that actually commits. Only the committed attempt's queue is drained below.
     let postCommitHooks: PostCommitHook[] = [];
     const result = await this.dbDriver.runTransaction(async (transaction) => {
-      this.currentTransaction = transaction;
+      // A fresh ambient store per attempt: the transaction, the attempt's post-commit hook
+      // queue (shared by every Db instance created inside — see runAfterCommit), and the
+      // ended-tombstone below.
       postCommitHooks = [];
-
+      const contextData: TransactionContextData = { currentTransaction: transaction, postCommitHooks };
       try {
-        return await this.transactionContextFactory.runInContext(transaction, async () => {
-          // Seed the post-commit hook queue on the ambient context so every Db instance created
-          // inside this transaction shares it (see runAfterCommit).
-          this.transactionContextFactory.getTransactionContext().postCommitHooks = postCommitHooks;
-          const result = await fn();
-          return result;
-        });
+        return await this.transactionContextFactory.runInContext(contextData, fn);
       } finally {
-        this.currentTransaction = undefined;
+        // Tombstone the store: detached work spawned inside the body still holds it by
+        // reference — the flag turns its next db operation into a loud error instead of a
+        // silent op on a finished transaction (see transactionForDriver).
+        contextData.ended = true;
       }
     });
 
@@ -714,6 +715,24 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return new Db<R>(this.dbDriver, this.getTable, this.transactionContextFactory, this.runAsSystem);
   }
 
+  /**
+   * The transaction every driver call rides, resolved from the ambient context AT CALL TIME
+   * (statelessness is the safety property: operations inside a transaction body always ride
+   * it; operations outside always use the pool). The one remaining failure shape — work that
+   * escaped a finished transaction's body while holding its context — throws here by name;
+   * handing the driver an ended transaction would fail anyway, with a far worse error.
+   */
+  private transactionForDriver(): any {
+    const context = this.transactionContextFactory.getTransactionContext();
+    if (context.ended) {
+      throw new Error(
+        `Db operation issued in the context of a transaction that already ended: work spawned inside a runTransaction body (and not awaited by it) survived the transaction. Await the work inside the body, or run it outside the transaction.`
+      );
+    }
+
+    return context.currentTransaction;
+  }
+
   // Utility: simple chunker
   private chunk<T>(arr: T[], size: number): T[][] {
     if (size <= 0) {

package/src/transaction/TransactionContextFactory.ts

@@ -16,9 +16,16 @@ export interface TransactionContextData {
    * `Db.runTransaction` once the driver reports the commit durable.
    */
   postCommitHooks?: PostCommitHook[];
+  /**
+   * Set by `Db.runTransaction` when the transaction completes. Work spawned inside the
+   * transaction body but not awaited by it still holds this store by reference (the async
+   * context propagates) — the flag turns any later db operation from that escaped context
+   * into a loud, named error instead of silently handing the driver a finished transaction.
+   */
+  ended?: boolean;
 }
 
 export interface DefaultTransactionContextFactory extends Loadable {
   getTransactionContext(): TransactionContextData;
-  runInContext<T>(transaction: any, fn: () => Promise<T>): Promise<T>;
+  runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T>;
 }