@warlock.js/cascade 5.20.0 → 5.22.0

package/esm/drivers/postgres/postgres-driver.mjs

@@ -2,14 +2,14 @@ import { databaseTransactionContext } from "../../context/database-transaction-c
 import { flushAfterCommit } from "../../transactions/after-commit.mjs";
 import { TransactionRollbackError } from "../../errors/transaction-rollback.error.mjs";
 import { UnsupportedUpdateOperationError } from "../../errors/unsupported-update-operation.error.mjs";
-import { isValidDateValue } from "../../utils/is-valid-date-value.mjs";
 import { PostgresBlueprint } from "./postgres-blueprint.mjs";
 import { PostgresDialect } from "./postgres-dialect.mjs";
 import { SqlDatabaseDirtyTracker } from "../../sql-database-dirty-tracker.mjs";
+import { convertPostgresValue } from "./postgres-type-converters.mjs";
+import { loadPostgresTTLPurgeJobs, unregisterAllPostgresTTLPurgeJobs } from "./postgres-ttl-purge.mjs";
 import { PostgresMigrationDriver } from "./postgres-migration-driver.mjs";
 import { PostgresQueryBuilder } from "./postgres-query-builder.mjs";
 import { PostgresSQLSerializer } from "./postgres-sql-serializer.mjs";
-import { PostgresSyncAdapter } from "./postgres-sync-adapter.mjs";
 import { assertPostgresUpdate } from "./postgres-update-validator.mjs";
 import { log } from "@warlock.js/logger";
 import { colors } from "@mongez/copper";
@@ -55,6 +55,7 @@ function buildPostgresPoolConfig(config) {
 		idleTimeoutMillis: config.idleTimeoutMillis ?? 3e4,
 		connectionTimeoutMillis: config.connectionTimeoutMillis ?? 1e4,
 		keepAlive: config.keepAlive ?? true,
+		maxUses: config.maxUses,
 		application_name: config.application_name ?? "cascade",
 		ssl: config.ssl
 	};
@@ -79,6 +80,10 @@ async function loadPg() {
 	}
 }
 /**
+* Transaction session -> the driver (data source) that opened it.
+*/
+const transactionOwners = /* @__PURE__ */ new WeakMap();
+/**
 * PostgreSQL database driver implementing the Cascade DriverContract.
 *
 * Provides connection pooling, CRUD operations, transactions, and
@@ -107,6 +112,11 @@ async function loadPg() {
 * await driver.disconnect();
 * ```
 */
