@warlock.js/cascade 5.24.0 → 5.25.0

package/cjs/index.cjs

@@ -317,7 +317,7 @@ var DataSourceRegistry = class {
 	defaultSource;
 	defaultIsExplicit = false;
 	events = new node_events.EventEmitter();
-	/** Replaced sources; their forwarded driver events are ignored (drivers have no `off`). */
+	/** Replaced sources; their forwarded driver events are ignored. */
 	detached = /* @__PURE__ */ new WeakSet();
 	/** In-flight `getOrRegister` factories, so concurrent callers share one creation. */
 	pending = /* @__PURE__ */ new Map();
@@ -368,6 +368,12 @@ var DataSourceRegistry = class {
 		source.driver.on("disconnected", () => {
 			if (!this.detached.has(source)) this.events.emit("disconnected", source);
 		});
+		source.driver.on("query", (event) => {
+			if (!this.detached.has(source)) this.events.emit("query", {
+				...event,
+				connection: source.name
+			});
+		});
 		return source;
 	}
 	/**
@@ -670,6 +676,20 @@ var UnsupportedLeanOperationError = class UnsupportedLeanOperationError extends
 	}
 };
 
+//#endregion
+//#region ../cascade/src/errors/unsupported-lock-for-update.error.ts
+/**
+* Error thrown when `lockForUpdate()` is requested on MongoDB, whose document
+* model has no row-level `SELECT ... FOR UPDATE` equivalent.
+*/
+var UnsupportedLockForUpdateError = class UnsupportedLockForUpdateError extends Error {
+	constructor() {
+		super("lockForUpdate() is unsupported on MongoDB. MongoDB has no row-level SELECT locking. Use a conditional atomic update instead, e.g. Model.atomic({ id, leaseUntil: { $lt: now } }, { $set: { status: \"processing\" } }, { trustedFilter: true }).");
+		this.name = "UnsupportedLockForUpdateError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, UnsupportedLockForUpdateError);
+	}
+};
+
 //#endregion
 //#region ../cascade/src/errors/unsupported-query-operation.error.ts
 /**
@@ -4045,6 +4065,27 @@ function offModelEvent(model, event, listener) {
 	model.events.off(event, listener);
 }
 
+//#endregion
+//#region ../cascade/src/model/generate-model-id.ts
+/**
+* Generate the next model id using the model's configured sequence options.
+*
+* This is shared by normal inserts and MongoDB upserts so both write paths
+* resolve random and configured sequence settings identically.
+*/
+async function generateModelId(ModelClass) {
+	const idGenerator = ModelClass.getDataSource().idGenerator;
+	if (!idGenerator) return;
+	const randomInt = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+	const initialId = ModelClass.initialId ? ModelClass.initialId : ModelClass.randomInitialId ? typeof ModelClass.randomInitialId === "function" ? ModelClass.randomInitialId() : randomInt(1e4, 499999) : 1;
+	const incrementIdBy = ModelClass.randomIncrement ? typeof ModelClass.randomIncrement === "function" ? ModelClass.randomIncrement() : randomInt(1, 10) : ModelClass.incrementIdBy || 1;
+	return await idGenerator.generateNextId({
+		table: ModelClass.table,
+		initialId,
+		incrementIdBy
+	});
+}
+
 //#endregion
 //#region ../cascade/src/validation/database-writer-validation-error.ts
 /**
@@ -4708,15 +4749,8 @@ var DatabaseWriter = class {
 	*/
 	async generateNextId() {
 		if (!this.ctor.autoGenerateId || this.model.get("id")) return;
-		const idGenerator = this.dataSource.idGenerator;
-		if (!idGenerator) return;
-		const initialId = this.resolveInitialId();
-		const incrementIdBy = this.resolveIncrementBy();
-		const id = await idGenerator.generateNextId({
-			table: this.table,
-			initialId,
-			incrementIdBy
-		});
+		const id = await generateModelId(this.ctor);
+		if (id === void 0) return;
 		this.model.set("id", id);
 	}
 	/**
@@ -4763,49 +4797,6 @@ var DatabaseWriter = class {
 		return operations;
 	}
 	/**
-	* Resolve the initial ID from model configuration.
-	*
-	* Priority:
-	* 1. Model.initialId (explicit value)
-	* 2. Model.randomInitialId (random or function)
-	* 3. Default: 1
-	*
-	* @returns The initial ID value
-	* @private
-	*/
-	resolveInitialId() {
-		if (this.ctor.initialId) return this.ctor.initialId;
-		if (this.ctor.randomInitialId) return typeof this.ctor.randomInitialId === "function" ? this.ctor.randomInitialId() : this.randomInt(1e4, 499999);
-		return 1;
-	}
-	/**
-	* Resolve the increment value from model configuration.
-	*
-	* Priority:
-	* 1. Model.incrementIdBy (explicit value)
-	* 2. Model.randomIncrement (random or function)
-	* 3. Default: 1
-	*
-	* @returns The increment value
-	* @private
-	*/
-	resolveIncrementBy() {
-		if (this.ctor.randomIncrement) return typeof this.ctor.randomIncrement === "function" ? this.ctor.randomIncrement() : this.randomInt(1, 10);
-		if (this.ctor.incrementIdBy) return this.ctor.incrementIdBy;
-		return 1;
-	}
-	/**
-	* Generate a random integer between min and max (inclusive).
-	*
-	* @param min - Minimum value
-	* @param max - Maximum value
-	* @returns Random integer
-	* @private
-	*/
-	randomInt(min, max) {
-		return Math.floor(Math.random() * (max - min + 1)) + min;
-	}
-	/**
 	* Trigger sync operations after successful save.
 	*
 	* Emits a model.updated event that ModelSyncOperation listens to.
@@ -5319,6 +5310,26 @@ function toDriverOptions(options) {
 	return rest;
 }
 /**
+* Add the same generated `id` that normal Mongo inserts receive to an upsert's
+* insert branch. `$setOnInsert` keeps an existing document's id immutable.
+*/
+async function withAutoGeneratedUpsertId(ModelClass, filter, operations, options) {
+	if (!options?.upsert || !ModelClass.autoGenerateId || ModelClass.getDriver().name !== "mongodb" || Array.isArray(operations)) return operations;
+	const filterId = filter.id;
+	const filterConstrainsId = Object.hasOwn(filter, "id") && (filterId === null || typeof filterId !== "object" || !Array.isArray(filterId) && Object.hasOwn(filterId, "$eq"));
+	const updateSuppliesId = Object.hasOwn(operations.$set ?? {}, "id") || Object.hasOwn(operations.$setOnInsert ?? {}, "id");
+	if (filterConstrainsId || updateSuppliesId) return operations;
+	const id = await generateModelId(ModelClass);
+	if (id === void 0) return operations;
+	return {
+		...operations,
+		$setOnInsert: {
+			...operations.$setOnInsert,
+			id
+		}
+	};
+}
+/**
 * Pin a driver-level write to the rows the model's global scopes (tenant, soft
 * delete) allow. The driver write APIs take a raw filter and never see scopes,
 * so the target ids are resolved through the scoped query builder and added to
@@ -5352,7 +5363,8 @@ async function performAtomic(ModelClass, filter, operations, options) {
 	const resolved = resolveFilter(filter, options);
 	const scoped = options?.upsert ? await scopeUpsertFilter(ModelClass, resolved) : await scopeWriteFilter(ModelClass, resolved, false);
 	if (!scoped) return 0;
-	const result = await ModelClass.getDriver().atomic(ModelClass.table, scoped, operations, toDriverOptions(options));
+	const upsertOperations = await withAutoGeneratedUpsertId(ModelClass, scoped, operations, options);
+	const result = await ModelClass.getDriver().atomic(ModelClass.table, scoped, upsertOperations, toDriverOptions(options));
 	return result.modifiedCount + (result.upsertedCount ?? 0);
 }
 /**
@@ -5389,7 +5401,8 @@ async function findOneAndUpdateRecord(ModelClass, filter, update, options) {
 	const resolved = resolveFilter(filter, options);
 	const scoped = options?.upsert ? await scopeUpsertFilter(ModelClass, resolved) : await scopeWriteFilter(ModelClass, resolved, true);
 	if (!scoped) return null;
-	const result = await ModelClass.getDriver().findOneAndUpdate(ModelClass.table, scoped, update, toDriverOptions(options));
+	const upsertUpdate = await withAutoGeneratedUpsertId(ModelClass, scoped, update, options);
+	const result = await ModelClass.getDriver().findOneAndUpdate(ModelClass.table, scoped, upsertUpdate, toDriverOptions(options));
 	if (!result) return null;
 	return ModelClass.hydrate(result);
 }
@@ -10466,7 +10479,7 @@ var QueryBuilder = class QueryBuilder {
 	}
 	/** Raw GROUP BY expression. */
 	groupByRaw(expression, bindings) {
-		this.addOperation("groupBy", {
+		this.addOperation("groupByRaw", {
 			expression,
 			bindings: bindings ?? []
 		});
@@ -13583,7 +13596,7 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 	* keeps a queue-claim pattern from silently running unlocked.
 	*/
 	lockForUpdate() {
-		throw new Error("lockForUpdate() is not supported by the MongoDB driver — MongoDB has no row-level SELECT locking. Use an atomic claim instead (e.g. findOneAndUpdate with a reservation filter).");
+		throw new UnsupportedLockForUpdateError();
 	}
 	/**
 	* Executes a callback with the query builder without breaking the chain.
@@ -14390,6 +14403,7 @@ var MongoDbDriver = class {
 	transactionOptions;
 	idGeneratorInstance;
 	_blueprint;
+	monitoredCommands = /* @__PURE__ */ new Map();
 	get blueprint() {
 		if (!this._blueprint) this._blueprint = new MongoDBBlueprint(this.database);
 		return this._blueprint;
@@ -14517,13 +14531,18 @@ var MongoDbDriver = class {
 					_warlock_js_logger.log.warn("database.mongodb", "connection", "Disconnected from database");
 				}
 			});
+			client.on("commandStarted", (event) => this.commandStarted(event));
+			client.on("commandSucceeded", (event) => this.commandSucceeded(event));
+			client.on("commandFailed", (event) => this.commandFailed(event));
 			if (this.config.logging) {
 				const ignoredCommands = [
 					"isMaster",
 					"hello",
 					"ping",
 					"saslStart",
-					"saslContinue"
+					"saslContinue",
+					"endSessions",
+					"buildInfo"
 				];
 				client.on("commandStarted", (event) => {
 					if (ignoredCommands.includes(event.commandName)) return;
@@ -14580,6 +14599,10 @@ var MongoDbDriver = class {
 	on(event, listener) {
 		this.events.on(event, listener);
 	}
+	/** Remove a previously registered driver event listener. */
+	off(event, listener) {
+		this.events.off(event, listener);
+	}
 	/**
 	* Insert a single document into the given collection.
 	*/
@@ -14896,7 +14919,7 @@ var MongoDbDriver = class {
 	*/
 	buildClientOptions() {
 		const baseOptions = { ...this.config.clientOptions ?? {} };
-		if (this.config.logging) baseOptions.monitorCommands = true;
+		if (baseOptions.monitorCommands === void 0) baseOptions.monitorCommands = true;
 		if (this.config.username && !baseOptions.auth) baseOptions.auth = {
 			username: this.config.username,
 			password: this.config.password
@@ -14910,6 +14933,65 @@ var MongoDbDriver = class {
 	emit(event, ...args) {
 		this.events.emit(event, ...args);
 	}
+	commandStarted(event) {
+		if (this.ignoredCommand(event.commandName) || this.events.listenerCount("query") === 0) return;
+		const started = performance.now();
+		const { lsid: _lsid, $clusterTime: _clusterTime, $db: _database, ...pipeline } = event.command;
+		const collection = event.command[event.commandName];
+		this.monitoredCommands.set(event.requestId, {
+			connection: this.name,
+			driver: "mongodb",
+			command: event.commandName,
+			collection: typeof collection === "string" ? collection : void 0,
+			pipeline,
+			started,
+			startedAt: performance.timeOrigin + started
+		});
+	}
+	commandSucceeded(event) {
+		const command = this.monitoredCommands.get(event.requestId);
+		if (!command) return;
+		this.monitoredCommands.delete(event.requestId);
+		const { started, ...query } = command;
+		const rowCount = event.reply?.n ?? event.reply?.cursor?.firstBatch?.length;
+		this.emitQueryEvent({
+			...query,
+			durationMs: performance.now() - started,
+			...typeof rowCount === "number" ? { rowCount } : {}
+		});
+	}
+	commandFailed(event) {
+		const command = this.monitoredCommands.get(event.requestId);
+		if (!command) return;
+		this.monitoredCommands.delete(event.requestId);
+		const { started, ...query } = command;
+		this.emitQueryEvent({
+			...query,
+			durationMs: performance.now() - started,
+			error: event.failure
+		});
+	}
+	/**
+	* Emit a `query` event. It runs inside the MongoDB client's own monitoring
+	* callback, and an observer must never break the client, so a throwing
+	* listener is swallowed here.
+	*/
+	emitQueryEvent(event) {
+		try {
+			this.emit("query", event);
+		} catch {}
+	}
+	ignoredCommand(command) {
+		return [
+			"isMaster",
+			"hello",
+			"ping",
+			"saslStart",
+			"saslContinue",
+			"endSessions",
+			"buildInfo"
+		].includes(command);
+	}
 	/**
 	* Ensure MongoDB is running as a replica set (required for transactions).
 	*
@@ -17315,12 +17397,11 @@ var PostgresQueryParser = class PostgresQueryParser {
 		const columns = Array.isArray(fields) ? fields : [fields];
 		this.groupColumns.push(...columns);
 	}
-	/**
-	* Process a raw GROUP BY expression (emitted verbatim, no quoting). Used by
-	* `groupByDate` to add a `date_trunc(...)` bucket to the GROUP BY clause.
-	*/
+	/** Process a raw GROUP BY expression, binding `?` placeholders positionally. */
 	processGroupByRaw(data) {
-		const expression = data.expression;
+		let expression = data.expression;
+		const bindings = data.bindings ?? [];
+		for (const binding of bindings) expression = expression.replace("?", this.addParam(binding));
 		this.groupRawExpressions.push(expression);
 	}
 	/**
@@ -19323,6 +19404,13 @@ var PostgresDriver = class {
 		if (!this._eventListeners.has(event)) this._eventListeners.set(event, /* @__PURE__ */ new Set());
 		this._eventListeners.get(event).add(listener);
 	}
+	/** Remove a previously registered driver event listener. */
+	off(event, listener) {
+		const listeners = this._eventListeners.get(event);
+		if (!listeners) return;
+		listeners.delete(listener);
+		if (listeners.size === 0) this._eventListeners.delete(event);
+	}
 	/**
 	* Serialize data for storage in PostgreSQL.
 	*
@@ -19824,12 +19912,12 @@ var PostgresDriver = class {
 			if (options?.isolationLevel) beginSql += ` ISOLATION LEVEL ${options.isolationLevel.toUpperCase()}`;
 			if (options?.readOnly) beginSql += " READ ONLY";
 			if (options?.deferrable) beginSql += " DEFERRABLE";
-			await client.query(beginSql);
+			await this.executePostgresQuery(() => client.query(beginSql), beginSql);
 			transactionStarted = true;
-			for (const [name, value] of settings) await client.query("SELECT set_config($1, $2, true)", [name, String(value)]);
+			for (const [name, value] of settings) await this.executePostgresQuery(() => client.query("SELECT set_config($1, $2, true)", [name, String(value)]), "SELECT set_config($1, $2, true)", [name, String(value)]);
 		} catch (error) {
 			if (transactionStarted) try {
-				await client.query("ROLLBACK");
+				await this.executePostgresQuery(() => client.query("ROLLBACK"), "ROLLBACK");
 			} catch {}
 			client.release(error instanceof Error ? error : new Error(String(error)));
 			throw error;
@@ -19838,7 +19926,7 @@ var PostgresDriver = class {
 			context: client,
 			commit: async () => {
 				try {
-					await client.query("COMMIT");
+					await this.executePostgresQuery(() => client.query("COMMIT"), "COMMIT");
 				} catch (error) {
 					client.release(error instanceof Error ? error : new Error(String(error)));
 					throw error;
@@ -19847,7 +19935,7 @@ var PostgresDriver = class {
 			},
 			rollback: async () => {
 				try {
-					await client.query("ROLLBACK");
+					await this.executePostgresQuery(() => client.query("ROLLBACK"), "ROLLBACK");
 				} catch (error) {
 					client.release(error instanceof Error ? error : new Error(String(error)));
 					throw error;
@@ -20080,8 +20168,8 @@ var PostgresDriver = class {
 					paramCount: params.length
 				}
 			});
-			if (txClient) result = await txClient.query(sql, params);
-			else result = await this.pool.query(sql, params);
+			if (txClient) result = await this.executePostgresQuery(() => txClient.query(sql, params), sql, params);
+			else result = await this.executePostgresQuery(() => this.pool.query(sql, params), sql, params);
 			if (this.config.logging) {
 				const duration = (performance.now() - startTime).toFixed(2);
 				_warlock_js_logger.log.success({
@@ -20114,6 +20202,47 @@ var PostgresDriver = class {
 			throw error;
 		}
 	}
+	/** Execute SQL and emit its public query event when the event is observed. */
+	async executePostgresQuery(execute, sql, bindings = []) {
+		if (!this._eventListeners.get("query")?.size) return execute();
+		const started = performance.now();
+		const startedAt = performance.timeOrigin + started;
+		let result;
+		try {
+			result = await execute();
+		} catch (error) {
+			this.emitQueryEvent({
+				connection: this.name,
+				driver: "postgres",
+				sql,
+				bindings,
+				durationMs: performance.now() - started,
+				startedAt,
+				error
+			});
+			throw error;
+		}
+		const event = {
+			connection: this.name,
+			driver: "postgres",
+			sql,
+			bindings,
+			durationMs: performance.now() - started,
+			startedAt
+		};
+		if (typeof result.rowCount === "number") event.rowCount = result.rowCount;
+		this.emitQueryEvent(event);
+		return result;
+	}
+	/**
+	* Emit a `query` event. An observer is never allowed to fail the query it
+	* observes, so a throwing listener is swallowed here.
+	*/
+	emitQueryEvent(event) {
+		try {
+			this.emit("query", event);
+		} catch {}
+	}
 	/**
 	* Emit an event to all registered listeners.
 	*
@@ -25321,6 +25450,7 @@ exports.UndefinedWhereValueError = UndefinedWhereValueError;
 exports.UnsafeFilterError = UnsafeFilterError;
 exports.UnsafeRawExpressionError = UnsafeRawExpressionError;
 exports.UnsupportedLeanOperationError = UnsupportedLeanOperationError;
+exports.UnsupportedLockForUpdateError = UnsupportedLockForUpdateError;
 exports.UnsupportedQueryOperationError = UnsupportedQueryOperationError;
 exports.UnsupportedUpdateOperationError = UnsupportedUpdateOperationError;
 exports.afterCommit = afterCommit;