@warlock.js/cascade 5.11.0 → 5.13.0

package/esm/drivers/postgres/postgres-driver.d.mts

@@ -5,7 +5,7 @@ import { DatabaseDriver } from "../../utils/connect-to-database.mjs";
 import { SQLSerializer } from "../../migration/sql-serializer.mjs";
 import { QueryBuilderContract } from "../../contracts/query-builder.contract.mjs";
 import { SyncAdapterContract } from "../../contracts/sync-adapter.contract.mjs";
-import { CreateDatabaseOptions, DriverContract, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult } from "../../contracts/database-driver.contract.mjs";
+import { AtomicUpdate, CreateDatabaseOptions, DriverAtomicUpdateOptions, DriverContract, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult } from "../../contracts/database-driver.contract.mjs";
 import { SqlDatabaseDirtyTracker } from "../../sql-database-dirty-tracker.mjs";
 import { PostgresDialect } from "./postgres-dialect.mjs";
 import { PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions } from "./types.mjs";
@@ -115,6 +115,8 @@ declare class PostgresDriver implements DriverContract {
    * @see PostgresPoolConfig.nativeArrayColumns
    */
   private readonly _nativeArrayColumns;
+  /** Unique keys per table, resolved from `pg_index` for upsert conflict targets. */
+  private readonly _uniqueKeys;
   /**
    * Native-array columns discovered by introspecting the live schema on
    * connect, keyed `table → { column, … }`. Authoritative and table-scoped, so
@@ -289,14 +291,44 @@ declare class PostgresDriver implements DriverContract {
    */
   update(table: string, filter: Record<string, unknown>, update: UpdateOperations, _options?: Record<string, unknown>): Promise<UpdateResult>;
   /**
-   * Find one and update a single row matching the filter and return the updated row
-   * @param table - Target table name
-   * @param filter - Filter conditions
-   * @param update - Update operations ($set, $unset, $inc)
-   * @param options - Optional update options
-   * @returns The updated row or null
+   * Find one row matching the filter, update it, and return it.
+   *
+   * - `upsert`: `INSERT … ON CONFLICT (target) DO UPDATE … RETURNING *`, where
+   *   the target is the primary key or a unique index whose columns are all
+   *   equality keys of the filter (see {@link executeUpsert}).
+   * - `returnDocument` (default `"after"`): `"before"` returns the row as it
+   *   was, and is not available together with `upsert`.
+   *
+   * The row is chosen with `SELECT … LIMIT 1 FOR UPDATE` and matched by primary
+   * key with the filter repeated, so concurrent callers re-check the filter
+   * against the latest committed row instead of overshooting it.
+   *
+   * @throws UnsupportedUpdateOperationError for pipeline updates, `arrayFilters`,
+   *   array operators, `before` + `upsert`, or an underivable conflict target
+   */
+  findOneAndUpdate<T = unknown>(table: string, filter: Record<string, unknown>, update: AtomicUpdate, options?: DriverAtomicUpdateOptions): Promise<T | null>;
+  /**
+   * Upsert through `INSERT … ON CONFLICT (target) DO UPDATE SET … [WHERE rest] RETURNING *`.
+   *
+   * Conflict target rule: the first unique index of the table (primary key
+   * first; partial and expression indexes excluded) whose columns are ALL
+   * equality keys of the filter — a non-null value that is not an operator
+   * object. Any other filter predicate becomes the `DO UPDATE … WHERE`, so an
+   * existing row that fails it is left untouched and no row is returned.
+   *
+   * Inserted row: filter equality values, then `$setOnInsert`, then `$set`,
+   * then `$inc` (n) / `$dec` (-n); `$unset` columns are omitted.
+   *
+   * @throws UnsupportedUpdateOperationError when no conflict target can be derived
    */
-  findOneAndUpdate<T = unknown>(table: string, filter: Record<string, unknown>, update: UpdateOperations, _options?: Record<string, unknown>): Promise<T | null>;
+  private executeUpsert;
+  /**
+   * Unique keys of a table (primary key first), read from `pg_index`.
+   *
+   * Partial and expression indexes are excluded — they cannot be an
+   * `ON CONFLICT (columns)` target. Non-empty results are cached per table.
+   */
+  private getUniqueKeys;
   /**
    * Update multiple rows matching the filter.
    *
@@ -415,7 +447,7 @@ declare class PostgresDriver implements DriverContract {
    * @param options - Optional options
    * @returns Update result
    */
-  atomic(table: string, filter: Record<string, unknown>, operations: UpdateOperations, _options?: Record<string, unknown>): Promise<UpdateResult>;
+  atomic(table: string, filter: Record<string, unknown>, operations: AtomicUpdate, options?: DriverAtomicUpdateOptions): Promise<UpdateResult>;
   /**
    * Get the sync adapter for bulk denormalized updates.
    *
@@ -471,6 +503,16 @@ declare class PostgresDriver implements DriverContract {
    * payloads) keep their existing bind-as-value behavior.
    */
   private isOperatorFilter;
+  /**
+   * Build the SET clauses for an update.
+   *
+   * @param table - Target table name (for value serialization)
+   * @param update - Update operations (`$setOnInsert` is not part of SET)
+   * @param startIndex - First placeholder index
+   * @param qualifier - Quoted table name to qualify right-hand column references
+   *   (needed where another relation with the same columns is in scope)
+   */
+  private buildSetClauses;
   /**
    * Build an UPDATE query from update operations.
    *
@@ -479,6 +521,7 @@ declare class PostgresDriver implements DriverContract {
    * @param update - Update operations
    * @param limit - Optional limit (for single row update)
    * @returns Object with SQL and parameters
+   * @throws UnsupportedUpdateOperationError for operations SQL cannot express
    */
   private buildUpdateQuery;
   /**

package/esm/drivers/postgres/postgres-driver.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-driver.d.mts","names":[],"sources":["../../../../../../../../cascade/src/drivers/postgres/postgres-driver.ts"],"mappings":"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"}
+{"version":3,"file":"postgres-driver.d.mts","names":[],"sources":["../../../../../../../../cascade/src/drivers/postgres/postgres-driver.ts"],"mappings":"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"}

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

@@ -1,5 +1,6 @@
 import { databaseTransactionContext } from "../../context/database-transaction-context.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";
@@ -8,6 +9,7 @@ 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 { colors } from "@mongez/copper";
 import { log } from "@warlock.js/logger";
 
@@ -165,6 +167,8 @@ var PostgresDriver = class {
 	* @see PostgresPoolConfig.nativeArrayColumns
 	*/
 	_nativeArrayColumns;
+	/** Unique keys per table, resolved from `pg_index` for upsert conflict targets. */
+	_uniqueKeys = /* @__PURE__ */ new Map();
 	/**
 	* Native-array columns discovered by introspecting the live schema on
 	* connect, keyed `table → { column, … }`. Authoritative and table-scoped, so
@@ -486,17 +490,120 @@ var PostgresDriver = class {
 		}
 	}
 	/**
-	* Find one and update a single row matching the filter and return the updated row
-	* @param table - Target table name
-	* @param filter - Filter conditions
-	* @param update - Update operations ($set, $unset, $inc)
-	* @param options - Optional update options
-	* @returns The updated row or null
+	* Find one row matching the filter, update it, and return it.
+	*
+	* - `upsert`: `INSERT … ON CONFLICT (target) DO UPDATE … RETURNING *`, where
+	*   the target is the primary key or a unique index whose columns are all
+	*   equality keys of the filter (see {@link executeUpsert}).
+	* - `returnDocument` (default `"after"`): `"before"` returns the row as it
+	*   was, and is not available together with `upsert`.
+	*
+	* The row is chosen with `SELECT … LIMIT 1 FOR UPDATE` and matched by primary
+	* key with the filter repeated, so concurrent callers re-check the filter
+	* against the latest committed row instead of overshooting it.
+	*
+	* @throws UnsupportedUpdateOperationError for pipeline updates, `arrayFilters`,
+	*   array operators, `before` + `upsert`, or an underivable conflict target
 	*/
-	async findOneAndUpdate(table, filter, update, _options) {
-		const { sql, params } = this.buildUpdateQuery(table, filter, update, 1);
-		const sqlWithReturning = `${sql} RETURNING *`;
-		return (await this.query(sqlWithReturning, params)).rows[0] ?? null;
+	async findOneAndUpdate(table, filter, update, options) {
+		const operations = assertPostgresUpdate(update, options);
+		const returnBefore = options?.returnDocument === "before";
+		if (options?.upsert) {
+			if (returnBefore) throw new UnsupportedUpdateOperationError("returnDocument: before with upsert", "postgres", "Use returnDocument: \"after\", or read the row before upserting inside a transaction.");
+			const { row } = await this.executeUpsert(table, filter, operations);
+			return row ?? null;
+		}
+		const primaryKey = (await this.getUniqueKeys(table)).find((key) => key.primary)?.columns;
+		if (!primaryKey) {
+			if (returnBefore) throw new UnsupportedUpdateOperationError("returnDocument: before without a primary key", "postgres");
+			const { sql, params } = this.buildUpdateQuery(table, filter, operations, 1);
+			return (await this.query(`${sql} RETURNING *`, params)).rows[0] ?? null;
+		}
+		const quotedTable = this.dialect.quoteIdentifier(table);
+		const keyList = (qualifier) => primaryKey.map((column) => (qualifier ? `${qualifier}.` : "") + this.dialect.quoteIdentifier(column)).join(", ");
+		const set = this.buildSetClauses(table, operations, 1, returnBefore ? quotedTable : void 0);
+		if (set.clauses.length === 0) throw new Error("No update operations specified");
+		const inner = this.buildWhereClause(filter, set.nextIndex);
+		const outer = this.buildWhereClause(filter, set.nextIndex + inner.whereParams.length, quotedTable);
+		const params = [
+			...set.params,
+			...inner.whereParams,
+			...outer.whereParams
+		];
+		const outerCondition = outer.condition ? ` AND ${outer.condition}` : "";
+		if (returnBefore) {
+			const before = this.dialect.quoteIdentifier("__cascade_before");
+			const sql = `UPDATE ${quotedTable} SET ${set.clauses.join(", ")} FROM (SELECT * FROM ${quotedTable} ${inner.whereClause} LIMIT 1 FOR UPDATE) AS ${before} WHERE (${keyList(quotedTable)}) = (${keyList(before)})${outerCondition} RETURNING ${before}.*`;
+			return (await this.query(sql, params)).rows[0] ?? null;
+		}
+		const sql = `UPDATE ${quotedTable} SET ${set.clauses.join(", ")} WHERE (${keyList(quotedTable)}) = (SELECT ${keyList()} FROM ${quotedTable} ${inner.whereClause} LIMIT 1 FOR UPDATE)${outerCondition} RETURNING *`;
+		return (await this.query(sql, params)).rows[0] ?? null;
+	}
+	/**
+	* Upsert through `INSERT … ON CONFLICT (target) DO UPDATE SET … [WHERE rest] RETURNING *`.
+	*
+	* Conflict target rule: the first unique index of the table (primary key
+	* first; partial and expression indexes excluded) whose columns are ALL
+	* equality keys of the filter — a non-null value that is not an operator
+	* object. Any other filter predicate becomes the `DO UPDATE … WHERE`, so an
+	* existing row that fails it is left untouched and no row is returned.
+	*
+	* Inserted row: filter equality values, then `$setOnInsert`, then `$set`,
+	* then `$inc` (n) / `$dec` (-n); `$unset` columns are omitted.
+	*
+	* @throws UnsupportedUpdateOperationError when no conflict target can be derived
+	*/
+	async executeUpsert(table, filter, operations) {
+		const equalityKeys = new Set(Object.entries(filter).filter(([, value]) => value !== null && value !== void 0 && !this.isOperatorFilter(value)).map(([key]) => key));
+		const target = (await this.getUniqueKeys(table)).find((key) => key.columns.every((column) => equalityKeys.has(column)));
+		if (!target) throw new UnsupportedUpdateOperationError("upsert without a unique conflict target", "postgres", `Filter on every column of the primary key or of a unique index of "${table}".`);
+		const insertRow = {};
+		for (const key of equalityKeys) insertRow[key] = filter[key];
+		Object.assign(insertRow, operations.$setOnInsert, operations.$set);
+		for (const [key, amount] of Object.entries(operations.$inc ?? {})) insertRow[key] = amount;
+		for (const [key, amount] of Object.entries(operations.$dec ?? {})) insertRow[key] = -amount;
+		for (const key of Object.keys(operations.$unset ?? {})) delete insertRow[key];
+		const columns = Object.keys(insertRow).filter((key) => insertRow[key] !== void 0);
+		const params = columns.map((key) => this.serializeValue(key, insertRow[key], table));
+		const quotedTable = this.dialect.quoteIdentifier(table);
+		const quotedColumns = columns.map((column) => this.dialect.quoteIdentifier(column)).join(", ");
+		const placeholders = columns.map((_, index) => this.dialect.placeholder(index + 1)).join(", ");
+		const set = this.buildSetClauses(table, operations, columns.length + 1, quotedTable);
+		params.push(...set.params);
+		const firstTargetColumn = this.dialect.quoteIdentifier(target.columns[0]);
+		const doUpdateSet = set.clauses.length > 0 ? set.clauses.join(", ") : `${firstTargetColumn} = ${quotedTable}.${firstTargetColumn}`;
+		const remainingFilter = Object.fromEntries(Object.entries(filter).filter(([key]) => !target.columns.includes(key)));
+		const where = this.buildWhereClause(remainingFilter, set.nextIndex, quotedTable);
+		params.push(...where.whereParams);
+		const conflictColumns = target.columns.map((column) => this.dialect.quoteIdentifier(column)).join(", ");
+		const insertedFlag = "__cascade_inserted";
+		const sql = `INSERT INTO ${quotedTable} (${quotedColumns}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns}) DO UPDATE SET ${doUpdateSet} ${where.whereClause} RETURNING *, (xmax = 0) AS "${insertedFlag}"`;
+		const returned = (await this.query(sql, params)).rows[0];
+		if (!returned) return { inserted: false };
+		const { [insertedFlag]: inserted, ...row } = returned;
+		return {
+			row,
+			inserted: inserted === true
+		};
+	}
+	/**
+	* Unique keys of a table (primary key first), read from `pg_index`.
+	*
+	* Partial and expression indexes are excluded — they cannot be an
+	* `ON CONFLICT (columns)` target. Non-empty results are cached per table.
+	*/
+	async getUniqueKeys(table) {
+		const cached = this._uniqueKeys.get(table);
+		if (cached) return cached;
+		const result = await this.query(`SELECT array_agg(a.attname::text ORDER BY k.ord) AS columns, i.indisprimary AS primary
+       FROM pg_index i
+       CROSS JOIN LATERAL unnest(i.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+       JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+       WHERE i.indrelid = to_regclass($1) AND i.indisunique AND i.indpred IS NULL AND i.indexprs IS NULL
+       GROUP BY i.indexrelid, i.indisprimary
+       ORDER BY i.indisprimary DESC, i.indexrelid`, [this.dialect.quoteIdentifier(table)]);
+		if (result.rows.length > 0) this._uniqueKeys.set(table, result.rows);
+		return result.rows;
 	}
 	/**
 	* Update multiple rows matching the filter.
@@ -703,8 +810,16 @@ var PostgresDriver = class {
 	* @param options - Optional options
 	* @returns Update result
 	*/
-	async atomic(table, filter, operations, _options) {
-		const { sql, params } = this.buildUpdateQuery(table, filter, operations);
+	async atomic(table, filter, operations, options) {
+		const update = assertPostgresUpdate(operations, options);
+		if (options?.upsert) {
+			const { row, inserted } = await this.executeUpsert(table, filter, update);
+			return {
+				modifiedCount: row && !inserted ? 1 : 0,
+				upsertedCount: row && inserted ? 1 : 0
+			};
+		}
+		const { sql, params } = this.buildUpdateQuery(table, filter, update);
 		return { modifiedCount: (await this.query(sql, params)).rowCount ?? 0 };
 	}
 	/**
@@ -818,12 +933,12 @@ var PostgresDriver = class {
 	* @param startParamIndex - Starting parameter index
 	* @returns Object with WHERE clause string and parameters
 	*/
-	buildWhereClause(filter, startParamIndex) {
+	buildWhereClause(filter, startParamIndex, qualifier) {
 		const conditions = [];
 		const params = [];
 		let paramIndex = startParamIndex;
 		for (const [key, value] of Object.entries(filter)) {
-			const quotedKey = this.dialect.quoteIdentifier(key);
+			const quotedKey = (qualifier ? `${qualifier}.` : "") + this.dialect.quoteIdentifier(key);
 			if (value === null) conditions.push(`${quotedKey} IS NULL`);
 			else if (this.isOperatorFilter(value)) for (const [operator, operand] of Object.entries(value)) switch (operator) {
 				case "$in":
@@ -873,9 +988,11 @@ var PostgresDriver = class {
 				params.push(value);
 			}
 		}
+		const condition = conditions.join(" AND ");
 		return {
-			whereClause: conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "",
-			whereParams: params
+			whereClause: condition ? `WHERE ${condition}` : "",
+			whereParams: params,
+			condition
 		};
 	}
 	/**
@@ -890,39 +1007,54 @@ var PostgresDriver = class {
 		return keys.length > 0 && keys.every((key) => key.startsWith("$"));
 	}
 	/**
-	* Build an UPDATE query from update operations.
+	* Build the SET clauses for an update.
 	*
-	* @param table - Target table name
-	* @param filter - Filter conditions
-	* @param update - Update operations
-	* @param limit - Optional limit (for single row update)
-	* @returns Object with SQL and parameters
+	* @param table - Target table name (for value serialization)
+	* @param update - Update operations (`$setOnInsert` is not part of SET)
+	* @param startIndex - First placeholder index
+	* @param qualifier - Quoted table name to qualify right-hand column references
+	*   (needed where another relation with the same columns is in scope)
 	*/
-	buildUpdateQuery(table, filter, update, limit) {
-		const setClauses = [];
+	buildSetClauses(table, update, startIndex, qualifier) {
+		const clauses = [];
 		const params = [];
-		let paramIndex = 1;
+		let paramIndex = startIndex;
+		const reference = (quotedKey) => qualifier ? `${qualifier}.${quotedKey}` : quotedKey;
 		if (update.$set) for (const [key, value] of Object.entries(update.$set)) {
-			setClauses.push(`${this.dialect.quoteIdentifier(key)} = ${this.dialect.placeholder(paramIndex++)}`);
+			clauses.push(`${this.dialect.quoteIdentifier(key)} = ${this.dialect.placeholder(paramIndex++)}`);
 			params.push(value === void 0 ? value : this.serializeValue(key, value, table));
 		}
-		if (update.$unset) for (const key of Object.keys(update.$unset)) setClauses.push(`${this.dialect.quoteIdentifier(key)} = NULL`);
-		if (update.$inc) for (const [key, amount] of Object.entries(update.$inc)) {
-			const quotedKey = this.dialect.quoteIdentifier(key);
-			setClauses.push(`${quotedKey} = COALESCE(${quotedKey}, 0) + ${this.dialect.placeholder(paramIndex++)}`);
-			params.push(amount);
-		}
-		if (update.$dec) for (const [key, amount] of Object.entries(update.$dec)) {
+		if (update.$unset) for (const key of Object.keys(update.$unset)) clauses.push(`${this.dialect.quoteIdentifier(key)} = NULL`);
+		for (const [operator, sign] of [["$inc", "+"], ["$dec", "-"]]) for (const [key, amount] of Object.entries(update[operator] ?? {})) {
 			const quotedKey = this.dialect.quoteIdentifier(key);
-			setClauses.push(`${quotedKey} = COALESCE(${quotedKey}, 0) - ${this.dialect.placeholder(paramIndex++)}`);
+			clauses.push(`${quotedKey} = COALESCE(${reference(quotedKey)}, 0) ${sign} ${this.dialect.placeholder(paramIndex++)}`);
 			params.push(amount);
 		}
-		if (setClauses.length === 0) throw new Error("No update operations specified");
+		return {
+			clauses,
+			params,
+			nextIndex: paramIndex
+		};
+	}
+	/**
+	* Build an UPDATE query from update operations.
+	*
+	* @param table - Target table name
+	* @param filter - Filter conditions
+	* @param update - Update operations
+	* @param limit - Optional limit (for single row update)
+	* @returns Object with SQL and parameters
+	* @throws UnsupportedUpdateOperationError for operations SQL cannot express
+	*/
+	buildUpdateQuery(table, filter, update, limit) {
+		const set = this.buildSetClauses(table, assertPostgresUpdate(update), 1);
+		if (set.clauses.length === 0) throw new Error("No update operations specified");
+		const params = [...set.params];
 		const quotedTable = this.dialect.quoteIdentifier(table);
-		const { whereClause, whereParams } = this.buildWhereClause(filter, paramIndex);
+		const { whereClause, whereParams } = this.buildWhereClause(filter, set.nextIndex);
 		params.push(...whereParams);
-		let sql = `UPDATE ${quotedTable} SET ${setClauses.join(", ")} ${whereClause}`;
-		if (limit === 1 && whereClause) sql = `UPDATE ${quotedTable} SET ${setClauses.join(", ")} WHERE ctid IN (SELECT ctid FROM ${quotedTable} ${whereClause} LIMIT 1)`;
+		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)`;
 		return {
 			sql,
 			params