@nextlyhq/adapter-sqlite 0.0.2-alpha.66 → 0.0.2-alpha.68

package/README.md

@@ -81,11 +81,11 @@ Most users do not need this.
 
 ## Compatibility
 
-| Tool             | Version |
-| ---------------- | ------- |
-| Node.js          | 20+     |
-| `better-sqlite3` | 11+     |
-| `nextly`         | 0.0.x   |
+| Tool             | Version               |
+| ---------------- | --------------------- |
+| Node.js          | 20.19+, 22.12+ or 24+ |
+| `better-sqlite3` | 11+                   |
+| `nextly`         | 0.0.x                 |
 
 ## Documentation
 

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var async_hooks = require('async_hooks');
 var adapterDrizzle = require('@nextlyhq/adapter-drizzle');
 var types = require('@nextlyhq/adapter-drizzle/types');
 var versionCheck = require('@nextlyhq/adapter-drizzle/version-check');
@@ -89,6 +90,18 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
    * surface area without changing the achievable concurrency.
    */
   transactionQueue = Promise.resolve();
+  /**
+   * The transaction the current async chain is running inside, if any.
+   *
+   * A `transaction()` call made from INSIDE a transaction's work — a store
+   * writing on behalf of the caller, a plugin's write inside its own
+   * `ctx.db.transaction` — used to queue behind the very transaction that
+   * was waiting for it, and neither ever settled: that hung every later
+   * transaction on the instance too. Such a call now runs as a SAVEPOINT of
+   * the active transaction instead, so it commits or rolls back with it and
+   * its own failure undoes only its own part.
+   */
+  transactionScope = new async_hooks.AsyncLocalStorage();
   /**
    * Creates a new SQLite adapter instance.
    *
@@ -251,19 +264,190 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
    * @returns Result of the work function
    *
    * @remarks
-   * Uses better-sqlite3's native transaction handling which:
-   * - Automatically commits on success
-   * - Automatically rolls back on error
-   * - Converts nested transactions to savepoints
+   * The adapter manages the transaction itself, because better-sqlite3's
+   * `db.transaction()` does not take async work: it runs `BEGIN IMMEDIATE`,
+   * then `COMMIT` when `work` resolves or `ROLLBACK` when it throws.
+   * - Top-level calls run one at a time.
+   * - A call made inside an open transaction's work joins it as a savepoint
+   *   (`SAVEPOINT` / `RELEASE` / `ROLLBACK TO`).
+   * - Nested calls of one scope run one at a time.
+   * - A call made later from a savepoint that has already released joins the
+   *   innermost scope still open.
+   * - Nested work started and not awaited finishes before the enclosing scope
+   *   commits or rolls back.
    *
    * Note: SQLite uses DEFERRED, IMMEDIATE, or EXCLUSIVE transaction modes
-   * rather than isolation levels. This adapter uses IMMEDIATE by default.
+   * rather than isolation levels. This adapter uses IMMEDIATE.
    */
   async transaction(work, _options) {
+    const own = this.transactionScope.getStore();
+    const parent = this.nestingScope();
+    if (own && parent !== own) own.writesAfterClosing += 1;
+    if (parent) {
+      return enqueueIn(parent, () => this.runSavepoint(work, parent));
+    }
     const run = async () => this.runTransaction(work);
     const next = this.transactionQueue.then(run, run);
     this.transactionQueue = next.catch(() => void 0);
-    return next;
+    const { result, effects } = await next;
+    await this.runHeldEffects(effects);
+    return result;
+  }
+  /**
+   * Hold `effect` until the transaction enclosing this async context commits,
+   * or run it now when none does.
+   *
+   * The effect belongs to the scope this async context runs in, even one
+   * that has already released or rolled back: a service whose own
+   * transaction nested as a savepoint registers from its caller's scope once
+   * that savepoint has released, and the change is undoable for as long as
+   * any scope around it is. The outermost transaction runs the effect once
+   * its COMMIT succeeds, unless a scope between the effect's scope and the
+   * outermost transaction rolled back, and drops every effect on ROLLBACK or
+   * a failed COMMIT. A context whose outermost transaction has already
+   * finished is outside any transaction, so its effect runs now, unless what
+   * it announces was undone and it has run no transaction since.
+   */
+  async afterCommit(effect, onDeferredFailure) {
+    const scope = this.transactionScope.getStore();
+    if (!scope) {
+      await effect();
+      return;
+    }
+    const root = outermost(scope);
+    if (!root.finished) {
+      root.held.push({
+        effect: this.inRegisteringContext(effect),
+        onDeferredFailure,
+        scope,
+        writesBefore: scope.writesAfterClosing
+      });
+      return;
+    }
+    if (!undone(scope, scope.writesAfterClosing)) await effect();
+  }
+  /**
+   * `effect`, bound to the async context it is registered from.
+   *
+   * A held effect runs after the outermost COMMIT, from the code that ran the
+   * outermost transaction, so without this it sees that code's context rather
+   * than its own: whatever its caller pinned around the write is gone. That
+   * includes who is calling. A scope pinned for a scoped API key lost there
+   * leaves a hook's nested call judged by the key's owner instead of the key,
+   * and a person's frame lost there leaves the hook told of nobody.
+   *
+   * The adapter's own transaction scope is the one store it leaves: the
+   * effect runs once that transaction has finished, outside it, as an effect
+   * held to the outermost commit always has.
+   */
+  inRegisteringContext(effect) {
+    return async_hooks.AsyncResource.bind(() => this.transactionScope.exit(effect));
+  }
+  /**
+   * Run the effects a committed transaction held, in order. A failure is
+   * reported, never thrown: the change is durable, and reporting the
+   * transaction as failed would invite a retry of something already done.
+   */
+  async runHeldEffects(effects) {
+    for (const { effect, onDeferredFailure } of effects) {
+      try {
+        await effect();
+      } catch (error) {
+        this.reportHeldEffectFailure(error, onDeferredFailure);
+      }
+    }
+  }
+  /** Hand a held effect's failure to its reporter, or to the adapter's log. */
+  reportHeldEffectFailure(error, onDeferredFailure) {
+    try {
+      if (onDeferredFailure) {
+        onDeferredFailure(error);
+        return;
+      }
+    } catch {
+    }
+    const failure = error instanceof Error ? error : new Error(String(error));
+    if (this.config.logger?.error) {
+      this.config.logger.error(failure, { phase: "after-commit" });
+    } else {
+      console.error("An effect held until commit failed:", failure);
+    }
+  }
+  /**
+   * Whether a `transaction()` call made here would join an open transaction
+   * as a savepoint. On SQLite it would: the connection is the only one, so a
+   * transaction open on it encloses whatever the async chain that opened it
+   * starts.
+   */
+  inTransaction() {
+    return this.nestingScope() !== void 0;
+  }
+  /**
+   * Whether the calling async flow is inside a transaction that has not
+   * finished, judged from the transaction this flow was started inside,
+   * never from the connection: another request's open transaction answers
+   * false here, where its own `transaction()` queues behind that one.
+   *
+   * A flow started inside a transaction, even inside a savepoint that has
+   * since released, stays inside it until its outermost transaction has
+   * committed or rolled back: until then whatever it writes on the one
+   * connection lands in that transaction.
+   */
+  transactionOpenInFlow() {
+    const own = this.transactionScope.getStore();
+    return own !== void 0 && !outermost(own).finished;
+  }
+  /**
+   * The scope a `transaction()` call made here nests in, or none when it
+   * opens a transaction of its own.
+   *
+   * A call made later from inside a savepoint that has since released runs
+   * inside the innermost scope open on the connection. Queued on an enclosing
+   * scope, or on the instance, it would wait behind the scope running there,
+   * which may be the one awaiting it. Savepoints on one connection form a
+   * stack, so whatever opens now is inside that innermost scope anyway; when
+   * none is open the call queues on the instance.
+   *
+   * The innermost open scope need not be related to the call. When it is a
+   * sibling savepoint that later rolls back, the call's write rolls back with
+   * it, although the call itself already resolved. Waiting for an unrelated
+   * scope instead could wait on the very scope that awaits the call.
+   */
+  nestingScope() {
+    const own = this.transactionScope.getStore();
+    return own?.active ? own : own?.open.at(-1);
+  }
+  /**
+   * Run `work` as a savepoint of the active transaction: released when it
+   * resolves, rolled back to when it throws.
+   */
+  async runSavepoint(work, parent) {
+    const db = this.ensureDb();
+    const depth = parent.depth + 1;
+    const name = `nextly_sp_${depth}`;
+    try {
+      const ctx = this.createTransactionContext(db);
+      db.exec(`SAVEPOINT ${name}`);
+      const scope = openScope(parent);
+      try {
+        const result = await this.transactionScope.run(scope, () => work(ctx));
+        await settleNested(scope);
+        db.exec(`RELEASE ${name}`);
+        return result;
+      } catch (error) {
+        await settleNested(scope);
+        scope.rolledBack = true;
+        try {
+          db.exec(`ROLLBACK TO ${name}`);
+          db.exec(`RELEASE ${name}`);
+        } catch {
+        }
+        throw error;
+      }
+    } catch (error) {
+      if (types.isApplicationError(error)) throw error;
+      throw this.classifyError(error);
+    }
   }
   /**
    * Inner transaction body. Kept private so callers always go through
@@ -276,17 +460,29 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
     try {
       const ctx = this.createTransactionContext(db);
       db.exec("BEGIN IMMEDIATE");
+      const scope = openScope();
       try {
-        const result = await work(ctx);
+        const result = await this.transactionScope.run(scope, () => work(ctx));
+        await settleNested(scope);
         db.exec("COMMIT");
+        scope.finished = true;
         if (this.config.logger?.debug) {
           const durationMs = Date.now() - startTime;
           this.config.logger.debug("Transaction committed", {
             durationMs
           });
         }
-        return result;
+        return {
+          result,
+          effects: scope.held.filter(
+            (held) => !undone(held.scope, held.writesBefore)
+          )
+        };
       } catch (error) {
+        await settleNested(scope);
+        scope.rolledBack = true;
+        scope.finished = true;
+        scope.held.length = 0;
         try {
           db.exec("ROLLBACK");
         } catch {
@@ -439,10 +635,12 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
     ).primaryKeys.flatMap((key) => key.columns);
   }
   createTransactionContext(db) {
-    const buildTxExecutor = () => betterSqlite3.drizzle({ client: db });
-    let txExecutor;
-    const txDb = () => txExecutor ??= buildTxExecutor();
+    const txHandles = this.transactionDrizzleHandles(
+      (relations) => relations ? betterSqlite3.drizzle({ client: db, relations }) : betterSqlite3.drizzle({ client: db })
+    );
+    const txDb = txHandles.bare;
     return {
+      drizzleWithRelations: txHandles.withRelations,
       // SQLite has no row-level locking and needs none here: `withTransaction`
       // opens SQLite transactions with BEGIN IMMEDIATE, which takes the write
       // lock up front and serializes writers for the whole transaction.
@@ -579,7 +777,10 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
   // fallow-ignore-next-line complexity
   classifyError(error, sql) {
     if (types.isDatabaseError(error)) return error;
-    const sqliteError = findDriverError(error);
+    const sqliteError = this.driverErrorIn(
+      error,
+      (candidate) => typeof candidate.code === "string" && candidate.code !== ""
+    );
     let kind = "unknown";
     if (sqliteError.code) {
       kind = SQLITE_ERROR_CODES[sqliteError.code] || "unknown";
@@ -611,21 +812,50 @@ var SqliteAdapter = class extends adapterDrizzle.DrizzleAdapter {
     });
   }
 };
-function findDriverError(error) {
-  let cursor = error;
-  for (let depth = 0; depth < 10 && cursor != null; depth++) {
-    if (typeof cursor.code === "string" && cursor.code.length > 0)
-      return cursor;
-    cursor = cursor.cause;
-  }
-  return error ?? {};
-}
 function createSqliteAdapter(config) {
   return new SqliteAdapter(config);
 }
 function isSqliteAdapter(value) {
   return value instanceof SqliteAdapter;
 }
+function openScope(parent) {
+  const scope = {
+    active: true,
+    depth: parent ? parent.depth + 1 : 0,
+    parent,
+    rolledBack: false,
+    writesAfterClosing: 0,
+    finished: false,
+    held: [],
+    queue: Promise.resolve(),
+    open: parent ? parent.open : []
+  };
+  scope.open.push(scope);
+  return scope;
+}
+function outermost(scope) {
+  let at = scope;
+  while (at.parent) at = at.parent;
+  return at;
+}
+function undone(scope, writesBefore) {
+  if (writesBefore > 0) return false;
+  for (let at = scope; at; at = at.parent) {
+    if (at.rolledBack) return true;
+  }
+  return false;
+}
+function enqueueIn(scope, run) {
+  const next = scope.queue.then(run, run);
+  scope.queue = next.catch(() => void 0);
+  return next;
+}
+async function settleNested(scope) {
+  scope.active = false;
+  const index = scope.open.indexOf(scope);
+  if (index !== -1) scope.open.splice(index, 1);
+  await scope.queue;
+}
 
 exports.SqliteAdapter = SqliteAdapter;
 exports.VERSION = VERSION;