@warlock.js/cascade 5.24.0 → 5.25.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.25.0 - 2026-09-28
+
+### Added
+
+- Drivers emit public `query` events for settled PostgreSQL SQL and MongoDB commands; `dataSourceRegistry` forwards them with the registered connection name for centralized inspection.
+
+### Fixed
+
+- PostgreSQL `groupByRaw()` now emits and parses its raw GROUP BY operation correctly, including bound parameters.
+- MongoDB `lockForUpdate()` now throws the public `UnsupportedLockForUpdateError` with guidance to use a conditional atomic update instead of a nonexistent row lock.
+- MongoDB atomic upserts now assign the model's auto-increment `id` on insert without changing an existing document's id.
+
 ## 5.24.0 - 2026-09-27
 
 ### Added
@@ -82,6 +94,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Added
@@ -212,12 +225,12 @@ changelogs.
 
 ### Security
 
-- **NoSQL operator injection via equality filters is now rejected.** `where({ field: value })`, `where(field, value)` and the filter-accepting model statics (`first`, `findFirst`, `findAll`, `count`, `paginate`, `deleteMany`, `deleteOne`, …) treated the value verbatim, so a request-controlled payload such as `{ password: { $ne: null } }` compiled into a MongoDB *operator* query instead of an equality match — the textbook auth-bypass primitive (`User.first({ email, password })` matched any user). Equality-position values (and top-level object-form keys) containing `$`-prefixed keys now throw `UnsafeFilterError`. Explicit operator APIs are unaffected: `where(field, operator, value)`, `whereIn`/`whereNull`/`whereBetween`/…, and the object form of `whereRaw`. Dotted paths (`"profile.name"`) and plain sub-document equality values remain valid. A `sanitizeFilter` / `sanitizeFilterValue` helper pair is exported for callers who forward request objects to other driver-level APIs
-- **String-mode `whereRaw()` / `orWhereRaw()` no longer compiles to `$where` on the MongoDB driver.** Any string expression was wrapped as `{ $where: "<js>" }` — JavaScript executed *inside* `mongod` for every scanned document (an injection sink whenever any part of the string was request-influenced, and an unindexed full-scan DoS even when trusted), with `?`-bindings substituted by string concatenation rather than real parameterization. The MongoDB parser now throws `UnsafeRawExpressionError` for string expressions and directs callers to the object form (`whereRaw({ $expr: … })`), which keeps working. SQL drivers keep string mode with real bindings
+- **NoSQL operator injection via equality filters is now rejected.** `where({ field: value })`, `where(field, value)` and the filter-accepting model statics (`first`, `findFirst`, `findAll`, `count`, `paginate`, `deleteMany`, `deleteOne`, …) treated the value verbatim, so a request-controlled payload such as `{ password: { $ne: null } }` compiled into a MongoDB _operator_ query instead of an equality match — the textbook auth-bypass primitive (`User.first({ email, password })` matched any user). Equality-position values (and top-level object-form keys) containing `$`-prefixed keys now throw `UnsafeFilterError`. Explicit operator APIs are unaffected: `where(field, operator, value)`, `whereIn`/`whereNull`/`whereBetween`/…, and the object form of `whereRaw`. Dotted paths (`"profile.name"`) and plain sub-document equality values remain valid. A `sanitizeFilter` / `sanitizeFilterValue` helper pair is exported for callers who forward request objects to other driver-level APIs
+- **String-mode `whereRaw()` / `orWhereRaw()` no longer compiles to `$where` on the MongoDB driver.** Any string expression was wrapped as `{ $where: "<js>" }` — JavaScript executed _inside_ `mongod` for every scanned document (an injection sink whenever any part of the string was request-influenced, and an unindexed full-scan DoS even when trusted), with `?`-bindings substituted by string concatenation rather than real parameterization. The MongoDB parser now throws `UnsafeRawExpressionError` for string expressions and directs callers to the object form (`whereRaw({ $expr: … })`), which keeps working. SQL drivers keep string mode with real bindings
 - **`static hidden` — fields `toJSON()` can never emit.** With no `resource`/`toJsonColumns` configured (the quick-start model shape), `toJSON()` — invoked implicitly by `JSON.stringify(model)` / `res.json(model)` — returned the entire raw document, password hashes and tokens included. Models can now declare `static hidden = ["password", …]`; those top-level fields are ALWAYS stripped from `toJSON()` output — with the raw-document default, with `toJsonColumns` (hidden wins), and from the data handed to a `resource` class. Defaults to `[]`, so nothing changes until a model declares hidden fields — but because that default still fails open, cascade now logs a one-time `console.warn` per model whose schema declares a credential-shaped field (`password`/`passwordHash`/`secret`/`token`/`apiKey`/`api_key`, case-insensitive) that no `hidden`/`resource`/`toJsonColumns` covers
 - **Atomic/find-and-modify statics now sanitize their filter.** `atomic()`, `findAndUpdate()`, `findOneAndUpdate()`, `findAndReplace()` and `findOneAndDelete()` forwarded their `filter` object straight to the driver — bypassing `where()` and therefore the operator-injection check above, so `{ role: { $ne: "admin" } }` from a request body was still a live operator query on these paths. The filter argument now runs through `sanitizeFilter` and throws `UnsafeFilterError` on `$`-prefixed keys. Update-operator semantics (`$set`/`$inc`/`$unset`/…) are untouched — only the FILTER is checked. Callers who legitimately need operator conditions must express them through the query API (`Model.query().where(…)`) instead of the raw filter argument
 - **Residual injection paths closed.** The three-argument equality form `where(field, "=", value)` now sanitizes its value like the two-argument form (other operators are unaffected), and the object form of `whereRaw()`/`orWhereRaw()` rejects the server-side JavaScript operators `$where`, `$function` and `$accumulator` anywhere in the expression (throws `UnsafeRawExpressionError`); `$expr` and the other aggregation operators keep working
