@warlock.js/cascade 4.4.0 → 4.6.0

package/cjs/index.cjs

@@ -196,6 +196,28 @@ var DataSource = class {
 		const driver = this.driver;
 		if (typeof driver.getIdGenerator === "function") return driver.getIdGenerator();
 	}
+	/**
+	* Execute a raw query against this data source's driver.
+	*
+	* Thin passthrough to `driver.query`, so it is transaction-aware: inside a
+	* `transaction()` scope the query auto-joins the active transaction
+	* client/session.
+	*
+	* @typeParam T - The expected row shape.
+	* @param sql - Raw SQL string (driver dialect).
+	* @param params - Optional positional query parameters.
+	* @returns The driver's raw query result (`rows` + `rowCount`).
+	*
+	* @example
+	* ```typescript
+	* const { rows } = await dataSource.raw<{ count: number }>(
+	*   "SELECT COUNT(*)::int AS count FROM users",
+	* );
+	* ```
+	*/
+	raw(sql, params) {
+		return this.driver.query(sql, params);
+	}
 };
 
 //#endregion
@@ -3862,13 +3884,14 @@ var DatabaseWriter = class {
 			mode: isInsert ? "insert" : "update"
 		});
 		if (options.skipValidation || !this.schema) return;
-		const validationSchema = isInsert ? this.schema.clone() : this.schema.clone(Object.keys(this.model.data)).extend({
+		const systemColumns = {
 			id: _warlock_js_seal.v.scalar().optional(),
 			_id: _warlock_js_seal.v.any().optional(),
 			...(0, _mongez_reinforcements.when)(this.ctor.createdAtColumn, () => ({ [this.ctor.createdAtColumn]: _warlock_js_seal.v.date().optional() })),
 			...(0, _mongez_reinforcements.when)(this.ctor.updatedAtColumn, () => ({ [this.ctor.updatedAtColumn]: _warlock_js_seal.v.date().optional() })),
 			...(0, _mongez_reinforcements.when)(this.ctor.deletedAtColumn, () => ({ [this.ctor.deletedAtColumn]: _warlock_js_seal.v.date().optional() }))
-		});
+		};
+		const validationSchema = isInsert ? this.schema.clone().extend(systemColumns) : this.schema.clone(Object.keys(this.model.data)).extend(systemColumns);
 		if (this.strictMode === "strip") validationSchema.stripUnknown();
 		else if (this.strictMode === "fail") validationSchema.allowUnknown(false);
 		else if (this.strictMode === "allow") validationSchema.allowUnknown(true);
