@warlock.js/cascade 5.25.0 → 5.27.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.27.0 - 2026-10-01
+
+### Changed
+
+- Dependency: @mongez/supportive-is 3.0 (type-predicate checkers).
+
+## 5.26.0 - 2026-09-30
+
+### Added
+
+- `whereTrusted(conditions)` on the query builder contract applies a code-authored filter without the unsafe-operator check, so MongoDB operators such as `$in` and `$lt` pass through. Never pass request input to it. The PostgreSQL builder throws `UnsupportedQueryOperationError` for operator objects, because its `where()` parser would otherwise bind them as plain values. Custom query builders must implement the new method.
+- Migrations can be registered with an origin (`"package"` or `"app"`). Package migrations run before every app migration while preserving the existing `order`, `createdAt`, and name sort within each partition. Direct `register()` calls default to `"app"`.
+
+### Fixed
+
+- Migrations now reject colliding unnamed index definitions before sending DDL to MongoDB or PostgreSQL, with guidance to provide an explicit index name. Declarative alter migrations with a custom `up()` but no `down()` now emit one rollback warning.
+- `trustedFilter: true` now works on `atomic()`, `findOneAndUpdate()` and `findAndUpdate()` with an operator filter such as `{ id: { $in: ids } }`. The scoped-write lookup re-ran the filter through `where()`, which rejected the operator, so these calls threw `UnsafeFilterError` even when the filter was trusted. Global scopes (tenant, soft delete) still apply to the write. `findAndUpdate()` now accepts `trustedFilter`.
+
 ## 5.25.0 - 2026-09-28
 
 ### Added

package/cjs/index.cjs

@@ -5309,6 +5309,10 @@ function toDriverOptions(options) {
 	const { trustedFilter: _trustedFilter, ...rest } = options;
 	return rest;
 }
+function applyWriteFilter(query, filter, trustedFilter) {
+	if (trustedFilter && typeof query.whereTrusted === "function") return query.whereTrusted(filter);
+	return query.where(filter);
+}
 /**
 * Add the same generated `id` that normal Mongo inserts receive to an upsert's
 * insert branch. `$setOnInsert` keeps an existing document's id immutable.
@@ -5335,9 +5339,9 @@ async function withAutoGeneratedUpsertId(ModelClass, filter, operations, options
 * so the target ids are resolved through the scoped query builder and added to
 * the filter. `null` means no visible row matches: the write must be a no-op.
 */
