@warlock.js/cascade 5.21.0 → 5.22.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.22.1 - 2026-09-25
+
+### Changed
+
+- Lockstep patch release; package APIs are unchanged.
+
+## 5.22.0 - 2026-09-25
+
+### Added
+
+- PostgreSQL TTL indexes register purge jobs and persist retention rules in index comments so jobs restore after reconnect.
+
+### Fixed
+
+- Post-commit sync fan-out retries transient failures without failing committed writes.
+
 ## 5.21.0 - 2026-09-25
 
 ### Added

package/cjs/index.cjs

@@ -35,6 +35,7 @@ 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_scheduler = require("@warlock.js/scheduler");
 let fs = require("fs");
 fs = __toESM(fs, 1);
 let path = require("path");
@@ -3500,6 +3501,69 @@ function getBooleanField(model, key, defaultValue) {
 	return getFieldValue(model, key, defaultValue);
 }
 
+//#endregion
+//#region ../cascade/src/sync/sync-fanout.ts
+/**
+* Serializes post-commit sync fan-out and retries transient failures without
+* making the already-committed write, delete, or restore fail.
+*/
+var SyncFanoutQueue = class {
+	jobs = [];
+	maxAttempts;
+	retryDelay;
+	reportFailure;
+	draining = false;
+	idleResolvers = [];
+	constructor(options = {}) {
+		this.maxAttempts = options.maxAttempts ?? 3;
+		this.retryDelay = options.retryDelay ?? ((attempt) => attempt * 50);
+		this.reportFailure = options.reportFailure ?? ((job, error) => {
+			_warlock_js_logger.log.error("database", "sync.failed", `[cascade] ${job.operation} sync failed for ${job.sourceModel} after ${this.maxAttempts} attempts: ${error}`);
+		});
+	}
+	/** Add a committed lifecycle fan-out job without awaiting its execution. */
+	enqueue(job) {
+		this.jobs.push(job);
+		if (!this.draining) {
+			this.draining = true;
+			this.drain();
+		}
+	}
+	/** Wait until the currently queued fan-out jobs have settled. */
+	async flush() {
+		if (!this.draining && this.jobs.length === 0) return;
+		await new Promise((resolve) => this.idleResolvers.push(resolve));
+	}
+	async drain() {
+		while (this.jobs.length > 0) {
+			const job = this.jobs.shift();
+			if (job) await this.execute(job);
+		}
+		this.draining = false;
+		this.idleResolvers.splice(0).forEach((resolve) => resolve());
+	}
+	async execute(job) {
+		let error;
+		for (let attempt = 1; attempt <= this.maxAttempts; attempt++) try {
+			await job.execute();
+			return;
+		} catch (caught) {
+			error = caught;
+			if (attempt < this.maxAttempts) await this.wait(this.retryDelay(attempt));
+		}
+		this.reportFailure(job, error);
+	}
+	async wait(milliseconds) {
+		if (milliseconds <= 0) return;
+		await new Promise((resolve) => setTimeout(resolve, milliseconds));
+	}
+};
+const syncFanoutQueue = new SyncFanoutQueue();
+/** Queue a lifecycle sync after its database change has committed. */
+function enqueueSyncFanout(job) {
+	syncFanoutQueue.enqueue(job);
+}
+
 //#endregion
 //#region ../cascade/src/remover/database-remover.ts
 /**
@@ -3675,12 +3739,12 @@ var DatabaseRemover = class {
 	*
 	* @private
 	*/
-	async triggerSync() {
-		try {
-			await triggerModelEvent(this.ctor, "deleted", this.model);
-		} catch (error) {
-			_warlock_js_logger.log.error("database", "sync.failed", `[cascade] sync failed for ${this.ctor.name}: ${error}`);
-		}
+	triggerSync() {
+		enqueueSyncFanout({
+			sourceModel: this.ctor.name,
+			operation: "delete",
+			execute: () => triggerModelEvent(this.ctor, "deleted", this.model)
+		});
 	}
 };
 
