@warlock.js/cascade 5.11.0 → 5.13.0

package/cjs/index.cjs

@@ -475,6 +475,105 @@ var UnsafeRawExpressionError = class UnsafeRawExpressionError extends Error {
 	}
 };
 
+//#endregion
+//#region ../cascade/src/errors/unsupported-lean-operation.error.ts
+/**
+* Error thrown when a query in lean read mode (`.lean()`) asks for something
+* that needs hydrated Model instances — eager-loading relations with `with()`
+* or `joinWith()`.
+*
+* Relations are attached to Model instances and shaped (including the related
+* model's `hidden` fields) by the Model layer, so lean mode refuses them rather
+* than returning a half-loaded or unfiltered result.
+*/
+var UnsupportedLeanOperationError = class UnsupportedLeanOperationError extends Error {
+	/**
+	* The rejected builder operation (e.g. `"with"`, `"joinWith"`).
+	*/
+	operation;
+	/**
+	* Creates a new UnsupportedLeanOperationError.
+	*
+	* @param operation - The rejected builder operation
+	*/
+	constructor(operation) {
+		super(`${operation}() cannot be combined with lean(): eager-loaded relations need hydrated models. Drop lean() for this query, or load the related records with a second lean query.`);
+		this.name = "UnsupportedLeanOperationError";
+		this.operation = operation;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, UnsupportedLeanOperationError);
+	}
+};
+
+//#endregion
+//#region ../cascade/src/errors/unsupported-query-operation.error.ts
+/**
+* Error thrown when a query builder is asked for a read operation its driver
+* cannot express — e.g. a MongoDB-only aggregation stage such as `unwind()` or
+* `addFields()` on a SQL driver.
+*
+* Builders throw this instead of silently dropping the stage, so a caller
+* never receives rows shaped differently from what the query asked for.
+*/
+var UnsupportedQueryOperationError = class UnsupportedQueryOperationError extends Error {
+	/**
+	* The operation that was rejected (e.g. `"unwind"`, `"addFields"`).
+	*/
+	operation;
+	/**
+	* The driver that rejected it (e.g. `"postgres"`).
+	*/
+	driver;
+	/**
+	* Creates a new UnsupportedQueryOperationError.
+	*
+	* @param operation - The rejected operation
+	* @param driver - The driver name
+	* @param hint - Optional guidance appended to the message
+	*/
+	constructor(operation, driver, hint) {
+		super(`The ${driver} driver does not support ${operation}() in queries.` + (hint ? ` ${hint}` : ""));
+		this.name = "UnsupportedQueryOperationError";
+		this.operation = operation;
+		this.driver = driver;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, UnsupportedQueryOperationError);
+	}
+};
+
+//#endregion
+//#region ../cascade/src/errors/unsupported-update-operation.error.ts
+/**
+* Error thrown when a driver is asked to perform an update it cannot express
+* natively — e.g. an aggregation-pipeline update, `arrayFilters` or `$addToSet`
+* on a SQL driver, or an upsert whose conflict target cannot be derived.
+*
+* Drivers throw this instead of silently dropping the operation, so a caller
+* never believes a write happened that did not.
+*/
+var UnsupportedUpdateOperationError = class UnsupportedUpdateOperationError extends Error {
+	/**
+	* The operation that was rejected (e.g. `"pipeline update"`, `"$addToSet"`).
+	*/
+	operation;
+	/**
+	* The driver that rejected it (e.g. `"postgres"`).
+	*/
+	driver;
+	/**
+	* Creates a new UnsupportedUpdateOperationError.
+	*
+	* @param operation - The rejected operation
+	* @param driver - The driver name
+	* @param hint - Optional guidance appended to the message
+	*/
+	constructor(operation, driver, hint) {
+		super(`The ${driver} driver does not support ${operation} in atomic updates.` + (hint ? ` ${hint}` : ""));
+		this.name = "UnsupportedUpdateOperationError";
+		this.operation = operation;
+		this.driver = driver;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, UnsupportedUpdateOperationError);
+	}
+};
+
 //#endregion
 //#region ../cascade/src/database-dirty-tracker.ts
 function canBeFlatten(object) {
@@ -4707,18 +4806,34 @@ function increaseField(ModelClass, filter, field, amount) {
 function decreaseField(ModelClass, filter, field, amount) {
 	return ModelClass.query().where(filter).decrement(field, amount);
 }
-async function performAtomic(ModelClass, filter, operations) {
-	return (await ModelClass.getDriver().atomic(ModelClass.table, sanitizeFilter(filter), operations)).modifiedCount;
+function resolveFilter(filter, options) {
+	return options?.trustedFilter ? filter : sanitizeFilter(filter);
+}
+function toDriverOptions(options) {
+	if (!options) return;
+	const { trustedFilter: _trustedFilter, ...rest } = options;
+	return rest;
+}
+/**
+* Run an atomic update and return the number of documents modified plus the
+* number inserted by an `upsert`.
+*/
+async function performAtomic(ModelClass, filter, operations, options) {
+	const result = await ModelClass.getDriver().atomic(ModelClass.table, resolveFilter(filter, options), operations, toDriverOptions(options));
+	return result.modifiedCount + (result.upsertedCount ?? 0);
 }
 async function updateById(ModelClass, id, data) {
 	return (await ModelClass.getDriver().update(ModelClass.table, { [ModelClass.primaryKey]: id }, { $set: data })).modifiedCount;
 }
-async function findAndUpdateRecords(ModelClass, filter, update) {
-	await performAtomic(ModelClass, filter, update);
+async function findAndUpdateRecords(ModelClass, filter, update, options) {
+	await performAtomic(ModelClass, filter, update, {
+		...options,
+		trustedFilter: false
+	});
 	return await ModelClass.query().where(filter).get();
 }
-async function findOneAndUpdateRecord(ModelClass, filter, update) {
-	const result = await ModelClass.getDriver().findOneAndUpdate(ModelClass.table, sanitizeFilter(filter), update);
+async function findOneAndUpdateRecord(ModelClass, filter, update, options) {
+	const result = await ModelClass.getDriver().findOneAndUpdate(ModelClass.table, resolveFilter(filter, options), update, toDriverOptions(options));
 	if (!result) return null;
 	return new ModelClass(result);
 }
@@ -6548,15 +6663,21 @@ var Model = class Model {
 		return decreaseField(this, filter, field, amount);
 	}
 	/**
-	* Perform atomic operation
-	* Example
+	* Perform an atomic update on every document/row matching the filter.
+	*
+	* @param filter - Filter conditions (operator keys rejected unless `trustedFilter`)
+	* @param operations - Update operators, or an aggregation pipeline (MongoDB only)
+	* @param options - `upsert`, `arrayFilters` (MongoDB only), `trustedFilter`
+	* @returns Number of documents modified plus the number inserted by an upsert
 	*
+	* @example
 	* ```typescript
-	* const user = await User.atomic({id: 1}, {$inc: {age: 1}})
-	* Returns user model with updated age
+	* await User.atomic({ id: 1 }, { $inc: { age: 1 } });
+	* await Counter.atomic({ key: "signups" }, { $inc: { count: 1 } }, { upsert: true });
+	* ```
 	*/
-	static async atomic(filter, operations) {
-		return performAtomic(this, filter, operations);
+	static async atomic(filter, operations, options) {
+		return performAtomic(this, filter, operations, options);
 	}
 	/**
 	* Perform an atomic update for the given id
@@ -6567,20 +6688,31 @@ var Model = class Model {
 	/**
 	* Find one and update multiple records that matches the provided filter and return the updated record
 	* @param filter - Filter conditions
-	* @param update - Update operations ($set, $unset, $inc)
+	* @param update - Update operators, or an aggregation pipeline (MongoDB only)
+	* @param options - `upsert`, `arrayFilters` (MongoDB only)
 	* @returns The updated records
 	*/
-	static async findAndUpdate(filter, update) {
-		return findAndUpdateRecords(this, filter, update);
+	static async findAndUpdate(filter, update, options) {
+		return findAndUpdateRecords(this, filter, update, options);
 	}
 	/**
 	* Find one and update a single record that matches the provided filter and return the updated record
 	* @param filter - Filter conditions
-	* @param update - Update operations ($set, $unset, $inc)
-	* @returns The updated record or null
+	* @param update - Update operators, or an aggregation pipeline (MongoDB only)
+	* @param options - `upsert`, `returnDocument` (default `"after"`), `arrayFilters`, `trustedFilter`
+	* @returns The record after (or before) the update, or null when nothing matched
+	*
+	* @example
+	* ```typescript
+	* const counter = await Counter.findOneAndUpdate(
+	*   { key: "signups" },
+	*   { $inc: { count: 1 }, $setOnInsert: { startedAt: new Date() } },
+	*   { upsert: true },
+	* );
+	* ```
 	*/
-	static async findOneAndUpdate(filter, update) {
-		return findOneAndUpdateRecord(this, filter, update);
+	static async findOneAndUpdate(filter, update, options) {
+		return findOneAndUpdateRecord(this, filter, update, options);
 	}
 	/**
 	* Find and replace the entire document that matches the provided filter and return the replaced document
@@ -8526,6 +8658,36 @@ var MongoMigrationDriver = class {
 	}
 };
 
+//#endregion
+//#region ../cascade/src/query-builder/lean-records.ts
+/**
+* Throw when a lean query also asks for eager-loaded relations.
+*
+* Called before the query executes, so nothing is fetched for a request that
+* cannot be answered.
+*
+* @throws UnsupportedLeanOperationError
+*/
+function assertLeanCompatible(state) {
+	if (state.eagerLoadRelations.size > 0) throw new UnsupportedLeanOperationError("with");
+	if (state.joinRelations && state.joinRelations.size > 0) throw new UnsupportedLeanOperationError("joinWith");
+}
+/**
+* Remove the model's `static hidden` top-level fields from lean rows, in place.
+*
+* The rows are fresh objects the driver just built, so mutating them is safe
+* and avoids a copy per row. Returns the same array.
+*/
+function stripHiddenFromLeanRecords(records, modelClass) {
+	const hidden = modelClass?.hidden;
+	if (!hidden || hidden.length === 0) return records;
+	for (const record of records) {
+		if (record === null || typeof record !== "object") continue;
+		for (const field of hidden) delete record[field];
+	}
+	return records;
+}
+
 //#endregion
 //#region ../cascade/src/query-builder/query-builder.ts
 /**
@@ -8580,6 +8742,8 @@ var QueryBuilder = class QueryBuilder {
 	relationDefinitions;
 	/** The Model class reference, required for relation resolution. */
 	modelClass;
+	/** True once `lean()` was called — execution skips Model hydration. */
+	isLean = false;
 	/**
 	* Append an operation to `operations[]` and update `opIndex`.
 	* Every fluent method calls this.
@@ -8671,8 +8835,22 @@ var QueryBuilder = class QueryBuilder {
 		cloned.countRelations = new Map(this.countRelations);
 		cloned.relationDefinitions = this.relationDefinitions;
 		cloned.modelClass = this.modelClass;
+		cloned.isLean = this.isLean;
 		return cloned;
 	}
+	/**
+	* Switch to lean read mode: execution returns the plain driver rows — no
+	* Model hydration, no driver deserialization, no hydrating/fetched
+	* callbacks. The model's `static hidden` fields are still stripped.
+	* Eager-loading relations in lean mode throws `UnsupportedLeanOperationError`.
+	*
+	* @example
+	* const rows = await User.query().where("isActive", true).lean().get();
+	*/
+	lean() {
+		this.isLean = true;
+		return this;
+	}
 	/** Disable one or more named global scopes for this query. */
 	withoutGlobalScope(...scopeNames) {
 		scopeNames.forEach((name) => this.disabledGlobalScopes.add(name));
@@ -10020,6 +10198,28 @@ function resolveLikePattern(pattern) {
 	return pattern instanceof RegExp ? pattern.source : likePatternToRegexSource(pattern);
 }
 
+//#endregion
+//#region ../cascade/src/drivers/mongodb/pipeline-stage-object.ts
+/**
+* Whether a value looks like one MongoDB aggregation stage: a plain object
+* with exactly one key, and that key is a `$`-prefixed stage name
+* (`{ $lookup: { ... } }`, `{ $addFields: { ... } }`).
+*
+* Used to validate caller-built stages (`joinRaw()`, `raw()` results) before
+* they reach the pipeline, so a SQL string or a filter object is rejected with
+* a named error instead of failing at execution time or being ignored.
+*
+* @param value - The candidate stage
+* @returns `true` when the value is a single-stage object
+*/
+function isPipelineStageObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	const keys = Object.keys(value);
+	return keys.length === 1 && keys[0].startsWith("$");
+}
+
 //#endregion
 //#region ../cascade/src/drivers/mongodb/mongodb-query-parser.ts
 /**
@@ -10086,42 +10286,110 @@ var MongoQueryParser = class {
 	* ```
 	*/
 	parse() {
+		this.groupFieldNames.clear();
+		this.countDistinctAliases.clear();
 		const pipeline = [];
 		let currentStage = null;
 		let currentBuffer = [];
-		for (const op of this.orderStages(this.operations)) if (op.mergeable && op.stage === currentStage) currentBuffer.push(op);
-		else {
+		let trailingProjectIndex = -1;
+		const emit = (stage, operations) => {
+			if (stage === "$raw") {
+				for (const op of operations) this.applyRawOperation(pipeline, op);
+				trailingProjectIndex = -1;
+				return;
+			}
+			const builtStage = this.buildStage(stage, operations);
+			if (!builtStage) return;
+			if (builtStage.$sort && trailingProjectIndex >= 0 && trailingProjectIndex === pipeline.length - 1) {
+				const projectStage = pipeline.pop();
+				pipeline.push(...this.placeSortAroundProjection(projectStage, builtStage));
+				trailingProjectIndex = -1;
+				return;
+			}
+			const stageIndex = pipeline.length;
+			pipeline.push(builtStage);
+			trailingProjectIndex = stage === "$project" ? stageIndex : -1;
+			this.trackGroupFieldNames(stage, operations, stageIndex);
+			const renameStage = this.buildGroupRenameStage(builtStage, stageIndex);
+			if (renameStage) pipeline.push(renameStage);
+		};
+		for (const op of this.orderStages(this.operations)) {
+			if (op.mergeable && op.stage === currentStage) {
+				currentBuffer.push(op);
+				continue;
+			}
 			if (currentBuffer.length > 0) {
-				const builtStage = this.buildStage(currentStage, currentBuffer);
-				if (builtStage) {
-					const stageIndex = pipeline.length;
-					pipeline.push(builtStage);
-					this.trackGroupFieldNames(currentStage, currentBuffer, stageIndex);
-				}
+				emit(currentStage, currentBuffer);
 				currentBuffer = [];
 			}
 			if (op.mergeable) {
 				currentStage = op.stage;
 				currentBuffer.push(op);
 			} else {
-				const builtStage = this.buildStage(op.stage, [op]);
-				if (builtStage) {
-					const stageIndex = pipeline.length;
-					pipeline.push(builtStage);
-					this.trackGroupFieldNames(op.stage, [op], stageIndex);
-				}
+				emit(op.stage, [op]);
 				currentStage = null;
 			}
 		}
-		if (currentBuffer.length > 0) {
-			const builtStage = this.buildStage(currentStage, currentBuffer);
-			if (builtStage) {
-				const stageIndex = pipeline.length;
-				pipeline.push(builtStage);
-				this.trackGroupFieldNames(currentStage, currentBuffer, stageIndex);
-			}
+		if (currentBuffer.length > 0) emit(currentStage, currentBuffer);
+		return pipeline;
+	}
+	/**
+	* Apply a raw escape-hatch operation to the pipeline built so far.
+	*
+	* - `joinRaw`: appends the caller-built stages verbatim.
+	* - `raw`: calls the callback with the pipeline array. A returned array
+	*   replaces the pipeline; `undefined` keeps the (possibly mutated) array.
+	*
+	* @throws UnsupportedQueryOperationError when a `raw()` callback leaves
+	*   something other than an array of stage objects
+	*/
+	applyRawOperation(pipeline, op) {
+		if (op.type === "joinRaw") {
+			pipeline.push(...op.data.stages);
+			return;
 		}
-		return this.postProcessGroupStages(pipeline);
+		const result = op.data.builder(pipeline);
+		const next = result === void 0 ? pipeline : result;
+		if (!Array.isArray(next) || !next.every(isPipelineStageObject)) throw new UnsupportedQueryOperationError("raw", "mongodb", "The raw() callback receives the aggregation pipeline array and must return an array of stage objects, or mutate that array and return nothing.");
+		if (next !== pipeline) pipeline.splice(0, pipeline.length, ...next);
+	}
+	/**
+	* Order a `$sort` against the select `$project` it follows.
+	*
+	* A `$sort` after a `$project` cannot see fields the projection dropped, so
+	* `select(["title"]).orderBy("likes")` would not sort. The sort moves before
+	* the projection, unless it sorts by a field the projection computes
+	* (`selectRaw({ score: ... }).orderBy("score")`), which only exists after it:
+	*
+	* - no computed sort key: `$sort`, `$project`
+	* - only computed or selected sort keys: `$project`, `$sort` (unchanged)
+	* - computed AND unselected sort keys: `$addFields` (the computed keys),
+	*   `$sort`, `$project` (those keys passed through)
+	*/
+	placeSortAroundProjection(projectStage, sortStage) {
+		const projection = projectStage.$project;
+		const sortKeys = Object.keys(sortStage.$sort);
+		const isInclusionFlag = (value) => value === 1 || value === true || value === 0 || value === false;
+		const computedKeys = sortKeys.filter((key) => {
+			const value = projection[key];
+			return value !== void 0 && !isInclusionFlag(value) && value !== `$${key}`;
+		});
+		if (computedKeys.length === 0) return [sortStage, projectStage];
+		if (!sortKeys.some((key) => {
+			const value = projection[key];
+			return value === void 0 || value === 0 || value === false;
+		})) return [projectStage, sortStage];
+		const addFields = {};
+		const passThrough = { ...projection };
+		for (const key of computedKeys) {
+			addFields[key] = projection[key];
+			passThrough[key] = 1;
+		}
+		return [
+			{ $addFields: addFields },
+			sortStage,
+			{ $project: passThrough }
+		];
 	}
 	/**
 	* Reorder operations so filters run before projections, mirroring SQL
@@ -10130,11 +10398,13 @@ var MongoQueryParser = class {
 	* strips the filter column would run before the `$match` and silently drop
 	* every document (`select(["a"]).where("b", x)` → `[]`).
 	*
-	* Only *mergeable* `$match` operations are hoisted, and only within a
-	* segment of neighboring mergeable `$match` / `$project` / `$sort`
-	* operations. Any other operation — `$group`, `$lookup`, `$limit`, `$skip`,
-	* `$setWindowFields`, or a non-mergeable op (raw escapes, having-style
-	* post-group matches, `$sample`) — is a barrier: nothing moves across it.
+	* Only *mergeable* operations move, and only within a segment of neighboring
+	* mergeable `$match` / `$project` / `$sort` operations. Inside a segment the
+	* order is `$match`, then `$project`, then `$sort` (each keeping call order),
+	* and {@link placeSortAroundProjection} then decides whether the sort runs
+	* before the projection. Any other operation — `$group`, `$lookup`,
+	* `$limit`, `$skip`, `$setWindowFields`, raw escapes, having-style
+	* post-group matches, `$sample` — is a barrier: nothing moves across it.
 	* So `groupBy(...).where(...)` still filters AFTER the group, and
 	* `limit(...)` / `random()` keep their call-order meaning.
 	*/
@@ -10144,7 +10414,8 @@ var MongoQueryParser = class {
 		const flushSegment = () => {
 			if (segment.length === 0) return;
 			reordered.push(...segment.filter((op) => op.stage === "$match"));
-			reordered.push(...segment.filter((op) => op.stage !== "$match"));
+			reordered.push(...segment.filter((op) => op.stage === "$project"));
+			reordered.push(...segment.filter((op) => op.stage === "$sort"));
 			segment = [];
 		};
 		for (const op of operations) if (op.mergeable && (op.stage === "$match" || op.stage === "$project" || op.stage === "$sort")) segment.push(op);
@@ -10183,35 +10454,26 @@ var MongoQueryParser = class {
 		if (distinctAliases.size > 0) this.countDistinctAliases.set(stageIndex, distinctAliases);
 	}
 	/**
-	* Post-process pipeline to rename _id fields after $group stages.
-	*
-	* This automatically renames MongoDB's `_id` field to the actual field name(s)
-	* used for grouping, making the results more intuitive.
-	*
-	* @param pipeline - The aggregation pipeline
-	* @returns The processed pipeline
-	*/
-	postProcessGroupStages(pipeline) {
-		const processed = [];
-		for (let i = 0; i < pipeline.length; i++) {
-			const stage = pipeline[i];
-			if (stage.$group && this.groupFieldNames.has(i)) {
-				const fieldNames = this.groupFieldNames.get(i);
-				processed.push(stage);
-				const projection = {};
-				if (typeof fieldNames === "string") projection[fieldNames] = "$_id";
-				else if (Array.isArray(fieldNames) && fieldNames.length > 0) for (const fieldName of fieldNames) projection[fieldName] = `$_id.${fieldName}`;
-				const distinctAliases = this.countDistinctAliases.get(i);
-				const aggregateFields = Object.keys(stage.$group).filter((key) => key !== "_id");
-				for (const field of aggregateFields) if (distinctAliases?.has(field)) projection[field] = { $size: `$${field}` };
-				else projection[field] = 1;
-				if (Object.keys(projection).length > 0) {
-					projection._id = 0;
-					processed.push({ $project: projection });
-				}
-			} else processed.push(stage);
-		}
-		return processed;
+	* Build the `$project` that renames `_id` back to the grouped field name(s)
+	* right after a `$group` stage with tracked field names, so results carry
+	* the grouping columns instead of MongoDB's `_id`.
+	*
+	* @param stage - The stage just emitted
+	* @param stageIndex - Its index in the pipeline
+	* @returns The renaming `$project` stage, or null when none is needed
+	*/
+	buildGroupRenameStage(stage, stageIndex) {
+		if (!stage.$group || !this.groupFieldNames.has(stageIndex)) return null;
+		const fieldNames = this.groupFieldNames.get(stageIndex);
+		const projection = {};
+		if (typeof fieldNames === "string") projection[fieldNames] = "$_id";
+		else if (Array.isArray(fieldNames) && fieldNames.length > 0) for (const fieldName of fieldNames) projection[fieldName] = `$_id.${fieldName}`;
+		const distinctAliases = this.countDistinctAliases.get(stageIndex);
+		const aggregateFields = Object.keys(stage.$group).filter((key) => key !== "_id");
+		for (const field of aggregateFields) projection[field] = distinctAliases?.has(field) ? { $size: `$${field}` } : 1;
+		if (Object.keys(projection).length === 0) return null;
+		projection._id = 0;
+		return { $project: projection };
 	}
 	/**
 	* Convert the parsed pipeline to a pretty-printed string for debugging.
@@ -10311,6 +10573,23 @@ var MongoQueryParser = class {
 				const [first] = operations;
 				return first === void 0 ? null : { $setWindowFields: first.data.spec };
 			}
+			case "$unwind": {
+				const [first] = operations;
+				if (first === void 0) return null;
+				const { path, ...options } = first.data;
+				return Object.keys(options).length === 0 ? { $unwind: path } : { $unwind: {
+					path,
+					...options
+				} };
+			}
+			case "$addFields": {
+				const [first] = operations;
+				return first === void 0 ? null : { $addFields: first.data };
+			}
+			case "$vectorSearch": {
+				const [first] = operations;
+				return first === void 0 ? null : { $vectorSearch: first.data };
+			}
 			default: return null;
 		}
 	}
@@ -11127,6 +11406,13 @@ var MongoQueryParser = class {
 		const op = operations[0];
 		if (op === void 0) return null;
 		const options = op.data;
+		if (Array.isArray(options.pipeline)) return { $lookup: {
+			from: options.table,
+			...options.localField !== void 0 ? { localField: options.localField } : {},
+			...options.foreignField !== void 0 ? { foreignField: options.foreignField } : {},
+			as: options.alias || options.table,
+			pipeline: options.pipeline
+		} };
 		return { $lookup: {
 			from: options.table,
 			localField: options.localField,
@@ -12385,23 +12671,35 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		return this;
 	}
 	/**
-	* Performs a raw join using a custom aggregation pipeline.
+	* Performs a raw join using caller-built aggregation stages.
 	*
-	* This allows full control over the $lookup stage for complex join scenarios.
+	* The expression is one pipeline stage (typically `{ $lookup: { ... } }`) or
+	* an array of stages. They are emitted verbatim in call order, so a later
+	* `where()` / `orderBy()` can use the joined fields.
 	*
-	* @param expression - Raw expression (typically a $lookup stage or pipeline)
-	* @param _bindings - Optional bindings (not used in MongoDB but kept for API consistency)
+	* @param expression - A pipeline stage object, or an array of stage objects
+	* @param _bindings - Not used on MongoDB; kept for API consistency
+	* @throws UnsupportedQueryOperationError when the expression is not a stage
+	*   object or an array of them (e.g. a SQL `JOIN` string)
 	*/
 	joinRaw(expression, _bindings) {
-		this.operationsHelper.addMatchOperation("raw", { builder: () => expression }, false);
+		const stages = Array.isArray(expression) ? expression : [expression];
+		if (stages.length === 0 || !stages.every(isPipelineStageObject)) throw new UnsupportedQueryOperationError("joinRaw", "mongodb", "Pass a pipeline stage object such as { $lookup: { ... } }, or an array of stage objects.");
+		this.operationsHelper.addOperation("$raw", "joinRaw", { stages });
 		return this;
 	}
 	/**
-	* Allows direct manipulation of the native MongoDB query.
-	* @param builder - Function that receives and modifies the native query
+	* Allows direct manipulation of the native MongoDB aggregation pipeline.
+	*
+	* The callback receives the pipeline array built from the operations
+	* recorded before this call. Return a new array of stages to replace it, or
+	* mutate the array in place and return nothing. Operations recorded after
+	* `raw()` are appended to that result.
+	*
+	* @param builder - Receives the pipeline array; returns a replacement or nothing
 	*/
 	raw(builder) {
-		this.operationsHelper.addMatchOperation("raw", { builder }, false);
+		this.operationsHelper.addOperation("$raw", "raw", { builder });
 		return this;
 	}
 	/**
@@ -12424,6 +12722,8 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		cloned.fetchingCallback = this.fetchingCallback?.bind(cloned);
 		cloned.hydratingCallback = this.hydratingCallback?.bind(cloned);
 		cloned.fetchedCallback = this.fetchedCallback?.bind(cloned);
+		cloned.isLean = this.isLean;
+		cloned.modelClass = this.modelClass;
 		cloned.pendingGlobalScopes = this.pendingGlobalScopes;
 		cloned.availableLocalScopes = this.availableLocalScopes;
 		cloned.disabledGlobalScopes = new Set(this.disabledGlobalScopes);
@@ -12432,6 +12732,13 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		return cloned;
 	}
 	/**
+	* Switch to lean read mode — see `QueryBuilderContract.lean()`.
+	*/
+	lean() {
+		super.lean();
+		return this;
+	}
+	/**
 	* Row-level locking is a SQL capability — MongoDB has no
 	* `SELECT ... FOR UPDATE`. Throwing (instead of silently ignoring the call)
 	* keeps a queue-claim pattern from silently running unlocked.
@@ -12468,6 +12775,10 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 	async get() {
 		const startTime = Date.now();
 		if (this.fetchingCallback) await this.fetchingCallback(this);
+		if (this.isLean) {
+			assertLeanCompatible(this);
+			return stripHiddenFromLeanRecords(await this.execute(), this.modelClass);
+		}
 		const rawRecords = await this.execute();
 		if (this.hydratingCallback) await this.hydratingCallback(rawRecords, {
 			query: this,
@@ -12967,6 +13278,26 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		return this;
 	}
 	/**
+	* Deconstruct an array field into one document per element (`$unwind`).
+	* The short form is emitted when no option is given. See
+	* `QueryBuilderContract.unwind()`.
+	*/
+	unwind(field, options) {
+		const data = { path: field.startsWith("$") ? field : `$${field}` };
+		if (options?.preserveNullAndEmptyArrays !== void 0) data.preserveNullAndEmptyArrays = options.preserveNullAndEmptyArrays;
+		if (options?.includeArrayIndex !== void 0) data.includeArrayIndex = options.includeArrayIndex;
+		this.operationsHelper.addOperation("$unwind", "unwind", data, false);
+		return this;
+	}
+	/**
+	* Add computed fields while keeping every existing field (`$addFields`).
+	* See `QueryBuilderContract.addFields()`.
+	*/
+	addFields(fields) {
+		this.operationsHelper.addOperation("$addFields", "addFields", { ...fields }, false);
+		return this;
+	}
+	/**
 	* Nearest-neighbour vector similarity search via MongoDB Atlas $vectorSearch.
 	*
 	* Adds two pipeline stages:
@@ -13124,6 +13455,29 @@ var MongoSyncAdapter = class {
 	}
 };
 
+//#endregion
+//#region ../cascade/src/drivers/mongodb/mongodb-update-translator.ts
+/**
+* Translate cascade's driver-agnostic update into MongoDB's native form.
+*
+* Every operator is native except `$dec`, which MongoDB does not have: it is
+* folded into `$inc` with negated amounts. A pipeline (array-form) update is
+* returned untouched.
+*
+* @param update - Operator object or aggregation pipeline
+* @returns The update MongoDB accepts
+*/
+function toMongoUpdate(update) {
+	if (Array.isArray(update) || !update.$dec) return update;
+	const { $dec, ...rest } = update;
+	const increments = { ...rest.$inc };
+	for (const [field, amount] of Object.entries($dec)) increments[field] = (increments[field] ?? 0) - amount;
+	return {
+		...rest,
+		$inc: increments
+	};
+}
+
 //#endregion
 //#region ../cascade/src/drivers/mongodb/mongodb-driver.ts
 const DEFAULT_TRANSACTION_OPTIONS = {
@@ -13426,14 +13780,17 @@ var MongoDbDriver = class {
 		return (await this.getDatabaseInstance().collection(table).findOneAndReplace(filter, document))?.value;
 	}
 	/**
-	* Find one and update a single document that matches the provided filter and return the updated document
+	* Find one and update a single document that matches the provided filter.
+	*
+	* Native `upsert`, `arrayFilters`, pipeline updates and `returnDocument`
+	* (default `"after"`).
 	*/
 	async findOneAndUpdate(table, filter, update, options) {
 		const collection = this.getDatabaseInstance().collection(table);
 		const mongoOptions = this.withSession(options);
-		return await collection.findOneAndUpdate(filter, update, {
-			returnDocument: "after",
-			...mongoOptions
+		return await collection.findOneAndUpdate(filter, toMongoUpdate(update), {
+			...mongoOptions,
+			returnDocument: options?.returnDocument ?? "after"
 		});
 	}
 	/**
@@ -13624,11 +13981,17 @@ var MongoDbDriver = class {
 	* Execute atomic operations (typically $inc/$set style updates) against documents.
 	*
 	* Uses `updateMany` so callers can atomically modify any set of documents.
+	* `upsert`, `arrayFilters` and pipeline updates are native.
 	*/
 	async atomic(table, filter, operations, options) {
 		const collection = this.getDatabaseInstance().collection(table);
-		const mongoOptions = this.withSession(options);
-		return { modifiedCount: (await collection.updateMany(filter, operations, mongoOptions)).modifiedCount };
+		const { returnDocument: _returnDocument, ...updateOptions } = options ?? {};
+		const mongoOptions = this.withSession(updateOptions);
+		const result = await collection.updateMany(filter, toMongoUpdate(operations), mongoOptions);
+		return {
+			modifiedCount: result.modifiedCount,
+			upsertedCount: result.upsertedCount
+		};
 	}
 	/**
 	* Lazily create (and cache) the Mongo sync adapter.
@@ -15884,6 +16247,13 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 	get driver() {
 		return this.dataSource.driver;
 	}
+	/**
+	* Switch to lean read mode — see `QueryBuilderContract.lean()`.
+	*/
+	lean() {
+		super.lean();
+		return this;
+	}
 	clone() {
 		const cloned = new PostgresQueryBuilder(this.table, this.dataSource);
 		cloned.operations = [...this.operations];
@@ -15895,6 +16265,7 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 		cloned.countRelations = new Map(this.countRelations);
 		cloned.relationDefinitions = this.relationDefinitions;
 		cloned.modelClass = this.modelClass;
+		cloned.isLean = this.isLean;
 		cloned.hydrateCallback = this.hydrateCallback;
 		cloned.joinRelations = new Map(this.joinRelations);
 		cloned.joinRelationsApplied = this.joinRelationsApplied;
@@ -16013,6 +16384,22 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 	*   .get<VectorRow & { score: number }>();
 	* ```
 	*/
+	/**
+	* MongoDB-only stage. Always throws — see `QueryBuilderContract.unwind()`.
+	*
+	* @throws UnsupportedQueryOperationError
+	*/
+	unwind(_field, _options) {
+		throw new UnsupportedQueryOperationError("unwind", "postgres", "Query the array column with jsonb_array_elements()/unnest() through selectRaw/joinRaw, or model the elements as a related table.");
+	}
+	/**
+	* MongoDB-only stage. Always throws — see `QueryBuilderContract.addFields()`.
+	*
+	* @throws UnsupportedQueryOperationError
+	*/
+	addFields(_fields) {
+		throw new UnsupportedQueryOperationError("addFields", "postgres", "Add computed columns with selectRaw() alongside the table columns, e.g. selectRaw('\"posts\".*').selectRaw(\"likes + shares AS score\").");
+	}
 	similarTo(column, embedding, alias = "score") {
 		const literal = `[${embedding.join(",")}]`;
 		const quotedCol = this.driver.dialect.quoteIdentifier(column);
@@ -16210,6 +16597,7 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 		this.applyHasRelations();
 		this.applyCountRelations();
 		this.applyGroupByAggregates();
+		if (this.isLean) assertLeanCompatible(this);
 		if (this.fetchingCallback) await this.fetchingCallback(this);
 		const { query = "", bindings = [] } = new PostgresQueryParser({
 			table: this.table,
@@ -16217,6 +16605,10 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 		}).parse();
 		try {
 			let records = (await this.driver.query(query, bindings)).rows;
+			if (this.isLean) {
+				this.operations = [];
+				return stripHiddenFromLeanRecords(records, this.modelClass);
+			}
 			const joinedData = this.extractJoinedRelationData(records);
 			if (this.hydratingCallback) await this.hydratingCallback(records, {});
 			if (this.hydrateCallback) records = records.map((row, index) => this.hydrateCallback(row, index));
@@ -17434,6 +17826,38 @@ var PostgresSyncAdapter = class {
 	}
 };
 
+//#endregion
+//#region ../cascade/src/drivers/postgres/postgres-update-validator.ts
+/**
+* Update operators the Postgres driver can express in SQL.
+*
+* `$setOnInsert` only contributes to the INSERT half of an upsert; on a plain
+* update it is a no-op, exactly as in MongoDB.
+*/
+const SUPPORTED_OPERATORS = new Set([
+	"$set",
+	"$unset",
+	"$inc",
+	"$dec",
+	"$setOnInsert"
+]);
+/**
+* Reject every part of an update the Postgres driver cannot perform, so no
+* operator or option is ever silently dropped.
+*
+* @param update - The requested update
+* @param options - The requested update options
+* @returns The update, narrowed to an operator object
+* @throws UnsupportedUpdateOperationError for pipeline updates, `arrayFilters`,
+*   and any operator outside {@link SUPPORTED_OPERATORS}
+*/
+function assertPostgresUpdate(update, options) {
+	if (Array.isArray(update)) throw new UnsupportedUpdateOperationError("pipeline update", "postgres", "Use an operator object ($set/$unset/$inc/$dec) or a raw query.");
+	if (options?.arrayFilters !== void 0) throw new UnsupportedUpdateOperationError("arrayFilters", "postgres");
+	for (const operator of Object.keys(update)) if (!SUPPORTED_OPERATORS.has(operator)) throw new UnsupportedUpdateOperationError(operator, "postgres", "Supported operators: $set, $unset, $inc, $dec, $setOnInsert.");
+	return update;
+}
+
 //#endregion
 //#region ../cascade/src/drivers/postgres/postgres-driver.ts
 /**
@@ -17589,6 +18013,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
@@ -17910,17 +18336,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.
@@ -18127,8 +18656,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 };
 	}
 	/**
@@ -18242,12 +18779,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":
@@ -18297,9 +18834,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
 		};
 	}
 	/**
@@ -18314,39 +18853,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
@@ -23101,6 +23655,9 @@ exports.SyncManager = SyncManager;
 exports.TransactionRollbackError = TransactionRollbackError;
 exports.UnsafeFilterError = UnsafeFilterError;
 exports.UnsafeRawExpressionError = UnsafeRawExpressionError;
+exports.UnsupportedLeanOperationError = UnsupportedLeanOperationError;
+exports.UnsupportedQueryOperationError = UnsupportedQueryOperationError;
+exports.UnsupportedUpdateOperationError = UnsupportedUpdateOperationError;
 exports.arrayBigInt = arrayBigInt;
 exports.arrayBoolean = arrayBoolean;
 exports.arrayDate = arrayDate;