@@ -3899,7 +3922,7 @@ var DatabaseWriter = class {
 		await this.generateNextId();
 		const dataToInsert = this.model.data;
 		const createdAtColumn = this.ctor.createdAtColumn;
-		if (createdAtColumn) dataToInsert[createdAtColumn] = /* @__PURE__ */ new Date();
+		if (createdAtColumn && dataToInsert[createdAtColumn] == null) dataToInsert[createdAtColumn] = /* @__PURE__ */ new Date();
 		const updatedAtColumn = this.ctor.updatedAtColumn;
 		if (updatedAtColumn) dataToInsert[updatedAtColumn] = /* @__PURE__ */ new Date();
 		if (!options.skipEvents) await this.model.emitEvent("creating");
@@ -4857,6 +4880,16 @@ function getGlobalEvents() {
 
 //#endregion
 //#region ../@warlock.js/cascade/src/model/methods/write-methods.ts
+/**
+* Default number of rows processed per chunk by {@link createManyRecords}.
+*
+* Chunking keeps a single huge `createMany` call from flooding the driver:
+* the default path runs each chunk's `save()` calls under one `Promise.all`,
+* and the bulk path emits one multi-row `insertMany` per chunk so the
+* generated `INSERT ... VALUES (...),(...)` stays under the database's bind
+* parameter ceiling.
+*/
+const DEFAULT_CREATE_MANY_BATCH_SIZE = 500;
 async function saveModel(model, options) {
 	if (options?.merge) model.merge(options.merge);
 	await new DatabaseWriter(model).save(options);
@@ -4867,8 +4900,160 @@ async function createRecord(ModelClass, data) {
 	await model.save();
 	return model;
 }
-async function createManyRecords(ModelClass, data) {
-	return await Promise.all(data.map((item) => createRecord(ModelClass, item)));
+/**
+* Split an array into sequential chunks of at most `size` elements.
+*
+* @param items - The array to split.
+* @param size - Maximum chunk length (callers pass a value `>= 1`).
+* @returns An array of chunks preserving the original order.
+*/
+function chunkArray(items, size) {
+	const chunks = [];
+	for (let index = 0; index < items.length; index += size) chunks.push(items.slice(index, index + size));
+	return chunks;
+}
+/**
+* Create many records, chunking the work so a huge array can't overwhelm the
+* driver.
+*
+* Two strategies are available via `options.bulk`:
+*
+* - **Default (`bulk` falsy):** each row is persisted through `save()`, so
+*   model hooks, lifecycle events, casts and generated ids are all preserved.
+*   Rows are processed in sequential chunks of `batchSize`, each chunk running
+*   under a single `Promise.all`, so an array of millions of rows can't open
+*   millions of concurrent inserts at once.
+*
+* - **Bulk (`bulk: true`):** each chunk is routed to the driver's native
+*   multi-row insert (`insertMany`) for 10–100× throughput. This SKIPS the
+*   per-row save lifecycle (no `saving` / `creating` / `created` / `saved`
+*   events, hooks, or sync). Rows are still prepped through the writer
+*   pipeline (validation, casting, timestamps, defaults, id-generation) so the
+*   persisted columns match the default path, and the values returned by the
+*   driver (generated `_id`, timestamps, SQL `RETURNING *`) are merged back
+*   onto the returned models.
+*
+* Both strategies return the created model instances (an empty array is a
+* no-op that never touches the driver).
+*
+* @param ModelClass - The model class to create records for.
+* @param data - The rows to insert.
+* @param options - Chunking / bulk options.
+* @returns The created model instances.
+*
+* @example
+* ```typescript
+* // Default: per-row save(), chunked in batches of 500
+* const users = await User.createMany(rows);
+*
+* // Bulk: one multi-row INSERT per 1000-row chunk (skips per-row hooks)
+* const users = await User.createMany(rows, { bulk: true, batchSize: 1000 });
+* ```
+*/
+async function createManyRecords(ModelClass, data, options = {}) {
+	if (data.length === 0) return [];
+	const chunks = chunkArray(data, options.batchSize && options.batchSize > 0 ? options.batchSize : 500);
+	if (options.bulk === true) return await createManyBulk(ModelClass, chunks);
+	const created = [];
+	for (const chunk of chunks) {
+		const models = chunk.map((item) => new ModelClass(item));
+		await assignIdBlock(ModelClass, models);
+		const chunkModels = await Promise.all(models.map(async (model) => {
+			await model.save();
+			return model;
+		}));
+		created.push(...chunkModels);
+	}
+	return created;
+}
+/**
+* Reserve a single contiguous id block for one chunk and pre-assign the ids to
+* the models that don't already carry one, so the per-row writer's id
+* generation no-ops (its `model.get("id")` guard short-circuits). This turns N
+* per-row counter round-trips into ONE per chunk.
+*
+* Falls back to per-row generation (a no-op here) when:
+* - the model disables auto-generation (`autoGenerateId === false`) — e.g. SQL,
+*   which uses native `SERIAL`;
+* - the data source's id generator has no batch API (`generateNextIds`) — the
+*   optional contract member is feature-detected;
+* - the model uses a random initial id / increment — a random stride can't form
+*   a contiguous block, so those models keep per-row generation.
+*
+* Only models WITHOUT a caller-supplied id consume a block slot, so a chunk
+* mixing supplied and auto ids allocates exactly the right number (no gaps).
+*
+* @param ModelClass - The model class being inserted.
+* @param models - The freshly-constructed (unsaved) models for one chunk.
+*/
+async function assignIdBlock(ModelClass, models) {
+	if (!ModelClass.autoGenerateId || ModelClass.randomInitialId || ModelClass.randomIncrement) return;
+	const idGenerator = ModelClass.getDataSource().idGenerator;
+	if (!idGenerator || typeof idGenerator.generateNextIds !== "function") return;
+	const idLessModels = models.filter((model) => !model.get("id"));
+	if (idLessModels.length === 0) return;
+	const ids = await idGenerator.generateNextIds({
+		table: ModelClass.table,
+		initialId: ModelClass.initialId || 1,
+		incrementIdBy: ModelClass.incrementIdBy || 1,
+		count: idLessModels.length
+	});
+	if (ids.length !== idLessModels.length) throw new Error(`generateNextIds returned ${ids.length} id(s) for ${idLessModels.length} row(s) on "${ModelClass.table}" — a batch id generator must return exactly the requested count.`);
+	idLessModels.forEach((model, index) => {
+		model.set("id", ids[index]);
+	});
+}
+/**
+* Bulk variant of {@link createManyRecords}: prep each row through the writer
+* pipeline (validation, casting, timestamps, defaults, id-generation) without
+* touching the database, then flush each chunk with a single
+* `driver.insertMany` call.
+*
+* The writer reuse is achieved by swapping the driver's single-row `insert`
+* for a capturing stub for the lifetime of the bulk operation: running
+* `writer.save({ skipEvents, skipSync })` exercises the real prep but records
+* the prepared document instead of issuing N single-row inserts. The original
+* `insert` is always restored in `finally`.
+*
+* @param ModelClass - The model class to create records for.
+* @param chunks - Pre-chunked rows.
+* @returns The created model instances with driver-returned values merged in.
+*/
+async function createManyBulk(ModelClass, chunks) {
+	const driver = ModelClass.getDataSource().driver;
+	const table = ModelClass.table;
+	const originalInsert = driver.insert;
+	driver.insert = (async (_table, document) => {
+		return { document };
+	});
+	const created = [];
+	try {
+		for (const chunk of chunks) {
+			const models = chunk.map((item) => new ModelClass(item));
+			await assignIdBlock(ModelClass, models);
+			const preparedDocuments = await Promise.all(models.map(async (model) => {
+				await new DatabaseWriter(model).save({
+					skipEvents: true,
+					skipSync: true
+				});
+				return { ...model.data };
+			}));
+			const results = await driver.insertMany(table, preparedDocuments);
+			models.forEach((model, index) => {
+				const result = results[index];
+				if (result) {
+					const returnedDocument = "document" in result ? result.document : result;
+					model.merge(returnedDocument);
+				}
+				model.dirtyTracker.reset();
+				model.isNew = false;
+			});
+			created.push(...models);
+		}
+	} finally {
+		driver.insert = originalInsert;
+	}
+	return created;
 }
 async function findOrCreateRecord(ModelClass, filter, data) {
 	const existing = await ModelClass.first(filter);
@@ -5760,6 +5945,39 @@ var Model = class Model {
 		return this.getDataSource().driver;
 	}
 	/**
+	* Execute a raw query against this model's driver.
+	*
+	* Delegates to `getDriver().query`, so it inherits the driver's
+	* transaction awareness: when called inside an active `transaction()`
+	* scope the query auto-joins that transaction's client/session, otherwise
+	* it runs on the pool. The return value is the driver's raw result
+	* ({@link RawQueryResult}) — `rows` typed as `T` plus `rowCount` — not
+	* hydrated model instances.
+	*
+	* Note: MongoDB drivers throw, as they do not support raw SQL.
+	*
+	* @typeParam T - The expected row shape.
+	* @param sql - Raw SQL string (driver dialect).
+	* @param params - Optional positional query parameters.
+	* @returns The driver's raw query result.
+	*
+	* @example
+	* ```typescript
+	* const { rows } = await User.raw<{ id: number; total: number }>(
+	*   "SELECT id, COUNT(*) AS total FROM orders WHERE user_id = $1 GROUP BY id",
+	*   [userId],
+	* );
+	*
+	* // Auto-joins the active transaction() scope:
+	* await User.transaction(async () => {
+	*   await User.raw("UPDATE users SET active = true WHERE id = $1", [id]);
+	* });
+	* ```
+	*/
+	static raw(sql, params) {
+		return this.getDriver().query(sql, params);
+	}
+	/**
 	* Generate next id and set it to current model's id
 	*/
 	async generateNextId() {
@@ -6297,10 +6515,39 @@ var Model = class Model {
 		return createRecord(this, data);
 	}
 	/**
-	* Create many documents and return an array of created models
+	* Create many records and return an array of created models.
+	*
+	* The work is always chunked into batches of `options.batchSize`
+	* (default 500) so a huge input array can't overwhelm the driver.
+	*
+	* **Default path** (no options, or `bulk` falsy): each row is persisted
+	* through `save()`, preserving model hooks, lifecycle events, casts and
+	* generated ids. Each chunk runs under a single `Promise.all`.
+	*
+	* **Bulk path** (`bulk: true`): each chunk is routed to the driver's native
+	* multi-row insert (`insertMany`) for 10–100× throughput. This SKIPS the
+	* per-row save lifecycle (no `saving` / `creating` / `created` / `saved`
+	* events, hooks, or sync). Casts, timestamps, defaults and id-generation are
+	* still applied (rows are prepped through the same writer pipeline) so the
+	* persisted columns match the default path.
+	*
+	* An empty array is a no-op that never touches the driver.
+	*
+	* @param data - The rows to insert.
+	* @param options - Chunking / bulk options.
+	* @returns The created model instances.
+	*
+	* @example
+	* ```typescript
+	* // Default: per-row save(), chunked in batches of 500
+	* const users = await User.createMany(rows);
+	*
+	* // Bulk: one multi-row INSERT per 1000-row chunk (skips per-row hooks)
+	* const users = await User.createMany(rows, { bulk: true, batchSize: 1000 });
+	* ```
 	*/
-	static async createMany(data) {
-		return createManyRecords(this, data);
+	static async createMany(data, options) {
+		return createManyRecords(this, data, options);
 	}
 	/**
 	* Find a record or create it if not found.
@@ -6699,26 +6946,99 @@ const $agg = {
 		};
 	},
 	/**
-	* Sum a numeric field across documents in each group.
+	* Count the number of distinct values of a field in each group.
 	*
-	* @param field - The field name to sum
+	* @param field - The field name to count distinct values of
+	* @returns Abstract count-distinct expression
+	*
+	* @example
+	* ```typescript
+	* query.groupBy("country", {
+	*   uniqueCities: $agg.countDistinct("city")
+	* });
+	* ```
+	*
+	* **Cross-driver.** Translates to:
+	* - SQL: `COUNT(DISTINCT city)`
+	* - MongoDB: `{ $addToSet: "$city" }` in the `$group` stage, finalized with
+	*   `{ $size: "$uniqueCities" }` in the renaming `$project` (the standard
+	*   distinct-count-per-group pattern, since `$size` is not a `$group`
+	*   accumulator).
+	*/
+	countDistinct(field) {
+		return {
+			__agg: "countDistinct",
+			__field: field
+		};
+	},
+	/**
+	* Sum a numeric field — or a composed arithmetic expression — across
+	* documents in each group.
+	*
+	* Pass a bare column name to sum a single field (unchanged from v1), or a
+	* typed `$expr` node (`$expr.mul` / `$expr.add` / `$expr.sub` / `$expr.div` /
+	* `$expr.col` / `$expr.lit`) to sum a computed value such as `price * quantity`.
+	*
+	* @param input - A field name or a typed `ColumnExpression`
 	* @returns Abstract sum expression
 	*
 	* @example
 	* ```typescript
+	* import { $agg, $expr } from "@warlock.js/cascade";
+	*
+	* // Bare column
+	* query.groupBy("type", { totalDuration: $agg.sum("duration") });
+	*
+	* // Composed expression: SUM(price * quantity)
+	* query.groupBy("type", { revenue: $agg.sum($expr.mul("price", "quantity")) });
+	* ```
+	*
+	* Translates to:
+	* - SQL: `SUM("duration")` / `SUM(("price" * "quantity"))`
+	* - MongoDB: `{ $sum: "$duration" }` / `{ $sum: { $multiply: ["$price", "$quantity"] } }`
+	*/
+	sum(input) {
+		if (typeof input === "string") return {
+			__agg: "sum",
+			__field: input
+		};
+		return {
+			__agg: "sum",
+			__field: null,
+			__expr: input
+		};
+	},
+	/**
+	* Sum a raw, driver-native expression escape hatch.
+	*
+	* Equivalent to `$agg.sum($expr.raw(expression))`. The raw string is emitted
+	* verbatim into the generated query — never build it from untrusted input.
+	* Reach for the typed {@link sum} form first; this exists only for fragments
+	* the typed combinators can't express.
+	*
+	* @param expression - A raw expression fragment (e.g. `"price * quantity"`)
+	* @returns Abstract sum expression wrapping the raw fragment
+	*
+	* @example
+	* ```typescript
 	* query.groupBy("type", {
-	*   totalDuration: $agg.sum("duration")
+	*   net: $agg.sumRaw("price * quantity * (1 - discount)"),
 	* });
 	* ```
 	*
 	* Translates to:
-	* - MongoDB: `{ $sum: "$duration" }`
-	* - SQL: `SUM(duration)`
+	* - SQL: `SUM(price * quantity * (1 - discount))`
+	* - MongoDB: throws — raw SQL fragments are not portable to a pipeline; use
+	*   the typed {@link sum} form (or `groupByRaw`) on MongoDB instead.
 	*/
-	sum(field) {
+	sumRaw(expression) {
 		return {
 			__agg: "sum",
-			__field: field
+			__field: null,
+			__expr: {
+				__expr: "raw",
+				expression
+			}
 		};
 	},
 	/**
@@ -6891,6 +7211,156 @@ const $agg = {
 	}
 };
 
+//#endregion
+//#region ../@warlock.js/cascade/src/expressions/column-expressions.ts
+/**
+* Type guard: is `value` one of the typed column-expression nodes?
+*
+* @param value - The value to test
+* @returns `true` when `value` is a `ColumnExpression` node
+*/
+function isColumnExpression(value) {
+	return typeof value === "object" && value !== null && typeof value.__expr === "string";
+}
+/**
+* Reference a column/field by name.
+*
+* @param column - The column/field name
+* @returns A column-reference expression node
+*/
+function col(column) {
+	return {
+		__expr: "column",
+		column
+	};
+}
+/**
+* A scalar literal (number or boolean) operand.
+*
+* @param value - The literal value
+* @returns A literal expression node
+*/
+function lit(value) {
+	return {
+		__expr: "literal",
+		value
+	};
+}
+/**
+* Multiply two or more operands.
+*
+* @param operands - Column names, literals, or nested expression nodes
+* @returns A multiply expression node
+*/
+function mul(...operands) {
+	return {
+		__expr: "multiply",
+		operands: operands.map(toColumnExpression)
+	};
+}
+/**
+* Add two or more operands.
+*
+* @param operands - Column names, literals, or nested expression nodes
+* @returns An add expression node
+*/
+function add(...operands) {
+	return {
+		__expr: "add",
+		operands: operands.map(toColumnExpression)
+	};
+}
+/**
+* Subtract `right` from `left`.
+*
+* @param left - The minuend
+* @param right - The subtrahend
+* @returns A subtract expression node
+*/
+function sub(left, right) {
+	return {
+		__expr: "subtract",
+		operands: [toColumnExpression(left), toColumnExpression(right)]
+	};
+}
+/**
+* Divide `left` by `right`.
+*
+* @param left - The dividend
+* @param right - The divisor
+* @returns A divide expression node
+*/
+function div(left, right) {
+	return {
+		__expr: "divide",
+		operands: [toColumnExpression(left), toColumnExpression(right)]
+	};
+}
+/**
+* Wrap a raw expression string as an escape hatch.
+*
+* The string is emitted verbatim — never build it from untrusted input. Use
+* this only when the typed `$expr.mul` / `$expr.add` / `$expr.sub` /
+* `$expr.div` / `$expr.col` / `$expr.lit` combinators can't express what you
+* need.
+*
+* @param expression - A raw, driver-native expression fragment
+* @returns A raw expression node
+*/
+function raw(expression) {
+	return {
+		__expr: "raw",
+		expression
+	};
+}
+/**
+* Normalize an expression input to a `ColumnExpression` node. A bare string
+* becomes a `$expr.col(...)` reference; an existing node passes through
+* unchanged.
+*
+* @param input - A typed expression node or a bare column-name string
+* @returns The corresponding `ColumnExpression` node
+*/
+function toColumnExpression(input) {
+	return typeof input === "string" ? col(input) : input;
+}
+/**
+* Typed, database-agnostic column-expression builders.
+*
+* Grouped under one object (like `$agg`) so the scalar arithmetic that feeds
+* an aggregate reads as a single, discoverable namespace: `$agg.sum($expr.mul(
+* "price", "quantity"))`. Each builder returns a plain, closed `ColumnExpression`
+* node — the driver translates it to native SQL / a Mongo pipeline.
+*
+* @example
+* ```typescript
+* import { $agg, $expr } from "@warlock.js/cascade";
+*
+* // SUM(price * quantity)
+* query.groupBy("product_id", { revenue: $agg.sum($expr.mul("price", "quantity")) });
+*
+* // SUM((1 - discount) * price)
+* query.groupBy("product_id", {
+*   net: $agg.sum($expr.mul($expr.sub($expr.lit(1), "discount"), "price")),
+* });
+*
+* // price * 1.2 (e.g. tax)
+* $agg.sum($expr.mul("price", $expr.lit(1.2)));
+*
+* // escape hatch (Postgres-only, emitted verbatim — never from user input)
+* $agg.sum($expr.raw("price * quantity * (1 - discount)"));
+* ```
+*/
+const $expr = {
+	col,
+	lit,
+	mul,
+	add,
+	sub,
+	div,
+	raw
+};
+
 //#endregion
 //#region ../@warlock.js/cascade/src/utils/is-valid-date-value.ts
 const isoRegex = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?)?$/;
@@ -6963,43 +7433,54 @@ var MongoDBBlueprint = class {
 
 //#endregion
 //#region ../@warlock.js/cascade/src/drivers/mongodb/mongodb-id-generator.ts
+/** Number of times a reservation retries after a duplicate-key (E11000) error. */
+const MAX_RESERVE_ATTEMPTS = 3;
+/** MongoDB duplicate-key error code. */
+const DUPLICATE_KEY_ERROR_CODE = 11e3;
+/**
+* Is `error` a MongoDB duplicate-key (E11000) error?
+*
+* Raised when two concurrent first-time upserts race to create the same
+* counter document once the unique index on `{ collection: 1 }` exists.
+*/
+function isDuplicateKeyError(error) {
+	return typeof error === "object" && error !== null && error.code === DUPLICATE_KEY_ERROR_CODE;
+}
 /**
 * MongoDB-specific ID generator for auto-incrementing integer IDs.
 *
-* Maintains a separate collection that tracks the last generated ID for each table.
-* Generates auto-incrementing IDs similar to SQL's AUTO_INCREMENT feature.
+* Maintains a separate collection that tracks the last generated ID for each
+* table, mimicking SQL's `AUTO_INCREMENT` / `SERIAL`.
 *
 * **Collection Structure:**
 * ```json
-* {
-*   "collection": "users",
-*   "id": 12345
-* }
+* { "collection": "users", "id": 12345 }
 * ```
 *
-* **Features:**
-* - Atomic ID generation using findOneAndUpdate with aggregation pipeline
-* - Automatic transaction support (driver handles session context)
-* - Configurable initial ID and increment values
-* - Thread-safe and concurrent-safe
+* **Atomicity & concurrency:**
+* - Each id (or block of ids) is reserved with a SINGLE atomic
+*   `findOneAndUpdate` on one document; MongoDB serializes concurrent writes to
+*   the same document, so concurrent callers receive distinct, non-overlapping
+*   ids/blocks.
+* - A unique index on `{ collection: 1 }` is ensured lazily (once per instance)
+*   so two concurrent first-time upserts for a brand-new table can't create
+*   duplicate counter documents; the loser of that race gets an E11000 and is
+*   retried (by then the document exists, so it takes the increment branch).
+*
+* **Transactions — IMPORTANT:** the counter write is its OWN standalone,
+* immediately-durable operation. It does NOT join an ambient
+* `transaction()` session (it calls `findOneAndUpdate` directly without a
+* session). This is intentional and matches SQL `SERIAL` semantics: if the
+* surrounding transaction rolls back, the inserted records are undone but the
+* consumed id(s) are NOT — they remain a gap in the sequence. Do not rely on
+* id reservation being rolled back with a transaction.
 *
 * @example
 * ```typescript
-* const mongoDriver = new MongoDbDriver(config);
 * const idGenerator = new MongoIdGenerator(mongoDriver);
 *
-* const dataSource = new DataSource({
-*   name: "primary",
-*   driver: mongoDriver,
-*   idGenerator,
-* });
-*
-* // Generate IDs with custom configuration
-* const id = await idGenerator.generateNextId({
-*   table: "users",
-*   initialId: 1000,
-*   incrementIdBy: 1
-* });
+* const id = await idGenerator.generateNextId({ table: "users" });        // one id
+* const ids = await idGenerator.generateNextIds({ table: "users", count: 100 }); // a block
 * ```
 */
 var MongoIdGenerator = class {
@@ -7012,15 +7493,15 @@ var MongoIdGenerator = class {
 	*/
 	counterCollection = "MasterMind";
 	/**
+	* Memoized "ensure unique index" promise — the index is created at most once
+	* per generator instance, before the first reservation completes.
+	*/
+	indexEnsured;
+	/**
 	* Create a new MongoDB ID generator instance.
 	*
 	* @param driver - The MongoDB driver instance
 	* @param counterCollection - Name of the collection storing ID counters (default: "MasterMind")
-	*
-	* @example
-	* ```typescript
-	* const idGenerator = new MongoIdGenerator(mongoDriver, "id_counters");
-	* ```
 	*/
 	constructor(driver, counterCollection) {
 		this.driver = driver;
@@ -7029,66 +7510,149 @@ var MongoIdGenerator = class {
 	/**
 	* Generate the next ID for a table.
 	*
-	* Uses atomic findOneAndUpdate with aggregation pipeline to ensure uniqueness
-	* even in concurrent scenarios. Automatically participates in active transactions.
+	* Reserves a single id via one atomic `findOneAndUpdate` (see the class doc
+	* for the atomicity / transaction contract). Equivalent to a block of size 1.
 	*
 	* @param options - Configuration for ID generation
 	* @returns The generated ID
 	*
 	* @example
 	* ```typescript
-	* // Simple usage
-	* const id = await idGenerator.generateNextId({ table: "users" });
-	*
-	* // With custom initial ID
-	* const id = await idGenerator.generateNextId({
-	*   table: "products",
-	*   initialId: 1000,
-	*   incrementIdBy: 1
-	* });
+	* const id = await idGenerator.generateNextId({ table: "users", initialId: 1000 });
 	* ```
 	*/
 	async generateNextId(options) {
 		const { table, initialId = 1, incrementIdBy = 1 } = options;
-		return (await this.driver.getDatabase().collection(this.counterCollection).findOneAndUpdate({ collection: table }, [{ $set: {
-			id: { $cond: {
-				if: { $or: [{ $eq: ["$id", null] }, { $not: "$id" }] },
-				then: initialId,
-				else: { $add: ["$id", incrementIdBy] }
-			} },
-			collection: table
-		} }], {
-			upsert: true,
-			returnDocument: "after"
-		}))?.id ?? initialId;
+		await this.ensureIndexes();
+		return await this.reserveBlock(table, initialId, incrementIdBy, 1);
 	}
 	/**
-	* Get the last generated ID for a table.
+	* Reserve a contiguous block of `count` ids in a single atomic operation.
 	*
-	* @param table - The table/collection name
-	* @returns The last generated ID, or 0 if none exists
+	* Advances the counter by `count * incrementIdBy` in one `findOneAndUpdate`
+	* (so the stored last id becomes the block's last id) and returns the block
+	* in ascending order. See the class doc for the non-transactional contract.
+	*
+	* @param options - `GenerateIdOptions` plus the block `count`
+	* @returns The reserved ids in ascending order (length `count`)
 	*
 	* @example
 	* ```typescript
-	* const lastId = await idGenerator.getLastId("users");
-	* console.log(`Last user ID: ${lastId}`);
+	* const ids = await idGenerator.generateNextIds({ table: "users", count: 100 });
+	* // ids[0] is the first id, ids[99] the last; getLastId("users") === ids[99]
 	* ```
 	*/
+	async generateNextIds(options) {
+		const { table, initialId = 1, incrementIdBy = 1, count } = options;
+		if (count <= 0) return [];
+		await this.ensureIndexes();
+		const firstId = await this.reserveBlock(table, initialId, incrementIdBy, count) - (count - 1) * incrementIdBy;
+		return Array.from({ length: count }, (_, index) => firstId + index * incrementIdBy);
+	}
+	/**
+	* Atomically advance the counter for `table` by a whole block and return the
+	* block's LAST id.
+	*
+	* One `findOneAndUpdate` with an aggregation pipeline:
+	* - **Cold start** (counter field missing or null): seed `initialId + (count - 1) * incrementIdBy`
+	*   so the FIRST id of the block equals `initialId` (the `count - 1` here vs
+	*   `count` in the steady-state branch is deliberate — the counter stores the
+	*   last-issued id and the very first id must be exactly `initialId`).
+	* - **Steady state**: add `count * incrementIdBy` to the stored counter.
+	*
+	* Retries on a duplicate-key error from the cold-start upsert race (see
+	* {@link isDuplicateKeyError}).
+	*
+	* @param table - The table/collection the block is for
+	* @param initialId - The first id ever issued for this table
+	* @param incrementIdBy - The fixed stride between ids
+	* @param count - Block size (`>= 1`)
+	* @returns The last id of the reserved block
+	*/
+	async reserveBlock(table, initialId, incrementIdBy, count) {
+		const run = async () => {
+			const lastId = (await this.driver.getDatabase().collection(this.counterCollection).findOneAndUpdate({ collection: table }, [{ $set: {
+				id: { $cond: {
+					if: { $or: [{ $eq: [{ $type: "$id" }, "missing"] }, { $eq: ["$id", null] }] },
+					then: initialId + (count - 1) * incrementIdBy,
+					else: { $add: ["$id", count * incrementIdBy] }
+				} },
+				collection: table
+			} }], {
+				upsert: true,
+				returnDocument: "after"
+			}))?.id;
+			if (typeof lastId !== "number") throw new Error(`Failed to reserve an id block for "${table}": counter returned no id.`);
+			return lastId;
+		};
+		return await this.withDuplicateKeyRetry(run);
+	}
+	/**
+	* Run `operation`, retrying on a duplicate-key (E11000) error up to
+	* {@link MAX_RESERVE_ATTEMPTS} times. Only the cold-start upsert race throws
+	* E11000 (once the unique index exists); on retry the counter document
+	* already exists, so the increment branch runs and succeeds. Any other error
+	* is rethrown immediately.
+	*
+	* @param operation - The reservation to run
+	* @returns The operation's result
+	*/
+	async withDuplicateKeyRetry(operation) {
+		let lastError;
+		for (let attempt = 1; attempt <= MAX_RESERVE_ATTEMPTS; attempt++) try {
+			return await operation();
+		} catch (error) {
+			if (!isDuplicateKeyError(error)) throw error;
+			lastError = error;
+		}
+		throw lastError;
+	}
+	/**
+	* Ensure the unique index on `{ collection: 1 }` exists (once per instance).
+	*
+	* Best-effort: a pre-existing duplicate counter document (created before this
+	* index existed) makes index creation fail with E11000. We swallow that
+	* rather than block app boot — without the index the generator degrades to
+	* its prior (un-indexed) behavior, and the retry path becomes a no-op since
+	* E11000 can no longer be raised by the upsert.
+	*/
+	async ensureIndexes() {
+		if (!this.indexEnsured) this.indexEnsured = this.createCounterIndex();
+		return await this.indexEnsured;
+	}
+	/**
+	* Create the unique index on the counter collection's `collection` field.
+	* Failures are swallowed (see {@link ensureIndexes}).
+	*/
+	async createCounterIndex() {
+		try {
+			await this.driver.getDatabase().collection(this.counterCollection).createIndex({ collection: 1 }, {
+				unique: true,
+				name: "collection_unique"
+			});
+		} catch {}
+	}
+	/**
+	* Get the last generated ID for a table.
+	*
+	* @param table - The table/collection name
+	* @returns The last generated ID, or 0 if none exists
+	*/
 	async getLastId(table) {
 		return (await this.driver.queryBuilder(this.counterCollection).where("collection", table).first())?.id ?? 0;
 	}
 	/**
 	* Set the last ID for a table.
 	*
-	* Creates or updates the counter document for the specified table.
-	* Useful for seeding or resetting ID sequences.
+	* Creates or updates the counter document for the specified table. Useful for
+	* seeding or resetting ID sequences.
 	*
 	* @param table - The table/collection name
 	* @param id - The ID to set as the last generated ID
 	*
 	* @example
 	* ```typescript
-	* // Reset user IDs to start from 1000
+	* // Reset user IDs to start from 1000 (next generated id is 1001)
 	* await idGenerator.setLastId("users", 1000);
 	* ```
 	*/
@@ -9024,6 +9588,13 @@ var MongoQueryParser = class {
 	*/
 	groupFieldNames = /* @__PURE__ */ new Map();
 	/**
+	* Track `countDistinct` aggregate aliases per group stage. The renaming
+	* `$project` finalizes these with `{ $size: "$alias" }` over the set built
+	* by `$addToSet` in the `$group` stage.
+	* Maps pipeline index to the set of aliases needing `$size` finalization.
+	*/
+	countDistinctAliases = /* @__PURE__ */ new Map();
+	/**
 	* Create a new MongoDB query parser.
 	*
 	* @param options - Configuration options for the parser
@@ -9100,10 +9671,24 @@ var MongoQueryParser = class {
 			if (op.type === "groupByWithAggregates" && op.data.fields) {
 				const fieldNames = this.extractGroupFieldNames(op.data.fields);
 				if (fieldNames) this.groupFieldNames.set(stageIndex, fieldNames);
+				this.trackCountDistinctAliases(stageIndex, op.data.aggregates);
+			} else if (op.type === "groupByDate") {
+				this.groupFieldNames.set(stageIndex, op.data.column);
+				this.trackCountDistinctAliases(stageIndex, op.data.aggregates ?? {});
 			}
 		}
 	}
 	/**
+	* Record which aggregate aliases in a group stage are `countDistinct` so the
+	* renaming `$project` can finalize them with `{ $size: "$alias" }` over the
+	* set built by `$addToSet` (the standard distinct-count-per-group pattern).
+	*/
+	trackCountDistinctAliases(stageIndex, aggregates) {
+		const distinctAliases = /* @__PURE__ */ new Set();
+		for (const [alias, expression] of Object.entries(aggregates)) if (isAggregateExpression(expression) && expression.__agg === "countDistinct") distinctAliases.add(alias);
+		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)
@@ -9122,8 +9707,10 @@ var MongoQueryParser = class {
 				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) projection[field] = 1;
+				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 });
@@ -9827,6 +10414,11 @@ var MongoQueryParser = class {
 				if (stage) return stage;
 				break;
 			}
+			case "groupByDate": {
+				const stage = this.buildGroupByDateStage(op.data.column, op.data.unit, op.data.aggregates ?? {});
+				if (stage) return stage;
+				break;
+			}
 			case "groupByRaw": {
 				const expression = op.data.expression;
 				if (expression && typeof expression === "object") return { $group: expression };
@@ -9863,6 +10455,24 @@ var MongoQueryParser = class {
 		return { $group: groupStage };
 	}
 	/**
+	* Build a `$group` stage that buckets documents by a `$dateTrunc` of a date
+	* field, optionally running aggregates over each bucket.
+	*
+	* @param column - The date field to bucket
+	* @param unit - The bucket granularity
+	* @param aggregates - Aggregate operations (abstract or raw)
+	* @returns The `$group` stage
+	*/
+	buildGroupByDateStage(column, unit, aggregates) {
+		const groupStage = { _id: { $dateTrunc: {
+			date: `$${column}`,
+			unit
+		} } };
+		for (const [alias, expression] of Object.entries(aggregates)) if (isAggregateExpression(expression)) groupStage[alias] = this.translateAggregateExpression(expression);
+		else groupStage[alias] = expression;
+		return { $group: groupStage };
+	}
+	/**
 	* Extract field names from GroupByInput for renaming _id.
 	*
 	* @param fields - The grouping fields
@@ -9886,7 +10496,11 @@ var MongoQueryParser = class {
 	translateAggregateExpression(expr) {
 		switch (expr.__agg) {
 			case "count": return { $sum: 1 };
+			case "countDistinct":
+				if (!expr.__field) throw new Error("Count distinct aggregate requires a field name");
+				return { $addToSet: `$${expr.__field}` };
 			case "sum":
+				if (expr.__expr) return { $sum: this.columnExpressionToMongo(expr.__expr) };
 				if (!expr.__field) throw new Error("Sum aggregate requires a field name");
 				return { $sum: `$${expr.__field}` };
 			case "avg":
@@ -9913,6 +10527,35 @@ var MongoQueryParser = class {
 			default: throw new Error(`Unknown aggregate function: ${expr.__agg}`);
 		}
 	}
+	/**
+	* Compile a typed {@link ColumnExpression} tree into a MongoDB aggregation
+	* expression.
+	*
+	* Column references become `$field` paths; literals are emitted verbatim;
+	* arithmetic ops map to `$add` / `$subtract` / `$multiply` / `$divide`. The
+	* `raw` node is rejected — a raw SQL fragment is not portable to a MongoDB
+	* pipeline, so callers must use the typed combinators (or `groupByRaw`) here.
+	*
+	* @param expression - The expression tree to compile
+	* @returns A MongoDB aggregation expression (e.g. `{ $multiply: ["$price", "$quantity"] }`)
+	*/
+	columnExpressionToMongo(expression) {
+		switch (expression.__expr) {
+			case "column": return `$${expression.column}`;
+			case "literal": return expression.value;
+			case "raw": throw new Error("$agg.sumRaw / $expr.raw is not portable to a MongoDB pipeline — a raw SQL fragment has no MongoDB equivalent. Use the typed $expr combinators ($expr.mul / $expr.add / $expr.sub / $expr.div / $expr.col / $expr.lit) or groupByRaw instead.");
+			case "add":
+			case "subtract":
+			case "multiply":
+			case "divide": return { [{
+				add: "$add",
+				subtract: "$subtract",
+				multiply: "$multiply",
+				divide: "$divide"
+			}[expression.__expr]]: expression.operands.map((operand) => this.columnExpressionToMongo(operand)) };
+			default: throw new Error(`Unsupported column expression node: ${JSON.stringify(expression)}`);
+		}
+	}
 	buildGroupId(fields) {
 		if (!fields) return null;
 		if (typeof fields === "string") return `$${fields}`;
@@ -11055,6 +11698,38 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		return this;
 	}
 	/**
+	* Portable date-bucketed grouping.
+	*
+	* Groups documents by `column` truncated to the given bucket
+	* (`day` / `week` / `month` / `year`) via MongoDB's `$dateTrunc`, and runs
+	* the optional aggregates over each bucket. The bucket is exposed under the
+	* column's own name in the output (the `_id` is renamed in a follow-up
+	* `$project`, the same convention as `groupBy`).
+	*
+	* @param column - The date field to bucket
+	* @param unit - The bucket granularity
+	* @param aggregates - Optional aggregate operations keyed by output alias
+	*
+	* @example
+	* ```typescript
+	* import { $agg, $expr } from "@warlock.js/cascade";
+	*
+	* query.groupByDate("created_at", "month", {
+	*   revenue: $agg.sum($expr.mul("price", "quantity")),
+	* });
+	* // $group: { _id: { $dateTrunc: { date: "$created_at", unit: "month" } },
+	* //           revenue: { $sum: { $multiply: ["$price", "$quantity"] } } }
+	* ```
+	*/
+	groupByDate(column, unit, aggregates) {
+		this.operationsHelper.addGroupOperation("groupByDate", {
+			column,
+			unit,
+			aggregates: aggregates ?? {}
+		}, false);
+		return this;
+	}
+	/**
 	* Groups documents using a raw MongoDB expression.
 	* @param expression - The raw grouping expression
 	* @param bindings - Optional parameter bindings
@@ -12897,18 +13572,24 @@ var PostgresDialect = class {
 	/**
 	* Translate a database-agnostic aggregate expression to PostgreSQL SQL.
 	*
-	* The five scalar aggregates map to their ANSI SQL function. `distinct`,
-	* `floor`, `first` and `last` are MongoDB-only for v1 — none has a
-	* single-scalar `GROUP BY` equivalent on PostgreSQL, so they throw instead
-	* of emitting a silently-different semantic (the footgun this guards).
+	* The scalar aggregates map to their ANSI SQL function, and `countDistinct`
+	* maps to `COUNT(DISTINCT …)`. `distinct`, `floor`, `first` and `last` are
+	* MongoDB-only for v1 — none has a single-scalar `GROUP BY` equivalent on
+	* PostgreSQL, so they throw instead of emitting a silently-different semantic
+	* (the footgun this guards).
 	*
 	* @param expression - The abstract aggregate (`$agg.*`) to translate
 	* @returns The SQL fragment (e.g. `SUM("amount")`, `COUNT(*)`)
 	*/
 	aggregateToSql(expression) {
+		if (expression.__expr) {
+			if (expression.__agg !== "sum") throw new Error(`$agg.${expression.__agg} does not support a composed column expression yet — only $agg.sum(...) does. Use a bare column name here.`);
+			return `SUM(${this.columnExpressionToSql(expression.__expr)})`;
+		}
 		const column = expression.__field === null ? "*" : this.quoteIdentifier(expression.__field);
 		switch (expression.__agg) {
 			case "count": return "COUNT(*)";
+			case "countDistinct": return `COUNT(DISTINCT ${column})`;
 			case "sum": return `SUM(${column})`;
 			case "avg": return `AVG(${column})`;
 			case "min": return `MIN(${column})`;
@@ -12916,6 +13597,53 @@ var PostgresDialect = class {
 			default: throw new Error(`$agg.${expression.__agg} is MongoDB-only and not supported on a PostgreSQL groupBy. Use selectRaw / havingRaw with the equivalent SQL (window function / DISTINCT / FLOOR) if you need it here.`);
 		}
 	}
+	/**
+	* Compile a typed {@link ColumnExpression} tree into a SQL fragment.
+	*
+	* Column references flow through {@link quoteIdentifier} (so user-supplied
+	* names are quoted/escaped, never raw-interpolated); literals are emitted as
+	* numeric/boolean SQL constants; arithmetic ops are parenthesised. The `raw`
+	* node is the only path that emits a string verbatim — it is opt-in by name.
+	*
+	* @param expression - The expression tree to compile
+	* @returns A SQL fragment (e.g. `("price" * "quantity")`)
+	*/
+	columnExpressionToSql(expression) {
+		switch (expression.__expr) {
+			case "column": return this.quoteIdentifier(expression.column);
+			case "literal": return typeof expression.value === "boolean" ? this.booleanLiteral(expression.value) : String(expression.value);
+			case "raw": return expression.expression;
+			case "add":
+			case "subtract":
+			case "multiply":
+			case "divide": {
+				const operator = {
+					add: "+",
+					subtract: "-",
+					multiply: "*",
+					divide: "/"
+				}[expression.__expr];
+				return `(${expression.operands.map((operand) => this.columnExpressionToSql(operand)).join(` ${operator} `)})`;
+			}
+			default: throw new Error(`Unsupported column expression node: ${JSON.stringify(expression)}`);
+		}
+	}
+	/**
+	* Build a `date_trunc` bucket expression for a portable `groupByDate`.
+	*
+	* @param column - The date/timestamp column to truncate
+	* @param unit - The bucket granularity
+	* @returns The SQL fragment (e.g. `date_trunc('month', "created_at")`)
+	*
+	* @example
+	* ```typescript
+	* dialect.dateTruncSql("created_at", "month");
+	* // date_trunc('month', "created_at")
+	* ```
+	*/
+	dateTruncSql(column, unit) {
+		return `date_trunc('${unit}', ${this.quoteIdentifier(column)})`;
+	}
 };
 
 //#endregion
@@ -13764,10 +14492,16 @@ var PostgresQueryParser = class PostgresQueryParser {
 	*/
 	orderClauses = [];
 	/**
-	* GROUP BY columns.
+	* GROUP BY columns (bare identifiers — get quoted).
 	*/
 	groupColumns = [];
 	/**
+	* Raw GROUP BY expressions (emitted verbatim — e.g. a `date_trunc(...)`
+	* bucket). Kept separate from `groupColumns` so they bypass identifier
+	* quoting while still landing in the same `GROUP BY` clause.
+	*/
+	groupRawExpressions = [];
+	/**
 	* HAVING clauses.
 	*/
 	havingClauses = [];
@@ -13938,6 +14672,9 @@ var PostgresQueryParser = class PostgresQueryParser {
 			case "groupBy":
 				this.processGroupBy(data);
 				break;
+			case "groupByRaw":
+				this.processGroupByRaw(data);
+				break;
 			case "having":
 				this.processHaving(data);
 				break;
@@ -13972,9 +14709,9 @@ var PostgresQueryParser = class PostgresQueryParser {
 		parts.push(fromClause);
 		if (this.joinClauses.length > 0) parts.push(this.joinClauses.join(" "));
 		if (this.whereClauses.length > 0) parts.push(`WHERE ${this.whereClauses.join(" ")}`);
-		if (this.groupColumns.length > 0) {
-			const quotedCols = this.groupColumns.map((c) => this.dialect.quoteIdentifier(c));
-			parts.push(`GROUP BY ${quotedCols.join(", ")}`);
+		if (this.groupColumns.length > 0 || this.groupRawExpressions.length > 0) {
+			const allGroupTerms = [...this.groupColumns.map((c) => this.dialect.quoteIdentifier(c)), ...this.groupRawExpressions];
+			parts.push(`GROUP BY ${allGroupTerms.join(", ")}`);
 		}
 		if (this.havingClauses.length > 0) parts.push(`HAVING ${this.havingClauses.join(" AND ")}`);
 		if (this.orderClauses.length > 0) parts.push(`ORDER BY ${this.orderClauses.join(", ")}`);
@@ -14432,6 +15169,14 @@ var PostgresQueryParser = class PostgresQueryParser {
 		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.
+	*/
+	processGroupByRaw(data) {
+		const expression = data.expression;
+		this.groupRawExpressions.push(expression);
+	}
+	/**
 	* Process HAVING operation.
 	*/
 	processHaving(data) {
@@ -14612,6 +15357,53 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 		if (!aggregates) return super.groupBy(fields);
 		const fieldList = Array.isArray(fields) ? fields : [fields];
 		this.addOperation("select", { fields: fieldList });
+		this.projectGroupAggregates(aggregates);
+		return super.groupBy(fields);
+	}
+	/**
+	* Portable date-bucketed GROUP BY.
+	*
+	* Truncates `column` to the given bucket (`day` / `week` / `month` / `year`)
+	* via PostgreSQL's `date_trunc`, projects the bucket under the column's own
+	* name, and groups by the truncated expression. Optional `aggregates` follow
+	* the same rules as the two-arg `groupBy` (`$agg.*` helpers or raw SQL
+	* strings; MongoDB operator objects and MongoDB-only aggregates throw).
+	*
+	* Emits (for `groupByDate("created_at", "month", { revenue: $agg.sum(...) })`):
+	* `SELECT date_trunc('month', "created_at") AS "created_at", SUM(...) AS "revenue"
+	*  FROM ... GROUP BY date_trunc('month', "created_at")`
+	*
+	* @param column - The date/timestamp column to bucket
+	* @param unit - The bucket granularity
+	* @param aggregates - Optional aggregate projections keyed by output alias
+	*
+	* @example
+	* Order.query().groupByDate("created_at", "month", {
+	*   revenue: $agg.sum($expr.mul("price", "quantity")),
+	* });
+	*/
+	groupByDate(column, unit, aggregates) {
+		const bucketSql = this.driver.dialect.dateTruncSql(column, unit);
+		this.addOperation("selectRaw", {
+			expression: `${bucketSql} AS ${this.driver.dialect.quoteIdentifier(column)}`,
+			bindings: []
+		});
+		if (aggregates) this.projectGroupAggregates(aggregates);
+		this.addOperation("groupByRaw", {
+			expression: bucketSql,
+			bindings: []
+		});
+		return this;
+	}
+	/**
+	* Translate a `{ alias: aggregate }` map into `selectRaw` projections and
+	* record each alias → SQL so `applyGroupByAggregates` can later rewrite a
+	* `having()` on the alias. Shared by `groupBy` and `groupByDate`.
+	*
+	* `$agg.distinct/floor/first/last` throw (MongoDB-only on Postgres v1);
+	* MongoDB operator objects throw (not portable to SQL).
+	*/
+	projectGroupAggregates(aggregates) {
 		for (const [alias, expression] of Object.entries(aggregates)) {
 			let sql;
 			if (isAggregateExpression(expression)) sql = this.driver.dialect.aggregateToSql(expression);
@@ -14623,7 +15415,6 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 				bindings: []
 			});
 		}
-		return super.groupBy(fields);
 	}
 	/**
 	* Nearest-neighbour vector similarity search via pgvector cosine distance.
@@ -16134,12 +16925,20 @@ var PostgresDriver = class {
 	*/
 	_syncAdapter;
 	/**
+	* Lookup set of column names that hold native PostgreSQL arrays
+	* (`JSONB[]`, `TEXT[]`, …) and must NOT be JSON-text encoded.
+	*
+	* @see PostgresPoolConfig.nativeArrayColumns
+	*/
+	_nativeArrayColumns;
+	/**
 	* Create a new PostgreSQL driver instance.
 	*
 	* @param config - PostgreSQL connection configuration
 	*/
 	constructor(config) {
 		this.config = config;
+		this._nativeArrayColumns = new Set(config.nativeArrayColumns ?? []);
 	}
 	/**
 	* Get the connection pool instance.
@@ -16240,15 +17039,56 @@ var PostgresDriver = class {
 		const serialized = {};
 		for (const [key, value] of Object.entries(data)) {
 			if (value === void 0) continue;
-			if (value instanceof Date) serialized[key] = value.toISOString();
-			else if (typeof value === "bigint") serialized[key] = value.toString();
-			else if (typeof value === "object" && value !== null && !Array.isArray(value)) serialized[key] = value;
-			else if (Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === "number")) serialized[key] = `[${value.join(",")}]`;
-			else serialized[key] = value;
+			serialized[key] = this.serializeValue(key, value);
 		}
 		return serialized;
 	}
 	/**
+	* Serialize a single column value into a node-pg bindable parameter.
+	*
+	* Shared by {@link serialize} (INSERT path) and {@link buildUpdateQuery}
+	* `$set` (UPDATE path) so both encode `json` / `jsonb` columns identically.
+	*
+	* Encoding rules (in order):
+	* - `Date` → ISO string.
+	* - `bigint` → decimal string (node-pg has no native bigint binding).
+	* - all-number array → pgvector literal `'[n1,n2,...]'`. node-pg would
+	*   otherwise emit a `{n1,n2,...}` array literal, which the `vector` type
+	*   rejects. This branch is preserved exactly.
+	* - any other array (object-array, string-array, mixed, empty `[]`) →
+	*   `JSON.stringify`. node-pg renders a raw JS array as a PostgreSQL array
+	*   literal `{...}` (and `[]` as `{}`), which a `json` / `jsonb` column
+	*   rejects — so we bind the value as JSON text instead, the form those
+	*   columns accept. Columns listed in `nativeArrayColumns` are exempt:
+	*   their raw array is passed through so node-pg emits the `{...}` literal
+	*   a genuine `JSONB[]` / `TEXT[]` column needs.
+	* - plain object → `JSON.stringify`. Equivalent to node-pg's own object
+	*   handling, made explicit so both write paths agree.
+	* - everything else (scalars: string, number, boolean, null) → untouched.
+	*
+	* Boundary note: the serializer has no access to the table schema, so it
+	* cannot tell a `json` / `jsonb` column from a native-array column purely
+	* from the value. `nativeArrayColumns` is the explicit, opt-in escape hatch
+	* for the latter. No `::jsonb` placeholder cast is added: a JSON-text string
+	* binds correctly to `json` / `jsonb` without one, and a blind cast would
+	* misfire on columns we cannot positively identify as jsonb.
+	*
+	* @param key - Column name (used to honour `nativeArrayColumns`)
+	* @param value - The raw value to serialize (never `undefined`)
+	* @returns The value ready to bind as a query parameter
+	*/
+	serializeValue(key, value) {
+		if (value instanceof Date) return value.toISOString();
+		if (typeof value === "bigint") return value.toString();
+		if (Array.isArray(value)) {
+			if (value.length > 0 && value.every((v) => typeof v === "number")) return `[${value.join(",")}]`;
+			if (this._nativeArrayColumns.has(key)) return value;
+			return JSON.stringify(value);
+		}
+		if (typeof value === "object" && value !== null) return JSON.stringify(value);
+		return value;
+	}
+	/**
 	* Get the dirty tracker for this driver.
 	*/
 	getDirtyTracker(data) {
@@ -16717,7 +17557,7 @@ var PostgresDriver = class {
 		let paramIndex = 1;
 		if (update.$set) for (const [key, value] of Object.entries(update.$set)) {
 			setClauses.push(`${this.dialect.quoteIdentifier(key)} = ${this.dialect.placeholder(paramIndex++)}`);
-			params.push(value);
+			params.push(value === void 0 ? value : this.serializeValue(key, value));
 		}
 		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)) {
@@ -21301,6 +22141,7 @@ async function listExecutedMigrations() {
 
 //#endregion
 exports.$agg = $agg;
+exports.$expr = $expr;
 exports.BelongsTo = BelongsTo;
 exports.BelongsToMany = BelongsToMany;
 exports.ColumnBuilder = ColumnBuilder;
@@ -21384,6 +22225,7 @@ exports.int = int;
 exports.integer = integer;
 exports.ipAddress = ipAddress;
 exports.isAggregateExpression = isAggregateExpression;
+exports.isColumnExpression = isColumnExpression;
 exports.isMongoDBDriverLoaded = isMongoDBDriverLoaded;
 exports.json = json;
 exports.lineString = lineString;
@@ -21414,6 +22256,7 @@ exports.time = time;
 exports.timestamp = timestamp;
 exports.tinyInt = tinyInt;
 exports.tinyInteger = tinyInteger;
+exports.toColumnExpression = toColumnExpression;
 exports.transaction = transaction;
 exports.tryResolveModelClass = tryResolveModelClass;
 exports.ulid = ulid;