@@ -4749,12 +4813,12 @@ var DatabaseWriter = class {
 	* @param changedFields - Fields that were changed (for filtering)
 	* @private
 	*/
-	async triggerSync(changedFields) {
-		try {
-			await triggerModelEvent(this.ctor, "updated", this.model, changedFields);
-		} catch (error) {
-			_warlock_js_logger.log.error("database", "sync.failed", `[cascade] sync failed for ${this.ctor.name}: ${error}`);
-		}
+	triggerSync(changedFields) {
+		enqueueSyncFanout({
+			sourceModel: this.ctor.name,
+			operation: "update",
+			execute: () => triggerModelEvent(this.ctor, "updated", this.model, changedFields)
+		});
 	}
 };
 
@@ -5692,16 +5756,17 @@ var DatabaseRestorer = class {
 		return `${this.table}Trash`;
 	}
 	/**
-	* Re-run sync for a restored record so embedded copies come back up to date.
-	* Failures are swallowed: the restore itself already succeeded.
-	* TODO(5.22, K2:B10): move this fan-out to a retry/queue-backed path.
+	* Queue sync for a restored record so embedded copies come back up to date.
+	* The restore has already succeeded, so queued failures are retried separately.
 	*
 	* @private
 	*/
-	async triggerSync(model) {
-		try {
-			await triggerModelEvent(this.ctor, "updated", model, Object.keys(model.data));
-		} catch {}
+	triggerSync(model) {
+		enqueueSyncFanout({
+			sourceModel: this.ctor.name,
+			operation: "restore",
+			execute: () => triggerModelEvent(this.ctor, "updated", model, Object.keys(model.data))
+		});
 	}
 };
 
@@ -15478,6 +15543,100 @@ function convertPostgresValue(value, dataTypeID) {
 	return parseVector(value) ?? value;
 }
 
+//#endregion
+//#region ../cascade/src/drivers/postgres/postgres-ttl-purge.ts
+const TTL_PURGE_INTERVAL_MINUTES = 1;
+const TTL_COMMENT_PREFIX = "warlock_ttl:";
+let nextDriverId = 0;
+const driverIds = /* @__PURE__ */ new WeakMap();
+const driverJobs = /* @__PURE__ */ new WeakMap();
+function getDriverId(driver) {
+	let id = driverIds.get(driver);
+	if (id === void 0) {
+		id = nextDriverId++;
+		driverIds.set(driver, id);
+	}
+	return id;
+}
+/** Persist the retention rule with the index so a restarted process can restore its job. */
+function postgresTTLPurgeComment(table, column, expireAfterSeconds) {
+	return TTL_COMMENT_PREFIX + JSON.stringify({
+		table,
+		column,
+		expireAfterSeconds
+	});
+}
+/**
+* Return the scheduler job name for one PostgreSQL TTL index.
+*
+* The driver id prevents two data sources with identically named tables from
+* replacing each other's purge jobs on the shared scheduler singleton.
+*/
+function postgresTTLPurgeJobName(driver, table, column) {
+	return `cascade:postgres:${getDriverId(driver)}:ttl:${table}:${column}`;
+}
+/**
+* Delete rows which have outlived a PostgreSQL TTL index's retention period.
+*
+* Identifiers are produced by the dialect, while the retention interval stays
+* parameterized so a migration value can never become executable SQL.
+*/
+async function purgeExpiredPostgresRows(driver, table, column, expireAfterSeconds) {
+	const quotedTable = driver.dialect.quoteIdentifier(table);
+	const quotedColumn = driver.dialect.quoteIdentifier(column);
+	await driver.query(`DELETE FROM ${quotedTable} WHERE ${quotedColumn} < NOW() - ($1 * INTERVAL '1 second')`, [expireAfterSeconds]);
+}
+/**
+* Register the in-process scheduler purge job for a PostgreSQL TTL index.
+*
+* The application owns the scheduler lifecycle: callers must start the shared
+* scheduler during bootstrap. Re-registering replaces a previous job for the
+* same driver/index so repeated migration setup cannot leak callbacks.
+*/
+function registerPostgresTTLPurgeJob(driver, table, column, expireAfterSeconds) {
+	const name = postgresTTLPurgeJobName(driver, table, column);
+	_warlock_js_scheduler.scheduler.removeJob(name);
+	_warlock_js_scheduler.scheduler.addJob((0, _warlock_js_scheduler.job)(name, () => purgeExpiredPostgresRows(driver, table, column, expireAfterSeconds)).everyMinutes(TTL_PURGE_INTERVAL_MINUTES));
+	let names = driverJobs.get(driver);
+	if (!names) {
+		names = /* @__PURE__ */ new Set();
+		driverJobs.set(driver, names);
+	}
+	names.add(name);
+}
+/** Remove the scheduler callback associated with a dropped PostgreSQL TTL index. */
+function unregisterPostgresTTLPurgeJob(driver, table, column) {
+	const name = postgresTTLPurgeJobName(driver, table, column);
+	_warlock_js_scheduler.scheduler.removeJob(name);
+	driverJobs.get(driver)?.delete(name);
+}
+/** Remove a driver's callbacks before its pool is closed. */
+function unregisterAllPostgresTTLPurgeJobs(driver) {
+	for (const name of driverJobs.get(driver) ?? []) _warlock_js_scheduler.scheduler.removeJob(name);
+	driverJobs.delete(driver);
+}
+/** Restore registered retention rules from index comments on every connection. */
+async function loadPostgresTTLPurgeJobs(driver) {
+	const result = await driver.query(`SELECT d.description FROM pg_catalog.pg_description d
+      JOIN pg_catalog.pg_class c ON c.oid = d.objoid
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind = 'i' AND n.nspname = current_schema()
+        AND d.description LIKE 'warlock_ttl:%'`);
+	for (const row of result.rows ?? []) {
+		if (typeof row.description !== "string" || !row.description.startsWith(TTL_COMMENT_PREFIX)) continue;
+		let rule;
+		try {
+			rule = JSON.parse(row.description.slice(12));
+		} catch {
+			continue;
+		}
+		if (!rule || typeof rule !== "object") continue;
+		const { table, column, expireAfterSeconds } = rule;
+		if (typeof table !== "string" || table.length === 0 || typeof column !== "string" || column.length === 0 || !Number.isSafeInteger(expireAfterSeconds) || expireAfterSeconds < 0) continue;
+		registerPostgresTTLPurgeJob(driver, table, column, expireAfterSeconds);
+	}
+}
+
 //#endregion
 //#region ../cascade/src/drivers/postgres/postgres-migration-driver.ts
 /**
@@ -15933,7 +16092,7 @@ var PostgresMigrationDriver = class {
 	*
 	* Note: PostgreSQL doesn't have native TTL indexes like MongoDB.
 	* This creates a plain index (a `NOW()` predicate is not IMMUTABLE, so a
-	* partial index cannot be built) and requires a scheduled job for cleanup.
+	* partial index cannot be built) and registers a scheduler purge job.
 	*
 	* @param table - Table name
 	* @param column - Date column
@@ -15945,6 +16104,9 @@ var PostgresMigrationDriver = class {
 		const indexName = `idx_${table}_ttl_${column}`;
 		const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);
 		await this.execute(`CREATE INDEX ${quotedIndexName} ON ${quotedTable} (${quotedColumn})`);
+		const comment = postgresTTLPurgeComment(table, column, expireAfterSeconds).replaceAll("'", "''");
+		await this.execute(`COMMENT ON INDEX ${quotedIndexName} IS '${comment}'`);
+		registerPostgresTTLPurgeJob(this.driver, table, column, expireAfterSeconds);
 	}
 	/**
 	* Drop a TTL index.
@@ -15954,6 +16116,7 @@ var PostgresMigrationDriver = class {
 	*/
 	async dropTTLIndex(table, column) {
 		await this.dropIndex(table, `idx_${table}_ttl_${column}`);
+		unregisterPostgresTTLPurgeJob(this.driver, table, column);
 	}
 	/**
 	* List all indexes on a table.
@@ -19055,6 +19218,7 @@ var PostgresDriver = class {
 			_warlock_js_logger.log.success("database.postgres", "connection", `Connected to database ${_mongez_copper.colors.bold(_mongez_copper.colors.yellowBright(this.config.database))}`);
 			this._isConnected = true;
 			await this.loadNativeArrayColumns();
+			await loadPostgresTTLPurgeJobs(this);
 			this.emit("connected");
 		} catch (error) {
 			_warlock_js_logger.log.fatal("database.postgres", "connection", "Failed to connect to database");
@@ -19069,6 +19233,7 @@ var PostgresDriver = class {
 	*/
 	async disconnect() {
 		if (!this._isConnected || !this._pool) return;
+		unregisterAllPostgresTTLPurgeJobs(this);
 		await this._pool.end();
 		this._pool = void 0;
 		this._isConnected = false;