@warlock.js/cascade 5.23.2 → 5.25.0

package/README.md

@@ -1,102 +1,102 @@
-# cascade
-
-A powerful, model-first TypeScript ORM for **MongoDB and PostgreSQL** on `Node.js`.
-
-## Features
-
-Cascade is a unified ORM for MongoDB and PostgreSQL — one model-first API runs against both engines. Define a model once (its `@warlock.js/seal` schema doubles as the TypeScript type, the runtime validator, and the DB shape) and query straight off the class. It's fast, type-safe, and built for real-world apps.
-
-Some but not all of the features:
-
-
-- **Easy to use:** `Cascade` is very easy to use, it's just a wrapper around MongoDB driver.
-- **Supports multiple connections:** You can perform multiple connections to different MongoDB connections and use each one of them separately.
-- **Supports multiple databases:** `Cascade` supports multiple databases, you can connect to multiple databases at the same time.
-- **Powerful Aggregate framework:** `Cascade` has a powerful aggregate framework that helps you to perform complex queries.
-- **Basic CRUD operations:** `Cascade` supports basic CRUD operations, you can perform create, read, update and delete operations.
-- **Events Driven:** `Cascade` is events driven, you can listen to events and perform actions, for example before creating, updating or deleting a document.
-- **Powerful Models:** `Cascade` has a powerful models system, a Model is a collection manager document based, it manages a collection's document easily with many utilities.
-- **Learning curve:** `Cascade` has a very small learning curve, you can learn it in few minutes.
-- **Pagination support:** `Cascade` supports pagination, you can paginate your results easily.
-- **Output formatting:** `Cascade` supports output formatting, you can format your output easily when model is sent as a response.
-- **Auto incremented id:** `Cascade` supports auto incremented id, you can use it as a primary key for your documents.
-- **Random or sequential id:** `Cascade` supports random or sequential id.
-- **Recycle Bin:** Reduce collection documents by removing the document entirely from the collection, but move it to a separate collection trash.
-- **Migration system:** `Cascade` has a migration system, you can create migrations and run them easily.
-- **Data casting:** You can cast your data to a specific type or using custom casting.
-- **Embedded documents:** `Cascade` supports single and multiple embedded documents, you can embed documents inside other documents.
-- **Syncing Models**: Auto update documents when model's data is updated or deleted.
-
-
-## Server-only
-
-`@warlock.js/cascade`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. `@warlock.js/web`'s build treats this as a boundary: app client code cannot value-import this package (type-only imports are still allowed), while server loaders/controllers/modules can import it freely.
-
-## Installation
-
-```bash
-npm i @warlock.js/cascade
-```
-
-Using yarn:
-
-```bash
-yarn add @warlock.js/cascade
-```
-
-Using pnpm:
-
-```bash
-pnpm add @warlock.js/cascade
-```
-
-
-## Peek inside cascade
-
-Here is a simple example of defining a User model:
-
-```ts title="src/models/user.ts"
-import { Model, RegisterModel } from "@warlock.js/cascade";
-
-@RegisterModel()
-export class User extends Model {
-  /**
-   * The table / collection name.
-   * Must be defined explicitly.
-   */
-  public static table = "users";
-}
-```
-
-A quick example of creating a user:
-
-```ts title="src/controllers/users.ts"
-import { User } from "src/models/user";
-
-export async function createUser() {
-  const user = await User.create({
-    name: "Hasan Zohdy",
-    email: "hassanzohdy@gmail.com",
-  });
-
-  console.log(user.data);
-}
-```
-
-Outputs something similar to:
-
-```json
-{
-  "id": 1231412,
-  "_id": "fagtrw43qwedasjoijwq",
-  "name": "Hasan Zohdy",
-  "email": "hassanzohdy@gmail.com",
-  "createdAt": "2023-06-01 00:00:00",
-  "updatedAt": "2023-06-01 00:00:00"
-}
-```
-
-
-## Documentation
-
+# cascade
+
+A powerful, model-first TypeScript ORM for **MongoDB and PostgreSQL** on `Node.js`.
+
+## Features
+
+Cascade is a unified ORM for MongoDB and PostgreSQL — one model-first API runs against both engines. Define a model once (its `@warlock.js/seal` schema doubles as the TypeScript type, the runtime validator, and the DB shape) and query straight off the class. It's fast, type-safe, and built for real-world apps.
+
+Some but not all of the features:
+
+
+- **Easy to use:** `Cascade` is very easy to use, it's just a wrapper around MongoDB driver.
+- **Supports multiple connections:** You can perform multiple connections to different MongoDB connections and use each one of them separately.
+- **Supports multiple databases:** `Cascade` supports multiple databases, you can connect to multiple databases at the same time.
+- **Powerful Aggregate framework:** `Cascade` has a powerful aggregate framework that helps you to perform complex queries.
+- **Basic CRUD operations:** `Cascade` supports basic CRUD operations, you can perform create, read, update and delete operations.
+- **Events Driven:** `Cascade` is events driven, you can listen to events and perform actions, for example before creating, updating or deleting a document.
+- **Powerful Models:** `Cascade` has a powerful models system, a Model is a collection manager document based, it manages a collection's document easily with many utilities.
+- **Learning curve:** `Cascade` has a very small learning curve, you can learn it in few minutes.
+- **Pagination support:** `Cascade` supports pagination, you can paginate your results easily.
+- **Output formatting:** `Cascade` supports output formatting, you can format your output easily when model is sent as a response.
+- **Auto incremented id:** `Cascade` supports auto incremented id, you can use it as a primary key for your documents.
+- **Random or sequential id:** `Cascade` supports random or sequential id.
+- **Recycle Bin:** Reduce collection documents by removing the document entirely from the collection, but move it to a separate collection trash.
+- **Migration system:** `Cascade` has a migration system, you can create migrations and run them easily.
+- **Data casting:** You can cast your data to a specific type or using custom casting.
+- **Embedded documents:** `Cascade` supports single and multiple embedded documents, you can embed documents inside other documents.
+- **Syncing Models**: Auto update documents when model's data is updated or deleted.
+
+
+## Server-only
+
+`@warlock.js/cascade`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. `@warlock.js/web`'s build treats this as a boundary: app client code cannot value-import this package (type-only imports are still allowed), while server loaders/controllers/modules can import it freely.
+
+## Installation
+
+```bash
+npm i @warlock.js/cascade
+```
+
+Using yarn:
+
+```bash
+yarn add @warlock.js/cascade
+```
+
+Using pnpm:
+
+```bash
+pnpm add @warlock.js/cascade
+```
+
+
+## Peek inside cascade
+
+Here is a simple example of defining a User model:
+
+```ts title="src/models/user.ts"
+import { Model, RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Model {
+  /**
+   * The table / collection name.
+   * Must be defined explicitly.
+   */
+  public static table = "users";
+}
+```
+
+A quick example of creating a user:
+
+```ts title="src/controllers/users.ts"
+import { User } from "src/models/user";
+
+export async function createUser() {
+  const user = await User.create({
+    name: "Hasan Zohdy",
+    email: "hassanzohdy@gmail.com",
+  });
+
+  console.log(user.data);
+}
+```
+
+Outputs something similar to:
+
+```json
+{
+  "id": 1231412,
+  "_id": "fagtrw43qwedasjoijwq",
+  "name": "Hasan Zohdy",
+  "email": "hassanzohdy@gmail.com",
+  "createdAt": "2023-06-01 00:00:00",
+  "updatedAt": "2023-06-01 00:00:00"
+}
+```
+
+
+## Documentation
+
 To see the full documentation, please visit [Cascade Documentation](https://warlock.js.org/docs/cascade/getting-started/introduction) 

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
 /**
@@ -4589,6 +4630,7 @@ var DatabaseWriter = class {
 		else {
 			const validated = result.data;
 			for (const column of Object.keys(dataToValidate)) if (column in validated) this.model.set(column, validated[column]);
+			else if (dataToValidate[column] === null && column in validationSchema.schema) this.model.set(column, null);
 			else this.unvalidatedColumns.add(column);
 		}
 		if (!options.skipEvents) await this.model.emitEvent("validated", { result });
@@ -4707,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);
 	}
 	/**
@@ -4762,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.
@@ -5318,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
@@ -5351,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);
 }
 /**
@@ -5388,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);
 }
@@ -10465,7 +10479,7 @@ var QueryBuilder = class QueryBuilder {
 	}
 	/** Raw GROUP BY expression. */
 	groupByRaw(expression, bindings) {
-		this.addOperation("groupBy", {
+		this.addOperation("groupByRaw", {
 			expression,
 			bindings: bindings ?? []
 		});
@@ -13582,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.
@@ -14389,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;
@@ -14516,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;
@@ -14579,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.
 	*/
@@ -14895,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
@@ -14909,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).
 	*
@@ -17314,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);
 	}
 	/**
@@ -19322,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.
 	*
@@ -19814,14 +19903,22 @@ var PostgresDriver = class {
 	* @returns Transaction contract with commit/rollback methods
 	*/
 	async beginTransaction(options) {
+		const settings = Object.entries(options?.settings ?? {});
+		for (const [name] of settings) if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name)) throw new Error(`Invalid PostgreSQL transaction setting name: "${name}"`);
 		const client = await this.pool.connect();
+		let transactionStarted = false;
 		try {
 			let beginSql = "BEGIN";
 			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 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 this.executePostgresQuery(() => client.query("ROLLBACK"), "ROLLBACK");
+			} catch {}
 			client.release(error instanceof Error ? error : new Error(String(error)));
 			throw error;
 		}
@@ -19829,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;
@@ -19838,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;
@@ -20071,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({
@@ -20105,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.
 	*
@@ -25312,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;