@warlock.js/cascade 5.19.0 → 5.20.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.20.0 - 2026-09-24
+
+### Added
+
+- `afterCommit(fn)` — run a side effect only once the transaction has committed. Inside a transaction, `fn` is queued and runs after the outermost COMMIT (in order, awaited one by one); it is discarded on rollback or a failed COMMIT. Outside a transaction, it runs on the next microtask. Errors are logged and never change the transaction result. Use it in model event listeners (`saved`, `created`, ...) for cache clears, sitemap regeneration and emails.
+
 ## 5.19.0 - 2026-09-23
 
 ### Changed

package/cjs/index.cjs

@@ -27,6 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 let _warlock_js_context = require("@warlock.js/context");
+let _warlock_js_logger = require("@warlock.js/logger");
 let node_events = require("node:events");
 let _mongez_reinforcements = require("@mongez/reinforcements");
 let _mongez_supportive_is = require("@mongez/supportive-is");
@@ -34,7 +35,6 @@ let _mongez_events = require("@mongez/events");
 _mongez_events = __toESM(_mongez_events, 1);
 let _warlock_js_seal = require("@warlock.js/seal");
 let _mongez_copper = require("@mongez/copper");
-let _warlock_js_logger = require("@warlock.js/logger");
 let fs = require("fs");
 fs = __toESM(fs, 1);
 let path = require("path");