-async function scopeWriteFilter(ModelClass, filter, single) {
+async function scopeWriteFilter(ModelClass, filter, single, trustedFilter = false) {
 	const primaryKey = ModelClass.primaryKey;
-	const ids = await ModelClass.query().where(filter).pluck(primaryKey);
+	const ids = await applyWriteFilter(ModelClass.query(), filter, trustedFilter).pluck(primaryKey);
 	if (ids.length === 0) return null;
 	return {
 		...filter,
@@ -5349,10 +5353,10 @@ async function scopeWriteFilter(ModelClass, filter, single) {
 * the driver would insert or, worse, update a row a scope hides (another
 * tenant's, a soft-deleted one), so a hidden match is refused.
 */
-async function scopeUpsertFilter(ModelClass, filter) {
-	const scoped = await scopeWriteFilter(ModelClass, filter, true);
+async function scopeUpsertFilter(ModelClass, filter, trustedFilter = false) {
+	const scoped = await scopeWriteFilter(ModelClass, filter, true, trustedFilter);
 	if (scoped) return scoped;
-	if (await ModelClass.query().withoutGlobalScopes().where(filter).exists()) throw new Error(`${ModelClass.name}: upsert matches a row hidden by a global scope (tenant or soft delete); refusing to touch it.`);
+	if (await applyWriteFilter(ModelClass.query().withoutGlobalScopes(), filter, trustedFilter).exists()) throw new Error(`${ModelClass.name}: upsert matches a row hidden by a global scope (tenant or soft delete); refusing to touch it.`);
 	return filter;
 }
 /**
@@ -5361,7 +5365,7 @@ async function scopeUpsertFilter(ModelClass, filter) {
 */
 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);
+	const scoped = options?.upsert ? await scopeUpsertFilter(ModelClass, resolved, options?.trustedFilter) : await scopeWriteFilter(ModelClass, resolved, false, options?.trustedFilter);
 	if (!scoped) return 0;
 	const upsertOperations = await withAutoGeneratedUpsertId(ModelClass, scoped, operations, options);
 	const result = await ModelClass.getDriver().atomic(ModelClass.table, scoped, upsertOperations, toDriverOptions(options));
@@ -5381,8 +5385,8 @@ async function updateById(ModelClass, id, data) {
 }
 async function findAndUpdateRecords(ModelClass, filter, update, options) {
 	const primaryKey = ModelClass.primaryKey;
-	const safeFilter = sanitizeFilter(filter);
-	const ids = await ModelClass.query().where(safeFilter).pluck(primaryKey);
+	const safeFilter = resolveFilter(filter, options);
+	const ids = await applyWriteFilter(ModelClass.query(), safeFilter, options?.trustedFilter ?? false).pluck(primaryKey);
 	if (ids.length === 0) {
 		if (!options?.upsert) return [];
 		await performAtomic(ModelClass, safeFilter, update, {
@@ -5399,7 +5403,7 @@ async function findAndUpdateRecords(ModelClass, filter, update, options) {
 }
 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);
+	const scoped = options?.upsert ? await scopeUpsertFilter(ModelClass, resolved, options?.trustedFilter) : await scopeWriteFilter(ModelClass, resolved, true, options?.trustedFilter);
 	if (!scoped) return null;
 	const upsertUpdate = await withAutoGeneratedUpsertId(ModelClass, scoped, update, options);
 	const result = await ModelClass.getDriver().findOneAndUpdate(ModelClass.table, scoped, upsertUpdate, toDriverOptions(options));
@@ -7296,7 +7300,7 @@ var Model = class Model {
 	* Find one and update multiple records that matches the provided filter and return the updated record
 	* @param filter - Filter conditions
 	* @param update - Update operators, or an aggregation pipeline (MongoDB only)
-	* @param options - `upsert`, `arrayFilters` (MongoDB only)
+	* @param options - `upsert`, `arrayFilters` (MongoDB only), `trustedFilter`
 	* @returns The updated records
 	*/
 	static async findAndUpdate(filter, update, options) {
@@ -9505,6 +9509,21 @@ var QueryBuilder = class QueryBuilder {
 		}
 		return this;
 	}
+	/**
+	* Add a code-authored object filter without the `$`-operator safety guard.
+	* Never use this with request input; callers must use where() for that.
+	*/
+	whereTrusted(conditions) {
+		for (const [field, value] of Object.entries(conditions)) {
+			assertDefined(value, field);
+			this.addOperation("where", {
+				field,
+				operator: "=",
+				value
+			});
+		}
+		return this;
+	}
 	orWhere(...args) {
 		if (args.length === 1 && typeof args[0] === "function") {
 			const sub = this.subQuery();
@@ -12375,6 +12394,15 @@ var MongoQueryBuilder = class MongoQueryBuilder extends QueryBuilder {
 		this.addWhereClause("where", args);
 		return this;
 	}
+	/**
+	* Add a code-authored MongoDB filter without the `$`-operator safety guard.
+	* Never use this with request input; callers must use where() for that.
+	*/
+	whereTrusted(conditions) {
+		for (const [field, value] of Object.entries(conditions)) assertDefined(value, field);
+		this.operationsHelper.addMatchOperation("where:object", conditions);
+		return this;
+	}
 	orWhere(...args) {
 		this.addWhereClause("orWhere", args);
 		return this;
@@ -17475,6 +17503,13 @@ function parseAggregateValue(value) {
 function toParserOps(ops) {
 	return ops;
 }
+function containsOperatorKey(value) {
+	if (Array.isArray(value)) return value.some(containsOperatorKey);
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	return Object.entries(value).some(([key, nested]) => key.startsWith("$") || containsOperatorKey(nested));
+}
 /**
 * PostgreSQL Query Builder.
 *
@@ -17495,6 +17530,14 @@ var PostgresQueryBuilder = class PostgresQueryBuilder extends QueryBuilder {
 	table;
 	/** Data source backing this builder. */
 	dataSource;
+	/**
+	* PostgreSQL has no parser for MongoDB-style object operators such as
+	* `{ id: { $in: [1, 2] } }`; accepting one would bind the object as `=`.
+	*/
+	whereTrusted(conditions) {
+		if (containsOperatorKey(conditions)) throw new UnsupportedQueryOperationError("whereTrusted with MongoDB-style operators", "postgres", "Use the portable whereIn()/where(field, operator, value) APIs instead.");
+		return super.whereTrusted(conditions);
+	}
 	/** Hydration callback for transforming result rows into model instances. */
 	hydrateCallback;
 	/** Invoked before query execution. */
@@ -22239,6 +22282,7 @@ var Migration = class {
 	* @internal
 	*/
 	async execute() {
+		this.assertNoGeneratedIndexNameCollisions();
 		for (const op of this.pendingOperations) await this.executeOperation(op);
 		this.pendingOperations.length = 0;
 	}
@@ -22275,6 +22319,7 @@ var Migration = class {
 	* @internal
 	*/
 	toSteps() {
+		this.assertNoGeneratedIndexNameCollisions();
 		const serializer = this.driver.driver.getSQLSerializer();
 		const steps = [];
 		let schemaRun = [];
@@ -22422,6 +22467,40 @@ var Migration = class {
 		}
 	}
 	/**
+	* Reject two unnamed indexes that a driver would give the same name before
+	* either DDL command is sent. MongoDB's default names include directions;
+	* PostgreSQL's include the table and columns.
+	*/
+	assertNoGeneratedIndexNameCollisions() {
+		const engine = this.databaseEngine;
+		if (engine !== "mongodb" && engine !== "postgres") return;
+		const unnamedIndexes = this.pendingOperations.flatMap((operation) => {
+			if (operation.type === "createIndex") {
+				const index = operation.payload;
+				return index.name ? [] : [index];
+			}
+			if (operation.type === "createUniqueIndex") {
+				const { columns, name } = operation.payload;
+				return name ? [] : [{
+					columns,
+					unique: true
+				}];
+			}
+			return [];
+		});
+		const seen = /* @__PURE__ */ new Map();
+		for (const index of unnamedIndexes) {
+			const generatedName = engine === "mongodb" ? index.columns.map((column, i) => `${column}_${index.directions?.[i] === "desc" ? -1 : 1}`).join("_") : `idx_${this.table}_${index.columns.join("_")}`;
+			const first = seen.get(generatedName);
+			if (first) throw new Error(`Migration queued two ${engine} indexes with the generated name "${generatedName}": ${this.describeIndex(first)} and ${this.describeIndex(index)}. Give one index an explicit name, for example { name: "..." }.`);
+			seen.set(generatedName, index);
+		}
+	}
+	describeIndex(index) {
+		const partial = index.where ? JSON.stringify(index.where) : "none";
+		return `columns [${index.columns.join(", ")}] (unique: ${!!index.unique}, partial: ${partial})`;
+	}
+	/**
 	* Check if a table exists.
 	*
 	* Useful for conditional migrations and idempotent operations.
@@ -24128,13 +24207,18 @@ Migration.create = function createMigration(model, columns, options = {}) {
 */
 Migration.alter = function alterMigration(model, schema, options = {}) {
 	const { order = 0, createdAt, transactional } = options;
-	return class AlterMigration extends Migration {
+	let missingDownWarningEmitted = false;
+	class AlterMigration extends Migration {
 		static order = order;
 		static createdAt = createdAt;
 		static transactional = transactional;
 		table = model.table;
 		dataSource = model.dataSource;
 		async up() {
+			if (options.up && !options.down && !missingDownWarningEmitted) {
+				missingDownWarningEmitted = true;
+				_warlock_js_logger.log.warn("database", "migration", `Migration "${AlterMigration.migrationName ?? this.table}" defines a custom up() without a down() rollback.`);
+			}
 			if (schema.add) wireColumns(this, schema.add);
 			if (schema.drop) for (const col of schema.drop) this.dropColumn(col);
 			if (schema.rename) for (const [from, to] of Object.entries(schema.rename)) this.renameColumn(from, to);
@@ -24187,7 +24271,8 @@ Migration.alter = function alterMigration(model, schema, options = {}) {
 		async down() {
 			if (options.down) await options.down.call(this);
 		}
-	};
+	}
+	return AlterMigration;
 };
 Migration.__declarativeFactoriesAttached = true;
 
@@ -24263,11 +24348,14 @@ function compareCreatedAt(a, b) {
 * Comparator for applying migrations — oldest first.
 *
 * Priority:
-*   1. `order` override (lower = earlier, default 0)
-*   2. `createdAt` timestamp (older = earlier)
-*   3. Alphabetical by migration name (last resort)
+*   1. package origin before app origin
+*   2. `order` override (lower = earlier, default 0)
+*   3. `createdAt` timestamp (older = earlier)
+*   4. Alphabetical by migration name (last resort)
 */
 function sortMigrations(a, b) {
+	const byOrigin = Number(a.origin === "app") - Number(b.origin === "app");
+	if (byOrigin !== 0) return byOrigin;
 	const byOrder = (a.order ?? 0) - (b.order ?? 0);
 	if (byOrder !== 0) return byOrder;
 	const byCreatedAt = compareCreatedAt(a.createdAt, b.createdAt);
@@ -24643,7 +24731,7 @@ var MigrationRunner = class {
 	* The migration name is read from `MigrationClass.migrationName`.
 	*
 	* @param MigrationClass - Migration class (must have static `name` set)
-	* @param createdAt - Optional timestamp for ordering
+	* @param origin - Registration source; defaults to `"app"` for direct registrations.
 	* @returns This runner for chaining
 	*
 	* @example
@@ -24652,7 +24740,7 @@ var MigrationRunner = class {
 	* runner.register(CreateUsersTable);
 	* ```
 	*/
-	register(MigrationClass) {
+	register(MigrationClass, origin = "app") {
 		const name = MigrationClass.migrationName;
 		if (!name) throw new Error("Migration class must have a static 'migrationName' property set. Set it in CLI after importing: MigrationClass.migrationName = \"filename\";");
 		const existing = this.migrations.find((m) => m.migrationName === name);
@@ -24660,6 +24748,7 @@ var MigrationRunner = class {
 			if (existing !== MigrationClass) throw new Error(`Duplicate migration name "${name}": two different migration classes resolve to the same name. Rename one of the files (or set a unique static 'migrationName').`);
 			return this;
 		}
+		MigrationClass.origin = origin;
 		this.migrations.push(MigrationClass);
 		return this;
 	}