feat: add WatchedFieldsMixin (#148)

* feat/add WatchedFieldsMixin and watch_fields decorator for field-change monitoring

* docs: add WatchedFieldsMixin

* feat: add on_event, on_create and on_delete

* docs: update README

docs/index.md

@@ -48,7 +48,7 @@ uv add "fastapi-toolsets[all]"
 - **Database**: Session management, transaction helpers, table locking, and polling-based row change detection
 - **Dependencies**: FastAPI dependency factories (`PathDependency`, `BodyDependency`) for automatic DB lookups from path or body parameters
 - **Fixtures**: Fixture system with dependency management, context support, and pytest integration
-- **Model Mixins**: SQLAlchemy mixins for common column patterns (`UUIDMixin`, `UUIDv7Mixin`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`)
+- **Model Mixins**: SQLAlchemy mixins for common column patterns (`UUIDMixin`, `UUIDv7Mixin`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`) and lifecycle callbacks (`WatchedFieldsMixin`) that fire after commit for insert, update, and delete events.
 - **Standardized API Responses**: Consistent response format with `Response`, `ErrorResponse`, `PaginatedResponse`, `CursorPaginatedResponse` and `OffsetPaginatedResponse`.
 - **Exception Handling**: Structured error responses with automatic OpenAPI documentation
 - **Logging**: Logging configuration with uvicorn integration via `configure_logging` and `get_logger`

docs/module/models.md

@@ -117,6 +117,86 @@ class Article(Base, UUIDMixin, TimestampMixin):
     title: Mapped[str]
 ```
 
+### [`WatchedFieldsMixin`](../reference/models.md#fastapi_toolsets.models.WatchedFieldsMixin)
+
+!!! info "Added in `v2.4`"
+
+`WatchedFieldsMixin` provides lifecycle callbacks that fire **after commit** — meaning the row is durably persisted when your callback runs. If the transaction rolls back, no callback fires.
+
+Three callbacks are available, each corresponding to a [`ModelEvent`](../reference/models.md#fastapi_toolsets.models.ModelEvent) value:
+
+| Callback | Event | Trigger |
+|---|---|---|
+| `on_create()` | `ModelEvent.CREATE` | After `INSERT` |
+| `on_delete()` | `ModelEvent.DELETE` | After `DELETE` |
+| `on_update(changes)` | `ModelEvent.UPDATE` | After `UPDATE` on a watched field |
+
+Server-side defaults (e.g. `id`, `created_at`) are fully populated in all callbacks. All callbacks support both `async def` and plain `def`. Use `@watch` to restrict which fields trigger `on_update`:
+
+| Decorator | `on_update` behaviour |
+|---|---|
+| `@watch("status", "role")` | Only fires when `status` or `role` changes |
+| *(no decorator)* | Fires when **any** mapped field changes |
+
+#### Option 1 — catch-all with `on_event`
+
+Override `on_event` to handle all event types in one place. The specific methods delegate here by default:
+
+```python
+from fastapi_toolsets.models import ModelEvent, UUIDMixin, WatchedFieldsMixin, watch
+
+@watch("status")
+class Order(Base, UUIDMixin, WatchedFieldsMixin):
+    __tablename__ = "orders"
+
+    status: Mapped[str]
+
+    async def on_event(self, event: ModelEvent, changes: dict | None = None) -> None:
+        if event == ModelEvent.CREATE:
+            await notify_new_order(self.id)
+        elif event == ModelEvent.DELETE:
+            await notify_order_cancelled(self.id)
+        elif event == ModelEvent.UPDATE:
+            await notify_status_change(self.id, changes["status"])
+```
+
+#### Option 2 — targeted overrides
+
+Override individual methods for more focused logic:
+
+```python
+@watch("status")
+class Order(Base, UUIDMixin, WatchedFieldsMixin):
+    __tablename__ = "orders"
+
+    status: Mapped[str]
+
+    async def on_create(self) -> None:
+        await notify_new_order(self.id)
+
+    async def on_delete(self) -> None:
+        await notify_order_cancelled(self.id)
+
+    async def on_update(self, changes: dict) -> None:
+        if "status" in changes:
+            old = changes["status"]["old"]
+            new = changes["status"]["new"]
+            await notify_status_change(self.id, old, new)
+```
+
+#### Field changes format
+
+The `changes` dict maps each watched field that changed to `{"old": ..., "new": ...}`. Only fields that actually changed are included:
+
+```python
+# status changed   → {"status": {"old": "pending", "new": "shipped"}}
+# two fields changed → {"status": {...}, "assigned_to": {...}}
+```
+
+!!! info "Multiple flushes in one transaction are merged: the earliest `old` and latest `new` are preserved, and `on_update` fires only once per commit."
+
+!!! warning "Callbacks fire only for ORM-level changes. Rows updated via raw SQL (`UPDATE ... SET ...`) are not detected."
+
 ## Composing mixins
 
 All mixins can be combined in any order. The only constraint is that exactly one primary key must be defined — either via `UUIDMixin` or directly on the model.

docs/reference/models.md

@@ -6,14 +6,19 @@ You can import them directly from `fastapi_toolsets.models`:
 
 ```python
 from fastapi_toolsets.models import (
+    ModelEvent,
     UUIDMixin,
     UUIDv7Mixin,
     CreatedAtMixin,
     UpdatedAtMixin,
     TimestampMixin,
+    WatchedFieldsMixin,
+    watch,
 )
 ```
 
+## ::: fastapi_toolsets.models.ModelEvent
+
 ## ::: fastapi_toolsets.models.UUIDMixin
 
 ## ::: fastapi_toolsets.models.UUIDv7Mixin
@@ -23,3 +28,7 @@ from fastapi_toolsets.models import (
 ## ::: fastapi_toolsets.models.UpdatedAtMixin
 
 ## ::: fastapi_toolsets.models.TimestampMixin
+
+## ::: fastapi_toolsets.models.WatchedFieldsMixin
+
+## ::: fastapi_toolsets.models.watch