sqlstack 3.5.0 → 3.6.0-dev.1

package/dist/esm/transactions.js

@@ -86,6 +86,8 @@ class TxState {
         this.started = false;
         this.completed = false;
         this.rollbackOnly = false;
+        /** SQLite opening statement: name-based transactions keep plain BEGIN. */
+        this.sqliteBegin = 'BEGIN';
         this.entry = entry;
         this.db = entry.db;
         this.options = {
@@ -131,7 +133,7 @@ class TxState {
             return;
         }
         // sqlite: existing connection is already bound
-        await this.db.query('BEGIN', []);
+        await this.db.query(this.sqliteBegin, []);
         this.started = true;
     }
     async query(sql, params) {
@@ -166,6 +168,9 @@ class TxState {
         finally {
             this.txDb = undefined;
             this.releaseFn = undefined;
+            const onRelease = this.onRelease;
+            this.onRelease = undefined;
+            onRelease?.();
         }
     }
     async finishOnSuccess() {
@@ -265,7 +270,533 @@ export async function withTransaction(fn, options) {
     };
     return isNewStore ? await als.run(store, run) : await run();
 }
-export const transaction = function (...args) {
+// ---------------------------------------------------------------------------
+// Scope-based @transaction (docs/transactions.md)
+// ---------------------------------------------------------------------------
+/**
+ * One @transaction method invocation. The root scope (no parent) owns every
+ * transaction opened in the flow and commits/rolls them back at its exit; a
+ * nested scope is a piece of its parent, delimited by savepoints.
+ */
+class TxScope {
+    constructor(parent) {
+        this.closed = false;
+        this.markAll = false;
+        this.marked = new Set();
+        this.afterCommit = [];
+        this.afterSettled = [];
+        /** Nested scopes: the savepoint this scope holds on each open transaction. */
+        this.savepoints = [];
+        // Root-only bookkeeping.
+        /** Transactions opened in this flow, in open order (root commits them). */
+        this.opened = [];
+        this.opening = new Map();
+        /** Databases this root has opened (multi_database event), with their reported names. */
+        this.seen = [];
+        this.savepointSeq = 0;
+        /** Siblings share one savepoint stack; descendants queue on their own parent. */
+        this.childTail = Promise.resolve();
+        this.parent = parent;
+        this.root = parent ? parent.root : this;
+        this.depth = parent ? parent.depth + 1 : 1;
+    }
+    get hasMarks() {
+        return this.markAll || this.marked.size > 0;
+    }
+    isMarked(state) {
+        return this.markAll || this.marked.has(state);
+    }
+    reserveChild() {
+        const ready = this.childTail;
+        let release;
+        this.childTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        return { ready, release };
+    }
+    async waitForChildren() {
+        let observed;
+        do {
+            observed = this.childTail;
+            await observed;
+        } while (observed !== this.childTail);
+    }
+}
+const eventListeners = new Set();
+/**
+ * Observe transaction trace events. Today the only event is
+ * `sqlstack.transaction.multi_database`, emitted once per root scope the
+ * moment it opens its second database. Returns an unsubscribe function.
+ * Listener errors are ignored so observation never affects a transaction.
+ */
+export function onTransactionEvent(listener) {
+    eventListeners.add(listener);
+    return () => {
+        eventListeners.delete(listener);
+    };
+}
+function emitTransactionEvent(event) {
+    for (const listener of [...eventListeners]) {
+        try {
+            listener(event);
+        }
+        catch {
+            // observation must never affect the transaction
+        }
+    }
+}
+/** Innermost scope of this flow that has not exited yet. */
+function activeScope(store) {
+    let scope = store?.scope;
+    while (scope && scope.closed)
+        scope = scope.parent;
+    return scope;
+}
+function requireScope(api) {
+    const scope = activeScope(getStore());
+    if (!scope) {
+        throw new SqlStackError(`transaction.${api}() called outside a @transaction method.`);
+    }
+    return scope;
+}
+// SQLite serialisation: one connection carries one transaction at a time, so
+// independent flows opening a scope transaction on the same connection wait
+// for the previous holder to release instead of failing with "cannot start a
+// transaction within a transaction". Keyed by the Database object (the
+// connection), which is the entry's database.
+const sqliteTails = new WeakMap();
+async function acquireSqliteTurn(db) {
+    const previous = sqliteTails.get(db) ?? Promise.resolve();
+    let release;
+    const mine = new Promise((resolve) => {
+        release = resolve;
+    });
+    sqliteTails.set(db, previous.then(() => mine));
+    await previous;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        release();
+    };
+}
+async function issueSavepoint(scope, state) {
+    const name = `sqlstack_sp_${scope.depth}_${++scope.root.savepointSeq}`;
+    await state.query(`SAVEPOINT ${name}`, []);
+    scope.savepoints.push({ state, name });
+}
+// A Database handle given to run(db, ...) that a @transaction scope opens a
+// transaction on gets one synthetic entry per handle object, so the scope's
+// TxState is keyed by the handle itself. Never registered anywhere; the name is
+// a label only (excluded from name matching in transaction.rollback(name)).
+const HANDLE_LABEL = 'handle';
+const handleEntries = new WeakMap();
+const syntheticEntries = new WeakSet();
+function handleEntryFor(db) {
+    let entry = handleEntries.get(db);
+    if (!entry) {
+        entry = { name: HANDLE_LABEL, db: db, owned: false, stack: undefined };
+        handleEntries.set(db, entry);
+        syntheticEntries.add(entry);
+    }
+    return entry;
+}
+function isHandleEntry(entry) {
+    return syntheticEntries.has(entry);
+}
+/**
+ * Whether a transaction keyed by `other` is the transaction `entry` must join:
+ * the same entry, or — when either side was opened through a handle — the
+ * same database object (identity). Two registered entries that merely share
+ * a Database are left as they were.
+ */
+function sameTransactionTarget(entry, other) {
+    if (entry === other)
+        return true;
+    return (isHandleEntry(entry) || isHandleEntry(other)) && entry.db === other.db;
+}
+function findOpenTransaction(store, entry) {
+    const direct = store.txByDb.get(entry);
+    if (direct)
+        return direct;
+    for (const [key, state] of store.txByDb) {
+        if (!state.completed && sameTransactionTarget(entry, key))
+            return state;
+    }
+    return undefined;
+}
+function findPendingOpen(root, entry) {
+    const direct = root.opening.get(entry);
+    if (direct)
+        return direct;
+    for (const [key, pending] of root.opening) {
+        if (sameTransactionTarget(entry, key))
+            return pending;
+    }
+    return undefined;
+}
+/** Name reported for `entry` in the multi_database event. */
+function reportedName(store, entry) {
+    if (!isHandleEntry(entry))
+        return entry.name;
+    // A handle that is the database of a registered entry this flow knows uses that name.
+    for (const key of store.txByDb.keys()) {
+        if (!isHandleEntry(key) && key.db === entry.db)
+            return key.name;
+    }
+    return HANDLE_LABEL;
+}
+async function openScopedTransaction(store, scope, entry) {
+    const existing = findOpenTransaction(store, entry);
+    if (existing)
+        return existing;
+    const root = scope.root;
+    const pending = findPendingOpen(root, entry);
+    if (pending)
+        return await pending;
+    const open = (async () => {
+        const state = new TxState(entry, undefined);
+        state.sqliteBegin = 'BEGIN IMMEDIATE';
+        const dialect = entry.db.dialect ?? 'sqlite';
+        // A flow that already holds this connection must not wait on itself.
+        const holdsConnection = root.opened.some((s) => s.db === entry.db && !s.completed);
+        if (dialect === 'sqlite' && !holdsConnection) {
+            state.onRelease = await acquireSqliteTurn(entry.db);
+        }
+        try {
+            await state.ensureStarted();
+        }
+        catch (err) {
+            await state.release();
+            throw err;
+        }
+        store.txByDb.set(entry, state);
+        root.opened.push(state);
+        if (!root.seen.some((s) => sameTransactionTarget(entry, s.entry))) {
+            root.seen.push({ entry, name: reportedName(store, entry) });
+            if (root.seen.length === 2) {
+                emitTransactionEvent({
+                    type: 'sqlstack.transaction.multi_database',
+                    databases: root.seen.map((s) => s.name),
+                });
+            }
+        }
+        // First opened inside a nested scope: every enclosing nested scope gets
+        // its savepoint right after BEGIN, outermost first.
+        const chain = [];
+        for (let s = scope; s && s.parent; s = s.parent)
+            chain.unshift(s);
+        for (const s of chain)
+            await issueSavepoint(s, state);
+        return state;
+    })();
+    root.opening.set(entry, open);
+    try {
+        return await open;
+    }
+    finally {
+        root.opening.delete(entry);
+    }
+}
+/**
+ * @internal The transaction a query on `entry` runs in: the one already open
+ * in this flow (including one a handle of the same database opened), or —
+ * while a @transaction scope is active — one opened on that entry by the
+ * query itself (on first execution, not on resolution). Undefined means "run
+ * on the database directly".
+ */
+export function getTransactionTarget(entry) {
+    const store = getStore();
+    const open = store ? findOpenTransaction(store, entry) : undefined;
+    if (open)
+        return open;
+    const scope = activeScope(store);
+    if (!store || !scope)
+        return undefined;
+    return {
+        async query(sql, params) {
+            if (scope.root.closed)
+                return await entry.db.query(sql, params);
+            const state = await openScopedTransaction(store, scope, entry);
+            return await state.query(sql, params);
+        },
+    };
+}
+/**
+ * @internal The transaction a query on a Database handle (run(db, ...)) runs
+ * in. A transaction already open in this flow on that exact object is joined
+ * (identity; registered or handle-opened). Inside a @transaction scope with
+ * none open, the query opens one on the handle on first execution, exactly as
+ * the name-resolved path does. Outside any scope the behaviour is unchanged:
+ * join by identity or run directly (undefined).
+ */
+export function getTransactionTargetForHandle(db) {
+    const store = getStore();
+    if (!store)
+        return undefined;
+    for (const state of store.txByDb.values()) {
+        if (state.db === db)
+            return state;
+    }
+    const scope = activeScope(store);
+    if (!scope)
+        return undefined;
+    return {
+        async query(sql, params) {
+            if (scope.root.closed)
+                return (await db.query(sql, params));
+            const state = await openScopedTransaction(store, scope, handleEntryFor(db));
+            return await state.query(sql, params);
+        },
+    };
+}
+function dropFromStore(store, state) {
+    if (store.txByDb.get(state.entry) === state)
+        store.txByDb.delete(state.entry);
+}
+async function runHooks(hooks) {
+    let failed = false;
+    let error;
+    for (const hook of hooks) {
+        try {
+            // Outside every scope: a hook that is itself @transaction opens a fresh one.
+            await als.exit(() => hook());
+        }
+        catch (err) {
+            if (!failed) {
+                failed = true;
+                error = err;
+            }
+        }
+    }
+    return { failed, error };
+}
+/** Roll back and release every transaction the root owns. Returns the first failure. */
+async function rollbackOwned(root, store) {
+    let failed = false;
+    let error;
+    for (const state of root.opened) {
+        try {
+            await state.rollbackIfStarted();
+        }
+        catch (err) {
+            if (!failed) {
+                failed = true;
+                error = err;
+            }
+        }
+        finally {
+            try {
+                await state.release();
+            }
+            catch (err) {
+                if (!failed) {
+                    failed = true;
+                    error = err;
+                }
+            }
+            dropFromStore(store, state);
+        }
+    }
+    root.opened.length = 0;
+    return { failed, error };
+}
+async function exitRootOnSuccess(root, store) {
+    // Name-based API compatibility: currentTransaction()?.rollbackOnly(err)
+    // rolls everything back and throws, exactly as it does for withTransaction.
+    const legacyMarked = root.opened.find((s) => s.rollbackOnly);
+    if (legacyMarked) {
+        const err = typeof legacyMarked.rollbackError !== 'undefined' ? legacyMarked.rollbackError : new RollbackTransactionError();
+        await rollbackOwned(root, store);
+        await runHooks(root.afterSettled);
+        throw err;
+    }
+    let failed = false;
+    let error;
+    for (const state of root.opened) {
+        try {
+            if (failed || root.isMarked(state))
+                await state.rollbackIfStarted();
+            else
+                await state.commitIfStarted();
+        }
+        catch (err) {
+            if (!failed) {
+                failed = true;
+                error = err;
+            }
+        }
+        finally {
+            try {
+                await state.release();
+            }
+            catch (err) {
+                if (!failed) {
+                    failed = true;
+                    error = err;
+                }
+            }
+            dropFromStore(store, state);
+        }
+    }
+    root.opened.length = 0;
+    const commitHooks = !failed && !root.hasMarks ? await runHooks(root.afterCommit) : { failed: false, error: undefined };
+    const settledHooks = await runHooks(root.afterSettled);
+    if (failed)
+        throw error;
+    if (commitHooks.failed)
+        throw commitHooks.error;
+    if (settledHooks.failed)
+        throw settledHooks.error;
+}
+async function exitRootOnError(root, store) {
+    await rollbackOwned(root, store);
+    await runHooks(root.afterSettled);
+}
+async function exitNestedOnSuccess(scope) {
+    const parent = scope.parent;
+    try {
+        for (const { state, name } of scope.savepoints) {
+            if (state.completed)
+                continue;
+            if (scope.isMarked(state))
+                await state.query(`ROLLBACK TO SAVEPOINT ${name}`, []);
+            await state.query(`RELEASE SAVEPOINT ${name}`, []);
+        }
+        if (!scope.hasMarks)
+            parent.afterCommit.push(...scope.afterCommit);
+    }
+    finally {
+        parent.afterSettled.push(...scope.afterSettled);
+    }
+}
+async function exitNestedOnError(scope) {
+    for (const { state, name } of scope.savepoints) {
+        if (state.completed)
+            continue;
+        try {
+            await state.query(`ROLLBACK TO SAVEPOINT ${name}`, []);
+            await state.query(`RELEASE SAVEPOINT ${name}`, []);
+        }
+        catch {
+            // the original error wins; the root rolls back everything if it propagates
+        }
+    }
+    scope.parent.afterSettled.push(...scope.afterSettled);
+}
+async function runInScope(fn) {
+    const outer = getStore();
+    const parent = activeScope(outer);
+    const scope = new TxScope(parent);
+    const store = { txByDb: outer?.txByDb ?? new Map(), scope };
+    // Reserve synchronously, before yielding: a parent must see even queued children.
+    const turn = parent?.reserveChild();
+    try {
+        if (turn)
+            await turn.ready;
+        return await als.run(store, async () => {
+            let out;
+            try {
+                if (parent) {
+                    // Siblings enter one at a time, so releasing one cannot erase another's savepoint.
+                    for (const state of scope.root.opened) {
+                        if (!state.completed)
+                            await issueSavepoint(scope, state);
+                    }
+                }
+                out = await fn();
+            }
+            catch (err) {
+                // Promise.all may reject while another child is still writing. Keep this
+                // scope active until those children settle, then roll back their work too.
+                await scope.waitForChildren();
+                scope.closed = true;
+                if (parent) {
+                    await exitNestedOnError(scope);
+                    throw err;
+                }
+                await exitRootOnError(scope, store);
+                throw isRollbackTransactionError(err) ? unwrapRollbackCause(err) : err;
+            }
+            await scope.waitForChildren();
+            scope.closed = true;
+            if (parent)
+                await exitNestedOnSuccess(scope);
+            else
+                await exitRootOnSuccess(scope, store);
+            return out;
+        });
+    }
+    finally {
+        // Release only after savepoint cleanup and descendants, on success or failure.
+        turn?.release();
+    }
+}
+function matchOpenTransaction(scope, target) {
+    const open = scope.root.opened.filter((s) => !s.completed);
+    const state = typeof target === 'string'
+        ? open.find((s) => !isHandleEntry(s.entry) && s.entry.name === target)
+        : open.find((s) => s.db === target);
+    if (!state) {
+        throw new SqlStackError(typeof target === 'string'
+            ? `transaction.rollback("${target}"): no transaction is open on a database named "${target}" in this scope.`
+            : 'transaction.rollback(db): no transaction is open on that database handle in this scope.');
+    }
+    return state;
+}
+/**
+ * Mark the innermost @transaction scope for rollback. Synchronous and
+ * non-throwing for the method: SQL after it still runs inside the open
+ * transaction; at scope exit the scope rolls back instead of committing and
+ * the method's return value still reaches the caller. With a target (a
+ * registered database name or a Database handle), only that database's open
+ * transaction is marked.
+ */
+function markRollback(target) {
+    const scope = requireScope('rollback');
+    if (typeof target === 'undefined') {
+        scope.markAll = true;
+        return;
+    }
+    scope.marked.add(matchOpenTransaction(scope, target));
+}
+/**
+ * Roll back everything the innermost scope has done so far, now. The root
+ * scope rolls back and releases its transactions (the next query opens fresh
+ * ones); a nested scope rolls back to its savepoints. Marks and the scope's
+ * pending afterCommit hooks are cleared; afterSettled hooks stay.
+ */
+async function restartScope() {
+    const scope = requireScope('restart');
+    const store = getStore();
+    if (scope.parent) {
+        for (const { state, name } of scope.savepoints) {
+            if (state.completed)
+                continue;
+            await state.query(`ROLLBACK TO SAVEPOINT ${name}`, []);
+        }
+    }
+    else {
+        const result = await rollbackOwned(scope, store);
+        if (result.failed)
+            throw result.error;
+    }
+    scope.markAll = false;
+    scope.marked.clear();
+    scope.afterCommit = [];
+}
+function registerAfterCommit(fn) {
+    if (typeof fn !== 'function')
+        throw new SqlStackError('transaction.afterCommit(fn) requires a function.');
+    requireScope('afterCommit').afterCommit.push(fn);
+}
+function registerAfterSettled(fn) {
+    if (typeof fn !== 'function')
+        throw new SqlStackError('transaction.afterSettled(fn) requires a function.');
+    requireScope('afterSettled').afterSettled.push(fn);
+}
+const transactionDecorator = function (...args) {
     // @transaction
     if (args.length === 3 && typeof args[2]?.value === 'function') {
         const [target, prop, desc] = args;
@@ -278,10 +809,30 @@ export const transaction = function (...args) {
         wrapMethod(target, prop, desc, options);
     };
 };
+export const transaction = Object.assign(transactionDecorator, {
+    rollback: markRollback,
+    restart: restartScope,
+    afterCommit: registerAfterCommit,
+    afterSettled: registerAfterSettled,
+});
+/**
+ * A name (`{ db }`) or an eager open (`lazy: false`) keeps the name-based
+ * behaviour of withTransaction. Everything else is a scope: no entry is
+ * resolved; queries open transactions on first touch.
+ */
+function isNameBased(options) {
+    return typeof options?.db !== 'undefined' || options?.lazy === false;
+}
 function wrapMethod(_target, _prop, desc, options) {
     const original = desc.value;
+    if (isNameBased(options)) {
+        desc.value = async function (...callArgs) {
+            return await withTransaction(() => original.apply(this, callArgs), options);
+        };
+        return;
+    }
     desc.value = async function (...callArgs) {
-        return await withTransaction(() => original.apply(this, callArgs), options);
+        return await runInScope(() => original.apply(this, callArgs));
     };
 }
 export function getActiveTransaction(entry) {