-- **A `merge()`d primary key can no longer retarget a write at another document.** `performUpdate()` built its filter from `model.get(primaryKey)` *after* `merge()` had run, so the canonical update-my-profile shape — `model.merge(req.body); await model.save()` — let a body carrying `{ id: "<victim-id>", role: "admin" }` redirect the UPDATE (and the mass-assigned fields with it) onto somebody else's row. Two independent controls now stand between a payload and the write target: (1) an instance captures its primary key at the moment it becomes persisted (`isNew` flipping to `false` — hydration, or the writer after an insert), and `update`/`replace`/`destroy` build their filter from that captured value, exposed as `model.trustedPrimaryKey`; (2) `merge()` on an already-persisted model drops the identity columns (`id`, `_id`, and the configured primary key) instead of applying them — which also covers `save({ merge })`. Identity columns are additionally excluded from the update's `$set`/`$unset`, so an explicit `set("id", …)` on a loaded record no longer rewrites the key of the row it is pinned to (`_id` was never writable in MongoDB anyway); changing a primary key is now a deliberate operation through the atomic/raw APIs. **Creating** a record with an explicit id is unchanged — a new model accepts identity columns — and the writer still merges driver-returned values (generated `_id`, `RETURNING *`) back onto the instance through a framework-internal path that request data never reaches
+- **A `merge()`d primary key can no longer retarget a write at another document.** `performUpdate()` built its filter from `model.get(primaryKey)` _after_ `merge()` had run, so the canonical update-my-profile shape — `model.merge(req.body); await model.save()` — let a body carrying `{ id: "<victim-id>", role: "admin" }` redirect the UPDATE (and the mass-assigned fields with it) onto somebody else's row. Two independent controls now stand between a payload and the write target: (1) an instance captures its primary key at the moment it becomes persisted (`isNew` flipping to `false` — hydration, or the writer after an insert), and `update`/`replace`/`destroy` build their filter from that captured value, exposed as `model.trustedPrimaryKey`; (2) `merge()` on an already-persisted model drops the identity columns (`id`, `_id`, and the configured primary key) instead of applying them — which also covers `save({ merge })`. Identity columns are additionally excluded from the update's `$set`/`$unset`, so an explicit `set("id", …)` on a loaded record no longer rewrites the key of the row it is pinned to (`_id` was never writable in MongoDB anyway); changing a primary key is now a deliberate operation through the atomic/raw APIs. **Creating** a record with an explicit id is unchanged — a new model accepts identity columns — and the writer still merges driver-returned values (generated `_id`, `RETURNING *`) back onto the instance through a framework-internal path that request data never reaches
 - **`whereLike` / `whereSearch` string arguments are matched literally instead of compiled as regexes.** `whereLike`, `whereNotLike`, `whereStartsWith`/`whereEndsWith` (and their `Not` variants) and the `$regex` form of `whereSearch` interpolated their argument straight into a MongoDB `$regex`. Wired to a search box — `User.query().whereSearch("name", req.query.q)`, the intended use — that handed the caller the regex engine running inside `mongod`: metacharacters rewrote the match semantics (`^.*$` matches everything, `^a`/`^b` probes read a value back character by character), and a nested-quantifier pattern such as `(a+)+$` backtracked catastrophically against every scanned document. String arguments are now escaped and treated as literals; the SQL `LIKE` wildcard `%` still expands (to `.*`, with runs of `%` collapsed) and matching stays unanchored/substring as this driver documents. An explicit `RegExp` argument — which cannot arrive as JSON — is still used as a pattern, so raw regex remains available to developer-authored queries; never build that `RegExp` from user input. `escapeRegex` / `likePatternToRegexSource` are exported for callers compiling their own patterns. The Postgres path was already parameterized (`ILIKE $1`) and is unchanged
 - **`@mongez/*` dependencies bumped to the 2026-08-17 security release**: `@mongez/reinforcements` `^3.3.0` → `^4.0.1`, `@mongez/dotenv` `^1.3.1` → `^1.3.2`, `@mongez/events` `^2.2.6` → `^2.2.7`, `@mongez/supportive-is` `^2.1.3` → `^2.1.4`. Reinforcements 4 adds a prototype-pollution guard to `set`/`merge`/`pick`/`defaults` — the utilities behind `model.set()` / `model.merge()`, i.e. exactly where request-shaped data enters a model — and a ReDoS fix in `repeatsOf`. Its breaking change (`Random` is CSPRNG-backed and no longer honors `Random.seed()`) does not affect cascade: the package imports no `Random` API and seeds nothing. Requires Node 20+, which cascade already targets
 