+/** Summarise bound parameters as count and types, never values. */
+function describeParams(params) {
+	const types = params.map((param) => param === null ? "null" : typeof param);
+	return `Params: ${params.length} (${types.join(", ")})`;
+}
 var PostgresDriver = class {
 	config;
 	/**
@@ -169,6 +179,8 @@ var PostgresDriver = class {
 	* @see PostgresPoolConfig.nativeArrayColumns
 	*/
 	_nativeArrayColumns;
+	/** Column `dataTypeID`s per result row, filled by `query()` for `deserialize()`. */
+	rowColumnTypes = /* @__PURE__ */ new WeakMap();
 	/** Unique keys per table, resolved from `pg_index` for upsert conflict targets. */
 	_uniqueKeys = /* @__PURE__ */ new Map();
 	/**
@@ -235,6 +247,7 @@ var PostgresDriver = class {
 			log.success("database.postgres", "connection", `Connected to database ${colors.bold(colors.yellowBright(this.config.database))}`);
 			this._isConnected = true;
 			await this.loadNativeArrayColumns();
+			await loadPostgresTTLPurgeJobs(this);
 			this.emit("connected");
 		} catch (error) {
 			log.fatal("database.postgres", "connection", "Failed to connect to database");
@@ -249,6 +262,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;
@@ -343,6 +357,16 @@ var PostgresDriver = class {
 		return this._nativeArrayColumns.has(column);
 	}
 	/**
+	* Drop the cached unique keys and re-read the native-array columns.
+	*
+	* Called by the migration driver after DDL so an in-process migration is
+	* visible to the serializer and to upserts without reconnecting.
+	*/
+	async invalidateSchemaCaches() {
+		this._uniqueKeys.clear();
+		await this.loadNativeArrayColumns();
+	}
+	/**
 	* Introspect the live schema for native-array columns so array values bind
 	* correctly with zero app configuration.
 	*
@@ -394,26 +418,11 @@ var PostgresDriver = class {
 	* @returns Deserialized JavaScript object
 	*/
 	deserialize(data) {
+		const columnTypes = this.rowColumnTypes.get(data);
+		if (!columnTypes) return data;
 		for (const [key, value] of Object.entries(data)) {
 			if (typeof value !== "string") continue;
-			if (isValidDateValue(value)) {
-				data[key] = new Date(value);
-				continue;
-			}
-			if (value.charCodeAt(0) === 91 && value.charCodeAt(value.length - 1) === 93) {
-				const parts = value.slice(1, -1).split(",");
-				const nums = new Array(parts.length);
-				let isNumericVector = parts.length > 0;
-				for (let i = 0; i < parts.length; i++) {
-					const n = +(parts[i] ?? "");
-					if (!Number.isFinite(n)) {
-						isNumericVector = false;
-						break;
-					}
-					nums[i] = n;
-				}
-				if (isNumericVector) data[key] = nums;
-			}
+			data[key] = convertPostgresValue(value, columnTypes.get(key));
 		}
 		return data;
 	}
@@ -490,7 +499,15 @@ var PostgresDriver = class {
 		try {
 			return { modifiedCount: (await this.query(sql, params)).rowCount ?? 0 };
 		} catch (error) {
-			console.log("PG Query Error in:", sql, params);
+			log.error({
+				module: "database.postgres",
+				action: "update.error",
+				message: `${sql} | ${describeParams(params)}`,
+				context: {
+					sql,
+					paramCount: params.length
+				}
+			});
 			throw error;
 		}
 	}
@@ -667,7 +684,8 @@ var PostgresDriver = class {
 		const conflictColumns = options?.conflictColumns ?? Object.keys(filter);
 		if (conflictColumns.length === 0) throw new Error("Upsert requires conflictColumns option or filter with columns");
 		const quotedConflictColumns = conflictColumns.map((c) => this.dialect.quoteIdentifier(c)).join(", ");
-		const setClauses = columns.filter((col) => !conflictColumns.includes(col)).map((col, i) => {
+		const createdAtColumn = options?.createdAtColumn ?? this.modelDefaults.createdAtColumn;
+		const setClauses = columns.filter((col) => !conflictColumns.includes(col) && col !== createdAtColumn).map((col, i) => {
 			const valueIndex = columns.indexOf(col) + 1;
 			return `${this.dialect.quoteIdentifier(col)} = ${this.dialect.placeholder(valueIndex)}`;
 		}).join(", ");
@@ -685,7 +703,7 @@ var PostgresDriver = class {
 	async findOneAndDelete(table, filter, _options) {
 		const quotedTable = this.dialect.quoteIdentifier(table);
 		const { whereClause, whereParams } = this.buildWhereClause(filter, 1);
-		const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1) RETURNING *`;
+		const sql = `${this.singleRowTarget("DELETE FROM " + quotedTable, quotedTable, filter, whereClause)} RETURNING *`;
 		const result = await this.query(sql, whereParams);
 		return result.rows[0] ? result.rows[0] : null;
 	}
@@ -700,7 +718,7 @@ var PostgresDriver = class {
 	async delete(table, filter, _options) {
 		const quotedTable = this.dialect.quoteIdentifier(table);
 		const { whereClause, whereParams } = this.buildWhereClause(filter ?? {}, 1);
-		const sql = `DELETE FROM ${quotedTable} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;
+		const sql = this.singleRowTarget("DELETE FROM " + quotedTable, quotedTable, filter ?? {}, whereClause);
 		return (await this.query(sql, whereParams)).rowCount ?? 0;
 	}
 	/**
@@ -801,29 +819,32 @@ var PostgresDriver = class {
 		const ctx = { rollback(reason) {
 			throw new TransactionRollbackError(reason);
 		} };
-		if (databaseTransactionContext.hasActiveTransaction()) return fn(ctx);
+		if (this.canJoinActiveTransaction()) return fn(ctx);
 		const tx = await this.beginTransaction(options);
-		databaseTransactionContext.enter({ session: tx.context });
+		transactionOwners.set(tx.context, this);
 		let commitStarted = false;
 		let committedCallbacks = [];
 		let result;
-		try {
-			result = await fn(ctx);
-			commitStarted = true;
-			await tx.commit();
-			committedCallbacks = databaseTransactionContext.takeAfterCommit();
-		} catch (error) {
-			if (commitStarted) log.error(`database.postgress`, "transaction", "Transaction COMMIT failed; client discarded, no rollback issued");
-			else try {
-				await tx.rollback();
-				log.error(`database.postgress`, "transaction", "Transaction operation failed, rolled back everything");
-			} catch (rollbackError) {
-				log.error(`database.postgress`, "transaction", rollbackError);
+		await databaseTransactionContext.run({
+			session: tx.context,
+			afterCommit: []
+		}, async () => {
+			try {
+				result = await fn(ctx);
+				commitStarted = true;
+				await tx.commit();
+				committedCallbacks = databaseTransactionContext.takeAfterCommit();
+			} catch (error) {
+				if (commitStarted) log.error(`database.postgress`, "transaction", "Transaction COMMIT failed; client discarded, no rollback issued");
+				else try {
+					await tx.rollback();
+					log.error(`database.postgress`, "transaction", "Transaction operation failed, rolled back everything");
+				} catch (rollbackError) {
+					log.error(`database.postgress`, "transaction", rollbackError);
+				}
+				throw error;
 			}
-			throw error;
-		} finally {
-			databaseTransactionContext.exit();
-		}
+		});
 		await flushAfterCommit(committedCallbacks);
 		return result;
 	}
@@ -856,13 +877,94 @@ var PostgresDriver = class {
 	/**
 	* Get the sync adapter for bulk denormalized updates.
 	*
+	* Sync instructions arrive in the portable Mongo shape (`$set` with a `field.$`
+	* positional key, `$pull`, `$unset`, dotted filter keys), so they are translated
+	* to jsonb SQL here instead of being handed to `updateMany`, which would quote
+	* `"tags.$"` as a column name.
+	*
 	* @returns Sync adapter instance
 	*/
 	syncAdapter() {
-		if (!this._syncAdapter) this._syncAdapter = new PostgresSyncAdapter(this);
+		if (!this._syncAdapter) {
+			const executeOne = (instruction) => this.executeSyncInstruction(instruction);
+			this._syncAdapter = {
+				executeOne,
+				executeArrayUpdate: executeOne,
+				executeBatch: async (instructions) => {
+					let affected = 0;
+					for (const instruction of instructions) affected += await executeOne(instruction);
+					return affected;
+				}
+			};
+		}
 		return this._syncAdapter;
 	}
 	/**
+	* Execute one sync instruction as a jsonb UPDATE.
+	*
+	* @param instruction - Sync instruction in the portable Mongo shape
+	* @returns Number of affected rows
+	*/
+	async executeSyncInstruction(instruction) {
+		const { sql, params } = this.buildSyncStatement(instruction);
+		return (await this.query(sql, params)).rowCount ?? 0;
+	}
+	/**
+	* Translate a sync instruction to a jsonb UPDATE statement.
+	*
+	* @param instruction - Sync instruction
+	* @returns SQL and parameters
+	* @throws Error for update operators a sync cannot express
+	*/
+	buildSyncStatement(instruction) {
+		const params = [];
+		const bind = (value) => {
+			params.push(value);
+			return this.dialect.placeholder(params.length);
+		};
+		const quote = (name) => this.dialect.quoteIdentifier(name);
+		const elementMatch = (idField, idValue, operator) => `(e->>${bind(idField)}::text) ${operator} ${bind(String(idValue))}::text`;
+		const clauses = [];
+		for (const [key, value] of Object.entries(instruction.update)) if (key === "$set") for (const [path, embed] of Object.entries(value)) if (path.endsWith(".$")) {
+			const column = quote(path.slice(0, -2));
+			const { identifierField, identifierValue } = instruction;
+			if (!identifierField || identifierValue === void 0) throw new Error(`Positional update on "${path}" requires an identifier field/value.`);
+			const match = elementMatch(identifierField, identifierValue, "=");
+			clauses.push(`${column} = (SELECT COALESCE(jsonb_agg(CASE WHEN ${match} THEN ${bind(JSON.stringify(embed))}::jsonb ELSE e END), '[]'::jsonb) FROM jsonb_array_elements(${column}::jsonb) e)`);
+		} else if (path.includes(".")) {
+			const [head, ...rest] = path.split(".");
+			const column = quote(head);
+			clauses.push(`${column} = jsonb_set(COALESCE(${column}::jsonb, '{}'::jsonb), ${bind(rest)}::text[], ${bind(JSON.stringify(embed))}::jsonb)`);
+		} else clauses.push(`${quote(path)} = ${bind(JSON.stringify(embed))}::jsonb`);
+		else if (key === "$pull") for (const [field, criteria] of Object.entries(value)) {
+			const column = quote(field);
+			const entries = Object.entries(criteria);
+			const [idField, idValue] = entries[0] ?? [];
+			if (entries.length !== 1 || !idField) throw new Error(`$pull on "${field}" must match a single identifier field.`);
+			const match = elementMatch(idField, idValue, "IS DISTINCT FROM");
+			clauses.push(`${column} = (SELECT COALESCE(jsonb_agg(e), '[]'::jsonb) FROM jsonb_array_elements(${column}::jsonb) e WHERE ${match})`);
+		}
+		else if (key === "$unset") for (const field of Object.keys(value)) clauses.push(`${quote(field)} = NULL`);
+		else throw new Error(`Unsupported sync update operator "${key}" on the Postgres driver.`);
+		if (clauses.length === 0) throw new Error("No update operations specified for the sync instruction.");
+		const conditions = [];
+		for (const [key, value] of Object.entries(instruction.filter)) {
+			if (!key.includes(".")) {
+				conditions.push(`${quote(key)} = ${bind(value)}`);
+				continue;
+			}
+			const [head, ...rest] = key.split(".");
+			const column = quote(head);
+			const path = bind(rest);
+			conditions.push(instruction.isArrayUpdate && head === instruction.arrayField ? `EXISTS (SELECT 1 FROM jsonb_array_elements(${column}::jsonb) e WHERE (e #>> ${path}::text[]) = ${bind(String(value))}::text)` : `(${column}::jsonb #>> ${path}::text[]) = ${bind(String(value))}::text`);
+		}
+		const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+		return {
+			sql: `UPDATE ${quote(instruction.targetTable)} SET ${clauses.join(", ")}${where}`,
+			params
+		};
+	}
+	/**
 	* Get the migration driver for schema operations.
 	*
 	* @returns Migration driver instance
@@ -879,6 +981,25 @@ var PostgresDriver = class {
 		return new PostgresSQLSerializer(this.dialect);
 	}
 	/**
+	* Whether an active transaction can be joined: one exists and it is not
+	* owned by a different data source (sessions opened outside `transaction()`
+	* carry no owner tag and are joinable).
+	*/
+	canJoinActiveTransaction() {
+		const session = databaseTransactionContext.getSession();
+		if (!session) return false;
+		const owner = transactionOwners.get(session);
+		return owner === void 0 || owner === this;
+	}
+	/**
+	* The ambient transaction session, only when it belongs to this driver's
+	* data source.
+	*/
+	getOwnSession() {
+		const session = databaseTransactionContext.getSession();
+		return session && transactionOwners.get(session) === this ? session : void 0;
+	}
+	/**
 	* Execute a raw SQL query.
 	*
 	* Automatically uses the transaction client if one is active.
@@ -887,15 +1008,15 @@ var PostgresDriver = class {
 	* @param params - Query parameters
 	* @returns Query result
 	*/
+	recordColumnTypes(result) {
+		if (!result.fields?.length || !result.rows?.length) return;
+		const columnTypes = new Map(result.fields.map((field) => [field.name, field.dataTypeID]));
+		for (const row of result.rows) if (row && typeof row === "object") this.rowColumnTypes.set(row, columnTypes);
+	}
 	async query(sql, params = []) {
-		const txClient = databaseTransactionContext.getSession();
+		const txClient = this.getOwnSession();
 		const startTime = this.config.logging ? performance.now() : 0;
-		let paramsString = "";
-		if (this.config.logging && params.length > 0) {
-			paramsString = JSON.stringify(params);
-			if (paramsString.length > 300) paramsString = paramsString.substring(0, 300) + "...";
-			paramsString = ` | Params: ${paramsString}`;
-		}
+		const paramsString = this.config.logging && params.length > 0 ? ` | ${describeParams(params)}` : "";
 		try {
 			let result;
 			if (this.config.logging) log.info({
@@ -903,8 +1024,8 @@ var PostgresDriver = class {
 				action: "query.executing",
 				message: `${sql}${paramsString}`,
 				context: {
-					params,
-					sql
+					sql,
+					paramCount: params.length
 				}
 			});
 			if (txClient) result = await txClient.query(sql, params);
@@ -916,12 +1037,13 @@ var PostgresDriver = class {
 					action: "query.executed",
 					message: `[${duration}ms] ${sql}${paramsString}`,
 					context: {
-						params,
 						sql,
+						paramCount: params.length,
 						duration
 					}
 				});
 			}
+			this.recordColumnTypes(result);
 			return result;
 		} catch (error) {
 			if (this.config.logging) {
@@ -932,7 +1054,7 @@ var PostgresDriver = class {
 					message: `[${duration}ms] ${sql}${paramsString}`,
 					context: {
 						sql,
-						params,
+						paramCount: params.length,
 						error: error instanceof Error ? error.message : String(error)
 					}
 				});
@@ -1084,14 +1206,28 @@ var PostgresDriver = class {
 		const quotedTable = this.dialect.quoteIdentifier(table);
 		const { whereClause, whereParams } = this.buildWhereClause(filter, set.nextIndex);
 		params.push(...whereParams);
-		let sql = `UPDATE ${quotedTable} SET ${set.clauses.join(", ")} ${whereClause}`;
-		if (limit === 1 && whereClause) sql = `UPDATE ${quotedTable} SET ${set.clauses.join(", ")} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;
+		const head = `UPDATE ${quotedTable} SET ${set.clauses.join(", ")}`;
 		return {
-			sql,
+			sql: limit === 1 && whereClause ? this.singleRowTarget(head, quotedTable, filter, whereClause) : `${head} ${whereClause}`,
 			params
 		};
 	}
 	/**
+	* Build the `<head> WHERE ...` statement for a single-row UPDATE/DELETE.
+	*
+	* A filter pinned to the primary key (`id = <value>`) already matches at most
+	* one row, so it is used as-is: a ctid subquery would re-check a stale tuple
+	* after waiting on a concurrent write and silently update 0 rows.
+	* Without a PK, the ctid subquery locks its candidate with
+	* `FOR UPDATE SKIP LOCKED` so concurrent callers claim different rows
+	* instead of losing the write.
+	*/
+	singleRowTarget(head, quotedTable, filter, whereClause) {
+		const id = filter.id;
+		if (id !== void 0 && id !== null && (typeof id !== "object" || id instanceof Date)) return `${head} ${whereClause}`;
+		return `${head} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1 FOR UPDATE SKIP LOCKED)`;
+	}
+	/**
 	* Create a new database.
 	*
 	* Note: This requires connecting to a system database (like 'postgres')