@@ -98,6 +98,23 @@ var DatabaseTransactionContext = class extends _warlock_js_context.Context {
 		this.set("session", session);
 	}
 	/**
+	* Queue a callback to run once the active transaction commits
+	*/
+	addAfterCommit(fn) {
+		const queue = this.get("afterCommit") ?? [];
+		queue.push(fn);
+		this.set("afterCommit", queue);
+	}
+	/**
+	* Take (and empty) the queued after-commit callbacks.
+	* Must be called before `exit()`, which clears the store.
+	*/
+	takeAfterCommit() {
+		const queue = this.get("afterCommit") ?? [];
+		this.set("afterCommit", []);
+		return queue;
+	}
+	/**
 	* Exit the transaction context
 	*/
 	exit() {
@@ -113,6 +130,48 @@ var DatabaseTransactionContext = class extends _warlock_js_context.Context {
 const databaseTransactionContext = new DatabaseTransactionContext();
 _warlock_js_context.contextManager.register("db.transaction", databaseTransactionContext);
 
+//#endregion
+//#region ../cascade/src/transactions/after-commit.ts
+function reportFailure(error) {
+	_warlock_js_logger.log.error("database", "afterCommit", `[cascade] afterCommit callback failed: ${error}`);
+}
+/**
+* Run a callback only once the current transaction has COMMITTED.
+*
+* Model events (`saved`, `created`, `updated`, `deleted`) fire INSIDE the
+* transaction, before COMMIT. Anything that must observe committed data
+* (cache invalidation, sitemap regeneration, webhooks) belongs here.
+*
+* - Inside a transaction: queued, run after the outermost COMMIT, in order,
+*   awaited one by one. Discarded on rollback or a failed COMMIT.
+* - Outside a transaction: run on the next microtask (not awaited by the caller).
+* - A callback that throws is logged; it never affects the transaction result
+*   or the remaining callbacks.
+* - Callbacks run after the transaction context has exited, so any DB work
+*   they do is outside the finished transaction.
+*
+* @example
+* Product.events().onSaved(() => afterCommit(() => regenerateSitemap()));
+*/
+function afterCommit(fn) {
+	if (databaseTransactionContext.hasActiveTransaction()) {
+		databaseTransactionContext.addAfterCommit(fn);
+		return;
+	}
+	Promise.resolve().then(fn).catch(reportFailure);
+}
+/**
+* Run committed callbacks sequentially. Never throws.
+* Drivers call this after a successful COMMIT and after the context exited.
+*/
+async function flushAfterCommit(callbacks) {
+	for (const callback of callbacks) try {
+		await callback();
+	} catch (error) {
+		reportFailure(error);
+	}
+}
+
 //#endregion
 //#region ../cascade/src/data-source/data-source.ts
 /**
@@ -13979,15 +14038,18 @@ var MongoDbDriver = class {
 		await session.startTransaction(this.transactionOptions);
 		databaseTransactionContext.enter({ session });
 		let finished = false;
-		const finalize = async (operation) => {
+		const finalize = async (operation, committing = false) => {
 			if (finished) return;
+			let committedCallbacks = [];
 			try {
 				await operation();
+				if (committing) committedCallbacks = databaseTransactionContext.takeAfterCommit();
 			} finally {
 				finished = true;
 				databaseTransactionContext.exit();
 				await session.endSession().catch(() => void 0);
 			}
+			await flushAfterCommit(committedCallbacks);
 		};
 		return {
 			context: session,
@@ -13999,7 +14061,7 @@ var MongoDbDriver = class {
 						await session.abortTransaction().catch(() => void 0);
 						throw error;
 					}
-				});
+				}, true);
 			},
 			rollback: async () => {
 				await finalize(async () => {
@@ -14030,6 +14092,8 @@ var MongoDbDriver = class {
 		if (databaseTransactionContext.hasActiveTransaction()) return fn(ctx);
 		await this.ensureReplicaSetAvailable();
 		const session = this.getClientInstance().startSession();
+		let committedCallbacks = [];
+		let result;
 		try {
 			await session.startTransaction({
 				...this.transactionOptions,
@@ -14037,9 +14101,9 @@ var MongoDbDriver = class {
 			});
 			databaseTransactionContext.enter({ session });
 			try {
-				const result = await fn(ctx);
+				result = await fn(ctx);
 				await session.commitTransaction();
-				return result;
+				committedCallbacks = databaseTransactionContext.takeAfterCommit();
 			} catch (error) {
 				await session.abortTransaction().catch(() => void 0);
 				throw error;
@@ -14049,6 +14113,8 @@ var MongoDbDriver = class {
 		} finally {
 			await session.endSession().catch(() => void 0);
 		}
+		await flushAfterCommit(committedCallbacks);
+		return result;
 	}
 	/**
 	* Execute atomic operations (typically $inc/$set style updates) against documents.
@@ -18723,11 +18789,13 @@ var PostgresDriver = class {
 		const tx = await this.beginTransaction(options);
 		databaseTransactionContext.enter({ session: tx.context });
 		let commitStarted = false;
+		let committedCallbacks = [];
+		let result;
 		try {
-			const result = await fn(ctx);
+			result = await fn(ctx);
 			commitStarted = true;
 			await tx.commit();
-			return result;
+			committedCallbacks = databaseTransactionContext.takeAfterCommit();
 		} catch (error) {
 			if (commitStarted) _warlock_js_logger.log.error(`database.postgress`, "transaction", "Transaction COMMIT failed; client discarded, no rollback issued");
 			else try {
@@ -18740,6 +18808,8 @@ var PostgresDriver = class {
 		} finally {
 			databaseTransactionContext.exit();
 		}
+		await flushAfterCommit(committedCallbacks);
+		return result;
 	}
 	/**
 	* Perform an atomic update operation.
@@ -23758,6 +23828,7 @@ exports.UnsafeRawExpressionError = UnsafeRawExpressionError;
 exports.UnsupportedLeanOperationError = UnsupportedLeanOperationError;
 exports.UnsupportedQueryOperationError = UnsupportedQueryOperationError;
 exports.UnsupportedUpdateOperationError = UnsupportedUpdateOperationError;
+exports.afterCommit = afterCommit;
 exports.arrayBigInt = arrayBigInt;
 exports.arrayBoolean = arrayBoolean;
 exports.arrayDate = arrayDate;