@spfn/core 0.3.0-beta.4 → 0.3.0-beta.6

package/dist/db/index.js

@@ -3,7 +3,7 @@ import { env } from '@spfn/core/config';
 import { logger } from '@spfn/core/logger';
 import net from 'net';
 import postgres from 'postgres';
-import { QueryError, ConnectionError, DeadlockError, TransactionError, ConstraintViolationError, DuplicateEntryError, DatabaseError } from '@spfn/core/errors';
+import { QueryError, ConnectionError, DeadlockError, TransactionError, ConstraintViolationError, DuplicateEntryError, SerializableError } from '@spfn/core/errors';
 import { parseNumber, parseBoolean } from '@spfn/core/env';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, dirname, basename } from 'path';
@@ -1743,6 +1743,32 @@ function pendingMigrationsSummary(targets) {
   return `${pending} pending migration(s) in ${names}`;
 }
 var txLogger = logger.child("@spfn/core:transaction");
+var concurrentNestingReported = false;
+function reportConcurrentNesting() {
+  if (concurrentNestingReported) {
+    return;
+  }
+  concurrentNestingReported = true;
+  txLogger.warn("Concurrent nested transactions are serialized", {
+    reason: "sibling SAVEPOINTs share the outer transaction's connection, where one sibling's ROLLBACK TO would discard the other's writes",
+    hint: "await nested calls one at a time, or pass requiresNew: true to give a branch its own connection. A nested call whose callback awaits a sibling started after it deadlocks."
+  });
+}
+function createNestedFrameGate() {
+  let tail = Promise.resolve();
+  let pending = 0;
+  return {
+    run(frame) {
+      if (pending > 0) {
+        reportConcurrentNesting();
+      }
+      pending++;
+      const result = tail.then(frame);
+      tail = result.then(() => void pending--, () => void pending--);
+      return result;
+    }
+  };
+}
 var asyncContext = new AsyncLocalStorage();
 function getTransactionContext() {
   return asyncContext.getStore() ?? null;
@@ -1755,7 +1781,7 @@ function runWithTransaction(tx, txId, callback) {
   const existingContext = getTransactionContext();
   const newLevel = existingContext ? existingContext.level + 1 : 1;
   if (existingContext) {
-    txLogger.info("Nested transaction started (SAVEPOINT)", {
+    txLogger.debug("Nested transaction started (SAVEPOINT)", {
       outerTxId: existingContext.txId,
       innerTxId: txId,
       level: newLevel
@@ -1763,9 +1789,19 @@ function runWithTransaction(tx, txId, callback) {
   } else {
     txLogger.debug("Root transaction context set", { txId, level: newLevel });
   }
-  const afterCommitCallbacks = existingContext ? existingContext.afterCommitCallbacks : [];
+  const beforeCommitCallbacks = existingContext?.beforeCommitCallbacks ?? [];
+  const afterCommitCallbacks = existingContext?.afterCommitCallbacks ?? [];
+  const afterRollbackCallbacks = existingContext?.afterRollbackCallbacks ?? [];
   return asyncContext.run(
-    { tx, txId, level: newLevel, afterCommitCallbacks },
+    {
+      tx,
+      txId,
+      level: newLevel,
+      beforeCommitCallbacks,
+      afterCommitCallbacks,
+      afterRollbackCallbacks,
+      nestedFrames: createNestedFrameGate()
+    },
     callback
   );
 }
@@ -1781,14 +1817,67 @@ function onAfterCommit(callback) {
   }
   context.afterCommitCallbacks.push(callback);
 }
+function onBeforeCommit(callback) {
+  const context = getTransactionContext();
+  if (!context) {
+    txLogger.warn(
+      "beforeCommit callback ran immediately (no transaction): a throw cannot abort anything"
+    );
+    Promise.resolve().then(callback).catch((err) => {
+      txLogger.error("beforeCommit callback failed (no transaction)", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    });
+    return;
+  }
+  context.beforeCommitCallbacks.push(callback);
+}
+function onAfterRollback(callback) {
+  const context = getTransactionContext();
+  if (!context) {
+    txLogger.warn("afterRollback callback ignored (no transaction)");
+    return;
+  }
+  context.afterRollbackCallbacks.push(callback);
+}
 var MAX_TIMEOUT_MS = 2147483647;
 var txLogger2 = logger.child("@spfn/core:transaction");
+function logSafely(emit) {
+  try {
+    emit();
+  } catch {
+  }
+}
+async function runBeforeCommitCallbacks(callbacks) {
+  for (const cb of [...callbacks]) {
+    await cb();
+  }
+}
+async function runAfterRollbackCallbacks(callbacks, txId, context, enableLogging) {
+  if (enableLogging) {
+    logSafely(() => txLogger2.debug("Executing afterRollback callbacks", {
+      txId,
+      context,
+      count: callbacks.length
+    }));
+  }
+  for (const cb of callbacks) {
+    await Promise.resolve().then(cb).catch((err) => logSafely(() => {
+      txLogger2.error("afterRollback callback failed", {
+        txId,
+        context,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }));
+  }
+}
 async function runInTransaction(callback, options = {}) {
   const defaultTimeout = env.TRANSACTION_TIMEOUT;
   const {
     slowThreshold = 1e3,
     enableLogging = true,
-    context = "transaction"
+    context = "transaction",
+    requiresNew = false
   } = options;
   const timeout = options.timeout ?? defaultTimeout;
   const idleTimeout = options.idleTimeout ?? env.TRANSACTION_IDLE_TIMEOUT;
@@ -1866,24 +1955,37 @@ async function runInTransaction(callback, options = {}) {
     }
     throw error;
   }
-  const existingContext = getTransactionContext();
-  const isNested = existingContext !== null;
-  if (isNested && timeout > 0 && enableLogging) {
+  const savepointOwner = requiresNew ? null : getTransactionContext();
+  const isNested = savepointOwner !== null;
+  if (isNested && options.timeout !== void 0 && options.timeout > 0 && enableLogging) {
     txLogger2.warn("Timeout ignored in nested transaction", {
       txId,
       context,
-      outerTxId: existingContext.txId,
+      outerTxId: savepointOwner.txId,
       requestedTimeout: `${timeout}ms`,
-      reason: "SET LOCAL statement_timeout affects the entire outer transaction"
+      reason: "the SAVEPOINT runs under the outer transaction's statement_timeout; SET LOCAL here would re-scope the whole outer transaction"
     });
   }
   if (enableLogging) {
     txLogger2.debug("Transaction started", { txId, context });
   }
   const startTime = Date.now();
+  let beforeCommitCallbacks = [];
   let afterCommitCallbacks = [];
+  let afterRollbackCallbacks = [];
+  const openTransaction = (body) => {
+    if (savepointOwner) {
+      return savepointOwner.nestedFrames.run(
+        () => savepointOwner.tx.transaction(body)
+      );
+    }
+    if (requiresNew) {
+      return asyncContext.exit(() => writeDb.transaction(body));
+    }
+    return writeDb.transaction(body);
+  };
   try {
-    const result = await writeDb.transaction(async (tx) => {
+    const result = await openTransaction(async (tx) => {
       const transaction = tx;
       if (timeout > 0 && !isNested) {
         await transaction.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
@@ -1892,81 +1994,117 @@ async function runInTransaction(callback, options = {}) {
         await transaction.execute(sql.raw(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeout}`));
       }
       return await runWithTransaction(transaction, txId, async () => {
-        const innerResult = await callback(transaction);
         if (!isNested) {
           const ctx = getTransactionContext();
           if (ctx) {
-            afterCommitCallbacks = [...ctx.afterCommitCallbacks];
+            beforeCommitCallbacks = ctx.beforeCommitCallbacks;
+            afterCommitCallbacks = ctx.afterCommitCallbacks;
+            afterRollbackCallbacks = ctx.afterRollbackCallbacks;
+          }
+        }
+        const innerResult = await callback(transaction);
+        if (!isNested && beforeCommitCallbacks.length > 0) {
+          if (enableLogging) {
+            logSafely(() => txLogger2.debug("Executing beforeCommit callbacks", {
+              txId,
+              context,
+              count: beforeCommitCallbacks.length
+            }));
           }
+          await runBeforeCommitCallbacks(beforeCommitCallbacks);
         }
         return innerResult;
       });
     });
     const duration = Date.now() - startTime;
     if (enableLogging) {
-      if (duration >= slowThreshold) {
-        txLogger2.warn("Slow transaction committed", {
-          txId,
-          context,
-          duration: `${duration}ms`,
-          threshold: `${slowThreshold}ms`,
-          hint: "A transaction holds a pooled connection (and row locks) for its whole duration. If this is slow because of non-DB work (external API, etc.) inside the transaction, move that work out \u2014 it starves the connection pool."
-        });
-      } else {
-        txLogger2.debug("Transaction committed", {
-          txId,
-          context,
-          duration: `${duration}ms`
-        });
-      }
+      logSafely(() => {
+        if (duration >= slowThreshold) {
+          txLogger2.warn("Slow transaction committed", {
+            txId,
+            context,
+            duration: `${duration}ms`,
+            threshold: `${slowThreshold}ms`,
+            hint: "A transaction holds a pooled connection (and row locks) for its whole duration. If this is slow because of non-DB work (external API, etc.) inside the transaction, move that work out \u2014 it starves the connection pool."
+          });
+        } else {
+          txLogger2.debug("Transaction committed", {
+            txId,
+            context,
+            duration: `${duration}ms`
+          });
+        }
+      });
     }
     if (!isNested && afterCommitCallbacks.length > 0) {
       if (enableLogging) {
-        txLogger2.debug("Executing afterCommit callbacks", {
+        logSafely(() => txLogger2.debug("Executing afterCommit callbacks", {
           txId,
           context,
           count: afterCommitCallbacks.length
-        });
+        }));
       }
       for (const cb of afterCommitCallbacks) {
-        Promise.resolve().then(cb).catch((err) => {
+        Promise.resolve().then(cb).catch((err) => logSafely(() => {
           txLogger2.error("afterCommit callback failed", {
             txId,
             context,
             error: err instanceof Error ? err.message : String(err)
           });
-        });
+        }));
       }
     }
     return result;
   } catch (error) {
     const duration = Date.now() - startTime;
     if (enableLogging) {
-      if (duration >= slowThreshold) {
-        txLogger2.warn("Slow transaction rolled back", {
-          txId,
-          context,
-          duration: `${duration}ms`,
-          threshold: `${slowThreshold}ms`,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.name : "Unknown",
-          hint: "If the error is an idle-in-transaction timeout, the transaction held a pooled connection while awaiting non-DB work (external API, etc.). Move that work out of the transaction."
-        });
-      } else {
-        txLogger2.error("Transaction rolled back", {
-          txId,
-          context,
-          duration: `${duration}ms`,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.name : "Unknown"
-        });
-      }
+      logSafely(() => {
+        if (duration >= slowThreshold) {
+          txLogger2.warn("Slow transaction rolled back", {
+            txId,
+            context,
+            duration: `${duration}ms`,
+            threshold: `${slowThreshold}ms`,
+            error: error instanceof Error ? error.message : String(error),
+            errorType: error instanceof Error ? error.name : "Unknown",
+            hint: "If the error is an idle-in-transaction timeout, the transaction held a pooled connection while awaiting non-DB work (external API, etc.). Move that work out of the transaction."
+          });
+        } else {
+          txLogger2.error("Transaction rolled back", {
+            txId,
+            context,
+            duration: `${duration}ms`,
+            error: error instanceof Error ? error.message : String(error),
+            errorType: error instanceof Error ? error.name : "Unknown"
+          });
+        }
+      });
+    }
+    if (!isNested && afterRollbackCallbacks.length > 0) {
+      await runAfterRollbackCallbacks(afterRollbackCallbacks, txId, context, enableLogging).catch(() => void 0);
     }
     throw error;
   }
 }
 
 // src/db/transaction/middleware.ts
+var SQLSTATE_PATTERN = /^[0-9A-Z]{5}$/;
+function isDriverOriginError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const candidate = error;
+  if (typeof candidate.code !== "string") {
+    return false;
+  }
+  if (POSTGRES_JS_CONNECTION_CODES.has(candidate.code)) {
+    return true;
+  }
+  if (!SQLSTATE_PATTERN.test(candidate.code)) {
+    return false;
+  }
+  return typeof candidate.severity === "string" || typeof candidate.severity_local === "string";
+}
 function Transactional(options = {}) {
   return createMiddleware(async (c, next) => {
     const route = `${c.req.method} ${c.req.path}`;
@@ -1986,13 +2124,10 @@ function Transactional(options = {}) {
       );
     } catch (error) {
       reportDatabaseError(error);
-      if (error instanceof DatabaseError) {
-        throw error;
-      }
-      if (error instanceof TransactionError) {
+      if (error instanceof SerializableError) {
         throw error;
       }
-      if (error && typeof error === "object" && "code" in error && typeof error.code === "string") {
+      if (isDriverOriginError(error)) {
         throw fromPostgresError(error);
       }
       throw error;
@@ -2531,6 +2666,6 @@ var BaseRepository = class {
   }
 };
 
-export { BaseRepository, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, RUN_MIGRATIONS_HINT, RepositoryError, Transactional, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { BaseRepository, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, RUN_MIGRATIONS_HINT, RepositoryError, Transactional, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, onAfterRollback, onBeforeCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map