@vibeorm/runtime 2.5.0 → 3.0.0

package/dist/adapter-kit/index.js

@@ -62,10 +62,14 @@ async function runNestedSavepoint(params) {
       await drainDescendants({ node });
       assertNotPoisoned({ state: scope.state });
       if (execute !== undefined) {
+        const cleanup = params.cleanup ?? execute;
+        let cleanupStage = "rollback";
         try {
-          await execute(`ROLLBACK TO SAVEPOINT ${node.name}`);
+          await cleanup(`ROLLBACK TO SAVEPOINT ${node.name}`);
+          cleanupStage = "release";
+          await cleanup(`RELEASE SAVEPOINT ${node.name}`);
         } catch (rollbackFailure) {
-          const poisoned = savepointRollbackFailedError({ cause: error, rollbackFailure });
+          const poisoned = savepointRollbackFailedError({ cause: error, rollbackFailure, cleanupStage });
           scope.state.poisoned = poisoned;
           throw poisoned;
         }
@@ -85,14 +89,16 @@ function markSavepointOpened(params) {
 }
 function savepointRollbackFailedError(params) {
   const { cause, rollbackFailure } = params;
+  const releaseFailed = params.cleanupStage === "release";
   const rollbackErrorCode = rollbackFailure instanceof VibeError ? rollbackFailure.code : undefined;
   return new VibeError({
     code: "VIBE_TRANSACTION",
-    message: "a nested transaction failed and the ROLLBACK TO SAVEPOINT that should have undone it failed too \u2014 " + "the savepoint stack no longer describes this connection, so the commit state of the whole transaction " + "is UNKNOWN and no further statement is accepted on any of its handles. The top-level transaction is " + "being rolled back; nothing is retried automatically.",
+    message: (releaseFailed ? "a nested transaction failed and RELEASE SAVEPOINT after its confirmed rollback failed too. " : "a nested transaction failed and ROLLBACK TO SAVEPOINT failed too. ") + "The savepoint stack no longer describes this connection, so the commit state of the whole transaction " + "is UNKNOWN and no further statement is accepted on any of its handles. The top-level transaction is " + "being rolled back; nothing is retried automatically.",
     meta: {
       reason: "savepoint-rollback-failed",
       outcome: "unknown",
-      rollbackFailed: true,
+      rollbackFailed: !releaseFailed,
+      ...releaseFailed ? { cleanupStage: "release" } : {},
       ...rollbackErrorCode === undefined ? {} : { rollbackErrorCode }
     },
     cause
@@ -103,7 +109,7 @@ function isSavepointRollbackFailedError(error) {
   return reason === "savepoint-rollback-failed";
 }
 function transactionAbortedError(params) {
-  const cause = params.cause;
+  const cause = mappedCauseOf({ error: params.cause }) ?? params.cause;
   const causeCode = cause instanceof VibeError ? cause.code : undefined;
   const sqlstate = cause instanceof VibeError && typeof cause.meta.sqlstate === "string" ? cause.meta.sqlstate : undefined;
   return new VibeError({
@@ -111,13 +117,23 @@ function transactionAbortedError(params) {
     message: "the transaction is aborted: a statement inside it failed and PostgreSQL discards every later statement and the COMMIT itself " + "(the server answers COMMIT with ROLLBACK and no error). Nothing from this transaction was committed. " + "Let the failure propagate out of the callback, or run the statement that may fail inside a nested transaction so its savepoint is rolled back.",
     meta: {
       reason: "aborted",
-      outcome: "rolled-back",
+      outcome: "not-committed",
       ...causeCode === undefined ? {} : { causeCode },
       ...sqlstate === undefined ? {} : { sqlstate }
     },
     ...cause === undefined ? {} : { cause }
   });
 }
+var MAPPED_CAUSE = Symbol.for("vibeorm.adapter-kit.mapped-cause");
+function recordMappedCause(params) {
+  Object.defineProperty(params.raw, MAPPED_CAUSE, { value: params.mapped, enumerable: false, configurable: true, writable: false });
+}
+function mappedCauseOf(params) {
+  if (!(params.error instanceof Error))
+    return;
+  const mapped = params.error[MAPPED_CAUSE];
+  return mapped instanceof VibeError ? mapped : undefined;
+}
 function isTransactionAbortedError(error) {
   const reason = error?.meta?.reason;
   return reason === "aborted";
@@ -154,16 +170,50 @@ async function waitForTurn(params) {
     await open.settled;
   }
 }
+var ADMISSIONS = new WeakMap;
 async function acquire(params) {
   const { scope } = params;
-  for (;; ) {
-    assertNotPoisoned({ state: scope.state });
-    assertNotAborted({ state: scope.state });
-    const open = scope.state.open;
-    if (mayProceed({ scope, open }))
-      return pushNode({ scope, parent: open });
-    await open.settled;
+  assertNotPoisoned({ state: scope.state });
+  assertNotAborted({ state: scope.state });
+  const open = scope.state.open;
+  if (mayProceed({ scope, open }))
+    return pushNode({ scope, parent: open });
+  let blocker = open;
+  while (blocker.parent !== null && !mayProceed({ scope, open: blocker.parent })) {
+    blocker = blocker.parent;
+  }
+  return new Promise((resolve, reject) => {
+    const waiter = { scope, resolve, reject, next: null };
+    const queue = ADMISSIONS.get(blocker);
+    if (queue === undefined)
+      ADMISSIONS.set(blocker, { head: waiter, tail: waiter });
+    else {
+      queue.tail.next = waiter;
+      queue.tail = waiter;
+    }
+  });
+}
+function handOffAdmissions(params) {
+  const queue = ADMISSIONS.get(params.node);
+  if (queue === undefined)
+    return;
+  ADMISSIONS.delete(params.node);
+  const state = params.node.scope.state;
+  const refusal = state.poisoned ?? (state.aborted === null ? null : transactionAbortedError({ cause: state.aborted.cause }));
+  if (refusal !== null) {
+    let waiter = queue.head;
+    while (waiter !== null) {
+      waiter.reject(refusal);
+      waiter = waiter.next;
+    }
+    return;
   }
+  const first = queue.head;
+  const successor = pushNode({ scope: first.scope, parent: state.open });
+  if (first.next !== null)
+    ADMISSIONS.set(successor, { head: first.next, tail: queue.tail });
+  first.next = null;
+  first.resolve(successor);
 }
 function pushNode(params) {
   const { scope, parent } = params;
@@ -191,6 +241,7 @@ function closeNode(params) {
   if (state.open === node)
     state.open = node.parent;
   node.settle();
+  handOffAdmissions({ node });
 }
 async function drainDescendants(params) {
   const state = params.node.scope.state;
@@ -214,6 +265,8 @@ function refuseNestedTransactionOptions(params) {
     passed.push("timeout");
   if (options.deadline !== undefined)
     passed.push("deadline");
+  if (options.accessMode !== undefined)
+    passed.push("accessMode");
   if (passed.length === 0)
     return;
   const meta = { provider, nested: true };
@@ -223,12 +276,76 @@ function refuseNestedTransactionOptions(params) {
     meta.timeout = options.timeout;
   if (options.deadline !== undefined)
     meta.deadline = options.deadline;
+  if (options.accessMode !== undefined)
+    meta.accessMode = options.accessMode;
   throw new VibeError2({
     code: "VIBE_VALIDATION",
     message: `nested transactions run as savepoints and cannot honor ${passed.join(" or ")} \u2014 a savepoint cannot change the isolation level of the transaction it joins, a nested timeout is not enforceable, and a nested deadline would need its own session setting on a connection it does not own (it inherits the top-level one instead); pass options on the top-level $transaction`,
     meta
   });
 }
+function readOnlyRequested(params) {
+  const accessMode = params.options?.accessMode;
+  if (accessMode === undefined)
+    return false;
+  if (accessMode === "readOnly")
+    return true;
+  throw new VibeError2({
+    code: "VIBE_VALIDATION",
+    message: `transaction accessMode must be "readOnly" or omitted, received ${JSON.stringify(accessMode) ?? String(accessMode)}`,
+    meta: { provider: params.provider, accessMode }
+  });
+}
+// packages/runtime/src/adapter-kit/deferred-control.ts
+var SAVEPOINT_TEXT = /^SAVEPOINT (\S+)$/;
+var RELEASE_TEXT = /^RELEASE SAVEPOINT (\S+)$/;
+var ROLLBACK_TO_TEXT = /^ROLLBACK TO SAVEPOINT (\S+)$/;
+function createDeferredControl(params) {
+  let pending = [...params.opening];
+  let opened = params.opening.length === 0;
+  const elided = new Set;
+  const dropFrom = (name) => {
+    const index = pending.indexOf(`SAVEPOINT ${name}`);
+    if (index === -1)
+      return false;
+    pending = pending.slice(0, index);
+    return true;
+  };
+  return {
+    opened: () => opened,
+    hasPending: () => pending.length > 0,
+    take: () => {
+      const taken = pending;
+      pending = [];
+      if (taken.length > 0)
+        opened = true;
+      return taken;
+    },
+    routeSavepoint: ({ text }) => {
+      const savepoint = SAVEPOINT_TEXT.exec(text);
+      if (savepoint !== null) {
+        pending.push(text);
+        return "deferred";
+      }
+      const release = RELEASE_TEXT.exec(text);
+      if (release !== null) {
+        const name = release[1];
+        if (elided.delete(name))
+          return "elided";
+        return dropFrom(name) ? "elided" : "send";
+      }
+      const rollbackTo = ROLLBACK_TO_TEXT.exec(text);
+      if (rollbackTo !== null) {
+        const name = rollbackTo[1];
+        if (!dropFrom(name))
+          return "send";
+        elided.add(name);
+        return "elided";
+      }
+      return "send";
+    }
+  };
+}
 // packages/runtime/src/adapter-kit/transaction-budget.ts
 import { VibeError as VibeError3 } from "@vibeorm/schema";
 var DEFAULT_DEADLINE_CLOCK = () => Date.now();
@@ -313,7 +430,7 @@ function engineStatementBudgetMs(params) {
 }
 function transactionDeadlineError(params) {
   const { provider, stage, totalMs, overdueMs } = params;
-  const what = stage === "commit" ? "the transaction was rolled back instead of committed" : "the statement was never sent and the transaction is being rolled back";
+  const what = stage === "commit" ? "COMMIT was never sent, so the transaction did not commit" : "the statement was never sent, and the transaction will not commit";
   return new VibeError3({
     code: "VIBE_TRANSACTION",
     message: `transaction deadline of ${totalMs} ms expired ${Math.max(0, Math.round(overdueMs))} ms ago \u2014 ${what}. ` + "Nothing is retried automatically: work the callback did outside the database may already have happened.",
@@ -332,13 +449,13 @@ function transactionOutcomeUnknownError(params) {
   const { provider, totalMs, cause } = params;
   return new VibeError3({
     code: "VIBE_TRANSACTION",
-    message: `transaction deadline of ${totalMs} ms expired and the rollback that should have cleaned up failed \u2014 ` + "the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data " + "before deciding.",
+    message: `transaction deadline of ${totalMs} ms expired while COMMIT was in flight and the client stopped waiting for its answer \u2014 ` + "the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data " + "before deciding.",
     meta: {
       provider,
       reason: "transaction-outcome-unknown",
       outcome: "unknown",
-      totalMs,
-      rollbackFailed: true
+      stage: "commit",
+      totalMs
     },
     cause
   });
@@ -347,15 +464,87 @@ function isTransactionDeadlineError(error) {
   const reason = error?.meta?.reason;
   return reason === "transaction-deadline";
 }
+// packages/runtime/src/adapter-kit/transaction-outcome.ts
+var REPORT_VERSION = 1;
+var REGISTRY_KEY = Symbol.for("vibeorm.adapter-kit.transaction-outcome");
+function sharedRegistry() {
+  const existing = globalThis[REGISTRY_KEY];
+  if (existing instanceof WeakMap)
+    return existing;
+  const created = new WeakMap;
+  if (!Object.isExtensible(globalThis))
+    return created;
+  Object.defineProperty(globalThis, REGISTRY_KEY, { value: created, enumerable: false, configurable: false, writable: false });
+  return created;
+}
+var REPORTS = sharedRegistry();
+function isReportable(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+function recordTransactionOutcome(params) {
+  const { error, report } = params;
+  if (!isReportable(error))
+    return;
+  REPORTS.set(error, Object.freeze({ version: REPORT_VERSION, report: Object.freeze({ ...report }) }));
+}
+function transactionOutcomeOf(params) {
+  const { error } = params;
+  if (!isReportable(error))
+    return;
+  const stored = REPORTS.get(error);
+  return stored?.version === REPORT_VERSION ? stored.report : undefined;
+}
+function failedCommitOutcome(params) {
+  const { commit, stateLost } = params;
+  if (commit === "sent" || commit === "unanswered")
+    return "unknown";
+  return stateLost ? "unknown" : "not-committed";
+}
+function closeFailedTransactionBudget(params) {
+  const { error, budget, scope, commit } = params;
+  const stateLost = isSavepointRollbackFailedError(error) || isSavepointRollbackFailedError(scope.state.poisoned);
+  const outcome = failedCommitOutcome({ commit, stateLost });
+  budget.close({ outcome });
+  return outcome;
+}
+function settleFailedTransaction(params) {
+  const { error, provider, budget, scope, commit, rollback, connection } = params;
+  const outcome = closeFailedTransactionBudget({ error, budget, scope, commit });
+  const abandoned = commit === "unanswered" && budget.totalMs !== null && isTransactionDeadlineError(error);
+  const thrown = abandoned ? transactionOutcomeUnknownError({ provider, totalMs: budget.totalMs, cause: error }) : error;
+  recordTransactionOutcome({
+    error: thrown,
+    report: { commit: outcome, commitSent: commit !== "not-sent", rollback, connection }
+  });
+  return thrown;
+}
 // packages/runtime/src/adapter-kit/row-changes.ts
 function statementRowChanges(params) {
-  const { effect, count } = params;
+  const { effect } = params;
   if (effect === "read")
     return 0;
-  if (effect !== "write")
+  if (effect === "writeTally")
+    return tallyOf({ rows: params.resultRows });
+  const count = effect === "write" ? params.count : effect === "writeRows" ? params.rows : undefined;
+  if (effect !== "write" && effect !== "writeRows")
     return "unknown";
   return typeof count === "number" && Number.isSafeInteger(count) && count >= 0 ? count : "unknown";
 }
+var ROW_CHANGES_COLUMN = "__vibe_row_changes";
+function tallyOf(params) {
+  const { rows } = params;
+  if (rows === undefined || rows.length === 0)
+    return "unknown";
+  let total = 0;
+  for (const row of rows) {
+    const value = row[ROW_CHANGES_COLUMN];
+    const count = typeof value === "number" ? value : typeof value === "bigint" ? Number(value) : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    if (!Number.isSafeInteger(count) || count < 0)
+      return "unknown";
+    total += count;
+  }
+  return Number.isSafeInteger(total) ? total : "unknown";
+}
 function observeRowChanges(params) {
   const state = params.scope.state;
   if (state.rowChanges === "unknown")
@@ -369,7 +558,7 @@ function observeRowChanges(params) {
 }
 function dispatchSynchronousRowChanges(params) {
   const { scope } = params;
-  if (scope === undefined)
+  if (scope === undefined || scope.state.rowChanges === "unknown")
     return params.run();
   const before = scope.state.rowChanges;
   if (params.effect !== "read")
@@ -448,12 +637,105 @@ function withCleanupCause(params) {
   }
   return cause;
 }
-// packages/runtime/src/adapter-kit/sqlite-session.ts
+// packages/runtime/src/adapter-kit/adapter-lifecycle.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 import { VibeError as VibeError5 } from "@vibeorm/schema";
+function adapterClosedError(params) {
+  const { driver, state } = params;
+  return new VibeError5({
+    code: "VIBE_ADAPTER_CLOSED",
+    message: `This ${driver} adapter was disconnected${state === "closing" ? " and is closing" : ""}; it accepts no new work. Create a new adapter to connect again.`,
+    meta: { driver, state }
+  });
+}
+function disconnectInActiveCallbackError(params) {
+  return new VibeError5({
+    code: "VIBE_TRANSACTION",
+    message: "disconnect() was called from inside this adapter's own running transaction or session callback; it would wait for that callback to finish. Return from the callback first, then disconnect.",
+    meta: { reason: "disconnect-in-active-callback", driver: params.driver }
+  });
+}
+function transactionLifecycleRefusal(params) {
+  const { method } = params;
+  return new VibeError5({
+    code: "VIBE_VALIDATION",
+    message: `${method}() is not available on a transaction client \u2014 the connection is owned by the open transaction; call it on the client that started the transaction`,
+    meta: { method, inTransaction: true }
+  });
+}
+function createAdapterLifecycleGate(params) {
+  const { driver, cleanup, isConnectionReentrant } = params;
+  const callbacks = new AsyncLocalStorage2;
+  let state = "open";
+  let active = 0;
+  let drained = null;
+  let completion = null;
+  const settleOne = () => {
+    active -= 1;
+    if (active === 0 && drained !== null) {
+      const resolve = drained;
+      drained = null;
+      resolve();
+    }
+  };
+  return {
+    admit(admitParams) {
+      if (state !== "open")
+        return Promise.reject(adapterClosedError({ driver, state }));
+      active += 1;
+      const result = new Promise((resolve) => {
+        resolve(admitParams.run());
+      });
+      result.then(settleOne, settleOne);
+      return result;
+    },
+    inCallback(callbackParams) {
+      const token = { active: true };
+      return callbacks.run(token, () => new Promise((resolve) => {
+        resolve(callbackParams.run());
+      })).finally(() => {
+        token.active = false;
+      });
+    },
+    disconnect() {
+      if (callbacks.getStore()?.active === true || isConnectionReentrant?.() === true) {
+        return Promise.reject(disconnectInActiveCallbackError({ driver }));
+      }
+      if (completion !== null)
+        return completion;
+      state = "closing";
+      const drain = active === 0 ? Promise.resolve() : new Promise((resolve) => {
+        drained = resolve;
+      });
+      completion = drain.then(() => cleanup()).then(() => {
+        state = "closed";
+      }, (error) => {
+        state = "closed";
+        throw error;
+      });
+      return completion;
+    }
+  };
+}
+function runShutdownCleanup(params) {
+  let failure;
+  let chain = Promise.resolve();
+  for (const step of params.steps) {
+    chain = chain.then(step).then(undefined, (error) => {
+      failure = failure === undefined ? { error } : { error: withCleanupCause({ cause: failure.error, cleanupCause: error }) };
+    });
+  }
+  return chain.then(() => {
+    if (failure !== undefined)
+      throw failure.error;
+  });
+}
+// packages/runtime/src/adapter-kit/sqlite-session.ts
+import { VibeError as VibeError6 } from "@vibeorm/schema";
 import { SQLITE_SESSION_SQL } from "@vibeorm/sql";
 async function runSqliteSession(params) {
   if (params.inTransaction())
-    throw new VibeError5({
+    throw new VibeError6({
       code: "VIBE_TRANSACTION",
       message: "A migration session cannot borrow a SQLite connection with an open transaction.",
       meta: { reason: "session-in-transaction" }
@@ -461,7 +743,7 @@ async function runSqliteSession(params) {
   const rows = await params.execute({ text: SQLITE_SESSION_SQL.lockingMode, values: [] });
   const mode = rows[0]?.locking_mode;
   if (mode !== "normal" && mode !== "exclusive")
-    throw new VibeError5({
+    throw new VibeError6({
       code: "VIBE_ADAPTER",
       message: "SQLite did not report its locking mode; no migration was started.",
       meta: { reason: "session-lock-mode" }
@@ -500,11 +782,16 @@ async function runSqliteSession(params) {
 }
 export {
   DEFAULT_DEADLINE_CLOCK,
+  ROW_CHANGES_COLUMN,
   abortTransactionOnServerFailure,
+  closeFailedTransactionBudget,
+  createAdapterLifecycleGate,
+  createDeferredControl,
   createSavepointCounter,
   createSavepointScope,
   dispatchSynchronousRowChanges,
   engineStatementBudgetMs,
+  failedCommitOutcome,
   isSavepointRollbackFailedError,
   isTransactionAbortedError,
   isTransactionDeadlineError,
@@ -512,21 +799,27 @@ export {
   markTransactionAborted,
   nextSavepointName,
   observeRowChanges,
+  readOnlyRequested,
   readRowChanges,
+  recordTransactionOutcome,
   refuseNestedTransactionOptions,
   runNestedSavepoint,
   runPinnedSession,
   runRootScope,
+  runShutdownCleanup,
   runSqliteSession,
   savepointRollbackFailedError,
   scopeTurn,
+  settleFailedTransaction,
   startTransactionBudget,
   statementRowChanges,
   transactionAbortedError,
   transactionClosedError,
   transactionDeadlineError,
+  transactionLifecycleRefusal,
+  transactionOutcomeOf,
   transactionOutcomeUnknownError,
   validateTransactionDeadline
 };
 
-//# debugId=9043FC0FD9D8EA9E64756E2164756E21
+//# debugId=DA2DF3165F53603864756E2164756E21