@uql/core 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -3,12 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [3.14.0](https://github.com/rogerpadilla/uql/compare/@uql/core@3.13.1...@uql/core@3.14.0) (2026-03-07)
+# [3.15.0](https://github.com/rogerpadilla/uql/compare/@uql/core@3.14.1...@uql/core@3.15.0) (2026-03-07)
 
 
 ### Features
 
-* Standardize the `$select` query parameter to accept an object instead of an array for field selection. ([b4dca74](https://github.com/rogerpadilla/uql/commit/b4dca74e65013c14dd508c9ccea646b44eee1f3e))
+* Introduce entity lifecycle hooks and global querier listeners. ([27055ca](https://github.com/rogerpadilla/uql/commit/27055ca5be5364be0430300590f6d3ed3503bbec))
+* introduce entity lifecycle hooks with `@BeforeInsert`, `@AfterLoad`, `@BeforeUpdate`, `@BeforeDelete`, and `@AfterDelete` decorators. ([2e901bc](https://github.com/rogerpadilla/uql/commit/2e901bc83801a87ae30fdd069ae35a2d49c72328))
 
 
 
@@ -20,6 +21,41 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [3.15.0] - 2026-03-07
+### New Features
+- **Lifecycle Hooks**: Added entity-level lifecycle hook decorators for domain-specific logic. Seven decorators are available: `@BeforeInsert()`, `@AfterInsert()`, `@BeforeUpdate()`, `@AfterUpdate()`, `@BeforeDelete()`, `@AfterDelete()`, and `@AfterLoad()`. Hooks receive a `HookContext` with access to the active `querier` for transactional DB operations.
+  ```ts
+  @Entity()
+  class Article {
+    @BeforeInsert()
+    generateSlug() {
+      this.slug = this.title.toLowerCase().replace(/\s+/g, '-');
+    }
+
+    @AfterLoad()
+    maskSensitiveData() {
+      this.internalCode = '***';
+    }
+  }
+  ```
+- **Global Querier Listeners**: Added `QuerierListener` interface and `listeners` option on `ExtraOptions` for cross-cutting concerns (audit logging, automatic timestamps, cache invalidation). Listeners fire before entity-level hooks.
+  ```ts
+  const pool = new PgQuerierPool(connectionConfig, {
+    listeners: [{
+      beforeInsert: ({ entity, payloads }) => { /* audit log */ },
+      afterUpdate: ({ entity, querier }) => { /* invalidate cache */ },
+    }],
+  });
+  ```
+
+### Architecture
+- **Renamed Internal Methods**: `insertMany`/`updateMany` in `AbstractSqlQuerier` and `MongodbQuerier` are now `internalInsertMany`/`internalUpdateMany` (protected). Public `insertMany`/`updateMany` in `AbstractQuerier` wrap them with hook emission.
+- **New Utility**: `runHooks()` in `util/hook.util.ts` — lightweight hook invocation engine using `entity.prototype[method].call(payload, ctx)`.
+- **Hook Inheritance**: Entity hooks are inherited from parent classes (parent hooks execute first).
+
+### Test Coverage
+- **22 new tests** (11 for decorators, 11 for `runHooks`). Total: **1602 tests passing**. Coverage: Statements 97.2%, Branches 90.1%, Functions 98.4%, Lines 98.0%.
+
 ## [3.14.0] - 2026-03-07
 ### Type Safety
 - **Map-Only `$select`**: `$select` now only accepts the map form (e.g., `{ id: true, name: true }`), removing the less type-safe array form. Relation selections are now additive in map form.

package/README.md

@@ -29,6 +29,7 @@ const users = await querier.findMany(User, {
 | **Smart SQL Engine**                                               | Optimized sub-queries, placeholders ($1, $2), and minimal SQL generation via `QueryContext`.                                  |
 | **Thread-Safe by Design**                                          | Centralized task queue and `@Serialized()` decorator prevent race conditions.                                                 |
 | **[Declarative Transactions](https://uql.app/transactions)**  | Standard `@Transactional()` and `@InjectQuerier()` decorators for NestJS/DI.                                                |
+| **[Lifecycle Hooks](https://uql.app/entities/lifecycle-hooks)**| `@BeforeInsert`, `@AfterLoad` and 5 more decorators for validation, timestamps, and computed fields.                        |
 | **[Modern & Versatile](https://uql.app/entities/virtual-fields)** | **Pure ESM**, high-res timing, [Soft-delete](https://uql.app/entities/soft-delete), and **Vector/JSONB/JSON** support. |
 | **[Database Migrations](https://www.uql.app/migrations)**          | Built-in [Entity-First synchronization](https://uql.app/migrations#3-entity-first-synchronization-development) and a robust CLI for version-controlled schema evolution. |
 | **[Logging & Monitoring](https://www.uql.app/logging)**               | Professional-grade monitoring with slow-query detection and colored output.                                                     |
@@ -90,6 +91,10 @@ Annotate your classes with decorators. UQL's engine uses this metadata for both
 | `@ManyToOne`  | Defines a many-to-one relationship.                                            |
 | `@ManyToMany` | Defines a many-to-many relationship.                                           |
 | `@Virtual()`  | Defines a read-only field calculated via SQL (see Advanced).                    |
+| `@BeforeInsert` / `@AfterInsert` | Lifecycle hooks fired around `insert` operations.           |
+| `@BeforeUpdate` / `@AfterUpdate` | Lifecycle hooks fired around `update` operations.           |
+| `@BeforeDelete` / `@AfterDelete` | Lifecycle hooks fired around `delete` operations.           |
+| `@AfterLoad`  | Lifecycle hook fired after loading entities from the database.                  |
 
 ### Type Abstraction: Logical vs. Physical
 
@@ -531,6 +536,7 @@ Learn more about UQL at [uql.app](https://uql.app) for details on:
 
 - [Complex Logical Operators](https://uql.app/querying/logical-operators)
 - [Relationship Mapping (1-1, 1-M, M-M)](https://uql.app/querying/relations)
+- [Lifecycle Hooks](https://uql.app/entities/lifecycle-hooks)
 - [Soft Deletes & Auditing](https://uql.app/entities/soft-delete)
 - [Database Migration & Syncing](https://uql.app/migrations)