@@ -229,7 +242,7 @@ changelogs.
 
   Returns `PendingMigration { name, createdAt? }` rather than the migration classes: `MigrationClass` is module-local, so a public API returning it would hand consumers a type they cannot name. It deliberately omits `table`, which `status()` obtains by constructing each migration — instantiating user classes to decorate a listing lets a constructor throw inside the very call meant to report on a broken tree
 
-  `getPendingMigrations()` is now public alongside it. **Both document the trap in their own JSDoc:** only *registered* migrations can be pending, so a caller that has not registered anything receives `[]` — indistinguishable from a database with nothing pending, and the reason `@warlock.js/core`'s CLI loads before it reports
+  `getPendingMigrations()` is now public alongside it. **Both document the trap in their own JSDoc:** only _registered_ migrations can be pending, so a caller that has not registered anything receives `[]` — indistinguishable from a database with nothing pending, and the reason `@warlock.js/core`'s CLI loads before it reports
 
 ### Changed
 
@@ -240,7 +253,7 @@ changelogs.
 ### Fixed
 
 - `migrate:rollback` and `migrate:rollback --all` ran `down()` migrations in **apply order** instead of reverse. `getMigrationsToRollback` reversed the executed list and then re-sorted it ascending, which put it straight back into forward order and made the reverse dead code — so a rollback would drop a table before dropping the column added to it, failing with `relation "…" does not exist`. Any batch containing more than one migration was affected; single-migration batches hid it because one item has no order to get wrong
-- migration ordering now lives in `migration-order.ts` with an explicit `sortMigrationsForRollback`. The descending sort is required, not cosmetic: the executed list is read back ordered by `batch, name`, so it is alphabetical rather than chronological and simply *not* re-sorting after the reverse would have produced reverse-alphabetical order — a different wrong answer
+- migration ordering now lives in `migration-order.ts` with an explicit `sortMigrationsForRollback`. The descending sort is required, not cosmetic: the executed list is read back ordered by `batch, name`, so it is alphabetical rather than chronological and simply _not_ re-sorting after the reverse would have produced reverse-alphabetical order — a different wrong answer
 
 ## 4.9.1
 

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)