fix: add tests

docs: unified paginate() endpoint
feat: unified paginate() endpoint with typed pagination responses
2026-04-16 14:46:24 +02:00 · 2026-03-14 07:04:29 -04:00 · 2026-03-14 06:53:28 -04:00 · 2026-03-14 06:47:03 -04:00 · 2026-03-12 22:46:51 +01:00 · 2026-03-12 15:39:44 -04:00
46 changed files with 3643 additions and 1306 deletions
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ A modular collection of production-ready utilities for FastAPI. Install only wha

 ## Installation

-The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, logging):
+The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, model mixins, logging):

 ```bash
 uv add fastapi-toolsets
@@ -29,9 +29,9 @@ uv add fastapi-toolsets
 Install only the extras you need:

 ```bash
-uv add "fastapi-toolsets[cli]"      # CLI (typer)
-uv add "fastapi-toolsets[metrics]"  # Prometheus metrics (prometheus_client)
-uv add "fastapi-toolsets[pytest]"   # Pytest helpers (httpx, pytest-xdist)
+uv add "fastapi-toolsets[cli]"
+uv add "fastapi-toolsets[metrics]"
+uv add "fastapi-toolsets[pytest]"
 ```

 Or install everything:
@@ -48,6 +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`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`)
 - **Standardized API Responses**: Consistent response format with `Response`, `PaginatedResponse`, and `PydanticBase`
 - **Exception Handling**: Structured error responses with automatic OpenAPI documentation
 - **Logging**: Logging configuration with uvicorn integration via `configure_logging` and `get_logger`
--- a/docs/examples/pagination-search.md
+++ b/docs/examples/pagination-search.md
@@ -42,12 +42,17 @@ Declare `searchable_fields`, `facet_fields`, and `order_fields` once on [`CrudFa


 ## Routes
+
+```python title="routes.py:1:17"
+--8<-- "docs_src/examples/pagination_search/routes.py:1:17"
+```
+
 ### Offset pagination

 Best for admin panels or any UI that needs a total item count and numbered pages.

-```python title="routes.py:1:36"
--8<-- "docs_src/examples/pagination_search/routes.py:1:36"
+```python title="routes.py:20:40"
+--8<-- "docs_src/examples/pagination_search/routes.py:20:40"
 ```

 **Example request**
@@ -61,6 +66,7 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&or
 ```json
 {
  "status": "SUCCESS",
+  "pagination_type": "offset",
  "data": [
    { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
  ],
@@ -83,8 +89,8 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&or

 Best for feeds, infinite scroll, or any high-throughput API where offset performance degrades.

-```python title="routes.py:39:59"
--8<-- "docs_src/examples/pagination_search/routes.py:39:59"
+```python title="routes.py:43:63"
+--8<-- "docs_src/examples/pagination_search/routes.py:43:63"
 ```

 **Example request**
@@ -98,6 +104,7 @@ GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&orde
 ```json
 {
  "status": "SUCCESS",
+  "pagination_type": "cursor",
  "data": [
    { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
  ],
@@ -116,6 +123,47 @@ GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&orde

 Pass `next_cursor` as the `cursor` query parameter on the next request to advance to the next page.

+### Unified endpoint (both strategies)
+
+!!! info "Added in `v2.3.0`"
+
+[`paginate()`](../module/crud.md#unified-paginate--both-strategies-on-one-endpoint) lets a single endpoint support both strategies via a `pagination_type` query parameter. The `pagination_type` field in the response acts as a discriminator for frontend tooling.
+
+```python title="routes.py:66:90"
+--8<-- "docs_src/examples/pagination_search/routes.py:66:90"
+```
+
+**Offset request** (default)
+
+```
+GET /articles/?pagination_type=offset&page=1&items_per_page=10
+```
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "offset",
+  "data": ["..."],
+  "pagination": { "total_count": 42, "page": 1, "items_per_page": 10, "has_more": true }
+}
+```
+
+**Cursor request**
+
+```
+GET /articles/?pagination_type=cursor&items_per_page=10
+GET /articles/?pagination_type=cursor&items_per_page=10&cursor=eyJ2YWx1ZSI6...
+```
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "cursor",
+  "data": ["..."],
+  "pagination": { "next_cursor": "eyJ2YWx1ZSI6...", "prev_cursor": null, "items_per_page": 10, "has_more": true }
+}
+```
+
 ## Search behaviour

 Both endpoints inherit the same `searchable_fields` declared on `ArticleCrud`:
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,7 @@ A modular collection of production-ready utilities for FastAPI. Install only wha

 ## Installation

-The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, logging):
+The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, model mixins, logging):

 ```bash
 uv add fastapi-toolsets
@@ -29,9 +29,9 @@ uv add fastapi-toolsets
 Install only the extras you need:

 ```bash
-uv add "fastapi-toolsets[cli]"      # CLI (typer)
-uv add "fastapi-toolsets[metrics]"  # Prometheus metrics (prometheus_client)
-uv add "fastapi-toolsets[pytest]"   # Pytest helpers (httpx, pytest-xdist)
+uv add "fastapi-toolsets[cli]"
+uv add "fastapi-toolsets[metrics]"
+uv add "fastapi-toolsets[pytest]"
 ```

 Or install everything:
@@ -44,10 +44,11 @@ uv add "fastapi-toolsets[all]"

 ### Core

- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in full-text/faceted search and offset/cursor pagination.
+- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in full-text/faceted search and Offset/Cursor pagination.
 - **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`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`)
 - **Standardized API Responses**: Consistent response format with `Response`, `PaginatedResponse`, and `PydanticBase`
 - **Exception Handling**: Structured error responses with automatic OpenAPI documentation
 - **Logging**: Logging configuration with uvicorn integration via `configure_logging` and `get_logger`
--- a/docs/migration/v2.md
+++ b/docs/migration/v2.md
@@ -0,0 +1,137 @@
+# Migrating to v2.0
+
+This page covers every breaking change introduced in **v2.0** and the steps required to update your code.
+
+---
+
+## CRUD
+
+### `schema` is now required in `offset_paginate()` and `cursor_paginate()`
+
+Calls that omit `schema` will now raise a `TypeError` at runtime.
+
+Previously `schema` was optional; omitting it returned raw SQLAlchemy model instances inside the response. It is now a required keyword argument and the response always contains serialized schema instances.
+
+=== "Before (`v1`)"
+
+    ```python
+    # schema omitted — returned raw model instances
+    result = await UserCrud.offset_paginate(session=session, page=1)
+    result = await UserCrud.cursor_paginate(session=session, cursor=token)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    result = await UserCrud.offset_paginate(session=session, page=1, schema=UserRead)
+    result = await UserCrud.cursor_paginate(session=session, cursor=token, schema=UserRead)
+    ```
+
+### `as_response` removed from `create()`, `get()`, and `update()`
+
+Passing `as_response` to these methods will raise a `TypeError` at runtime.
+
+The `as_response=True` shorthand is replaced by passing a `schema` directly. The return value is a `Response[schema]` when `schema` is provided, or the raw model instance when it is not.
+
+=== "Before (`v1`)"
+
+    ```python
+    user = await UserCrud.create(session=session, obj=data, as_response=True)
+    user = await UserCrud.get(session=session, filters=filters, as_response=True)
+    user = await UserCrud.update(session=session, obj=data, filters, as_response=True)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    user = await UserCrud.create(session=session, obj=data, schema=UserRead)
+    user = await UserCrud.get(session=session, filters=filters, schema=UserRead)
+    user = await UserCrud.update(session=session, obj=data, filters, schema=UserRead)
+    ```
+
+### `delete()`: `as_response` renamed and return type changed
+
+`as_response` is gone, and the plain (non-response) call no longer returns `True`.
+
+Two changes were made to `delete()`:
+
+1. The `as_response` parameter is renamed to `return_response`.
+2. When called without `return_response=True`, the method now returns `None` on success instead of `True`.
+
+=== "Before (`v1`)"
+
+    ```python
+    ok = await UserCrud.delete(session=session, filters=filters)
+    if ok:  # True on success
+        ...
+
+    response = await UserCrud.delete(session=session, filters=filters, as_response=True)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    await UserCrud.delete(session=session, filters=filters)  # returns None
+
+    response = await UserCrud.delete(session=session, filters=filters, return_response=True)
+    ```
+
+### `paginate()` alias removed
+
+Any call to `crud.paginate(...)` will raise `AttributeError` at runtime.
+
+The `paginate` shorthand was an alias for `offset_paginate`. It has been removed; call `offset_paginate` directly.
+
+=== "Before (`v1`)"
+
+    ```python
+    result = await UserCrud.paginate(session=session, page=2, items_per_page=20, schema=UserRead)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    result = await UserCrud.offset_paginate(session=session, page=2, items_per_page=20, schema=UserRead)
+    ```
+
+---
+
+## Exceptions
+
+### Missing `api_error` raises `TypeError` at class definition time
+
+Unfinished or stub exception subclasses that previously compiled fine will now fail on import.
+
+In `v1`, a subclass without `api_error` would only fail when the exception was raised. In `v2`, `__init_subclass__` validates this at class definition time.
+
+=== "Before (`v1`)"
+
+    ```python
+    class MyError(ApiException):
+        pass  # fine until raised
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    class MyError(ApiException):
+        pass  # TypeError: MyError must define an 'api_error' class attribute.
+    ```
+
+For shared base classes that are not meant to be raised directly, use `abstract=True`:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors — not raised directly."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+```
+
+---
+
+## Schemas
+
+### `Pagination` alias removed
+
+`Pagination` was already deprecated in `v1` and is fully removed in `v2`, you now need to use [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) or [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination).
--- a/docs/module/crud.md
+++ b/docs/module/crud.md
@@ -7,10 +7,12 @@ Generic async CRUD operations for SQLAlchemy models with search, pagination, and

 ## Overview

-The `crud` module provides [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud), an abstract base class with a full suite of async database operations, and [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory), a convenience function to instantiate it for a given model.
+The `crud` module provides [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud), a base class with a full suite of async database operations, and [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory), a convenience function to instantiate it for a given model.

 ## Creating a CRUD class

+### Factory style
+
 ```python
 from fastapi_toolsets.crud import CrudFactory
 from myapp.models import User
@@ -18,10 +20,70 @@ from myapp.models import User
 UserCrud = CrudFactory(model=User)
 ```

-[`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory) dynamically creates a class named `AsyncUserCrud` with `User` as its model.
+[`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory) dynamically creates a class named `AsyncUserCrud` with `User` as its model. This is the most concise option for straightforward CRUD with no custom logic.
+
+### Subclass style
+
+!!! info "Added in `v2.3.0`"
+
+```python
+from fastapi_toolsets.crud.factory import AsyncCrud
+from myapp.models import User
+
+class UserCrud(AsyncCrud[User]):
+    model = User
+    searchable_fields = [User.username, User.email]
+    default_load_options = [selectinload(User.role)]
+```
+
+Subclassing [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud) directly is the preferred style when you need to add custom methods or when the configuration is complex enough to benefit from a named class body. 
+
+### Adding custom methods
+
+```python
+class UserCrud(AsyncCrud[User]):
+    model = User
+
+    @classmethod
+    async def get_active(cls, session: AsyncSession) -> list[User]:
+        return await cls.get_multi(session, filters=[User.is_active == True])
+```
+
+### Sharing a custom base across multiple models
+
+Define a generic base class with the shared methods, then subclass it for each model:
+
+```python
+from typing import Generic, TypeVar
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from fastapi_toolsets.crud.factory import AsyncCrud
+
+T = TypeVar("T", bound=DeclarativeBase)
+
+class AuditedCrud(AsyncCrud[T], Generic[T]):
+    """Base CRUD with custom function"""
+
+    @classmethod
+    async def get_active(cls, session: AsyncSession):
+        return await cls.get_multi(session, filters=[cls.model.is_active == True])
+
+
+class UserCrud(AuditedCrud[User]):
+    model = User
+    searchable_fields = [User.username, User.email]
+```
+
+You can also use the factory shorthand with the same base by passing `base_class`:
+
+```python
+UserCrud = CrudFactory(User, base_class=AuditedCrud)
+```

 ## Basic operations

+!!! info "`get_or_none` added in `v2.2`"
+
 ```python
 # Create
 user = await UserCrud.create(session=session, obj=UserCreateSchema(username="alice"))
@@ -29,6 +91,9 @@ user = await UserCrud.create(session=session, obj=UserCreateSchema(username="ali
 # Get one (raises NotFoundError if not found)
 user = await UserCrud.get(session=session, filters=[User.id == user_id])

+# Get one or None (never raises)
+user = await UserCrud.get_or_none(session=session, filters=[User.id == user_id])
+
 # Get first or None
 user = await UserCrud.first(session=session, filters=[User.email == email])

@@ -46,45 +111,74 @@ count = await UserCrud.count(session=session, filters=[User.is_active == True])
 exists = await UserCrud.exists(session=session, filters=[User.email == email])
 ```

+## Fetching a single record
+
+Three methods fetch a single record — choose based on how you want to handle the "not found" case and whether you need strict uniqueness:
+
+| Method | Not found | Multiple results |
+|---|---|---|
+| `get` | raises `NotFoundError` | raises `MultipleResultsFound` |
+| `get_or_none` | returns `None` | raises `MultipleResultsFound` |
+| `first` | returns `None` | returns the first match silently |
+
+Use `get` when the record must exist (e.g. a detail endpoint that should return 404):
+
+```python
+user = await UserCrud.get(session=session, filters=[User.id == user_id])
+```
+
+Use `get_or_none` when the record may not exist but you still want strict uniqueness enforcement:
+
+```python
+user = await UserCrud.get_or_none(session=session, filters=[User.email == email])
+if user is None:
+    ...  # handle missing case without catching an exception
+```
+
+Use `first` when you only care about any one match and don't need uniqueness:
+
+```python
+user = await UserCrud.first(session=session, filters=[User.is_active == True])
+```
+
 ## Pagination

 !!! info "Added in `v1.1` (only offset_pagination via `paginate` if `<v1.1`)"

-Two pagination strategies are available. Both return a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) but differ in how they navigate through results.
+Three pagination methods are available.  All return a typed response whose `pagination_type` field tells clients which strategy was used.

-| | `offset_paginate` | `cursor_paginate` |
-|---|---|---|
-| Total count | Yes | No |
-| Jump to arbitrary page | Yes | No |
-| Performance on deep pages | Degrades | Constant |
-| Stable under concurrent inserts | No | Yes |
-| Search compatible | Yes | Yes |
-| Use case | Admin panels, numbered pagination | Feeds, APIs, infinite scroll |
+| | `offset_paginate` | `cursor_paginate` | `paginate` |
+|---|---|---|---|
+| Return type | `OffsetPaginatedResponse` | `CursorPaginatedResponse` | either, based on `pagination_type` param |
+| Total count | Yes | No | / |
+| Jump to arbitrary page | Yes | No | / |
+| Performance on deep pages | Degrades | Constant | / |
+| Stable under concurrent inserts | No | Yes | / |
+| Use case | Admin panels, numbered pagination | Feeds, APIs, infinite scroll | single endpoint, both strategies |

 ### Offset pagination

 ```python
-@router.get(
-    "",
-    response_model=PaginatedResponse[User],
-)
+@router.get("")
 async def get_users(
    session: SessionDep,
    items_per_page: int = 50,
    page: int = 1,
-):
-    return await crud.UserCrud.offset_paginate(
+) -> OffsetPaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(
        session=session,
        items_per_page=items_per_page,
        page=page,
+        schema=UserRead,
    )
 ```

-The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) method returns a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) whose `pagination` field is an [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) object:
+The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) method returns an [`OffsetPaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPaginatedResponse):

 ```json
 {
  "status": "SUCCESS",
+  "pagination_type": "offset",
  "data": ["..."],
  "pagination": {
    "total_count": 100,
@@ -95,33 +189,29 @@ The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.Async
 }
 ```

-!!! warning "Deprecated: `paginate`"
-    The `paginate` function is a backward-compatible alias for `offset_paginate`. This function is **deprecated** and will be removed in **v2.0**.
-
 ### Cursor pagination

 ```python
-@router.get(
-    "",
-    response_model=PaginatedResponse[UserRead],
-)
+@router.get("")
 async def list_users(
    session: SessionDep,
    cursor: str | None = None,
    items_per_page: int = 20,
-):
+) -> CursorPaginatedResponse[UserRead]:
    return await UserCrud.cursor_paginate(
        session=session,
        cursor=cursor,
        items_per_page=items_per_page,
+        schema=UserRead,
    )
 ```

-The [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate) method returns a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) whose `pagination` field is a [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) object:
+The [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate) method returns a [`CursorPaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPaginatedResponse):

 ```json
 {
  "status": "SUCCESS",
+  "pagination_type": "cursor",
  "data": ["..."],
  "pagination": {
    "next_cursor": "eyJ2YWx1ZSI6ICIzZjQ3YWM2OS0uLi4ifQ==",
@@ -166,6 +256,41 @@ PostCrud = CrudFactory(model=Post, cursor_column=Post.id)
 PostCrud = CrudFactory(model=Post, cursor_column=Post.created_at)
 ```

+### Unified endpoint (both strategies)
+
+!!! info "Added in `v2.3.0`"
+
+[`paginate()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.paginate) dispatches to `offset_paginate` or `cursor_paginate` based on a `pagination_type` query parameter, letting you expose **one endpoint** that supports both strategies.  The `pagination_type` field in the response tells clients which strategy was used, enabling frontend discriminated-union typing.
+
+```python
+from fastapi_toolsets.crud import PaginationType
+from fastapi_toolsets.schemas import PaginatedResponse
+
+@router.get("")
+async def list_users(
+    session: SessionDep,
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = Query(1, ge=1, description="Current page (offset only)"),
+    cursor: str | None = Query(None, description="Cursor token (cursor only)"),
+    items_per_page: int = Query(20, ge=1, le=100),
+) -> PaginatedResponse[UserRead]:
+    return await UserCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        schema=UserRead,
+    )
+```
+
+```
+GET /users?pagination_type=offset&page=2&items_per_page=10
+GET /users?pagination_type=cursor&cursor=eyJ2YWx1ZSI6...&items_per_page=10
+```
+
+Both `page` and `cursor` are always accepted by the endpoint — unused parameters are silently ignored by `paginate()`.
+
 ## Search

 Two search strategies are available, both compatible with [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) and [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate).
@@ -180,6 +305,9 @@ Two search strategies are available, both compatible with [`offset_paginate`](..

 ### Full-text search

+!!! info "Added in `v2.2.1`"
+    The model's primary key is always included in `searchable_fields` automatically, so searching by ID works out of the box without any configuration. When no `searchable_fields` are declared, only the primary key is searched.
+
 Declare `searchable_fields` on the CRUD class. Relationship traversal is supported via tuples:

 ```python
@@ -205,40 +333,36 @@ result = await UserCrud.offset_paginate(
 This allows searching with both [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) and [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate):

 ```python
-@router.get(
-    "",
-    response_model=PaginatedResponse[User],
-)
+@router.get("")
 async def get_users(
    session: SessionDep,
    items_per_page: int = 50,
    page: int = 1,
    search: str | None = None,
-):
-    return await crud.UserCrud.offset_paginate(
+) -> OffsetPaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(
        session=session,
        items_per_page=items_per_page,
        page=page,
        search=search,
+        schema=UserRead,
    )
 ```

 ```python
-@router.get(
-    "",
-    response_model=PaginatedResponse[User],
-)
+@router.get("")
 async def get_users(
    session: SessionDep,
    cursor: str | None = None,
    items_per_page: int = 50,
    search: str | None = None,
-):
-    return await crud.UserCrud.cursor_paginate(
+) -> CursorPaginatedResponse[UserRead]:
+    return await UserCrud.cursor_paginate(
        session=session,
        items_per_page=items_per_page,
        cursor=cursor,
        search=search,
+        schema=UserRead,
    )
 ```

@@ -309,11 +433,12 @@ async def list_users(
    session: SessionDep,
    page: int = 1,
    filter_by: Annotated[dict[str, list[str]], Depends(UserCrud.filter_params())],
-) -> PaginatedResponse[UserRead]:
+) -> OffsetPaginatedResponse[UserRead]:
    return await UserCrud.offset_paginate(
        session=session,
        page=page,
        filter_by=filter_by,
+        schema=UserRead,
    )
 ```

@@ -353,8 +478,8 @@ from fastapi_toolsets.crud import OrderByClause
 async def list_users(
    session: SessionDep,
    order_by: Annotated[OrderByClause | None, Depends(UserCrud.order_params())],
-) -> PaginatedResponse[UserRead]:
-    return await UserCrud.offset_paginate(session=session, order_by=order_by)
+) -> OffsetPaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(session=session, order_by=order_by, schema=UserRead)
 ```

 The dependency adds two query parameters to the endpoint:
@@ -461,7 +586,7 @@ async def get_user(session: SessionDep, uuid: UUID) -> Response[UserRead]:
    )

@router.get("")
-async def list_users(session: SessionDep, page: int = 1) -> PaginatedResponse[UserRead]:
+async def list_users(session: SessionDep, page: int = 1) -> OffsetPaginatedResponse[UserRead]:
    return await crud.UserCrud.offset_paginate(
        session=session,
        page=page,
@@ -471,9 +596,6 @@ async def list_users(session: SessionDep, page: int = 1) -> PaginatedResponse[Us

 The schema must have `from_attributes=True` (or inherit from [`PydanticBase`](../reference/schemas.md#fastapi_toolsets.schemas.PydanticBase)) so it can be built from SQLAlchemy model instances.

-!!! warning "Deprecated: `as_response`"
-    The `as_response=True` parameter is **deprecated** and will be removed in **v2.0**. Replace it with `schema=YourSchema`.
-
 ---

 [:material-api: API Reference](../reference/crud.md)
--- a/docs/module/db.md
+++ b/docs/module/db.md
@@ -87,6 +87,37 @@ await wait_for_row_change(
 )
 ```

+## Creating a database
+
+!!! info "Added in `v2.1`"
+
+[`create_database`](../reference/db.md#fastapi_toolsets.db.create_database) creates a database at a given URL. It connects to *server_url* and issues a `CREATE DATABASE` statement:
+
+```python
+from fastapi_toolsets.db import create_database
+
+SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+
+await create_database(db_name="myapp_test", server_url=SERVER_URL)
+```
+
+For test isolation with automatic cleanup, use [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) from the `pytest` module instead — it handles drop-before, create, and drop-after automatically.
+
+## Cleaning up tables
+
+!!! info "Added in `v2.1`"
+
+[`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables) truncates all tables:
+
+```python
+from fastapi_toolsets.db import cleanup_tables
+
+@pytest.fixture(autouse=True)
+async def clean(db_session):
+    yield
+    await cleanup_tables(session=db_session, base=Base)
+```
+
 ---

 [:material-api: API Reference](../reference/db.md)
--- a/docs/module/exceptions.md
+++ b/docs/module/exceptions.md
@@ -21,30 +21,37 @@ init_exceptions_handlers(app=app)
 This registers handlers for:

 - [`ApiException`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ApiException) — all custom exceptions below
+- `HTTPException` — Starlette/FastAPI HTTP errors
 - `RequestValidationError` — Pydantic request validation (422)
 - `ResponseValidationError` — Pydantic response validation (422)
 - `Exception` — unhandled errors (500)

+It also patches `app.openapi()` to replace the default Pydantic 422 schema with a structured example matching the `ErrorResponse` format.
+
 ## Built-in exceptions

 | Exception | Status | Default message |
 |-----------|--------|-----------------|
 | [`UnauthorizedError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.UnauthorizedError) | 401 | Unauthorized |
 | [`ForbiddenError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ForbiddenError) | 403 | Forbidden |
-| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not found |
+| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not Found |
 | [`ConflictError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ConflictError) | 409 | Conflict |
-| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No searchable fields |
-| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid facet filter |
+| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No Searchable Fields |
+| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid Facet Filter |
+| [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) | 422 | Invalid Order Field |
+
+### Per-instance overrides
+
+All built-in exceptions accept optional keyword arguments to customise the response for a specific raise site without changing the class defaults:
+
+| Argument | Effect |
+|----------|--------|
+| `detail` | Overrides both `str(exc)` (log output) and the `message` field in the response body |
+| `desc` | Overrides the `description` field |
+| `data` | Overrides the `data` field |

 ```python
-from fastapi_toolsets.exceptions import NotFoundError
-
-@router.get("/users/{id}")
-async def get_user(id: int, session: AsyncSession = Depends(get_db)):
-    user = await UserCrud.first(session=session, filters=[User.id == id])
-    if not user:
-        raise NotFoundError
-    return user
+raise NotFoundError(detail="User 42 not found", desc="No user with that ID exists in the database.")
 ```

 ## Custom exceptions
@@ -58,12 +65,51 @@ from fastapi_toolsets.schemas import ApiError
 class PaymentRequiredError(ApiException):
    api_error = ApiError(
        code=402,
-        msg="Payment required",
+        msg="Payment Required",
        desc="Your subscription has expired.",
-        err_code="PAYMENT_REQUIRED",
+        err_code="BILLING-402",
    )
 ```

+!!! warning
+    Subclasses that do not define `api_error` raise a `TypeError` at **class creation time**, not at raise time.
+
+### Custom `__init__`
+
+Override `__init__` to compute `detail`, `desc`, or `data` dynamically, then delegate to `super().__init__()`:
+
+```python
+class OrderValidationError(ApiException):
+    api_error = ApiError(
+        code=422,
+        msg="Order Validation Failed",
+        desc="One or more order fields are invalid.",
+        err_code="ORDER-422",
+    )
+
+    def __init__(self, *field_errors: str) -> None:
+        super().__init__(
+            f"{len(field_errors)} validation error(s)",
+            desc=", ".join(field_errors),
+            data={"errors": [{"message": e} for e in field_errors]},
+        )
+```
+
+### Intermediate base classes
+
+Use `abstract=True` when creating a shared base that is not meant to be raised directly:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+
+class SubscriptionExpiredError(BillingError):
+    api_error = ApiError(code=402, msg="Subscription Expired", desc="...", err_code="BILLING-402-EXP")
+```
+
 ## OpenAPI response documentation

 Use [`generate_error_responses`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.generate_error_responses) to add error schemas to your endpoint's OpenAPI spec:
@@ -78,8 +124,7 @@ from fastapi_toolsets.exceptions import generate_error_responses, NotFoundError,
 async def get_user(...): ...
 ```

-!!! info
-    The pydantic validation error is automatically added by FastAPI.
+Multiple exceptions sharing the same HTTP status code are grouped under one entry, each appearing as a named example keyed by its `err_code`. This keeps the OpenAPI UI readable when several error variants map to the same status.

 ---

--- a/docs/module/metrics.md
+++ b/docs/module/metrics.md
@@ -36,7 +36,13 @@ This mounts the `/metrics` endpoint that Prometheus can scrape.

 ### Providers

-Providers are called once at startup and register metrics that are updated externally (e.g. counters, histograms):
+Providers are called once at startup by `init_metrics`. The return value (the Prometheus metric object) is stored in the registry and can be retrieved later with [`registry.get(name)`](../reference/metrics.md#fastapi_toolsets.metrics.registry.MetricsRegistry.get).
+
+Use providers when you want **deferred initialization**: the Prometheus metric is not registered with the global `CollectorRegistry` until `init_metrics` runs, not at import time. This is particularly useful for testing — importing the module in a test suite without calling `init_metrics` leaves no metrics registered, avoiding cross-test pollution.
+
+It is also useful when metrics are defined across multiple modules and merged with `include_registry`: any code that needs a metric can call `metrics.get()` on the shared registry instead of importing the metric directly from its origin module.
+
+If neither of these applies to you, declaring metrics at module level (e.g. `HTTP_REQUESTS = Counter(...)`) is simpler and equally valid.

 ```python
 from prometheus_client import Counter, Histogram
@@ -50,15 +56,32 @@ def request_duration():
    return Histogram("request_duration_seconds", "Request duration")
 ```

-### Collectors
-
-Collectors are called on every scrape. Use them for metrics that reflect current state (e.g. gauges):
+To use a provider's metric elsewhere (e.g. in a middleware), call `metrics.get()` inside the handler — **not** at module level, as providers are only initialized when `init_metrics` runs:

 ```python
+async def metrics_middleware(request: Request, call_next):
+    response = await call_next(request)
+    metrics.get("http_requests").labels(
+        method=request.method, status=response.status_code
+    ).inc()
+    return response
+```
+
+### Collectors
+
+Collectors are called on every scrape. Use them for metrics that reflect current state (e.g. gauges).
+
+!!! warning "Declare the metric at module level"
+    Do **not** instantiate the Prometheus metric inside the collector function. Doing so recreates it on every scrape, raising `ValueError: Duplicated timeseries in CollectorRegistry`. Declare it once at module level instead:
+
+```python
+from prometheus_client import Gauge
+
+_queue_depth = Gauge("queue_depth", "Current queue depth")
+
@metrics.register(collect=True)
-def queue_depth():
-    gauge = Gauge("queue_depth", "Current queue depth")
-    gauge.set(get_current_queue_depth())
+def collect_queue_depth():
+    _queue_depth.set(get_current_queue_depth())
 ```

 ## Merging registries
--- a/docs/module/models.md
+++ b/docs/module/models.md
@@ -0,0 +1,113 @@
+# Models
+
+!!! info "Added in `v2.0`"
+
+Reusable SQLAlchemy 2.0 mixins for common column patterns, designed to be composed freely on any `DeclarativeBase` model.
+
+## Overview
+
+The `models` module provides mixins that each add a single, well-defined column behaviour. They work with standard SQLAlchemy 2.0 declarative syntax and are fully compatible with `AsyncSession`.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+    content: Mapped[str]
+```
+
+All timestamp columns are timezone-aware (`TIMESTAMPTZ`). All defaults are server-side, so they are also applied when inserting rows via raw SQL outside the ORM.
+
+## Mixins
+
+### [`UUIDMixin`](../reference/models.md#fastapi_toolsets.models.UUIDMixin)
+
+Adds a `id: UUID` primary key generated server-side by PostgreSQL using `gen_random_uuid()` (requires PostgreSQL 13+). The value is retrieved via `RETURNING` after insert, so it is available on the Python object immediately after `flush()`.
+
+```python
+from fastapi_toolsets.models import UUIDMixin
+
+class User(Base, UUIDMixin):
+    __tablename__ = "users"
+
+    username: Mapped[str]
+
+# id is None before flush
+user = User(username="alice")
+await session.flush()
+print(user.id)  # UUID('...')
+```
+
+### [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin)
+
+Adds a `created_at: datetime` column set to `NOW()` on insert. The column has no `onupdate` hook — it is intentionally immutable after the row is created.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, CreatedAtMixin
+
+class Order(Base, UUIDMixin, CreatedAtMixin):
+    __tablename__ = "orders"
+
+    total: Mapped[float]
+```
+
+### [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin)
+
+Adds an `updated_at: datetime` column set to `NOW()` on insert and automatically updated to `NOW()` on every ORM-level update (via SQLAlchemy's `onupdate` hook).
+
+```python
+from fastapi_toolsets.models import UUIDMixin, UpdatedAtMixin
+
+class Post(Base, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "posts"
+
+    title: Mapped[str]
+
+post = Post(title="Hello")
+await session.flush()
+await session.refresh(post)
+
+post.title = "Hello World"
+await session.flush()
+await session.refresh(post)
+print(post.updated_at)
+```
+
+!!! note
+    `updated_at` is updated by SQLAlchemy at ORM flush time. If you update rows via raw SQL (e.g. `UPDATE posts SET ...`), the column will **not** be updated automatically — use a database trigger if you need that guarantee.
+
+### [`TimestampMixin`](../reference/models.md#fastapi_toolsets.models.TimestampMixin)
+
+Convenience mixin that combines [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin) and [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin). Equivalent to inheriting both.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+```
+
+## 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.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Event(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "events"
+    name: Mapped[str]
+
+class Counter(Base, UpdatedAtMixin):
+    __tablename__ = "counters"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    value: Mapped[int]
+```
+
+---
+
+[:material-api: API Reference](../reference/models.md)
--- a/docs/module/pytest.md
+++ b/docs/module/pytest.md
@@ -40,10 +40,10 @@ async def http_client(db_session):

 ## Database sessions in tests

-Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test:
+Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test, combined with [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) to set up a per-worker database:

 ```python
-from fastapi_toolsets.pytest import create_db_session, create_worker_database
+from fastapi_toolsets.pytest import create_worker_database, create_db_session

@pytest.fixture(scope="session")
 async def worker_db_url():
@@ -64,16 +64,28 @@ async def db_session(worker_db_url):
 !!! info
    In this example, the database is reset between each test using the argument `cleanup=True`.

+Use [`worker_database_url`](../reference/pytest.md#fastapi_toolsets.pytest.utils.worker_database_url) to derive the per-worker URL manually if needed:
+
+```python
+from fastapi_toolsets.pytest import worker_database_url
+
+url = worker_database_url("postgresql+asyncpg://user:pass@localhost/test_db", default_test_db="test")
+# e.g. "postgresql+asyncpg://user:pass@localhost/test_db_gw0" under xdist
+```
+
 ## Parallel testing with pytest-xdist

 The examples above are already compatible with parallel test execution with `pytest-xdist`.

 ## Cleaning up tables

-If you want to manually clean up a database you can use [`cleanup_tables`](../reference/pytest.md#fastapi_toolsets.pytest.utils.cleanup_tables), this will truncates all tables between tests for fast isolation:
+!!! warning
+    Since `V2.1.0` `cleanup_tables` now live in `fastapi_toolsets.db`. For backward compatibility the function is still available in `fastapi_toolsets.pytest`, but this will be remove in `V3.0.0`.
+
+If you want to manually clean up a database you can use [`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables), this will truncate all tables between tests for fast isolation:

 ```python
-from fastapi_toolsets.pytest import cleanup_tables
+from fastapi_toolsets.db import cleanup_tables

@pytest.fixture(autouse=True)
 async def clean(db_session):
--- a/docs/module/schemas.md
+++ b/docs/module/schemas.md
@@ -20,26 +20,113 @@ async def get_user(user: User = UserDep) -> Response[UserSchema]:
    return Response(data=user, message="User retrieved")
 ```

-### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
+### Paginated response models

-Wraps a list of items with pagination metadata and optional facet values.
+Three classes wrap paginated list results. Pick the one that matches your endpoint's strategy:
+
+| Class | `pagination` type | `pagination_type` field | Use when |
+|---|---|---|---|
+| [`OffsetPaginatedResponse[T]`](#offsetpaginatedresponset) | `OffsetPagination` | `"offset"` (fixed) | endpoint always uses offset |
+| [`CursorPaginatedResponse[T]`](#cursorpaginatedresponset) | `CursorPagination` | `"cursor"` (fixed) | endpoint always uses cursor |
+| [`PaginatedResponse[T]`](#paginatedresponset) | `OffsetPagination \| CursorPagination` | — | unified endpoint supporting both strategies |
+
+#### [`OffsetPaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPaginatedResponse)
+
+!!! info "Added in `v2.3.0`"
+
+Use as the return type when the endpoint always uses [`offset_paginate`](crud.md#offset-pagination).  The `pagination` field is guaranteed to be an [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) object; the response always includes a `pagination_type: "offset"` discriminator.

 ```python
-from fastapi_toolsets.schemas import PaginatedResponse, Pagination
+from fastapi_toolsets.schemas import OffsetPaginatedResponse

@router.get("/users")
-async def list_users() -> PaginatedResponse[UserSchema]:
-    return PaginatedResponse(
-        data=users,
-        pagination=Pagination(
-            total_count=100,
-            items_per_page=10,
-            page=1,
-            has_more=True,
-        ),
+async def list_users(
+    page: int = 1,
+    items_per_page: int = 20,
+) -> OffsetPaginatedResponse[UserSchema]:
+    return await UserCrud.offset_paginate(
+        session, page=page, items_per_page=items_per_page, schema=UserSchema
    )
 ```

+**Response shape:**
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "offset",
+  "data": ["..."],
+  "pagination": {
+    "total_count": 100,
+    "page": 1,
+    "items_per_page": 20,
+    "has_more": true
+  }
+}
+```
+
+#### [`CursorPaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPaginatedResponse)
+
+!!! info "Added in `v2.3.0`"
+
+Use as the return type when the endpoint always uses [`cursor_paginate`](crud.md#cursor-pagination).  The `pagination` field is guaranteed to be a [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) object; the response always includes a `pagination_type: "cursor"` discriminator.
+
+```python
+from fastapi_toolsets.schemas import CursorPaginatedResponse
+
+@router.get("/events")
+async def list_events(
+    cursor: str | None = None,
+    items_per_page: int = 20,
+) -> CursorPaginatedResponse[EventSchema]:
+    return await EventCrud.cursor_paginate(
+        session, cursor=cursor, items_per_page=items_per_page, schema=EventSchema
+    )
+```
+
+**Response shape:**
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "cursor",
+  "data": ["..."],
+  "pagination": {
+    "next_cursor": "eyJpZCI6IDQyfQ==",
+    "prev_cursor": null,
+    "items_per_page": 20,
+    "has_more": true
+  }
+}
+```
+
+#### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
+
+Base class and return type for endpoints that support **both** pagination strategies via a `pagination_type` query parameter (using [`paginate()`](crud.md#unified-paginate--both-strategies-on-one-endpoint))
+
+```python
+from fastapi_toolsets.crud import PaginationType
+from fastapi_toolsets.schemas import PaginatedResponse
+
+@router.get("/users")
+async def list_users(
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = 1,
+    cursor: str | None = None,
+    items_per_page: int = 20,
+) -> PaginatedResponse[UserSchema]:
+    return await UserCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        schema=UserSchema,
+    )
+```
+
+#### Pagination metadata models
+
 The optional `filter_attributes` field is populated when `facet_fields` are configured on the CRUD class (see [Filter attributes](crud.md#filter-attributes-facets)). It is `None` by default and can be hidden from API responses with `response_model_exclude_none=True`.

 ### [`ErrorResponse`](../reference/schemas.md#fastapi_toolsets.schemas.ErrorResponse)
--- a/docs/reference/db.md
+++ b/docs/reference/db.md
@@ -7,6 +7,8 @@ You can import them directly from `fastapi_toolsets.db`:
 ```python
 from fastapi_toolsets.db import (
    LockMode,
+    cleanup_tables,
+    create_database,
    create_db_dependency,
    create_db_context,
    get_transaction,
@@ -26,3 +28,7 @@ from fastapi_toolsets.db import (
 ## ::: fastapi_toolsets.db.lock_tables

 ## ::: fastapi_toolsets.db.wait_for_row_change
+
+## ::: fastapi_toolsets.db.create_database
+
+## ::: fastapi_toolsets.db.cleanup_tables
--- a/docs/reference/models.md
+++ b/docs/reference/models.md
@@ -0,0 +1,22 @@
+# `models`
+
+Here's the reference for the SQLAlchemy model mixins provided by the `models` module.
+
+You can import them directly from `fastapi_toolsets.models`:
+
+```python
+from fastapi_toolsets.models import (
+    UUIDMixin,
+    CreatedAtMixin,
+    UpdatedAtMixin,
+    TimestampMixin,
+)
+```
+
+## ::: fastapi_toolsets.models.UUIDMixin
+
+## ::: fastapi_toolsets.models.CreatedAtMixin
+
+## ::: fastapi_toolsets.models.UpdatedAtMixin
+
+## ::: fastapi_toolsets.models.TimestampMixin
--- a/docs/reference/pytest.md
+++ b/docs/reference/pytest.md
@@ -24,5 +24,3 @@ from fastapi_toolsets.pytest import (
 ## ::: fastapi_toolsets.pytest.utils.worker_database_url

 ## ::: fastapi_toolsets.pytest.utils.create_worker_database
-
-## ::: fastapi_toolsets.pytest.utils.cleanup_tables
--- a/docs/reference/schemas.md
+++ b/docs/reference/schemas.md
@@ -1,4 +1,4 @@
-# `schemas` module
+# `schemas`

 Here's the reference for all response models and types provided by the `schemas` module.

@@ -12,8 +12,12 @@ from fastapi_toolsets.schemas import (
    BaseResponse,
    Response,
    ErrorResponse,
-    Pagination,
+    OffsetPagination,
+    CursorPagination,
+    PaginationType,
    PaginatedResponse,
+    OffsetPaginatedResponse,
+    CursorPaginatedResponse,
 )
 ```

@@ -29,6 +33,14 @@ from fastapi_toolsets.schemas import (

 ## ::: fastapi_toolsets.schemas.ErrorResponse

-## ::: fastapi_toolsets.schemas.Pagination
+## ::: fastapi_toolsets.schemas.OffsetPagination
+
+## ::: fastapi_toolsets.schemas.CursorPagination
+
+## ::: fastapi_toolsets.schemas.PaginationType

 ## ::: fastapi_toolsets.schemas.PaginatedResponse
+
+## ::: fastapi_toolsets.schemas.OffsetPaginatedResponse
+
+## ::: fastapi_toolsets.schemas.CursorPaginatedResponse
--- a/docs_src/examples/pagination_search/routes.py
+++ b/docs_src/examples/pagination_search/routes.py
@@ -2,8 +2,12 @@ from typing import Annotated

 from fastapi import APIRouter, Depends, Query

-from fastapi_toolsets.crud import OrderByClause
-from fastapi_toolsets.schemas import PaginatedResponse
+from fastapi_toolsets.crud import OrderByClause, PaginationType
+from fastapi_toolsets.schemas import (
+    CursorPaginatedResponse,
+    OffsetPaginatedResponse,
+    PaginatedResponse,
+)

 from .crud import ArticleCrud
 from .db import SessionDep
@@ -24,7 +28,7 @@ async def list_articles_offset(
    page: int = Query(1, ge=1),
    items_per_page: int = Query(20, ge=1, le=100),
    search: str | None = None,
-) -> PaginatedResponse[ArticleRead]:
+) -> OffsetPaginatedResponse[ArticleRead]:
    return await ArticleCrud.offset_paginate(
        session=session,
        page=page,
@@ -47,7 +51,7 @@ async def list_articles_cursor(
    cursor: str | None = None,
    items_per_page: int = Query(20, ge=1, le=100),
    search: str | None = None,
-) -> PaginatedResponse[ArticleRead]:
+) -> CursorPaginatedResponse[ArticleRead]:
    return await ArticleCrud.cursor_paginate(
        session=session,
        cursor=cursor,
@@ -57,3 +61,30 @@ async def list_articles_cursor(
        order_by=order_by,
        schema=ArticleRead,
    )
+
+
+@router.get("/")
+async def list_articles(
+    session: SessionDep,
+    filter_by: Annotated[dict[str, list[str]], Depends(ArticleCrud.filter_params())],
+    order_by: Annotated[
+        OrderByClause | None,
+        Depends(ArticleCrud.order_params(default_field=Article.created_at)),
+    ],
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = Query(1, ge=1),
+    cursor: str | None = None,
+    items_per_page: int = Query(20, ge=1, le=100),
+    search: str | None = None,
+) -> PaginatedResponse[ArticleRead]:
+    return await ArticleCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        search=search,
+        filter_by=filter_by or None,
+        order_by=order_by,
+        schema=ArticleRead,
+    )
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "1.3.0"
+version = "2.2.1"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
--- a/src/fastapi_toolsets/init.py
+++ b/src/fastapi_toolsets/init.py
@@ -21,4 +21,4 @@ Example usage:
        return Response(data={"user": user.username}, message="Success")
 """

-__version__ = "1.3.0"
+__version__ = "2.2.1"
--- a/src/fastapi_toolsets/cli/commands/fixtures.py
+++ b/src/fastapi_toolsets/cli/commands/fixtures.py
@@ -72,7 +72,7 @@ async def load(
    registry = get_fixtures_registry()
    db_context = get_db_context()

-    context_list = [c.value for c in contexts] if contexts else [Context.BASE]
+    context_list = list(contexts) if contexts else [Context.BASE]

    ordered = registry.resolve_context_dependencies(*context_list)

--- a/src/fastapi_toolsets/crud/init.py
+++ b/src/fastapi_toolsets/crud/init.py
@@ -1,14 +1,19 @@
 """Generic async CRUD operations for SQLAlchemy models."""

 from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
-from .factory import CrudFactory, JoinType, M2MFieldType, OrderByClause
-from .search import (
+from ..schemas import PaginationType
+from ..types import (
    FacetFieldType,
-    SearchConfig,
-    get_searchable_fields,
+    JoinType,
+    M2MFieldType,
+    OrderByClause,
+    SearchFieldType,
 )
+from .factory import AsyncCrud, CrudFactory
+from .search import SearchConfig, get_searchable_fields

 __all__ = [
+    "AsyncCrud",
    "CrudFactory",
    "FacetFieldType",
    "get_searchable_fields",
@@ -17,5 +22,7 @@ __all__ = [
    "M2MFieldType",
    "NoSearchableFieldsError",
    "OrderByClause",
+    "PaginationType",
    "SearchConfig",
+    "SearchFieldType",
 ]
--- a/src/fastapi_toolsets/crud/factory.py
+++ b/src/fastapi_toolsets/crud/factory.py
--- a/src/fastapi_toolsets/crud/search.py
+++ b/src/fastapi_toolsets/crud/search.py
@@ -1,24 +1,23 @@
 """Search utilities for AsyncCrud."""

 import asyncio
+import functools
 from collections import Counter
 from collections.abc import Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal

-from sqlalchemy import String, or_, select
+from sqlalchemy import String, and_, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm.attributes import InstrumentedAttribute

 from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
+from ..types import FacetFieldType, SearchFieldType

 if TYPE_CHECKING:
    from sqlalchemy.sql.elements import ColumnElement

-SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
-FacetFieldType = SearchFieldType
-

@dataclass
 class SearchConfig:
@@ -37,6 +36,7 @@ class SearchConfig:
    match_mode: Literal["any", "all"] = "any"


+@functools.lru_cache(maxsize=128)
 def get_searchable_fields(
    model: type[DeclarativeBase],
    *,
@@ -101,14 +101,11 @@ def build_search_filters(
    if isinstance(search, str):
        config = SearchConfig(query=search, fields=search_fields)
    else:
-        config = search
-        if search_fields is not None:
-            config = SearchConfig(
-                query=config.query,
-                fields=search_fields,
-                case_sensitive=config.case_sensitive,
-                match_mode=config.match_mode,
-            )
+        config = (
+            replace(search, fields=search_fields)
+            if search_fields is not None
+            else search
+        )

    if not config.query or not config.query.strip():
        return [], []
@@ -227,8 +224,6 @@ async def build_facets(
                q = q.outerjoin(rel)

        if base_filters:
-            from sqlalchemy import and_
-
            q = q.where(and_(*base_filters))

        q = q.order_by(column)
--- a/src/fastapi_toolsets/db.py
+++ b/src/fastapi_toolsets/db.py
@@ -7,15 +7,19 @@ from enum import Enum
 from typing import Any, TypeVar

 from sqlalchemy import text
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase

+from .exceptions import NotFoundError
+
 __all__ = [
    "LockMode",
+    "cleanup_tables",
+    "create_database",
    "create_db_context",
    "create_db_dependency",
-    "lock_tables",
    "get_transaction",
+    "lock_tables",
    "wait_for_row_change",
 ]

@@ -186,6 +190,71 @@ async def lock_tables(
        yield session


+async def create_database(
+    db_name: str,
+    *,
+    server_url: str,
+) -> None:
+    """Create a database.
+
+    Connects to *server_url* using ``AUTOCOMMIT`` isolation and issues a
+    ``CREATE DATABASE`` statement for *db_name*.
+
+    Args:
+        db_name: Name of the database to create.
+        server_url: URL used for server-level DDL (must point to an existing
+            database on the same server).
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import create_database
+
+        SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+        await create_database("myapp_test", server_url=SERVER_URL)
+        ```
+    """
+    engine = create_async_engine(server_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text(f"CREATE DATABASE {db_name}"))
+    finally:
+        await engine.dispose()
+
+
+async def cleanup_tables(
+    session: AsyncSession,
+    base: type[DeclarativeBase],
+) -> None:
+    """Truncate all tables for fast between-test cleanup.
+
+    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
+    across every table in *base*'s metadata, which is significantly faster
+    than dropping and re-creating tables between tests.
+
+    This is a no-op when the metadata contains no tables.
+
+    Args:
+        session: An active async database session.
+        base: SQLAlchemy DeclarativeBase class containing model metadata.
+
+    Example:
+        ```python
+        @pytest.fixture
+        async def db_session(worker_db_url):
+            async with create_db_session(worker_db_url, Base) as session:
+                yield session
+                await cleanup_tables(session, Base)
+        ```
+    """
+    tables = base.metadata.sorted_tables
+    if not tables:
+        return
+
+    table_names = ", ".join(f'"{t.name}"' for t in tables)
+    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
+    await session.commit()
+
+
 _M = TypeVar("_M", bound=DeclarativeBase)


@@ -216,7 +285,7 @@ async def wait_for_row_change(
        The refreshed model instance with updated values

    Raises:
-        LookupError: If the row does not exist or is deleted during polling
+        NotFoundError: If the row does not exist or is deleted during polling
        TimeoutError: If timeout expires before a change is detected

    Example:
@@ -237,7 +306,7 @@ async def wait_for_row_change(
    """
    instance = await session.get(model, pk_value)
    if instance is None:
-        raise LookupError(f"{model.__name__} with pk={pk_value!r} not found")
+        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")

    if columns is not None:
        watch_cols = columns
@@ -261,7 +330,7 @@ async def wait_for_row_change(
        instance = await session.get(model, pk_value)

        if instance is None:
-            raise LookupError(f"{model.__name__} with pk={pk_value!r} was deleted")
+            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")

        current = {col: getattr(instance, col) for col in watch_cols}
        if current != initial:
--- a/src/fastapi_toolsets/dependencies.py
+++ b/src/fastapi_toolsets/dependencies.py
@@ -1,20 +1,17 @@
 """Dependency factories for FastAPI routes."""

 import inspect
-from collections.abc import AsyncGenerator, Callable
-from typing import Any, TypeVar, cast
+from collections.abc import Callable
+from typing import Any, cast

 from fastapi import Depends
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import DeclarativeBase

 from .crud import CrudFactory
+from .types import ModelType, SessionDependency

 __all__ = ["BodyDependency", "PathDependency"]

-ModelType = TypeVar("ModelType", bound=DeclarativeBase)
-SessionDependency = Callable[[], AsyncGenerator[AsyncSession, None]]
-

 def PathDependency(
    model: type[ModelType],
--- a/src/fastapi_toolsets/exceptions/exceptions.py
+++ b/src/fastapi_toolsets/exceptions/exceptions.py
@@ -6,32 +6,46 @@ from ..schemas import ApiError, ErrorResponse, ResponseStatus


 class ApiException(Exception):
-    """Base exception for API errors with structured response.
-
-    Subclass this to create custom API exceptions with consistent error format.
-    The exception handler will use api_error to generate the response.
-
-    Example:
-        ```python
-        class CustomError(ApiException):
-            api_error = ApiError(
-                code=400,
-                msg="Bad Request",
-                desc="The request was invalid.",
-                err_code="CUSTOM-400",
-            )
-        ```
-    """
+    """Base exception for API errors with structured response."""

    api_error: ClassVar[ApiError]

-    def __init__(self, detail: str | None = None):
+    def __init_subclass__(cls, abstract: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not abstract and not hasattr(cls, "api_error"):
+            raise TypeError(
+                f"{cls.__name__} must define an 'api_error' class attribute. "
+                "Pass abstract=True when creating intermediate base classes."
+            )
+
+    def __init__(
+        self,
+        detail: str | None = None,
+        *,
+        desc: str | None = None,
+        data: Any = None,
+    ) -> None:
        """Initialize the exception.

        Args:
-            detail: Optional override for the error message
+            detail: Optional human-readable message
+            desc: Optional per-instance override for the ``description`` field
+                in the HTTP response body.
+            data: Optional per-instance override for the ``data`` field in the
+                HTTP response body.
        """
-        super().__init__(detail or self.api_error.msg)
+        updates: dict[str, Any] = {}
+        if detail is not None:
+            updates["msg"] = detail
+        if desc is not None:
+            updates["desc"] = desc
+        if data is not None:
+            updates["data"] = data
+        if updates:
+            object.__setattr__(
+                self, "api_error", self.__class__.api_error.model_copy(update=updates)
+            )
+        super().__init__(self.api_error.msg)


 class UnauthorizedError(ApiException):
@@ -92,14 +106,15 @@ class NoSearchableFieldsError(ApiException):
        """Initialize the exception.

        Args:
-            model: The SQLAlchemy model class that has no searchable fields
+            model: The model class that has no searchable fields configured.
        """
        self.model = model
-        detail = (
-            f"No searchable fields found for model '{model.__name__}'. "
-            "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+        super().__init__(
+            desc=(
+                f"No searchable fields found for model '{model.__name__}'. "
+                "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+            )
        )
-        super().__init__(detail)


 class InvalidFacetFilterError(ApiException):
@@ -116,16 +131,17 @@ class InvalidFacetFilterError(ApiException):
        """Initialize the exception.

        Args:
-            key: The unknown filter key provided by the caller
-            valid_keys: Set of valid keys derived from the declared facet_fields
+            key: The unknown filter key provided by the caller.
+            valid_keys: Set of valid keys derived from the declared facet_fields.
        """
        self.key = key
        self.valid_keys = valid_keys
-        detail = (
-            f"'{key}' is not a declared facet field. "
-            f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+        super().__init__(
+            desc=(
+                f"'{key}' is not a declared facet field. "
+                f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+            )
        )
-        super().__init__(detail)


 class InvalidOrderFieldError(ApiException):
@@ -142,15 +158,14 @@ class InvalidOrderFieldError(ApiException):
        """Initialize the exception.

        Args:
-            field: The unknown order field provided by the caller
-            valid_fields: List of valid field names
+            field: The unknown order field provided by the caller.
+            valid_fields: List of valid field names.
        """
        self.field = field
        self.valid_fields = valid_fields
-        detail = (
-            f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
+        super().__init__(
+            desc=f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
        )
-        super().__init__(detail)


 def generate_error_responses(
@@ -158,44 +173,39 @@ def generate_error_responses(
 ) -> dict[int | str, dict[str, Any]]:
    """Generate OpenAPI response documentation for exceptions.

-    Use this to document possible error responses for an endpoint.
-
    Args:
-        *errors: Exception classes that inherit from ApiException
+        *errors: Exception classes that inherit from ApiException.

    Returns:
-        Dict suitable for FastAPI's responses parameter
-
-    Example:
-        ```python
-        from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError
-
-        @app.get(
-            "/admin",
-            responses=generate_error_responses(UnauthorizedError, ForbiddenError)
-        )
-        async def admin_endpoint():
-            ...
-        ```
+        Dict suitable for FastAPI's ``responses`` parameter.
    """
    responses: dict[int | str, dict[str, Any]] = {}

    for error in errors:
        api_error = error.api_error
+        code = api_error.code

-        responses[api_error.code] = {
-            "model": ErrorResponse,
-            "description": api_error.msg,
-            "content": {
-                "application/json": {
-                    "example": {
-                        "data": api_error.data,
-                        "status": ResponseStatus.FAIL.value,
-                        "message": api_error.msg,
-                        "description": api_error.desc,
-                        "error_code": api_error.err_code,
+        if code not in responses:
+            responses[code] = {
+                "model": ErrorResponse,
+                "description": api_error.msg,
+                "content": {
+                    "application/json": {
+                        "examples": {},
                    }
-                }
+                },
+            }
+
+        responses[code]["content"]["application/json"]["examples"][
+            api_error.err_code
+        ] = {
+            "summary": api_error.msg,
+            "value": {
+                "data": api_error.data,
+                "status": ResponseStatus.FAIL.value,
+                "message": api_error.msg,
+                "description": api_error.desc,
+                "error_code": api_error.err_code,
            },
        }

--- a/src/fastapi_toolsets/exceptions/handler.py
+++ b/src/fastapi_toolsets/exceptions/handler.py
@@ -1,56 +1,41 @@
 """Exception handlers for FastAPI applications."""

+from collections.abc import Callable
 from typing import Any

 from fastapi import FastAPI, Request, Response, status
-from fastapi.exceptions import RequestValidationError, ResponseValidationError
-from fastapi.openapi.utils import get_openapi
+from fastapi.exceptions import (
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+)
 from fastapi.responses import JSONResponse

 from ..schemas import ErrorResponse, ResponseStatus
 from .exceptions import ApiException

+_VALIDATION_LOCATION_PARAMS: frozenset[str] = frozenset(
+    {"body", "query", "path", "header", "cookie"}
+)
+

 def init_exceptions_handlers(app: FastAPI) -> FastAPI:
    """Register exception handlers and custom OpenAPI schema on a FastAPI app.

-    Installs handlers for :class:`ApiException`, validation errors, and
-    unhandled exceptions, and replaces the default 422 schema with a
-    consistent error format.
-
    Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.

    Returns:
-        The same FastAPI instance (for chaining)
-
-    Example:
-        ```python
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-        ```
+        The same FastAPI instance (for chaining).
    """
    _register_exception_handlers(app)
-    app.openapi = lambda: _custom_openapi(app)  # type: ignore[method-assign]
+    _original_openapi = app.openapi
+    app.openapi = lambda: _patched_openapi(app, _original_openapi)  # type: ignore[method-assign]
    return app


 def _register_exception_handlers(app: FastAPI) -> None:
-    """Register all exception handlers on a FastAPI application.
-
-    Args:
-        app: FastAPI application instance
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-    """
+    """Register all exception handlers on a FastAPI application."""

    @app.exception_handler(ApiException)
    async def api_exception_handler(request: Request, exc: ApiException) -> Response:
@@ -62,12 +47,25 @@ def _register_exception_handlers(app: FastAPI) -> None:
            description=api_error.desc,
            error_code=api_error.err_code,
        )
-
        return JSONResponse(
            status_code=api_error.code,
            content=error_response.model_dump(),
        )

+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+        """Handle Starlette/FastAPI HTTPException with a consistent error format."""
+        detail = exc.detail if isinstance(exc.detail, str) else "HTTP Error"
+        error_response = ErrorResponse(
+            message=detail,
+            error_code=f"HTTP-{exc.status_code}",
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=error_response.model_dump(),
+            headers=getattr(exc, "headers", None),
+        )
+
    @app.exception_handler(RequestValidationError)
    async def request_validation_handler(
        request: Request, exc: RequestValidationError
@@ -90,7 +88,6 @@ def _register_exception_handlers(app: FastAPI) -> None:
            description="An unexpected error occurred. Please try again later.",
            error_code="SERVER-500",
        )
-
        return JSONResponse(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            content=error_response.model_dump(),
@@ -105,11 +102,10 @@ def _format_validation_error(
    formatted_errors = []

    for error in errors:
-        field_path = ".".join(
-            str(loc)
-            for loc in error["loc"]
-            if loc not in ("body", "query", "path", "header", "cookie")
-        )
+        locs = error["loc"]
+        if locs and locs[0] in _VALIDATION_LOCATION_PARAMS:
+            locs = locs[1:]
+        field_path = ".".join(str(loc) for loc in locs)
        formatted_errors.append(
            {
                "field": field_path or "root",
@@ -131,34 +127,22 @@ def _format_validation_error(
    )


-def _custom_openapi(app: FastAPI) -> dict[str, Any]:
-    """Generate custom OpenAPI schema with standardized error format.
-
-    Replaces default 422 validation error responses with the custom format.
+def _patched_openapi(
+    app: FastAPI, original_openapi: Callable[[], dict[str, Any]]
+) -> dict[str, Any]:
+    """Generate the OpenAPI schema and replace default 422 responses.

    Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
+        original_openapi: The previous ``app.openapi`` callable to delegate to.

    Returns:
-        OpenAPI schema dict
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)  # Automatically sets custom OpenAPI
+        Patched OpenAPI schema dict.
    """
    if app.openapi_schema:
        return app.openapi_schema

-    openapi_schema = get_openapi(
-        title=app.title,
-        version=app.version,
-        openapi_version=app.openapi_version,
-        description=app.description,
-        routes=app.routes,
-    )
+    openapi_schema = original_openapi()

    for path_data in openapi_schema.get("paths", {}).values():
        for operation in path_data.values():
@@ -168,20 +152,25 @@ def _custom_openapi(app: FastAPI) -> dict[str, Any]:
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
-                                "example": {
-                                    "data": {
-                                        "errors": [
-                                            {
-                                                "field": "field_name",
-                                                "message": "value is not valid",
-                                                "type": "value_error",
-                                            }
-                                        ]
-                                    },
-                                    "status": ResponseStatus.FAIL.value,
-                                    "message": "Validation Error",
-                                    "description": "1 validation error(s) detected",
-                                    "error_code": "VAL-422",
+                                "examples": {
+                                    "VAL-422": {
+                                        "summary": "Validation Error",
+                                        "value": {
+                                            "data": {
+                                                "errors": [
+                                                    {
+                                                        "field": "field_name",
+                                                        "message": "value is not valid",
+                                                        "type": "value_error",
+                                                    }
+                                                ]
+                                            },
+                                            "status": ResponseStatus.FAIL.value,
+                                            "message": "Validation Error",
+                                            "description": "1 validation error(s) detected",
+                                            "error_code": "VAL-422",
+                                        },
+                                    }
                                }
                            }
                        },
--- a/src/fastapi_toolsets/fixtures/utils.py
+++ b/src/fastapi_toolsets/fixtures/utils.py
@@ -1,24 +1,84 @@
 """Fixture loading utilities for database seeding."""

 from collections.abc import Callable, Sequence
-from typing import Any, TypeVar
+from typing import Any

 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase

 from ..db import get_transaction
 from ..logger import get_logger
+from ..types import ModelType
 from .enum import LoadStrategy
 from .registry import Context, FixtureRegistry

 logger = get_logger()

-T = TypeVar("T", bound=DeclarativeBase)
+
+async def _load_ordered(
+    session: AsyncSession,
+    registry: FixtureRegistry,
+    ordered_names: list[str],
+    strategy: LoadStrategy,
+) -> dict[str, list[DeclarativeBase]]:
+    """Load fixtures in order."""
+    results: dict[str, list[DeclarativeBase]] = {}
+
+    for name in ordered_names:
+        fixture = registry.get(name)
+        instances = list(fixture.func())
+
+        if not instances:
+            results[name] = []
+            continue
+
+        model_name = type(instances[0]).__name__
+        loaded: list[DeclarativeBase] = []
+
+        async with get_transaction(session):
+            for instance in instances:
+                if strategy == LoadStrategy.INSERT:
+                    session.add(instance)
+                    loaded.append(instance)
+
+                elif strategy == LoadStrategy.MERGE:
+                    merged = await session.merge(instance)
+                    loaded.append(merged)
+
+                else:  # LoadStrategy.SKIP_EXISTING
+                    pk = _get_primary_key(instance)
+                    if pk is not None:
+                        existing = await session.get(type(instance), pk)
+                        if existing is None:
+                            session.add(instance)
+                            loaded.append(instance)
+                    else:
+                        session.add(instance)
+                        loaded.append(instance)
+
+        results[name] = loaded
+        logger.info(f"Loaded fixture '{name}': {len(loaded)} {model_name}(s)")
+
+    return results
+
+
+def _get_primary_key(instance: DeclarativeBase) -> Any | None:
+    """Get the primary key value of a model instance."""
+    mapper = instance.__class__.__mapper__
+    pk_cols = mapper.primary_key
+
+    if len(pk_cols) == 1:
+        return getattr(instance, pk_cols[0].name, None)
+
+    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
+    if all(v is not None for v in pk_values):
+        return pk_values
+    return None


 def get_obj_by_attr(
-    fixtures: Callable[[], Sequence[T]], attr_name: str, value: Any
-) -> T:
+    fixtures: Callable[[], Sequence[ModelType]], attr_name: str, value: Any
+) -> ModelType:
    """Get a SQLAlchemy model instance by matching an attribute value.

    Args:
@@ -57,13 +117,6 @@ async def load_fixtures(

    Returns:
        Dict mapping fixture names to loaded instances
-
-    Example:
-        ```python
-        # Loads 'roles' first (dependency), then 'users'
-        result = await load_fixtures(session, fixtures, "users")
-        print(result["users"])  # [User(...), ...]
-        ```
    """
    ordered = registry.resolve_dependencies(*names)
    return await _load_ordered(session, registry, ordered, strategy)
@@ -85,76 +138,6 @@ async def load_fixtures_by_context(

    Returns:
        Dict mapping fixture names to loaded instances
-
-    Example:
-        ```python
-        # Load base + testing fixtures
-        await load_fixtures_by_context(
-            session, fixtures,
-            Context.BASE, Context.TESTING
-        )
-        ```
    """
    ordered = registry.resolve_context_dependencies(*contexts)
    return await _load_ordered(session, registry, ordered, strategy)
-
-
-async def _load_ordered(
-    session: AsyncSession,
-    registry: FixtureRegistry,
-    ordered_names: list[str],
-    strategy: LoadStrategy,
-) -> dict[str, list[DeclarativeBase]]:
-    """Load fixtures in order."""
-    results: dict[str, list[DeclarativeBase]] = {}
-
-    for name in ordered_names:
-        fixture = registry.get(name)
-        instances = list(fixture.func())
-
-        if not instances:
-            results[name] = []
-            continue
-
-        model_name = type(instances[0]).__name__
-        loaded: list[DeclarativeBase] = []
-
-        async with get_transaction(session):
-            for instance in instances:
-                if strategy == LoadStrategy.INSERT:
-                    session.add(instance)
-                    loaded.append(instance)
-
-                elif strategy == LoadStrategy.MERGE:
-                    merged = await session.merge(instance)
-                    loaded.append(merged)
-
-                elif strategy == LoadStrategy.SKIP_EXISTING:
-                    pk = _get_primary_key(instance)
-                    if pk is not None:
-                        existing = await session.get(type(instance), pk)
-                        if existing is None:
-                            session.add(instance)
-                            loaded.append(instance)
-                    else:
-                        session.add(instance)
-                        loaded.append(instance)
-
-        results[name] = loaded
-        logger.info(f"Loaded fixture '{name}': {len(loaded)} {model_name}(s)")
-
-    return results
-
-
-def _get_primary_key(instance: DeclarativeBase) -> Any | None:
-    """Get the primary key value of a model instance."""
-    mapper = instance.__class__.__mapper__
-    pk_cols = mapper.primary_key
-
-    if len(pk_cols) == 1:
-        return getattr(instance, pk_cols[0].name, None)
-
-    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
-    if all(v is not None for v in pk_values):
-        return pk_values
-    return None
--- a/src/fastapi_toolsets/metrics/handler.py
+++ b/src/fastapi_toolsets/metrics/handler.py
@@ -51,19 +51,25 @@ def init_metrics(
    """
    for provider in registry.get_providers():
        logger.debug("Initialising metric provider '%s'", provider.name)
-        provider.func()
+        registry._instances[provider.name] = provider.func()

-    collectors = registry.get_collectors()
+    # Partition collectors and cache env check at startup — both are stable for the app lifetime.
+    async_collectors = [
+        c for c in registry.get_collectors() if asyncio.iscoroutinefunction(c.func)
+    ]
+    sync_collectors = [
+        c for c in registry.get_collectors() if not asyncio.iscoroutinefunction(c.func)
+    ]
+    multiprocess_mode = _is_multiprocess()

    @app.get(path, include_in_schema=False)
    async def metrics_endpoint() -> Response:
-        for collector in collectors:
-            if asyncio.iscoroutinefunction(collector.func):
-                await collector.func()
-            else:
-                collector.func()
+        for collector in sync_collectors:
+            collector.func()
+        for collector in async_collectors:
+            await collector.func()

-        if _is_multiprocess():
+        if multiprocess_mode:
            prom_registry = CollectorRegistry()
            multiprocess.MultiProcessCollector(prom_registry)
            output = generate_latest(prom_registry)
--- a/src/fastapi_toolsets/metrics/registry.py
+++ b/src/fastapi_toolsets/metrics/registry.py
@@ -19,31 +19,11 @@ class Metric:


 class MetricsRegistry:
-    """Registry for managing Prometheus metric providers and collectors.
-
-    Example:
-        ```python
-        from prometheus_client import Counter, Gauge
-        from fastapi_toolsets.metrics import MetricsRegistry
-
-        metrics = MetricsRegistry()
-
-        @metrics.register
-        def http_requests():
-            return Counter("http_requests_total", "Total HTTP requests", ["method", "status"])
-
-        @metrics.register(name="db_pool")
-        def database_pool_size():
-            return Gauge("db_pool_size", "Database connection pool size")
-
-        @metrics.register(collect=True)
-        def collect_queue_depth(gauge=Gauge("queue_depth", "Current queue depth")):
-            gauge.set(get_current_queue_depth())
-        ```
-    """
+    """Registry for managing Prometheus metric providers and collectors."""

    def __init__(self) -> None:
        self._metrics: dict[str, Metric] = {}
+        self._instances: dict[str, Any] = {}

    def register(
        self,
@@ -61,17 +41,6 @@ class MetricsRegistry:
            name: Metric name (defaults to function name).
            collect: If ``True``, the function is called on every scrape.
                If ``False`` (default), called once at init time.
-
-        Example:
-            ```python
-            @metrics.register
-            def my_counter():
-                return Counter("my_counter", "A counter")
-
-            @metrics.register(collect=True, name="queue")
-            def collect_queue_depth():
-                gauge.set(compute_depth())
-            ```
        """

        def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
@@ -87,6 +56,25 @@ class MetricsRegistry:
            return decorator(func)
        return decorator

+    def get(self, name: str) -> Any:
+        """Return the metric instance created by a provider.
+
+        Args:
+            name: The metric name (defaults to the provider function name).
+
+        Raises:
+            KeyError: If the metric name is unknown or ``init_metrics`` has not
+                been called yet.
+        """
+        if name not in self._instances:
+            if name in self._metrics:
+                raise KeyError(
+                    f"Metric '{name}' exists but has not been initialized yet. "
+                    "Ensure init_metrics() has been called before accessing metric instances."
+                )
+            raise KeyError(f"Unknown metric '{name}'.")
+        return self._instances[name]
+
    def include_registry(self, registry: "MetricsRegistry") -> None:
        """Include another :class:`MetricsRegistry` into this one.

@@ -95,18 +83,6 @@ class MetricsRegistry:

        Raises:
            ValueError: If a metric name already exists in the current registry.
-
-        Example:
-            ```python
-            main = MetricsRegistry()
-            sub = MetricsRegistry()
-
-            @sub.register
-            def sub_metric():
-                return Counter("sub_total", "Sub counter")
-
-            main.include_registry(sub)
-            ```
        """
        for metric_name, definition in registry._metrics.items():
            if metric_name in self._metrics:
--- a/src/fastapi_toolsets/models.py
+++ b/src/fastapi_toolsets/models.py
@@ -0,0 +1,47 @@
+"""SQLAlchemy model mixins for common column patterns."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Uuid, func, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+__all__ = [
+    "UUIDMixin",
+    "CreatedAtMixin",
+    "UpdatedAtMixin",
+    "TimestampMixin",
+]
+
+
+class UUIDMixin:
+    """Mixin that adds a UUID primary key auto-generated by the database."""
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid,
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+
+class CreatedAtMixin:
+    """Mixin that adds a ``created_at`` timestamp column."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+    )
+
+
+class UpdatedAtMixin:
+    """Mixin that adds an ``updated_at`` timestamp column."""
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class TimestampMixin(CreatedAtMixin, UpdatedAtMixin):
+    """Mixin that combines ``created_at`` and ``updated_at`` timestamp columns."""
--- a/src/fastapi_toolsets/pytest/utils.py
+++ b/src/fastapi_toolsets/pytest/utils.py
@@ -1,12 +1,12 @@
 """Pytest helper utilities for FastAPI testing."""

 import os
+import warnings
 from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
 from typing import Any

 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import text
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import (
    AsyncSession,
@@ -15,7 +15,134 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.orm import DeclarativeBase

-from ..db import create_db_context
+from sqlalchemy import text
+
+from ..db import (
+    cleanup_tables as _cleanup_tables,
+    create_database,
+    create_db_context,
+)
+
+
+async def cleanup_tables(
+    session: AsyncSession,
+    base: type[DeclarativeBase],
+) -> None:
+    """Truncate all tables for fast between-test cleanup.
+
+    .. deprecated::
+        Import ``cleanup_tables`` from ``fastapi_toolsets.db`` instead.
+        This re-export will be removed in v3.0.0.
+    """
+    warnings.warn(
+        "Importing cleanup_tables from fastapi_toolsets.pytest is deprecated "
+        "and will be removed in v3.0.0. "
+        "Use 'from fastapi_toolsets.db import cleanup_tables' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    await _cleanup_tables(session=session, base=base)
+
+
+def _get_xdist_worker(default_test_db: str) -> str:
+    """Return the pytest-xdist worker name, or *default_test_db* when not running under xdist.
+
+    Reads the ``PYTEST_XDIST_WORKER`` environment variable that xdist sets
+    automatically in each worker process (e.g. ``"gw0"``, ``"gw1"``).
+    When xdist is not installed or not active, the variable is absent and
+    *default_test_db* is returned instead.
+
+    Args:
+        default_test_db: Fallback value returned when ``PYTEST_XDIST_WORKER``
+            is not set.
+    """
+    return os.environ.get("PYTEST_XDIST_WORKER", default_test_db)
+
+
+def worker_database_url(database_url: str, default_test_db: str) -> str:
+    """Derive a per-worker database URL for pytest-xdist parallel runs.
+
+    Appends ``_{worker_name}`` to the database name so each xdist worker
+    operates on its own database.  When not running under xdist,
+    ``_{default_test_db}`` is appended instead.
+
+    The worker name is read from the ``PYTEST_XDIST_WORKER`` environment
+    variable (set automatically by xdist in each worker process).
+
+    Args:
+        database_url: Original database connection URL.
+        default_test_db: Suffix appended to the database name when
+            ``PYTEST_XDIST_WORKER`` is not set.
+
+    Returns:
+        A database URL with a worker- or default-specific database name.
+    """
+    worker = _get_xdist_worker(default_test_db=default_test_db)
+
+    url = make_url(database_url)
+    url = url.set(database=f"{url.database}_{worker}")
+    return url.render_as_string(hide_password=False)
+
+
+@asynccontextmanager
+async def create_worker_database(
+    database_url: str,
+    default_test_db: str = "test_db",
+) -> AsyncGenerator[str, None]:
+    """Create and drop a per-worker database for pytest-xdist isolation.
+
+    Derives a worker-specific database URL using :func:`worker_database_url`,
+    then delegates to :func:`~fastapi_toolsets.db.create_database` to create
+    and drop it.  Intended for use as a **session-scoped** fixture.
+
+    When running under xdist the database name is suffixed with the worker
+    name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.
+
+    Args:
+        database_url: Original database connection URL (used as the server
+            connection and as the base for the worker database name).
+        default_test_db: Suffix appended to the database name when
+            ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
+
+    Yields:
+        The worker-specific database URL.
+
+    Example:
+        ```python
+        from fastapi_toolsets.pytest import create_worker_database, create_db_session
+
+        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
+
+        @pytest.fixture(scope="session")
+        async def worker_db_url():
+            async with create_worker_database(DATABASE_URL) as url:
+                yield url
+
+        @pytest.fixture
+        async def db_session(worker_db_url):
+            async with create_db_session(
+                worker_db_url, Base, cleanup=True
+            ) as session:
+                yield session
+        ```
+    """
+    worker_url = worker_database_url(
+        database_url=database_url, default_test_db=default_test_db
+    )
+    worker_db_name: str = make_url(worker_url).database  # type: ignore[assignment]
+
+    engine = create_async_engine(database_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
+        await create_database(db_name=worker_db_name, server_url=database_url)
+
+        yield worker_url
+
+        async with engine.connect() as conn:
+            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
+    finally:
+        await engine.dispose()


@asynccontextmanager
@@ -156,160 +283,3 @@ async def create_db_session(
                await conn.run_sync(base.metadata.drop_all)
    finally:
        await engine.dispose()
-
-
-def _get_xdist_worker(default_test_db: str) -> str:
-    """Return the pytest-xdist worker name, or *default_test_db* when not running under xdist.
-
-    Reads the ``PYTEST_XDIST_WORKER`` environment variable that xdist sets
-    automatically in each worker process (e.g. ``"gw0"``, ``"gw1"``).
-    When xdist is not installed or not active, the variable is absent and
-    *default_test_db* is returned instead.
-
-    Args:
-        default_test_db: Fallback value returned when ``PYTEST_XDIST_WORKER``
-            is not set.
-    """
-    return os.environ.get("PYTEST_XDIST_WORKER", default_test_db)
-
-
-def worker_database_url(database_url: str, default_test_db: str) -> str:
-    """Derive a per-worker database URL for pytest-xdist parallel runs.
-
-    Appends ``_{worker_name}`` to the database name so each xdist worker
-    operates on its own database.  When not running under xdist,
-    ``_{default_test_db}`` is appended instead.
-
-    The worker name is read from the ``PYTEST_XDIST_WORKER`` environment
-    variable (set automatically by xdist in each worker process).
-
-    Args:
-        database_url: Original database connection URL.
-        default_test_db: Suffix appended to the database name when
-            ``PYTEST_XDIST_WORKER`` is not set.
-
-    Returns:
-        A database URL with a worker- or default-specific database name.
-
-    Example:
-        ```python
-        # With PYTEST_XDIST_WORKER="gw0":
-        url = worker_database_url(
-            "postgresql+asyncpg://user:pass@localhost/test_db",
-            default_test_db="test",
-        )
-        # "postgresql+asyncpg://user:pass@localhost/test_db_gw0"
-
-        # Without PYTEST_XDIST_WORKER:
-        url = worker_database_url(
-            "postgresql+asyncpg://user:pass@localhost/test_db",
-            default_test_db="test",
-        )
-        # "postgresql+asyncpg://user:pass@localhost/test_db_test"
-        ```
-    """
-    worker = _get_xdist_worker(default_test_db=default_test_db)
-
-    url = make_url(database_url)
-    url = url.set(database=f"{url.database}_{worker}")
-    return url.render_as_string(hide_password=False)
-
-
-@asynccontextmanager
-async def create_worker_database(
-    database_url: str,
-    default_test_db: str = "test_db",
-) -> AsyncGenerator[str, None]:
-    """Create and drop a per-worker database for pytest-xdist isolation.
-
-    Intended for use as a **session-scoped** fixture.  Connects to the server
-    using the original *database_url* (with ``AUTOCOMMIT`` isolation for DDL),
-    creates a dedicated database for the worker, and yields the worker-specific
-    URL.  On cleanup the worker database is dropped.
-
-    When running under xdist the database name is suffixed with the worker
-    name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.
-
-    Args:
-        database_url: Original database connection URL.
-        default_test_db: Suffix appended to the database name when
-            ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
-
-    Yields:
-        The worker-specific database URL.
-
-    Example:
-        ```python
-        from fastapi_toolsets.pytest import (
-            create_worker_database, create_db_session,
-        )
-
-        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
-
-        @pytest.fixture(scope="session")
-        async def worker_db_url():
-            async with create_worker_database(DATABASE_URL) as url:
-                yield url
-
-        @pytest.fixture
-        async def db_session(worker_db_url):
-            async with create_db_session(
-                worker_db_url, Base, cleanup=True
-            ) as session:
-                yield session
-        ```
-    """
-    worker_url = worker_database_url(
-        database_url=database_url, default_test_db=default_test_db
-    )
-    worker_db_name = make_url(worker_url).database
-
-    engine = create_async_engine(
-        database_url,
-        isolation_level="AUTOCOMMIT",
-    )
-    try:
-        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-            await conn.execute(text(f"CREATE DATABASE {worker_db_name}"))
-
-        yield worker_url
-
-        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-    finally:
-        await engine.dispose()
-
-
-async def cleanup_tables(
-    session: AsyncSession,
-    base: type[DeclarativeBase],
-) -> None:
-    """Truncate all tables for fast between-test cleanup.
-
-    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
-    across every table in *base*'s metadata, which is significantly faster
-    than dropping and re-creating tables between tests.
-
-    This is a no-op when the metadata contains no tables.
-
-    Args:
-        session: An active async database session.
-        base: SQLAlchemy DeclarativeBase class containing model metadata.
-
-    Example:
-        ```python
-        @pytest.fixture
-        async def db_session(worker_db_url):
-            async with create_db_session(worker_db_url, Base) as session:
-                yield session
-                await cleanup_tables(session, Base)
-        ```
-    """
-    tables = base.metadata.sorted_tables
-    if not tables:
-        return
-
-    table_names = ", ".join(f'"{t.name}"' for t in tables)
-    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
-    await session.commit()
--- a/src/fastapi_toolsets/schemas.py
+++ b/src/fastapi_toolsets/schemas.py
@@ -1,24 +1,26 @@
 """Base Pydantic schemas for API responses."""

 from enum import Enum
-from typing import Any, ClassVar, Generic, TypeVar
+from typing import Any, ClassVar, Generic, Literal

 from pydantic import BaseModel, ConfigDict

+from .types import DataT
+
 __all__ = [
    "ApiError",
    "CursorPagination",
+    "CursorPaginatedResponse",
    "ErrorResponse",
    "OffsetPagination",
-    "Pagination",
+    "OffsetPaginatedResponse",
    "PaginatedResponse",
+    "PaginationType",
    "PydanticBase",
    "Response",
    "ResponseStatus",
 ]

-DataT = TypeVar("DataT")
-

 class PydanticBase(BaseModel):
    """Base class for all Pydantic models with common configuration."""
@@ -108,10 +110,6 @@ class OffsetPagination(PydanticBase):
    has_more: bool


-# Backward-compatible - will be removed in v2.0
-Pagination = OffsetPagination
-
-
 class CursorPagination(PydanticBase):
    """Pagination metadata for cursor-based list responses.

@@ -128,9 +126,48 @@ class CursorPagination(PydanticBase):
    has_more: bool


+class PaginationType(str, Enum):
+    """Pagination strategy selector for :meth:`.AsyncCrud.paginate`."""
+
+    OFFSET = "offset"
+    CURSOR = "cursor"
+
+
 class PaginatedResponse(BaseResponse, Generic[DataT]):
-    """Paginated API response for list endpoints."""
+    """Paginated API response for list endpoints.
+
+    Base class and return type for endpoints that support both pagination
+    strategies.  Use :class:`OffsetPaginatedResponse` or
+    :class:`CursorPaginatedResponse` when the strategy is fixed;  use
+    ``PaginatedResponse`` as the return annotation for unified endpoints that
+    dispatch via :meth:`~fastapi_toolsets.crud.factory.AsyncCrud.paginate`.
+    """

    data: list[DataT]
    pagination: OffsetPagination | CursorPagination
+    pagination_type: PaginationType | None = None
    filter_attributes: dict[str, list[Any]] | None = None
+
+
+class OffsetPaginatedResponse(PaginatedResponse[DataT]):
+    """Paginated response with typed offset-based pagination metadata.
+
+    The ``pagination_type`` field is always ``"offset"`` and acts as a
+    discriminator, allowing frontend clients to narrow the union type returned
+    by a unified ``paginate()`` endpoint.
+    """
+
+    pagination: OffsetPagination
+    pagination_type: Literal[PaginationType.OFFSET] = PaginationType.OFFSET
+
+
+class CursorPaginatedResponse(PaginatedResponse[DataT]):
+    """Paginated response with typed cursor-based pagination metadata.
+
+    The ``pagination_type`` field is always ``"cursor"`` and acts as a
+    discriminator, allowing frontend clients to narrow the union type returned
+    by a unified ``paginate()`` endpoint.
+    """
+
+    pagination: CursorPagination
+    pagination_type: Literal[PaginationType.CURSOR] = PaginationType.CURSOR
--- a/src/fastapi_toolsets/types.py
+++ b/src/fastapi_toolsets/types.py
@@ -0,0 +1,27 @@
+"""Shared type aliases for the fastapi-toolsets package."""
+
+from collections.abc import AsyncGenerator, Callable, Mapping
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
+from sqlalchemy.orm.attributes import InstrumentedAttribute
+from sqlalchemy.sql.elements import ColumnElement
+
+# Generic TypeVars
+DataT = TypeVar("DataT")
+ModelType = TypeVar("ModelType", bound=DeclarativeBase)
+SchemaType = TypeVar("SchemaType", bound=BaseModel)
+
+# CRUD type aliases
+JoinType = list[tuple[type[DeclarativeBase], Any]]
+M2MFieldType = Mapping[str, QueryableAttribute[Any]]
+OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]
+
+# Search / facet type aliases
+SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
+FacetFieldType = SearchFieldType
+
+# Dependency type aliases
+SessionDependency = Callable[[], AsyncGenerator[AsyncSession, None]]
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -92,6 +92,15 @@ class IntRole(Base):
    name: Mapped[str] = mapped_column(String(50), unique=True)


+class Permission(Base):
+    """Test model with composite primary key."""
+
+    __tablename__ = "permissions"
+
+    subject: Mapped[str] = mapped_column(String(50), primary_key=True)
+    action: Mapped[str] = mapped_column(String(50), primary_key=True)
+
+
 class Event(Base):
    """Test model with DateTime and Date cursor columns."""

@@ -162,6 +171,7 @@ class UserRead(PydanticBase):

    id: uuid.UUID
    username: str
+    is_active: bool = True


 class UserUpdate(BaseModel):
@@ -218,12 +228,26 @@ class PostM2MUpdate(BaseModel):
    tag_ids: list[uuid.UUID] | None = None


+class IntRoleRead(PydanticBase):
+    """Schema for reading an IntRole."""
+
+    id: int
+    name: str
+
+
 class IntRoleCreate(BaseModel):
    """Schema for creating an IntRole."""

    name: str


+class EventRead(PydanticBase):
+    """Schema for reading an Event."""
+
+    id: uuid.UUID
+    name: str
+
+
 class EventCreate(BaseModel):
    """Schema for creating an Event."""

@@ -232,6 +256,13 @@ class EventCreate(BaseModel):
    scheduled_date: datetime.date


+class ProductRead(PydanticBase):
+    """Schema for reading a Product."""
+
+    id: uuid.UUID
+    name: str
+
+
 class ProductCreate(BaseModel):
    """Schema for creating a Product."""

--- a/tests/test_crud.py
+++ b/tests/test_crud.py
@@ -6,7 +6,7 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload

-from fastapi_toolsets.crud import CrudFactory
+from fastapi_toolsets.crud import CrudFactory, PaginationType
 from fastapi_toolsets.crud.factory import AsyncCrud
 from fastapi_toolsets.exceptions import NotFoundError

@@ -15,8 +15,10 @@ from .conftest import (
    EventCrud,
    EventDateCursorCrud,
    EventDateTimeCursorCrud,
+    EventRead,
    IntRoleCreate,
    IntRoleCursorCrud,
+    IntRoleRead,
    Post,
    PostCreate,
    PostCrud,
@@ -26,12 +28,14 @@ from .conftest import (
    ProductCreate,
    ProductCrud,
    ProductNumericCursorCrud,
+    ProductRead,
    Role,
    RoleCreate,
    RoleCrud,
    RoleCursorCrud,
    RoleRead,
    RoleUpdate,
+    Tag,
    TagCreate,
    TagCrud,
    User,
@@ -82,6 +86,101 @@ class TestCrudFactory:
        assert crud_with.default_load_options == options
        assert crud_without.default_load_options is None

+    def test_base_class_custom_methods_inherited(self):
+        """CrudFactory with base_class inherits custom methods from that base."""
+        from typing import Generic, TypeVar
+
+        from sqlalchemy.orm import DeclarativeBase
+
+        T = TypeVar("T", bound=DeclarativeBase)
+
+        class CustomBase(AsyncCrud[T], Generic[T]):
+            @classmethod
+            def custom_method(cls) -> str:
+                return f"custom:{cls.model.__name__}"
+
+        UserCrudCustom = CrudFactory(User, base_class=CustomBase)
+        PostCrudCustom = CrudFactory(Post, base_class=CustomBase)
+
+        assert issubclass(UserCrudCustom, CustomBase)
+        assert issubclass(PostCrudCustom, CustomBase)
+        assert UserCrudCustom.custom_method() == "custom:User"
+        assert PostCrudCustom.custom_method() == "custom:Post"
+
+    def test_base_class_pk_injected(self):
+        """PK is still injected when using a custom base_class."""
+        from typing import Generic, TypeVar
+
+        from sqlalchemy.orm import DeclarativeBase
+
+        T = TypeVar("T", bound=DeclarativeBase)
+
+        class CustomBase(AsyncCrud[T], Generic[T]):
+            pass
+
+        crud = CrudFactory(User, base_class=CustomBase)
+        assert crud.searchable_fields is not None
+        assert User.id in crud.searchable_fields
+
+
+class TestAsyncCrudSubclass:
+    """Tests for direct AsyncCrud subclassing (alternative to CrudFactory)."""
+
+    def test_subclass_with_model_only(self):
+        """Subclassing with just model auto-injects PK into searchable_fields."""
+
+        class UserCrudDirect(AsyncCrud[User]):
+            model = User
+
+        assert UserCrudDirect.searchable_fields == [User.id]
+
+    def test_subclass_with_explicit_fields_prepends_pk(self):
+        """Subclassing with searchable_fields prepends PK automatically."""
+
+        class UserCrudDirect(AsyncCrud[User]):
+            model = User
+            searchable_fields = [User.username]
+
+        assert UserCrudDirect.searchable_fields == [User.id, User.username]
+
+    def test_subclass_with_pk_already_in_fields(self):
+        """PK is not duplicated when already in searchable_fields."""
+
+        class UserCrudDirect(AsyncCrud[User]):
+            model = User
+            searchable_fields = [User.id, User.username]
+
+        assert UserCrudDirect.searchable_fields == [User.id, User.username]
+
+    def test_subclass_has_default_class_vars(self):
+        """Other ClassVars are None by default on a direct subclass."""
+
+        class UserCrudDirect(AsyncCrud[User]):
+            model = User
+
+        assert UserCrudDirect.facet_fields is None
+        assert UserCrudDirect.default_load_options is None
+        assert UserCrudDirect.cursor_column is None
+
+    def test_subclass_with_load_options(self):
+        """Direct subclass can declare default_load_options."""
+        opts = [selectinload(User.role)]
+
+        class UserCrudDirect(AsyncCrud[User]):
+            model = User
+            default_load_options = opts
+
+        assert UserCrudDirect.default_load_options is opts
+
+    def test_abstract_base_without_model_not_processed(self):
+        """Intermediate abstract class without model is not processed."""
+
+        class AbstractCrud(AsyncCrud[User]):
+            pass
+
+        # Should not raise, and searchable_fields inherits base default (None)
+        assert AbstractCrud.searchable_fields is None
+

 class TestResolveLoadOptions:
    """Tests for _resolve_load_options logic."""
@@ -169,7 +268,14 @@ class TestDefaultLoadOptionsIntegration:
    async def test_default_load_options_applied_to_paginate(
        self, db_session: AsyncSession
    ):
-        """default_load_options loads relationships automatically on paginate()."""
+        """default_load_options loads relationships automatically on offset_paginate()."""
+        from fastapi_toolsets.schemas import PydanticBase
+
+        class UserWithRoleRead(PydanticBase):
+            id: uuid.UUID
+            username: str
+            role: RoleRead | None = None
+
        UserWithDefaultLoad = CrudFactory(
            User, default_load_options=[selectinload(User.role)]
        )
@@ -178,7 +284,9 @@ class TestDefaultLoadOptionsIntegration:
            db_session,
            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
        )
-        result = await UserWithDefaultLoad.paginate(db_session)
+        result = await UserWithDefaultLoad.offset_paginate(
+            db_session, schema=UserWithRoleRead
+        )
        assert result.data[0].role is not None
        assert result.data[0].role.name == "admin"

@@ -282,6 +390,100 @@ class TestCrudGet:
        assert user.username == "active"


+class TestCrudGetOrNone:
+    """Tests for CRUD get_or_none operations."""
+
+    @pytest.mark.anyio
+    async def test_returns_record_when_found(self, db_session: AsyncSession):
+        """get_or_none returns the record when it exists."""
+        created = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        fetched = await RoleCrud.get_or_none(db_session, [Role.id == created.id])
+
+        assert fetched is not None
+        assert fetched.id == created.id
+        assert fetched.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_returns_none_when_not_found(self, db_session: AsyncSession):
+        """get_or_none returns None instead of raising NotFoundError."""
+        result = await RoleCrud.get_or_none(db_session, [Role.id == uuid.uuid4()])
+        assert result is None
+
+    @pytest.mark.anyio
+    async def test_with_schema_returns_response_when_found(
+        self, db_session: AsyncSession
+    ):
+        """get_or_none with schema returns Response[schema] when found."""
+        from fastapi_toolsets.schemas import Response
+
+        created = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        result = await RoleCrud.get_or_none(
+            db_session, [Role.id == created.id], schema=RoleRead
+        )
+
+        assert isinstance(result, Response)
+        assert isinstance(result.data, RoleRead)
+        assert result.data.name == "editor"
+
+    @pytest.mark.anyio
+    async def test_with_schema_returns_none_when_not_found(
+        self, db_session: AsyncSession
+    ):
+        """get_or_none with schema returns None (not Response) when not found."""
+        result = await RoleCrud.get_or_none(
+            db_session, [Role.id == uuid.uuid4()], schema=RoleRead
+        )
+        assert result is None
+
+    @pytest.mark.anyio
+    async def test_with_load_options(self, db_session: AsyncSession):
+        """get_or_none respects load_options."""
+        from sqlalchemy.orm import selectinload
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="member"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        fetched = await UserCrud.get_or_none(
+            db_session,
+            [User.id == user.id],
+            load_options=[selectinload(User.role)],
+        )
+
+        assert fetched is not None
+        assert fetched.role is not None
+        assert fetched.role.name == "member"
+
+    @pytest.mark.anyio
+    async def test_with_join(self, db_session: AsyncSession):
+        """get_or_none respects joins."""
+        user = await UserCrud.create(
+            db_session, UserCreate(username="author", email="author@test.com")
+        )
+        await PostCrud.create(
+            db_session,
+            PostCreate(title="Published", author_id=user.id, is_published=True),
+        )
+
+        fetched = await UserCrud.get_or_none(
+            db_session,
+            [User.id == user.id, Post.is_published == True],  # noqa: E712
+            joins=[(Post, Post.author_id == User.id)],
+        )
+        assert fetched is not None
+        assert fetched.id == user.id
+
+        # Filter that matches no join — returns None
+        missing = await UserCrud.get_or_none(
+            db_session,
+            [User.id == user.id, Post.is_published == False],  # noqa: E712
+            joins=[(Post, Post.author_id == User.id)],
+        )
+        assert missing is None
+
+
 class TestCrudFirst:
    """Tests for CRUD first operations."""

@@ -309,6 +511,38 @@ class TestCrudFirst:
        role = await RoleCrud.first(db_session)
        assert role is not None

+    @pytest.mark.anyio
+    async def test_first_with_schema(self, db_session: AsyncSession):
+        """First with schema returns a Response wrapping the serialized record."""
+        await RoleCrud.create(db_session, RoleCreate(name="admin"))
+
+        result = await RoleCrud.first(
+            db_session, [Role.name == "admin"], schema=RoleRead
+        )
+
+        assert result is not None
+        assert result.data is not None
+        assert result.data.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_first_with_schema_not_found(self, db_session: AsyncSession):
+        """First with schema returns None when no record matches."""
+        result = await RoleCrud.first(
+            db_session, [Role.name == "ghost"], schema=RoleRead
+        )
+        assert result is None
+
+    @pytest.mark.anyio
+    async def test_first_with_for_update(self, db_session: AsyncSession):
+        """First with with_for_update locks the row."""
+        await RoleCrud.create(db_session, RoleCreate(name="admin"))
+
+        role = await RoleCrud.first(
+            db_session, [Role.name == "admin"], with_for_update=True
+        )
+        assert role is not None
+        assert role.name == "admin"
+

 class TestCrudGetMulti:
    """Tests for CRUD get_multi operations."""
@@ -430,7 +664,7 @@ class TestCrudDelete:
        role = await RoleCrud.create(db_session, RoleCreate(name="to_delete"))
        result = await RoleCrud.delete(db_session, [Role.id == role.id])

-        assert result is True
+        assert result is None
        assert await RoleCrud.first(db_session, [Role.id == role.id]) is None

    @pytest.mark.anyio
@@ -454,6 +688,83 @@ class TestCrudDelete:
        assert len(remaining) == 1
        assert remaining[0].username == "u3"

+    @pytest.mark.anyio
+    async def test_delete_return_response(self, db_session: AsyncSession):
+        """Delete with return_response=True returns Response[None]."""
+        from fastapi_toolsets.schemas import Response
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="to_delete_resp"))
+        result = await RoleCrud.delete(
+            db_session, [Role.id == role.id], return_response=True
+        )
+
+        assert isinstance(result, Response)
+        assert result.data is None
+        assert await RoleCrud.first(db_session, [Role.id == role.id]) is None
+
+    @pytest.mark.anyio
+    async def test_delete_m2m_cascade(self, db_session: AsyncSession):
+        """Deleting a record with M2M relationships cleans up the association table."""
+        from sqlalchemy import text
+
+        user = await UserCrud.create(
+            db_session, UserCreate(username="author", email="author@test.com")
+        )
+        tag1 = await TagCrud.create(db_session, TagCreate(name="python"))
+        tag2 = await TagCrud.create(db_session, TagCreate(name="fastapi"))
+
+        post = await PostM2MCrud.create(
+            db_session,
+            PostM2MCreate(
+                title="M2M Delete Test",
+                author_id=user.id,
+                tag_ids=[tag1.id, tag2.id],
+            ),
+        )
+
+        await PostM2MCrud.delete(db_session, [Post.id == post.id])
+
+        # Post is gone
+        assert await PostCrud.first(db_session, [Post.id == post.id]) is None
+
+        # Association rows are gone — tags themselves must still exist
+        assert await TagCrud.first(db_session, [Tag.id == tag1.id]) is not None
+        assert await TagCrud.first(db_session, [Tag.id == tag2.id]) is not None
+
+        # No orphaned rows in post_tags
+        result = await db_session.execute(
+            text("SELECT COUNT(*) FROM post_tags WHERE post_id = :pid").bindparams(
+                pid=post.id
+            )
+        )
+        assert result.scalar() == 0
+
+    @pytest.mark.anyio
+    async def test_delete_m2m_does_not_delete_related_records(
+        self, db_session: AsyncSession
+    ):
+        """Deleting a post with M2M tags must not delete the tags themselves."""
+        user = await UserCrud.create(
+            db_session, UserCreate(username="author2", email="author2@test.com")
+        )
+        tag = await TagCrud.create(db_session, TagCreate(name="shared_tag"))
+
+        post1 = await PostM2MCrud.create(
+            db_session,
+            PostM2MCreate(title="Post 1", author_id=user.id, tag_ids=[tag.id]),
+        )
+        post2 = await PostM2MCrud.create(
+            db_session,
+            PostM2MCreate(title="Post 2", author_id=user.id, tag_ids=[tag.id]),
+        )
+
+        # Delete only post1
+        await PostM2MCrud.delete(db_session, [Post.id == post1.id])
+
+        # Tag and post2 still exist
+        assert await TagCrud.first(db_session, [Tag.id == tag.id]) is not None
+        assert await PostCrud.first(db_session, [Post.id == post2.id]) is not None
+

 class TestCrudExists:
    """Tests for CRUD exists operations."""
@@ -594,7 +905,9 @@ class TestCrudPaginate:

        from fastapi_toolsets.schemas import OffsetPagination

-        result = await RoleCrud.paginate(db_session, page=1, items_per_page=10)
+        result = await RoleCrud.offset_paginate(
+            db_session, page=1, items_per_page=10, schema=RoleRead
+        )

        assert isinstance(result.pagination, OffsetPagination)
        assert len(result.data) == 10
@@ -609,7 +922,9 @@ class TestCrudPaginate:
        for i in range(25):
            await RoleCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))

-        result = await RoleCrud.paginate(db_session, page=3, items_per_page=10)
+        result = await RoleCrud.offset_paginate(
+            db_session, page=3, items_per_page=10, schema=RoleRead
+        )

        assert len(result.data) == 5
        assert result.pagination.has_more is False
@@ -629,11 +944,12 @@ class TestCrudPaginate:

        from fastapi_toolsets.schemas import OffsetPagination

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            filters=[User.is_active == True],  # noqa: E712
            page=1,
            items_per_page=10,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -646,11 +962,12 @@ class TestCrudPaginate:
        await RoleCrud.create(db_session, RoleCreate(name="alpha"))
        await RoleCrud.create(db_session, RoleCreate(name="bravo"))

-        result = await RoleCrud.paginate(
+        result = await RoleCrud.offset_paginate(
            db_session,
            order_by=Role.name,
            page=1,
            items_per_page=10,
+            schema=RoleRead,
        )

        names = [r.name for r in result.data]
@@ -855,12 +1172,13 @@ class TestCrudJoins:
        from fastapi_toolsets.schemas import OffsetPagination

        # Paginate users with published posts
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            joins=[(Post, Post.author_id == User.id)],
            filters=[Post.is_published == True],  # noqa: E712
            page=1,
            items_per_page=10,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -889,12 +1207,13 @@ class TestCrudJoins:
        from fastapi_toolsets.schemas import OffsetPagination

        # Paginate with outer join
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            joins=[(Post, Post.author_id == User.id)],
            outer_join=True,
            page=1,
            items_per_page=10,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -931,70 +1250,6 @@ class TestCrudJoins:
        assert users[0].username == "multi_join"


-class TestAsResponse:
-    """Tests for as_response parameter (deprecated, kept for backward compat)."""
-
-    @pytest.mark.anyio
-    async def test_create_as_response(self, db_session: AsyncSession):
-        """Create with as_response=True returns Response and emits DeprecationWarning."""
-        from fastapi_toolsets.schemas import Response
-
-        data = RoleCreate(name="response_role")
-        with pytest.warns(DeprecationWarning, match="as_response is deprecated"):
-            result = await RoleCrud.create(db_session, data, as_response=True)
-
-        assert isinstance(result, Response)
-        assert result.data is not None
-        assert result.data.name == "response_role"
-
-    @pytest.mark.anyio
-    async def test_get_as_response(self, db_session: AsyncSession):
-        """Get with as_response=True returns Response and emits DeprecationWarning."""
-        from fastapi_toolsets.schemas import Response
-
-        created = await RoleCrud.create(db_session, RoleCreate(name="get_response"))
-        with pytest.warns(DeprecationWarning, match="as_response is deprecated"):
-            result = await RoleCrud.get(
-                db_session, [Role.id == created.id], as_response=True
-            )
-
-        assert isinstance(result, Response)
-        assert result.data is not None
-        assert result.data.id == created.id
-
-    @pytest.mark.anyio
-    async def test_update_as_response(self, db_session: AsyncSession):
-        """Update with as_response=True returns Response and emits DeprecationWarning."""
-        from fastapi_toolsets.schemas import Response
-
-        created = await RoleCrud.create(db_session, RoleCreate(name="old_name"))
-        with pytest.warns(DeprecationWarning, match="as_response is deprecated"):
-            result = await RoleCrud.update(
-                db_session,
-                RoleUpdate(name="new_name"),
-                [Role.id == created.id],
-                as_response=True,
-            )
-
-        assert isinstance(result, Response)
-        assert result.data is not None
-        assert result.data.name == "new_name"
-
-    @pytest.mark.anyio
-    async def test_delete_as_response(self, db_session: AsyncSession):
-        """Delete with as_response=True returns Response and emits DeprecationWarning."""
-        from fastapi_toolsets.schemas import Response
-
-        created = await RoleCrud.create(db_session, RoleCreate(name="to_delete"))
-        with pytest.warns(DeprecationWarning, match="as_response is deprecated"):
-            result = await RoleCrud.delete(
-                db_session, [Role.id == created.id], as_response=True
-            )
-
-        assert isinstance(result, Response)
-        assert result.data is None
-
-
 class TestCrudFactoryM2M:
    """Tests for CrudFactory with m2m_fields parameter."""

@@ -1475,92 +1730,35 @@ class TestSchemaResponse:
        assert isinstance(result, Response)

    @pytest.mark.anyio
-    async def test_paginate_with_schema(self, db_session: AsyncSession):
-        """paginate with schema returns PaginatedResponse[SchemaType]."""
+    async def test_offset_paginate_with_schema(self, db_session: AsyncSession):
+        """offset_paginate with schema returns PaginatedResponse[SchemaType]."""
        from fastapi_toolsets.schemas import PaginatedResponse

        await RoleCrud.create(db_session, RoleCreate(name="p_role1"))
        await RoleCrud.create(db_session, RoleCreate(name="p_role2"))

-        result = await RoleCrud.paginate(db_session, schema=RoleRead)
+        result = await RoleCrud.offset_paginate(db_session, schema=RoleRead)

        assert isinstance(result, PaginatedResponse)
        assert len(result.data) == 2
        assert all(isinstance(item, RoleRead) for item in result.data)

    @pytest.mark.anyio
-    async def test_paginate_schema_filters_fields(self, db_session: AsyncSession):
-        """paginate with schema only exposes schema fields per item."""
+    async def test_offset_paginate_schema_filters_fields(
+        self, db_session: AsyncSession
+    ):
+        """offset_paginate with schema only exposes schema fields per item."""
        await UserCrud.create(
            db_session,
            UserCreate(username="pg_user", email="pg@test.com"),
        )

-        result = await UserCrud.paginate(db_session, schema=UserRead)
+        result = await UserCrud.offset_paginate(db_session, schema=UserRead)

        assert isinstance(result.data[0], UserRead)
        assert result.data[0].username == "pg_user"
        assert not hasattr(result.data[0], "email")

-    @pytest.mark.anyio
-    async def test_as_response_true_without_schema_unchanged(
-        self, db_session: AsyncSession
-    ):
-        """as_response=True without schema still returns Response[ModelType] with a warning."""
-        from fastapi_toolsets.schemas import Response
-
-        created = await RoleCrud.create(db_session, RoleCreate(name="compat"))
-        with pytest.warns(DeprecationWarning, match="as_response is deprecated"):
-            result = await RoleCrud.get(
-                db_session, [Role.id == created.id], as_response=True
-            )
-
-        assert isinstance(result, Response)
-        assert isinstance(result.data, Role)
-
-    @pytest.mark.anyio
-    async def test_schema_with_explicit_as_response_true(
-        self, db_session: AsyncSession
-    ):
-        """schema combined with explicit as_response=True works correctly."""
-        from fastapi_toolsets.schemas import Response
-
-        created = await RoleCrud.create(db_session, RoleCreate(name="combined"))
-        result = await RoleCrud.get(
-            db_session,
-            [Role.id == created.id],
-            as_response=True,
-            schema=RoleRead,
-        )
-
-        assert isinstance(result, Response)
-        assert isinstance(result.data, RoleRead)
-
-
-class TestPaginateAlias:
-    """Tests that paginate is a backward-compatible alias for offset_paginate."""
-
-    def test_paginate_is_alias_of_offset_paginate(self):
-        """paginate and offset_paginate are the same underlying function."""
-        assert RoleCrud.paginate.__func__ is RoleCrud.offset_paginate.__func__
-
-    @pytest.mark.anyio
-    async def test_paginate_alias_returns_offset_pagination(
-        self, db_session: AsyncSession
-    ):
-        """paginate() still works and returns PaginatedResponse with OffsetPagination."""
-        from fastapi_toolsets.schemas import OffsetPagination, PaginatedResponse
-
-        for i in range(3):
-            await RoleCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))
-
-        result = await RoleCrud.paginate(db_session, page=1, items_per_page=10)
-
-        assert isinstance(result, PaginatedResponse)
-        assert isinstance(result.pagination, OffsetPagination)
-        assert result.pagination.total_count == 3
-        assert result.pagination.page == 1
-

 class TestCursorPaginate:
    """Tests for cursor-based pagination via cursor_paginate()."""
@@ -1573,7 +1771,9 @@ class TestCursorPaginate:
        for i in range(25):
            await RoleCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))

-        result = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=10)
+        result = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=10, schema=RoleRead
+        )

        assert isinstance(result, PaginatedResponse)
        assert isinstance(result.pagination, CursorPagination)
@@ -1591,7 +1791,9 @@ class TestCursorPaginate:
        for i in range(5):
            await RoleCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))

-        result = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=10)
+        result = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=10, schema=RoleRead
+        )

        assert isinstance(result.pagination, CursorPagination)
        assert len(result.data) == 5
@@ -1606,14 +1808,16 @@ class TestCursorPaginate:

        from fastapi_toolsets.schemas import CursorPagination

-        page1 = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=10)
+        page1 = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=10, schema=RoleRead
+        )
        assert isinstance(page1.pagination, CursorPagination)
        assert len(page1.data) == 10
        assert page1.pagination.has_more is True

        cursor = page1.pagination.next_cursor
        page2 = await RoleCursorCrud.cursor_paginate(
-            db_session, cursor=cursor, items_per_page=10
+            db_session, cursor=cursor, items_per_page=10, schema=RoleRead
        )
        assert isinstance(page2.pagination, CursorPagination)
        assert len(page2.data) == 5
@@ -1628,12 +1832,15 @@ class TestCursorPaginate:

        from fastapi_toolsets.schemas import CursorPagination

-        page1 = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=4)
+        page1 = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=4, schema=RoleRead
+        )
        assert isinstance(page1.pagination, CursorPagination)
        page2 = await RoleCursorCrud.cursor_paginate(
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=4,
+            schema=RoleRead,
        )

        ids_page1 = {r.id for r in page1.data}
@@ -1646,7 +1853,9 @@ class TestCursorPaginate:
        """cursor_paginate on an empty table returns empty data with no cursor."""
        from fastapi_toolsets.schemas import CursorPagination

-        result = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=10)
+        result = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=10, schema=RoleRead
+        )

        assert isinstance(result.pagination, CursorPagination)
        assert result.data == []
@@ -1671,6 +1880,7 @@ class TestCursorPaginate:
            db_session,
            filters=[User.is_active == True],  # noqa: E712
            items_per_page=20,
+            schema=UserRead,
        )

        assert len(result.data) == 5
@@ -1703,7 +1913,9 @@ class TestCursorPaginate:
        for i in range(5):
            await RoleNameCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))

-        result = await RoleNameCrud.cursor_paginate(db_session, items_per_page=3)
+        result = await RoleNameCrud.cursor_paginate(
+            db_session, items_per_page=3, schema=RoleRead
+        )

        assert isinstance(result.pagination, CursorPagination)
        assert len(result.data) == 3
@@ -1714,7 +1926,7 @@ class TestCursorPaginate:
    async def test_raises_without_cursor_column(self, db_session: AsyncSession):
        """cursor_paginate raises ValueError when cursor_column is not configured."""
        with pytest.raises(ValueError, match="cursor_column is not set"):
-            await RoleCrud.cursor_paginate(db_session)
+            await RoleCrud.cursor_paginate(db_session, schema=RoleRead)


 class TestCursorPaginatePrevCursor:
@@ -1728,7 +1940,9 @@ class TestCursorPaginatePrevCursor:

        from fastapi_toolsets.schemas import CursorPagination

-        result = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=3)
+        result = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=3, schema=RoleRead
+        )

        assert isinstance(result.pagination, CursorPagination)
        assert result.pagination.prev_cursor is None
@@ -1741,12 +1955,15 @@ class TestCursorPaginatePrevCursor:

        from fastapi_toolsets.schemas import CursorPagination

-        page1 = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=5)
+        page1 = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=5, schema=RoleRead
+        )
        assert isinstance(page1.pagination, CursorPagination)
        page2 = await RoleCursorCrud.cursor_paginate(
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=5,
+            schema=RoleRead,
        )
        assert isinstance(page2.pagination, CursorPagination)
        assert page2.pagination.prev_cursor is not None
@@ -1762,12 +1979,15 @@ class TestCursorPaginatePrevCursor:

        from fastapi_toolsets.schemas import CursorPagination

-        page1 = await RoleCursorCrud.cursor_paginate(db_session, items_per_page=5)
+        page1 = await RoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=5, schema=RoleRead
+        )
        assert isinstance(page1.pagination, CursorPagination)
        page2 = await RoleCursorCrud.cursor_paginate(
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=5,
+            schema=RoleRead,
        )
        assert isinstance(page2.pagination, CursorPagination)
        assert page2.pagination.prev_cursor is not None
@@ -1802,6 +2022,7 @@ class TestCursorPaginateWithSearch:
            db_session,
            search="admin",
            items_per_page=20,
+            schema=RoleRead,
        )

        assert len(result.data) == 5
@@ -1836,6 +2057,7 @@ class TestCursorPaginateExtraOptions:
            db_session,
            joins=[(Role, User.role_id == Role.id)],
            items_per_page=20,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, CursorPagination)
@@ -1867,6 +2089,7 @@ class TestCursorPaginateExtraOptions:
            joins=[(Role, User.role_id == Role.id)],
            outer_join=True,
            items_per_page=20,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, CursorPagination)
@@ -1876,7 +2099,12 @@ class TestCursorPaginateExtraOptions:
    @pytest.mark.anyio
    async def test_with_load_options(self, db_session: AsyncSession):
        """cursor_paginate passes load_options to the query."""
-        from fastapi_toolsets.schemas import CursorPagination
+        from fastapi_toolsets.schemas import CursorPagination, PydanticBase
+
+        class UserWithRoleRead(PydanticBase):
+            id: uuid.UUID
+            username: str
+            role: RoleRead | None = None

        role = await RoleCrud.create(db_session, RoleCreate(name="manager"))
        for i in range(3):
@@ -1893,6 +2121,7 @@ class TestCursorPaginateExtraOptions:
            db_session,
            load_options=[selectinload(User.role)],
            items_per_page=20,
+            schema=UserWithRoleRead,
        )

        assert isinstance(result.pagination, CursorPagination)
@@ -1912,6 +2141,7 @@ class TestCursorPaginateExtraOptions:
            db_session,
            order_by=Role.name.desc(),
            items_per_page=3,
+            schema=RoleRead,
        )

        assert isinstance(result.pagination, CursorPagination)
@@ -1925,7 +2155,9 @@ class TestCursorPaginateExtraOptions:
        for i in range(5):
            await IntRoleCursorCrud.create(db_session, IntRoleCreate(name=f"role{i}"))

-        page1 = await IntRoleCursorCrud.cursor_paginate(db_session, items_per_page=3)
+        page1 = await IntRoleCursorCrud.cursor_paginate(
+            db_session, items_per_page=3, schema=IntRoleRead
+        )

        assert isinstance(page1.pagination, CursorPagination)
        assert len(page1.data) == 3
@@ -1935,6 +2167,7 @@ class TestCursorPaginateExtraOptions:
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=3,
+            schema=IntRoleRead,
        )

        assert isinstance(page2.pagination, CursorPagination)
@@ -1955,7 +2188,9 @@ class TestCursorPaginateExtraOptions:
        await RoleCrud.create(db_session, RoleCreate(name="role01"))

        # First page succeeds (no cursor to decode)
-        page1 = await RoleNameCursorCrud.cursor_paginate(db_session, items_per_page=1)
+        page1 = await RoleNameCursorCrud.cursor_paginate(
+            db_session, items_per_page=1, schema=RoleRead
+        )
        assert page1.pagination.has_more is True
        assert isinstance(page1.pagination, CursorPagination)

@@ -1965,6 +2200,7 @@ class TestCursorPaginateExtraOptions:
                db_session,
                cursor=page1.pagination.next_cursor,
                items_per_page=1,
+                schema=RoleRead,
            )


@@ -2003,6 +2239,7 @@ class TestCursorPaginateSearchJoins:
            search="administrator",
            search_fields=[(User.role, Role.name)],
            items_per_page=20,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, CursorPagination)
@@ -2049,7 +2286,7 @@ class TestCursorPaginateColumnTypes:
            )

        page1 = await EventDateTimeCursorCrud.cursor_paginate(
-            db_session, items_per_page=3
+            db_session, items_per_page=3, schema=EventRead
        )

        assert isinstance(page1.pagination, CursorPagination)
@@ -2060,6 +2297,7 @@ class TestCursorPaginateColumnTypes:
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=3,
+            schema=EventRead,
        )

        assert isinstance(page2.pagination, CursorPagination)
@@ -2087,7 +2325,9 @@ class TestCursorPaginateColumnTypes:
                ),
            )

-        page1 = await EventDateCursorCrud.cursor_paginate(db_session, items_per_page=3)
+        page1 = await EventDateCursorCrud.cursor_paginate(
+            db_session, items_per_page=3, schema=EventRead
+        )

        assert isinstance(page1.pagination, CursorPagination)
        assert len(page1.data) == 3
@@ -2097,6 +2337,7 @@ class TestCursorPaginateColumnTypes:
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=3,
+            schema=EventRead,
        )

        assert isinstance(page2.pagination, CursorPagination)
@@ -2123,7 +2364,7 @@ class TestCursorPaginateColumnTypes:
            )

        page1 = await ProductNumericCursorCrud.cursor_paginate(
-            db_session, items_per_page=3
+            db_session, items_per_page=3, schema=ProductRead
        )

        assert isinstance(page1.pagination, CursorPagination)
@@ -2134,6 +2375,7 @@ class TestCursorPaginateColumnTypes:
            db_session,
            cursor=page1.pagination.next_cursor,
            items_per_page=3,
+            schema=ProductRead,
        )

        assert isinstance(page2.pagination, CursorPagination)
@@ -2142,3 +2384,72 @@ class TestCursorPaginateColumnTypes:
        page1_ids = {p.id for p in page1.data}
        page2_ids = {p.id for p in page2.data}
        assert page1_ids.isdisjoint(page2_ids)
+
+
+class TestPaginate:
+    """Tests for the unified paginate() method."""
+
+    @pytest.mark.anyio
+    async def test_offset_pagination(self, db_session: AsyncSession):
+        """paginate() with OFFSET returns OffsetPaginatedResponse."""
+        from fastapi_toolsets.schemas import OffsetPagination
+
+        await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await RoleCrud.create(db_session, RoleCreate(name="user"))
+
+        result = await RoleCrud.paginate(
+            db_session,
+            pagination_type=PaginationType.OFFSET,
+            schema=RoleRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination_type == PaginationType.OFFSET
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination(self, db_session: AsyncSession):
+        """paginate() with CURSOR returns CursorPaginatedResponse."""
+        from fastapi_toolsets.schemas import CursorPagination
+
+        await RoleCursorCrud.create(db_session, RoleCreate(name="admin"))
+
+        result = await RoleCursorCrud.paginate(
+            db_session,
+            pagination_type=PaginationType.CURSOR,
+            schema=RoleRead,
+        )
+
+        assert isinstance(result.pagination, CursorPagination)
+        assert result.pagination_type == PaginationType.CURSOR
+
+    @pytest.mark.anyio
+    async def test_invalid_items_per_page_raises(self, db_session: AsyncSession):
+        """paginate() raises ValueError when items_per_page < 1."""
+        with pytest.raises(ValueError, match="items_per_page"):
+            await RoleCrud.paginate(
+                db_session,
+                pagination_type=PaginationType.OFFSET,
+                items_per_page=0,
+                schema=RoleRead,
+            )
+
+    @pytest.mark.anyio
+    async def test_invalid_page_raises(self, db_session: AsyncSession):
+        """paginate() raises ValueError when page < 1 for offset pagination."""
+        with pytest.raises(ValueError, match="page"):
+            await RoleCrud.paginate(
+                db_session,
+                pagination_type=PaginationType.OFFSET,
+                page=0,
+                schema=RoleRead,
+            )
+
+    @pytest.mark.anyio
+    async def test_unknown_pagination_type_raises(self, db_session: AsyncSession):
+        """paginate() raises ValueError for unknown pagination_type."""
+        with pytest.raises(ValueError, match="Unknown pagination_type"):
+            await RoleCrud.paginate(
+                db_session,
+                pagination_type="unknown",
+                schema=RoleRead,
+            )  # type: ignore[no-matching-overload]
--- a/tests/test_crud_search.py
+++ b/tests/test_crud_search.py
@@ -23,6 +23,7 @@ from .conftest import (
    User,
    UserCreate,
    UserCrud,
+    UserRead,
 )


@@ -42,10 +43,11 @@ class TestPaginateSearch:
            db_session, UserCreate(username="bob_smith", email="bob@test.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="doe",
            search_fields=[User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -61,10 +63,11 @@ class TestPaginateSearch:
            db_session, UserCreate(username="company_bob", email="bob@other.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="company",
            search_fields=[User.username, User.email],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -89,10 +92,11 @@ class TestPaginateSearch:
            UserCreate(username="user1", email="u1@test.com", role_id=user_role.id),
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="admin",
            search_fields=[(User.role, Role.name)],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -108,10 +112,11 @@ class TestPaginateSearch:
        )

        # Search "admin" in username OR role.name
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="admin",
            search_fields=[User.username, (User.role, Role.name)],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -124,10 +129,11 @@ class TestPaginateSearch:
            db_session, UserCreate(username="JohnDoe", email="j@test.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="johndoe",
            search_fields=[User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -141,19 +147,21 @@ class TestPaginateSearch:
        )

        # Should not find (case mismatch)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search=SearchConfig(query="johndoe", case_sensitive=True),
            search_fields=[User.username],
+            schema=UserRead,
        )
        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 0

        # Should find (case match)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search=SearchConfig(query="JohnDoe", case_sensitive=True),
            search_fields=[User.username],
+            schema=UserRead,
        )
        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 1
@@ -168,11 +176,13 @@ class TestPaginateSearch:
            db_session, UserCreate(username="user2", email="u2@test.com")
        )

-        result = await UserCrud.paginate(db_session, search="")
+        result = await UserCrud.offset_paginate(db_session, search="", schema=UserRead)
        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 2

-        result = await UserCrud.paginate(db_session, search=None)
+        result = await UserCrud.offset_paginate(
+            db_session, search=None, schema=UserRead
+        )
        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 2

@@ -188,11 +198,12 @@ class TestPaginateSearch:
            UserCreate(username="inactive_john", email="ij@test.com", is_active=False),
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            filters=[User.is_active == True],  # noqa: E712
            search="john",
            search_fields=[User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -200,13 +211,18 @@ class TestPaginateSearch:
        assert result.data[0].username == "active_john"

    @pytest.mark.anyio
-    async def test_search_auto_detect_fields(self, db_session: AsyncSession):
-        """Auto-detect searchable fields when not specified."""
+    async def test_search_explicit_fields(self, db_session: AsyncSession):
+        """Search works when search_fields are passed per call."""
        await UserCrud.create(
            db_session, UserCreate(username="findme", email="other@test.com")
        )

-        result = await UserCrud.paginate(db_session, search="findme")
+        result = await UserCrud.offset_paginate(
+            db_session,
+            search="findme",
+            search_fields=[User.username],
+            schema=UserRead,
+        )

        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 1
@@ -218,10 +234,11 @@ class TestPaginateSearch:
            db_session, UserCreate(username="john", email="j@test.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="nonexistent",
            search_fields=[User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -237,12 +254,13 @@ class TestPaginateSearch:
                UserCreate(username=f"user_{i}", email=f"user{i}@test.com"),
            )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="user_",
            search_fields=[User.username],
            page=1,
            items_per_page=5,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -264,10 +282,11 @@ class TestPaginateSearch:
        )

        # Search in username, not in role
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="role",
            search_fields=[User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -286,11 +305,12 @@ class TestPaginateSearch:
            db_session, UserCreate(username="bob", email="b@test.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="@test.com",
            search_fields=[User.email],
            order_by=User.username,
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -310,10 +330,11 @@ class TestPaginateSearch:
        )

        # Search by UUID (partial match)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search="12345678",
            search_fields=[User.id, User.username],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -363,10 +384,11 @@ class TestSearchConfig:
        )

        # 'john' must be in username AND email
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search=SearchConfig(query="john", match_mode="all"),
            search_fields=[User.username, User.email],
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -380,9 +402,10 @@ class TestSearchConfig:
            db_session, UserCreate(username="test", email="findme@test.com")
        )

-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
            db_session,
            search=SearchConfig(query="findme", fields=[User.email]),
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -410,7 +433,7 @@ class TestNoSearchableFieldsError:
        from fastapi_toolsets.exceptions import NoSearchableFieldsError

        error = NoSearchableFieldsError(User)
-        assert "User" in str(error)
+        assert "User" in error.api_error.desc
        assert error.model is User

    def test_error_raised_when_no_fields(self):
@@ -434,7 +457,7 @@ class TestNoSearchableFieldsError:
            build_search_filters(NoStringModel, "test")

        assert exc_info.value.model is NoStringModel
-        assert "NoStringModel" in str(exc_info.value)
+        assert "NoStringModel" in exc_info.value.api_error.desc


 class TestGetSearchableFields:
@@ -478,7 +501,7 @@ class TestFacetsNotSet:
            db_session, UserCreate(username="alice", email="a@test.com")
        )

-        result = await UserCrud.offset_paginate(db_session)
+        result = await UserCrud.offset_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is None

@@ -490,7 +513,7 @@ class TestFacetsNotSet:
            db_session, UserCreate(username="alice", email="a@test.com")
        )

-        result = await UserCursorCrud.cursor_paginate(db_session)
+        result = await UserCursorCrud.cursor_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is None

@@ -509,7 +532,7 @@ class TestFacetsDirectColumn:
            db_session, UserCreate(username="bob", email="b@test.com")
        )

-        result = await UserFacetCrud.offset_paginate(db_session)
+        result = await UserFacetCrud.offset_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is not None
        # Distinct usernames, sorted
@@ -528,7 +551,7 @@ class TestFacetsDirectColumn:
            db_session, UserCreate(username="bob", email="b@test.com")
        )

-        result = await UserFacetCursorCrud.cursor_paginate(db_session)
+        result = await UserFacetCursorCrud.cursor_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is not None
        assert set(result.filter_attributes["email"]) == {"a@test.com", "b@test.com"}
@@ -544,7 +567,7 @@ class TestFacetsDirectColumn:
            db_session, UserCreate(username="bob", email="b@test.com")
        )

-        result = await UserFacetCrud.offset_paginate(db_session)
+        result = await UserFacetCrud.offset_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is not None
        assert "username" in result.filter_attributes
@@ -561,7 +584,7 @@ class TestFacetsDirectColumn:

        # Override: ask for email instead of username
        result = await UserFacetCrud.offset_paginate(
-            db_session, facet_fields=[User.email]
+            db_session, facet_fields=[User.email], schema=UserRead
        )

        assert result.filter_attributes is not None
@@ -587,6 +610,7 @@ class TestFacetsRespectFilters:
        result = await UserFacetCrud.offset_paginate(
            db_session,
            filters=[User.is_active == True],  # noqa: E712
+            schema=UserRead,
        )

        assert result.filter_attributes is not None
@@ -617,7 +641,7 @@ class TestFacetsRelationship:
            db_session, UserCreate(username="charlie", email="c@test.com")
        )

-        result = await UserRelFacetCrud.offset_paginate(db_session)
+        result = await UserRelFacetCrud.offset_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is not None
        assert set(result.filter_attributes["name"]) == {"admin", "editor"}
@@ -632,7 +656,7 @@ class TestFacetsRelationship:
            db_session, UserCreate(username="norole", email="n@test.com")
        )

-        result = await UserRelFacetCrud.offset_paginate(db_session)
+        result = await UserRelFacetCrud.offset_paginate(db_session, schema=UserRead)

        assert result.filter_attributes is not None
        assert result.filter_attributes["name"] == []
@@ -656,7 +680,10 @@ class TestFacetsRelationship:
        )

        result = await UserSearchFacetCrud.offset_paginate(
-            db_session, search="admin", search_fields=[(User.role, Role.name)]
+            db_session,
+            search="admin",
+            search_fields=[(User.role, Role.name)],
+            schema=UserRead,
        )

        assert result.filter_attributes is not None
@@ -678,7 +705,7 @@ class TestFilterBy:
        )

        result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by={"username": "alice"}
+            db_session, filter_by={"username": "alice"}, schema=UserRead
        )

        assert len(result.data) == 1
@@ -701,7 +728,7 @@ class TestFilterBy:
        )

        result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by={"username": ["alice", "bob"]}
+            db_session, filter_by={"username": ["alice", "bob"]}, schema=UserRead
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -726,7 +753,7 @@ class TestFilterBy:
        )

        result = await UserRelFacetCrud.offset_paginate(
-            db_session, filter_by={"name": "admin"}
+            db_session, filter_by={"name": "admin"}, schema=UserRead
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -749,6 +776,7 @@ class TestFilterBy:
            db_session,
            filters=[User.is_active == True],  # noqa: E712
            filter_by={"username": ["alice", "alice2"]},
+            schema=UserRead,
        )

        # Only alice passes both: is_active=True AND username IN [alice, alice2]
@@ -763,7 +791,7 @@ class TestFilterBy:

        with pytest.raises(InvalidFacetFilterError) as exc_info:
            await UserFacetCrud.offset_paginate(
-                db_session, filter_by={"nonexistent": "value"}
+                db_session, filter_by={"nonexistent": "value"}, schema=UserRead
            )

        assert exc_info.value.key == "nonexistent"
@@ -795,6 +823,7 @@ class TestFilterBy:
        result = await UserRoleFacetCrud.offset_paginate(
            db_session,
            filter_by={"name": "admin", "id": str(admin.id)},
+            schema=UserRead,
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -815,7 +844,7 @@ class TestFilterBy:
        )

        result = await UserFacetCursorCrud.cursor_paginate(
-            db_session, filter_by={"username": "alice"}
+            db_session, filter_by={"username": "alice"}, schema=UserRead
        )

        assert len(result.data) == 1
@@ -839,7 +868,7 @@ class TestFilterBy:
        )

        result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by=UserFilter(username="alice")
+            db_session, filter_by=UserFilter(username="alice"), schema=UserRead
        )

        assert isinstance(result.pagination, OffsetPagination)
@@ -865,7 +894,7 @@ class TestFilterBy:
        )

        result = await UserFacetCursorCrud.cursor_paginate(
-            db_session, filter_by=UserFilter(username="alice")
+            db_session, filter_by=UserFilter(username="alice"), schema=UserRead
        )

        assert len(result.data) == 1
@@ -974,7 +1003,9 @@ class TestFilterParamsSchema:

        dep = UserFacetCrud.filter_params()
        f = await dep(username=["alice"])
-        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )

        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 1
@@ -995,7 +1026,9 @@ class TestFilterParamsSchema:

        dep = UserFacetCursorCrud.filter_params()
        f = await dep(username=["alice"])
-        result = await UserFacetCursorCrud.cursor_paginate(db_session, filter_by=f)
+        result = await UserFacetCursorCrud.cursor_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )

        assert len(result.data) == 1
        assert result.data[0].username == "alice"
@@ -1013,7 +1046,9 @@ class TestFilterParamsSchema:

        dep = UserFacetCrud.filter_params()
        f = await dep()  # all fields None
-        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )

        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 2
--- a/tests/test_db.py
+++ b/tests/test_db.py
@@ -4,18 +4,25 @@ import asyncio
 import uuid

 import pytest
+from sqlalchemy import text
+from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase

 from fastapi_toolsets.db import (
    LockMode,
+    cleanup_tables,
+    create_database,
    create_db_context,
    create_db_dependency,
    get_transaction,
    lock_tables,
    wait_for_row_change,
 )
+from fastapi_toolsets.exceptions import NotFoundError
+from fastapi_toolsets.pytest import create_db_session

-from .conftest import DATABASE_URL, Base, Role, RoleCrud, User
+from .conftest import DATABASE_URL, Base, Role, RoleCrud, User, UserCrud


 class TestCreateDbDependency:
@@ -307,9 +314,9 @@ class TestWaitForRowChange:

    @pytest.mark.anyio
    async def test_nonexistent_row_raises(self, db_session: AsyncSession):
-        """Raises LookupError when the row does not exist."""
+        """Raises NotFoundError when the row does not exist."""
        fake_id = uuid.uuid4()
-        with pytest.raises(LookupError, match="not found"):
+        with pytest.raises(NotFoundError, match="not found"):
            await wait_for_row_change(db_session, Role, fake_id, interval=0.05)

    @pytest.mark.anyio
@@ -326,7 +333,7 @@ class TestWaitForRowChange:

    @pytest.mark.anyio
    async def test_deleted_row_raises(self, db_session: AsyncSession, engine):
-        """Raises LookupError when the row is deleted during polling."""
+        """Raises NotFoundError when the row is deleted during polling."""
        role = Role(name="delete_role")
        db_session.add(role)
        await db_session.commit()
@@ -340,6 +347,86 @@ class TestWaitForRowChange:
                await other.commit()

        delete_task = asyncio.create_task(delete_later())
-        with pytest.raises(LookupError):
+        with pytest.raises(NotFoundError):
            await wait_for_row_change(db_session, Role, role.id, interval=0.05)
        await delete_task
+
+
+class TestCreateDatabase:
+    """Tests for create_database."""
+
+    @pytest.mark.anyio
+    async def test_creates_database(self):
+        """Database is created by create_database."""
+        target_url = (
+            make_url(DATABASE_URL)
+            .set(database="test_create_db_general")
+            .render_as_string(hide_password=False)
+        )
+        expected_db: str = make_url(target_url).database  # type: ignore[assignment]
+
+        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+        try:
+            async with engine.connect() as conn:
+                await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
+
+            await create_database(db_name=expected_db, server_url=DATABASE_URL)
+
+            async with engine.connect() as conn:
+                result = await conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                    {"name": expected_db},
+                )
+                assert result.scalar() == 1
+
+            # Cleanup
+            async with engine.connect() as conn:
+                await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
+        finally:
+            await engine.dispose()
+
+
+class TestCleanupTables:
+    """Tests for cleanup_tables helper."""
+
+    @pytest.mark.anyio
+    async def test_truncates_all_tables(self):
+        """All table rows are removed after cleanup_tables."""
+        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
+            role = Role(id=uuid.uuid4(), name="cleanup_role")
+            session.add(role)
+            await session.flush()
+
+            user = User(
+                id=uuid.uuid4(),
+                username="cleanup_user",
+                email="cleanup@test.com",
+                role_id=role.id,
+            )
+            session.add(user)
+            await session.commit()
+
+            # Verify rows exist
+            roles_count = await RoleCrud.count(session)
+            users_count = await UserCrud.count(session)
+            assert roles_count == 1
+            assert users_count == 1
+
+            await cleanup_tables(session, Base)
+
+            # Verify tables are empty
+            roles_count = await RoleCrud.count(session)
+            users_count = await UserCrud.count(session)
+            assert roles_count == 0
+            assert users_count == 0
+
+    @pytest.mark.anyio
+    async def test_noop_for_empty_metadata(self):
+        """cleanup_tables does not raise when metadata has no tables."""
+
+        class EmptyBase(DeclarativeBase):
+            pass
+
+        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
+            # Should not raise
+            await cleanup_tables(session, EmptyBase)
--- a/tests/test_example_pagination_search.py
+++ b/tests/test_example_pagination_search.py
@@ -393,3 +393,105 @@ class TestCursorSorting:
        body = resp.json()
        assert body["error_code"] == "SORT-422"
        assert body["status"] == "FAIL"
+
+
+class TestPaginateUnified:
+    """Tests for the unified GET /articles/ endpoint using paginate()."""
+
+    @pytest.mark.anyio
+    async def test_defaults_to_offset_pagination(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Without pagination_type, defaults to offset pagination."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert "total_count" in body["pagination"]
+        assert body["pagination"]["total_count"] == 3
+
+    @pytest.mark.anyio
+    async def test_explicit_offset_pagination(self, client: AsyncClient, ex_db_session):
+        """pagination_type=offset returns OffsetPagination metadata."""
+        await seed(ex_db_session)
+
+        resp = await client.get(
+            "/articles/?pagination_type=offset&page=1&items_per_page=2"
+        )
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert body["pagination"]["total_count"] == 3
+        assert body["pagination"]["page"] == 1
+        assert body["pagination"]["has_more"] is True
+        assert len(body["data"]) == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_type(self, client: AsyncClient, ex_db_session):
+        """pagination_type=cursor returns CursorPagination metadata."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=cursor&items_per_page=2")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "cursor"
+        assert "next_cursor" in body["pagination"]
+        assert "total_count" not in body["pagination"]
+        assert body["pagination"]["has_more"] is True
+        assert len(body["data"]) == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_navigate_pages(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Cursor from first page can be used to fetch the next page."""
+        await seed(ex_db_session)
+
+        first = await client.get("/articles/?pagination_type=cursor&items_per_page=2")
+        assert first.status_code == 200
+        first_body = first.json()
+        next_cursor = first_body["pagination"]["next_cursor"]
+        assert next_cursor is not None
+
+        second = await client.get(
+            f"/articles/?pagination_type=cursor&items_per_page=2&cursor={next_cursor}"
+        )
+        assert second.status_code == 200
+        second_body = second.json()
+        assert second_body["pagination_type"] == "cursor"
+        assert second_body["pagination"]["has_more"] is False
+        assert len(second_body["data"]) == 1
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_with_search(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """paginate() with cursor type respects search parameter."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=cursor&search=fastapi")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "cursor"
+        assert len(body["data"]) == 1
+        assert body["data"][0]["title"] == "FastAPI tips"
+
+    @pytest.mark.anyio
+    async def test_offset_pagination_with_filter(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """paginate() with offset type respects filter_by parameter."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=offset&status=published")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert body["pagination"]["total_count"] == 2
--- a/tests/test_exceptions.py
+++ b/tests/test_exceptions.py
@@ -2,6 +2,7 @@

 import pytest
 from fastapi import FastAPI
+from fastapi.exceptions import HTTPException
 from fastapi.testclient import TestClient

 from fastapi_toolsets.exceptions import (
@@ -36,8 +37,8 @@ class TestApiException:
        assert error.api_error.msg == "I'm a teapot"
        assert str(error) == "I'm a teapot"

-    def test_custom_detail_message(self):
-        """Custom detail overrides default message."""
+    def test_detail_overrides_msg_and_str(self):
+        """detail sets both str(exc) and api_error.msg; class-level msg is unchanged."""

        class CustomError(ApiException):
            api_error = ApiError(
@@ -47,8 +48,172 @@ class TestApiException:
                err_code="BAD-400",
            )

-        error = CustomError("Custom message")
-        assert str(error) == "Custom message"
+        error = CustomError("Widget not found")
+        assert str(error) == "Widget not found"
+        assert error.api_error.msg == "Widget not found"
+        assert CustomError.api_error.msg == "Bad Request"  # class unchanged
+
+    def test_desc_override(self):
+        """desc kwarg overrides api_error.desc on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(desc="Custom desc.")
+        assert err.api_error.desc == "Custom desc."
+        assert MyError.api_error.desc == "Default."  # class unchanged
+
+    def test_data_override(self):
+        """data kwarg sets api_error.data on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(data={"key": "value"})
+        assert err.api_error.data == {"key": "value"}
+        assert MyError.api_error.data is None  # class unchanged
+
+    def test_desc_and_data_override(self):
+        """detail, desc and data can all be overridden together."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError("custom msg", desc="New desc.", data={"x": 1})
+        assert str(err) == "custom msg"
+        assert err.api_error.msg == "custom msg"  # detail also updates msg
+        assert err.api_error.desc == "New desc."
+        assert err.api_error.data == {"x": 1}
+        assert err.api_error.code == 400  # other fields unchanged
+
+    def test_class_api_error_not_mutated_after_instance_override(self):
+        """Raising with desc/data does not mutate the class-level api_error."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        MyError(desc="Changed", data={"x": 1})
+        assert MyError.api_error.desc == "Default."
+        assert MyError.api_error.data is None
+
+    def test_subclass_uses_super_with_desc_and_data(self):
+        """Subclasses can delegate detail/desc/data to super().__init__()."""
+
+        class BuildValidationError(ApiException):
+            api_error = ApiError(
+                code=422,
+                msg="Build Validation Error",
+                desc="The build configuration is invalid.",
+                err_code="BUILD-422",
+            )
+
+            def __init__(self, *errors: str) -> None:
+                super().__init__(
+                    f"{len(errors)} validation error(s)",
+                    desc=", ".join(errors),
+                    data={"errors": [{"message": e} for e in errors]},
+                )
+
+        err = BuildValidationError("Field A is required", "Field B is invalid")
+        assert str(err) == "2 validation error(s)"
+        assert err.api_error.msg == "2 validation error(s)"  # detail set msg
+        assert err.api_error.desc == "Field A is required, Field B is invalid"
+        assert err.api_error.data == {
+            "errors": [
+                {"message": "Field A is required"},
+                {"message": "Field B is invalid"},
+            ]
+        }
+        assert err.api_error.code == 422  # other fields unchanged
+
+    def test_detail_desc_data_in_http_response(self):
+        """detail/desc/data overrides all appear correctly in the FastAPI HTTP response."""
+
+        class DynamicError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+            def __init__(self, message: str) -> None:
+                super().__init__(
+                    message,
+                    desc=f"Detail: {message}",
+                    data={"reason": message},
+                )
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/error")
+        async def raise_error():
+            raise DynamicError("something went wrong")
+
+        client = TestClient(app)
+        response = client.get("/error")
+
+        assert response.status_code == 400
+        body = response.json()
+        assert body["message"] == "something went wrong"
+        assert body["description"] == "Detail: something went wrong"
+        assert body["data"] == {"reason": "something went wrong"}
+
+
+class TestApiExceptionGuard:
+    """Tests for the __init_subclass__ api_error guard."""
+
+    def test_missing_api_error_raises_type_error(self):
+        """Defining a subclass without api_error raises TypeError at class creation time."""
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class BrokenError(ApiException):
+                pass
+
+    def test_abstract_subclass_skips_guard(self):
+        """abstract=True allows intermediate base classes without api_error."""
+
+        class BaseGroupError(ApiException, abstract=True):
+            pass
+
+        # Concrete child must still define it
+        class ConcreteError(BaseGroupError):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Desc.", err_code="ERR-400"
+            )
+
+        err = ConcreteError()
+        assert err.api_error.code == 400
+
+    def test_abstract_child_still_requires_api_error_on_concrete(self):
+        """Concrete subclass of an abstract class must define api_error."""
+
+        class Base(ApiException, abstract=True):
+            pass
+
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class Concrete(Base):
+                pass
+
+    def test_inherited_api_error_satisfies_guard(self):
+        """Subclass that inherits api_error from a parent does not need its own."""
+
+        class ConcreteError(NotFoundError):
+            pass
+
+        err = ConcreteError()
+        assert err.api_error.code == 404


 class TestBuiltInExceptions:
@@ -90,7 +255,7 @@ class TestGenerateErrorResponses:
        assert responses[404]["description"] == "Not Found"

    def test_generates_multiple_responses(self):
-        """Generates responses for multiple exceptions."""
+        """Generates responses for multiple exceptions with distinct status codes."""
        responses = generate_error_responses(
            UnauthorizedError,
            ForbiddenError,
@@ -101,15 +266,24 @@ class TestGenerateErrorResponses:
        assert 403 in responses
        assert 404 in responses

-    def test_response_has_example(self):
-        """Generated response includes example."""
+    def test_response_has_named_example(self):
+        """Generated response uses named examples keyed by err_code."""
        responses = generate_error_responses(NotFoundError)
-        example = responses[404]["content"]["application/json"]["example"]
+        examples = responses[404]["content"]["application/json"]["examples"]

-        assert example["status"] == "FAIL"
-        assert example["error_code"] == "RES-404"
-        assert example["message"] == "Not Found"
-        assert example["data"] is None
+        assert "RES-404" in examples
+        value = examples["RES-404"]["value"]
+        assert value["status"] == "FAIL"
+        assert value["error_code"] == "RES-404"
+        assert value["message"] == "Not Found"
+        assert value["data"] is None
+
+    def test_response_example_has_summary(self):
+        """Each named example carries a summary equal to api_error.msg."""
+        responses = generate_error_responses(NotFoundError)
+        example = responses[404]["content"]["application/json"]["examples"]["RES-404"]
+
+        assert example["summary"] == "Not Found"

    def test_response_example_with_data(self):
        """Generated response includes data when set on ApiError."""
@@ -124,9 +298,49 @@ class TestGenerateErrorResponses:
            )

        responses = generate_error_responses(ErrorWithData)
-        example = responses[400]["content"]["application/json"]["example"]
+        value = responses[400]["content"]["application/json"]["examples"]["BAD-400"][
+            "value"
+        ]

-        assert example["data"] == {"details": "some context"}
+        assert value["data"] == {"details": "some context"}
+
+    def test_two_errors_same_code_both_present(self):
+        """Two exceptions with the same HTTP code produce two named examples."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+
+        assert 400 in responses
+        examples = responses[400]["content"]["application/json"]["examples"]
+        assert "ERR-A" in examples
+        assert "ERR-B" in examples
+        assert examples["ERR-A"]["value"]["message"] == "Bad A"
+        assert examples["ERR-B"]["value"]["message"] == "Bad B"
+
+    def test_two_errors_same_code_single_top_level_entry(self):
+        """Two exceptions with the same HTTP code produce exactly one top-level entry."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+        assert len([k for k in responses if k == 400]) == 1


 class TestInitExceptionsHandlers:
@@ -250,13 +464,68 @@ class TestInitExceptionsHandlers:
        assert data["status"] == "FAIL"
        assert data["error_code"] == "SERVER-500"

-    def test_custom_openapi_schema(self):
-        """Customizes OpenAPI schema for 422 responses."""
+    def test_handles_http_exception(self):
+        """Handles starlette HTTPException with consistent ErrorResponse envelope."""
        app = FastAPI()
        init_exceptions_handlers(app)

+        @app.get("/protected")
+        async def protected():
+            raise HTTPException(status_code=403, detail="Forbidden")
+
+        client = TestClient(app)
+        response = client.get("/protected")
+
+        assert response.status_code == 403
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-403"
+        assert data["message"] == "Forbidden"
+
+    def test_handles_http_exception_404_from_route(self):
+        """HTTPException(404) raised inside a route uses the consistent ErrorResponse envelope."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items/{item_id}")
+        async def get_item(item_id: int):
+            raise HTTPException(status_code=404, detail="Item not found")
+
+        client = TestClient(app)
+        response = client.get("/items/99")
+
+        assert response.status_code == 404
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-404"
+        assert data["message"] == "Item not found"
+
+    def test_handles_http_exception_forwards_headers(self):
+        """HTTPException with WWW-Authenticate header forwards it in the response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/secure")
+        async def secure():
+            raise HTTPException(
+                status_code=401,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        client = TestClient(app)
+        response = client.get("/secure")
+
+        assert response.status_code == 401
+        assert response.headers.get("www-authenticate") == "Bearer"
+
+    def test_custom_openapi_schema(self):
+        """Customises OpenAPI schema for 422 responses using named examples."""
        from pydantic import BaseModel

+        app = FastAPI()
+        init_exceptions_handlers(app)
+
        class Item(BaseModel):
            name: str

@@ -269,8 +538,128 @@ class TestInitExceptionsHandlers:
        post_op = openapi["paths"]["/items"]["post"]
        assert "422" in post_op["responses"]
        resp_422 = post_op["responses"]["422"]
-        example = resp_422["content"]["application/json"]["example"]
-        assert example["error_code"] == "VAL-422"
+        examples = resp_422["content"]["application/json"]["examples"]
+        assert "VAL-422" in examples
+        assert examples["VAL-422"]["value"]["error_code"] == "VAL-422"
+
+    def test_custom_openapi_preserves_app_metadata(self):
+        """_patched_openapi preserves custom FastAPI app-level metadata."""
+        app = FastAPI(
+            title="My API",
+            version="2.0.0",
+            description="Custom description",
+        )
+        init_exceptions_handlers(app)
+
+        schema = app.openapi()
+        assert schema["info"]["title"] == "My API"
+        assert schema["info"]["version"] == "2.0.0"
+
+    def test_handles_response_validation_error(self):
+        """Handles ResponseValidationError with a structured 422 response."""
+        from pydantic import BaseModel
+
+        class CountResponse(BaseModel):
+            count: int
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/broken", response_model=CountResponse)
+        async def broken():
+            return {"count": "not-a-number"}  # triggers ResponseValidationError
+
+        client = TestClient(app, raise_server_exceptions=False)
+        response = client.get("/broken")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "VAL-422"
+        assert "errors" in data["data"]
+
+    def test_handles_validation_error_with_non_standard_loc(self):
+        """Validation error with empty loc tuple maps the field to 'root'."""
+        from fastapi.exceptions import RequestValidationError
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/root-error")
+        async def root_error():
+            raise RequestValidationError(
+                [
+                    {
+                        "type": "custom",
+                        "loc": (),
+                        "msg": "root level error",
+                        "input": None,
+                        "url": "",
+                    }
+                ]
+            )
+
+        client = TestClient(app)
+        response = client.get("/root-error")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["data"]["errors"][0]["field"] == "root"
+
+    def test_openapi_schema_cached_after_first_call(self):
+        """app.openapi() returns the cached schema on subsequent calls."""
+        from pydantic import BaseModel
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        class Item(BaseModel):
+            name: str
+
+        @app.post("/items")
+        async def create_item(item: Item):
+            return item
+
+        schema_first = app.openapi()
+        schema_second = app.openapi()
+        assert schema_first is schema_second
+
+    def test_openapi_skips_operations_without_422(self):
+        """_patched_openapi leaves operations that have no 422 response unchanged."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/ping")
+        async def ping():
+            return {"ok": True}
+
+        schema = app.openapi()
+        get_op = schema["paths"]["/ping"]["get"]
+        assert "422" not in get_op["responses"]
+        assert "200" in get_op["responses"]
+
+    def test_openapi_skips_non_dict_path_item_values(self):
+        """_patched_openapi ignores non-dict values in path items (e.g. path-level parameters)."""
+        from fastapi_toolsets.exceptions.handler import _patched_openapi
+
+        app = FastAPI()
+
+        def fake_openapi() -> dict:
+            return {
+                "paths": {
+                    "/items": {
+                        "parameters": [
+                            {"name": "q", "in": "query"}
+                        ],  # list, not a dict
+                        "get": {"responses": {"200": {"description": "OK"}}},
+                    }
+                }
+            }
+
+        schema = _patched_openapi(app, fake_openapi)
+        # The list value was skipped without error; the GET operation is intact
+        assert schema["paths"]["/items"]["parameters"] == [{"name": "q", "in": "query"}]
+        assert "422" not in schema["paths"]["/items"]["get"]["responses"]


 class TestExceptionIntegration:
@@ -352,12 +741,12 @@ class TestInvalidOrderFieldError:
        assert error.field == "unknown"
        assert error.valid_fields == ["name", "created_at"]

-    def test_message_contains_field_and_valid_fields(self):
-        """Exception message mentions the bad field and valid options."""
+    def test_description_contains_field_and_valid_fields(self):
+        """api_error.desc mentions the bad field and valid options."""
        error = InvalidOrderFieldError("bad_field", ["name", "email"])
-        assert "bad_field" in str(error)
-        assert "name" in str(error)
-        assert "email" in str(error)
+        assert "bad_field" in error.api_error.desc
+        assert "name" in error.api_error.desc
+        assert "email" in error.api_error.desc

    def test_handled_as_422_by_exception_handler(self):
        """init_exceptions_handlers turns InvalidOrderFieldError into a 422 response."""
--- a/tests/test_fixtures.py
+++ b/tests/test_fixtures.py
@@ -14,7 +14,9 @@ from fastapi_toolsets.fixtures import (
    load_fixtures_by_context,
 )

-from .conftest import Role, User
+from fastapi_toolsets.fixtures.utils import _get_primary_key
+
+from .conftest import IntRole, Permission, Role, User


 class TestContext:
@@ -597,6 +599,46 @@ class TestLoadFixtures:
        count = await RoleCrud.count(db_session)
        assert count == 2

+    @pytest.mark.anyio
+    async def test_skip_existing_skips_if_record_exists(self, db_session: AsyncSession):
+        """SKIP_EXISTING returns empty loaded list when the record already exists."""
+        registry = FixtureRegistry()
+        role_id = uuid.uuid4()
+
+        @registry.register
+        def roles():
+            return [Role(id=role_id, name="admin")]
+
+        # First load — inserts the record.
+        result1 = await load_fixtures(
+            db_session, registry, "roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert len(result1["roles"]) == 1
+
+        # Remove from identity map so session.get() queries the DB in the second load.
+        db_session.expunge_all()
+
+        # Second load — record exists in DB, nothing should be added.
+        result2 = await load_fixtures(
+            db_session, registry, "roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert result2["roles"] == []
+
+    @pytest.mark.anyio
+    async def test_skip_existing_null_pk_inserts(self, db_session: AsyncSession):
+        """SKIP_EXISTING inserts when the instance has no PK set (auto-increment)."""
+        registry = FixtureRegistry()
+
+        @registry.register
+        def int_roles():
+            # No id provided — PK is None before INSERT (autoincrement).
+            return [IntRole(name="member")]
+
+        result = await load_fixtures(
+            db_session, registry, "int_roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert len(result["int_roles"]) == 1
+

 class TestLoadFixturesByContext:
    """Tests for load_fixtures_by_context function."""
@@ -755,3 +797,19 @@ class TestGetObjByAttr:
        """Raises StopIteration when value type doesn't match."""
        with pytest.raises(StopIteration):
            get_obj_by_attr(self.roles, "id", "not-a-uuid")
+
+
+class TestGetPrimaryKey:
+    """Unit tests for the _get_primary_key helper (composite PK paths)."""
+
+    def test_composite_pk_all_set(self):
+        """Returns a tuple when all composite PK values are set."""
+        instance = Permission(subject="post", action="read")
+        pk = _get_primary_key(instance)
+        assert pk == ("post", "read")
+
+    def test_composite_pk_partial_none(self):
+        """Returns None when any composite PK value is None."""
+        instance = Permission(subject="post")  # action is None
+        pk = _get_primary_key(instance)
+        assert pk is None
--- a/tests/test_metrics.py
+++ b/tests/test_metrics.py
@@ -159,6 +159,42 @@ class TestMetricsRegistry:
        assert registry.get_all()[0].func is second


+class TestGet:
+    """Tests for MetricsRegistry.get method."""
+
+    def test_get_returns_instance_after_init(self):
+        """get() returns the metric instance stored by init_metrics."""
+        app = FastAPI()
+        registry = MetricsRegistry()
+
+        @registry.register
+        def my_gauge():
+            return Gauge("get_test_gauge", "A test gauge")
+
+        init_metrics(app, registry)
+
+        instance = registry.get("my_gauge")
+        assert isinstance(instance, Gauge)
+
+    def test_get_raises_for_registered_but_not_initialized(self):
+        """get() raises KeyError with an informative message when init_metrics was not called."""
+        registry = MetricsRegistry()
+
+        @registry.register
+        def my_counter():
+            return Counter("get_uninit_counter", "A counter")
+
+        with pytest.raises(KeyError, match="not been initialized yet"):
+            registry.get("my_counter")
+
+    def test_get_raises_for_unknown_name(self):
+        """get() raises KeyError when the metric name is not registered at all."""
+        registry = MetricsRegistry()
+
+        with pytest.raises(KeyError, match="Unknown metric"):
+            registry.get("nonexistent")
+
+
 class TestIncludeRegistry:
    """Tests for MetricsRegistry.include_registry method."""

--- a/tests/test_models.py
+++ b/tests/test_models.py
@@ -0,0 +1,247 @@
+"""Tests for fastapi_toolsets.models mixins."""
+
+import uuid
+
+import pytest
+from sqlalchemy import String
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from fastapi_toolsets.models import (
+    CreatedAtMixin,
+    TimestampMixin,
+    UUIDMixin,
+    UpdatedAtMixin,
+)
+
+from .conftest import DATABASE_URL
+
+
+class MixinBase(DeclarativeBase):
+    pass
+
+
+class UUIDModel(MixinBase, UUIDMixin):
+    __tablename__ = "mixin_uuid_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class UpdatedAtModel(MixinBase, UpdatedAtMixin):
+    __tablename__ = "mixin_updated_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class CreatedAtModel(MixinBase, CreatedAtMixin):
+    __tablename__ = "mixin_created_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class TimestampModel(MixinBase, TimestampMixin):
+    __tablename__ = "mixin_timestamp_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class FullMixinModel(MixinBase, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "mixin_full_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+@pytest.fixture(scope="function")
+async def mixin_session():
+    engine = create_async_engine(DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(MixinBase.metadata.create_all)
+
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    session = session_factory()
+
+    try:
+        yield session
+    finally:
+        await session.close()
+        async with engine.begin() as conn:
+            await conn.run_sync(MixinBase.metadata.drop_all)
+        await engine.dispose()
+
+
+class TestUUIDMixin:
+    @pytest.mark.anyio
+    async def test_uuid_generated_by_db(self, mixin_session):
+        """UUID is generated server-side and populated after flush."""
+        obj = UUIDModel(name="test")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+
+        assert obj.id is not None
+        assert isinstance(obj.id, uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_uuid_is_primary_key(self):
+        """UUIDMixin adds id as primary key column."""
+        pk_cols = [c.name for c in UUIDModel.__table__.primary_key]
+        assert pk_cols == ["id"]
+
+    @pytest.mark.anyio
+    async def test_each_row_gets_unique_uuid(self, mixin_session):
+        """Each inserted row gets a distinct UUID."""
+        a = UUIDModel(name="a")
+        b = UUIDModel(name="b")
+        mixin_session.add_all([a, b])
+        await mixin_session.flush()
+
+        assert a.id != b.id
+
+    @pytest.mark.anyio
+    async def test_uuid_server_default_set(self):
+        """Column has gen_random_uuid() as server default."""
+        col = UUIDModel.__table__.c["id"]
+        assert col.server_default is not None
+        assert "gen_random_uuid" in str(col.server_default.arg)
+
+
+class TestUpdatedAtMixin:
+    @pytest.mark.anyio
+    async def test_updated_at_set_on_insert(self, mixin_session):
+        """updated_at is populated after insert."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None  # timezone-aware
+
+    @pytest.mark.anyio
+    async def test_updated_at_changes_on_update(self, mixin_session):
+        """updated_at is updated when the row is modified."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at >= original_ts
+
+    @pytest.mark.anyio
+    async def test_updated_at_column_is_not_nullable(self):
+        """updated_at column is non-nullable."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_server_default(self):
+        """updated_at column has a server-side default."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.server_default is not None
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_onupdate(self):
+        """updated_at column has an onupdate clause."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.onupdate is not None
+
+
+class TestCreatedAtMixin:
+    @pytest.mark.anyio
+    async def test_created_at_set_on_insert(self, mixin_session):
+        """created_at is populated after insert."""
+        obj = CreatedAtModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.created_at.tzinfo is not None  # timezone-aware
+
+    @pytest.mark.anyio
+    async def test_created_at_not_changed_on_update(self, mixin_session):
+        """created_at is not modified when the row is updated."""
+        obj = CreatedAtModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.created_at
+
+        obj.name = "updated"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_ts
+
+    @pytest.mark.anyio
+    async def test_created_at_column_is_not_nullable(self):
+        """created_at column is non-nullable."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_created_at_has_no_onupdate(self):
+        """created_at column has no onupdate clause."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert col.onupdate is None
+
+
+class TestTimestampMixin:
+    @pytest.mark.anyio
+    async def test_both_columns_set_on_insert(self, mixin_session):
+        """created_at and updated_at are both populated after insert."""
+        obj = TimestampModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.updated_at is not None
+
+    @pytest.mark.anyio
+    async def test_created_at_stable_updated_at_changes_on_update(self, mixin_session):
+        """On update: created_at stays the same, updated_at advances."""
+        obj = TimestampModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_created = obj.created_at
+        original_updated = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_created
+        assert obj.updated_at >= original_updated
+
+    @pytest.mark.anyio
+    async def test_timestamp_mixin_has_both_columns(self):
+        """TimestampModel exposes both created_at and updated_at columns."""
+        col_names = {c.name for c in TimestampModel.__table__.columns}
+        assert "created_at" in col_names
+        assert "updated_at" in col_names
+
+
+class TestFullMixinModel:
+    @pytest.mark.anyio
+    async def test_combined_mixins_work_together(self, mixin_session):
+        """UUIDMixin and UpdatedAtMixin can be combined on the same model."""
+        obj = FullMixinModel(name="combined")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert isinstance(obj.id, uuid.UUID)
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None
--- a/tests/test_pytest.py
+++ b/tests/test_pytest.py
@@ -8,11 +8,10 @@ from httpx import AsyncClient
 from sqlalchemy import select, text
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, selectinload
+from sqlalchemy.orm import selectinload

 from fastapi_toolsets.fixtures import Context, FixtureRegistry
 from fastapi_toolsets.pytest import (
-    cleanup_tables,
    create_async_client,
    create_db_session,
    create_worker_database,
@@ -406,7 +405,6 @@ class TestCreateWorkerDatabase:
        ) as url:
            assert make_url(url).database == expected_db

-            # Verify the database exists while inside the context
            engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
            async with engine.connect() as conn:
                result = await conn.execute(
@@ -416,7 +414,6 @@ class TestCreateWorkerDatabase:
                assert result.scalar() == 1
            await engine.dispose()

-        # After context exit the database should be dropped
        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
        async with engine.connect() as conn:
            result = await conn.execute(
@@ -439,7 +436,6 @@ class TestCreateWorkerDatabase:
        async with create_worker_database(DATABASE_URL) as url:
            assert make_url(url).database == expected_db

-            # Verify the database exists while inside the context
            engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
            async with engine.connect() as conn:
                result = await conn.execute(
@@ -449,7 +445,6 @@ class TestCreateWorkerDatabase:
                assert result.scalar() == 1
            await engine.dispose()

-        # After context exit the database should be dropped
        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
        async with engine.connect() as conn:
            result = await conn.execute(
@@ -467,18 +462,15 @@ class TestCreateWorkerDatabase:
            worker_database_url(DATABASE_URL, default_test_db="unused")
        ).database

-        # Pre-create the database to simulate a stale leftover
        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
        async with engine.connect() as conn:
            await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
            await conn.execute(text(f"CREATE DATABASE {expected_db}"))
        await engine.dispose()

-        # Should succeed despite the database already existing
        async with create_worker_database(DATABASE_URL) as url:
            assert make_url(url).database == expected_db

-        # Verify cleanup after context exit
        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
        async with engine.connect() as conn:
            result = await conn.execute(
@@ -487,49 +479,3 @@ class TestCreateWorkerDatabase:
            )
            assert result.scalar() is None
        await engine.dispose()
-
-
-class TestCleanupTables:
-    """Tests for cleanup_tables helper."""
-
-    @pytest.mark.anyio
-    async def test_truncates_all_tables(self):
-        """All table rows are removed after cleanup_tables."""
-        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
-            role = Role(id=uuid.uuid4(), name="cleanup_role")
-            session.add(role)
-            await session.flush()
-
-            user = User(
-                id=uuid.uuid4(),
-                username="cleanup_user",
-                email="cleanup@test.com",
-                role_id=role.id,
-            )
-            session.add(user)
-            await session.commit()
-
-            # Verify rows exist
-            roles_count = await RoleCrud.count(session)
-            users_count = await UserCrud.count(session)
-            assert roles_count == 1
-            assert users_count == 1
-
-            await cleanup_tables(session, Base)
-
-            # Verify tables are empty
-            roles_count = await RoleCrud.count(session)
-            users_count = await UserCrud.count(session)
-            assert roles_count == 0
-            assert users_count == 0
-
-    @pytest.mark.anyio
-    async def test_noop_for_empty_metadata(self):
-        """cleanup_tables does not raise when metadata has no tables."""
-
-        class EmptyBase(DeclarativeBase):
-            pass
-
-        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
-            # Should not raise
-            await cleanup_tables(session, EmptyBase)
--- a/tests/test_schemas.py
+++ b/tests/test_schemas.py
@@ -6,10 +6,12 @@ from pydantic import ValidationError
 from fastapi_toolsets.schemas import (
    ApiError,
    CursorPagination,
+    CursorPaginatedResponse,
    ErrorResponse,
    OffsetPagination,
+    OffsetPaginatedResponse,
    PaginatedResponse,
-    Pagination,
+    PaginationType,
    Response,
    ResponseStatus,
 )
@@ -199,20 +201,6 @@ class TestOffsetPagination:
        assert data["page"] == 2
        assert data["has_more"] is True

-    def test_pagination_alias_is_offset_pagination(self):
-        """Pagination is a backward-compatible alias for OffsetPagination."""
-        assert Pagination is OffsetPagination
-
-    def test_pagination_alias_constructs_offset_pagination(self):
-        """Code using Pagination(...) still works unchanged."""
-        pagination = Pagination(
-            total_count=10,
-            items_per_page=5,
-            page=2,
-            has_more=False,
-        )
-        assert isinstance(pagination, OffsetPagination)
-

 class TestCursorPagination:
    """Tests for CursorPagination schema."""
@@ -276,7 +264,7 @@ class TestPaginatedResponse:

    def test_create_paginated_response(self):
        """Create PaginatedResponse with data and pagination."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
            total_count=30,
            items_per_page=10,
            page=1,
@@ -294,7 +282,7 @@ class TestPaginatedResponse:

    def test_with_custom_message(self):
        """PaginatedResponse with custom message."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
            total_count=5,
            items_per_page=10,
            page=1,
@@ -310,7 +298,7 @@ class TestPaginatedResponse:

    def test_empty_data(self):
        """PaginatedResponse with empty data."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
            total_count=0,
            items_per_page=10,
            page=1,
@@ -327,12 +315,7 @@ class TestPaginatedResponse:

    def test_generic_type_hint(self):
        """PaginatedResponse supports generic type hints."""
-
-        class UserOut:
-            id: int
-            name: str
-
-        pagination = Pagination(
+        pagination = OffsetPagination(
            total_count=1,
            items_per_page=10,
            page=1,
@@ -347,7 +330,7 @@ class TestPaginatedResponse:

    def test_serialization(self):
        """PaginatedResponse serializes correctly."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
            total_count=100,
            items_per_page=10,
            page=5,
@@ -385,15 +368,190 @@ class TestPaginatedResponse:
        )
        assert isinstance(response.pagination, CursorPagination)

-    def test_pagination_alias_accepted(self):
-        """Constructing PaginatedResponse with Pagination (alias) still works."""
-        response = PaginatedResponse(
+
+class TestPaginationType:
+    """Tests for PaginationType enum."""
+
+    def test_offset_value(self):
+        """OFFSET has string value 'offset'."""
+        assert PaginationType.OFFSET == "offset"
+        assert PaginationType.OFFSET.value == "offset"
+
+    def test_cursor_value(self):
+        """CURSOR has string value 'cursor'."""
+        assert PaginationType.CURSOR == "cursor"
+        assert PaginationType.CURSOR.value == "cursor"
+
+    def test_is_string_enum(self):
+        """PaginationType is a string enum."""
+        assert isinstance(PaginationType.OFFSET, str)
+        assert isinstance(PaginationType.CURSOR, str)
+
+    def test_members(self):
+        """PaginationType has exactly two members."""
+        assert set(PaginationType) == {PaginationType.OFFSET, PaginationType.CURSOR}
+
+
+class TestOffsetPaginatedResponse:
+    """Tests for OffsetPaginatedResponse schema."""
+
+    def test_pagination_type_is_offset(self):
+        """pagination_type is always PaginationType.OFFSET."""
+        response = OffsetPaginatedResponse(
            data=[],
-            pagination=Pagination(
+            pagination=OffsetPagination(
                total_count=0, items_per_page=10, page=1, has_more=False
            ),
        )
+        assert response.pagination_type is PaginationType.OFFSET
+
+    def test_pagination_type_serializes_to_string(self):
+        """pagination_type serializes to 'offset' in JSON mode."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert response.model_dump(mode="json")["pagination_type"] == "offset"
+
+    def test_pagination_field_is_typed(self):
+        """pagination field is OffsetPagination, not the union."""
+        response = OffsetPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=OffsetPagination(
+                total_count=10, items_per_page=5, page=2, has_more=True
+            ),
+        )
        assert isinstance(response.pagination, OffsetPagination)
+        assert response.pagination.total_count == 10
+        assert response.pagination.page == 2
+
+    def test_is_subclass_of_paginated_response(self):
+        """OffsetPaginatedResponse IS a PaginatedResponse."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert isinstance(response, PaginatedResponse)
+
+    def test_pagination_type_default_cannot_be_overridden_to_cursor(self):
+        """pagination_type rejects values other than OFFSET."""
+        with pytest.raises(ValidationError):
+            OffsetPaginatedResponse(
+                data=[],
+                pagination=OffsetPagination(
+                    total_count=0, items_per_page=10, page=1, has_more=False
+                ),
+                pagination_type=PaginationType.CURSOR,  # type: ignore[arg-type]
+            )
+
+    def test_filter_attributes_defaults_to_none(self):
+        """filter_attributes defaults to None."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert response.filter_attributes is None
+
+    def test_full_serialization(self):
+        """Full JSON serialization includes all expected fields."""
+        response = OffsetPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=OffsetPagination(
+                total_count=1, items_per_page=10, page=1, has_more=False
+            ),
+            filter_attributes={"status": ["active"]},
+        )
+        data = response.model_dump(mode="json")
+
+        assert data["pagination_type"] == "offset"
+        assert data["status"] == "SUCCESS"
+        assert data["data"] == [{"id": 1}]
+        assert data["pagination"]["total_count"] == 1
+        assert data["filter_attributes"] == {"status": ["active"]}
+
+
+class TestCursorPaginatedResponse:
+    """Tests for CursorPaginatedResponse schema."""
+
+    def test_pagination_type_is_cursor(self):
+        """pagination_type is always PaginationType.CURSOR."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert response.pagination_type is PaginationType.CURSOR
+
+    def test_pagination_type_serializes_to_string(self):
+        """pagination_type serializes to 'cursor' in JSON mode."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert response.model_dump(mode="json")["pagination_type"] == "cursor"
+
+    def test_pagination_field_is_typed(self):
+        """pagination field is CursorPagination, not the union."""
+        response = CursorPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=CursorPagination(
+                next_cursor="abc123",
+                prev_cursor=None,
+                items_per_page=20,
+                has_more=True,
+            ),
+        )
+        assert isinstance(response.pagination, CursorPagination)
+        assert response.pagination.next_cursor == "abc123"
+        assert response.pagination.has_more is True
+
+    def test_is_subclass_of_paginated_response(self):
+        """CursorPaginatedResponse IS a PaginatedResponse."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert isinstance(response, PaginatedResponse)
+
+    def test_pagination_type_default_cannot_be_overridden_to_offset(self):
+        """pagination_type rejects values other than CURSOR."""
+        with pytest.raises(ValidationError):
+            CursorPaginatedResponse(
+                data=[],
+                pagination=CursorPagination(
+                    next_cursor=None, items_per_page=10, has_more=False
+                ),
+                pagination_type=PaginationType.OFFSET,  # type: ignore[arg-type]
+            )
+
+    def test_full_serialization(self):
+        """Full JSON serialization includes all expected fields."""
+        response = CursorPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=CursorPagination(
+                next_cursor="tok_next",
+                prev_cursor="tok_prev",
+                items_per_page=10,
+                has_more=True,
+            ),
+        )
+        data = response.model_dump(mode="json")
+
+        assert data["pagination_type"] == "cursor"
+        assert data["status"] == "SUCCESS"
+        assert data["pagination"]["next_cursor"] == "tok_next"
+        assert data["pagination"]["prev_cursor"] == "tok_prev"


 class TestFromAttributes:
--- a/uv.lock
+++ b/uv.lock
@@ -235,7 +235,7 @@ wheels = [

 [[package]]
 name = "fastapi"
-version = "0.133.1"
+version = "0.135.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "annotated-doc" },
@@ -244,14 +244,14 @@ dependencies = [
    { name = "typing-extensions" },
    { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/22/6f/0eafed8349eea1fa462238b54a624c8b408cd1ba2795c8e64aa6c34f8ab7/fastapi-0.133.1.tar.gz", hash = "sha256:ed152a45912f102592976fde6cbce7dae1a8a1053da94202e51dd35d184fadd6", size = 378741, upload-time = "2026-02-25T18:18:17.398Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/7b/f8e0211e9380f7195ba3f3d40c292594fd81ba8ec4629e3854c353aaca45/fastapi-0.135.1.tar.gz", hash = "sha256:d04115b508d936d254cea545b7312ecaa58a7b3a0f84952535b4c9afae7668cd", size = 394962, upload-time = "2026-03-01T18:18:29.369Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d2/c9/a175a7779f3599dfa4adfc97a6ce0e157237b3d7941538604aadaf97bfb6/fastapi-0.133.1-py3-none-any.whl", hash = "sha256:658f34ba334605b1617a65adf2ea6461901bdb9af3a3080d63ff791ecf7dc2e2", size = 109029, upload-time = "2026-02-25T18:18:18.578Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/72/42e900510195b23a56bde950d26a51f8b723846bfcaa0286e90287f0422b/fastapi-0.135.1-py3-none-any.whl", hash = "sha256:46e2fc5745924b7c840f71ddd277382af29ce1cdb7d5eab5bf697e3fb9999c9e", size = 116999, upload-time = "2026-03-01T18:18:30.831Z" },
 ]

 [[package]]
 name = "fastapi-toolsets"
-version = "1.3.0"
+version = "2.2.1"
 source = { editable = "." }
 dependencies = [
    { name = "asyncpg" },
@@ -1013,27 +1013,27 @@ wheels = [

 [[package]]
 name = "ruff"
-version = "0.15.2"
+version = "0.15.5"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/06/04/eab13a954e763b0606f460443fcbf6bb5a0faf06890ea3754ff16523dce5/ruff-0.15.2.tar.gz", hash = "sha256:14b965afee0969e68bb871eba625343b8673375f457af4abe98553e8bbb98342", size = 4558148, upload-time = "2026-02-19T22:32:20.271Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/77/9b/840e0039e65fcf12758adf684d2289024d6140cde9268cc59887dc55189c/ruff-0.15.5.tar.gz", hash = "sha256:7c3601d3b6d76dce18c5c824fc8d06f4eef33d6df0c21ec7799510cde0f159a2", size = 4574214, upload-time = "2026-03-05T20:06:34.946Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/2f/70/3a4dc6d09b13cb3e695f28307e5d889b2e1a66b7af9c5e257e796695b0e6/ruff-0.15.2-py3-none-linux_armv6l.whl", hash = "sha256:120691a6fdae2f16d65435648160f5b81a9625288f75544dc40637436b5d3c0d", size = 10430565, upload-time = "2026-02-19T22:32:41.824Z" },
-    { url = "https://files.pythonhosted.org/packages/71/0b/bb8457b56185ece1305c666dc895832946d24055be90692381c31d57466d/ruff-0.15.2-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:a89056d831256099658b6bba4037ac6dd06f49d194199215befe2bb10457ea5e", size = 10820354, upload-time = "2026-02-19T22:32:07.366Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/c1/e0532d7f9c9e0b14c46f61b14afd563298b8b83f337b6789ddd987e46121/ruff-0.15.2-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e36dee3a64be0ebd23c86ffa3aa3fd3ac9a712ff295e192243f814a830b6bd87", size = 10170767, upload-time = "2026-02-19T22:32:13.188Z" },
-    { url = "https://files.pythonhosted.org/packages/47/e8/da1aa341d3af017a21c7a62fb5ec31d4e7ad0a93ab80e3a508316efbcb23/ruff-0.15.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a9fb47b6d9764677f8c0a193c0943ce9a05d6763523f132325af8a858eadc2b9", size = 10529591, upload-time = "2026-02-19T22:32:02.547Z" },
-    { url = "https://files.pythonhosted.org/packages/93/74/184fbf38e9f3510231fbc5e437e808f0b48c42d1df9434b208821efcd8d6/ruff-0.15.2-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f376990f9d0d6442ea9014b19621d8f2aaf2b8e39fdbfc79220b7f0c596c9b80", size = 10260771, upload-time = "2026-02-19T22:32:36.938Z" },
-    { url = "https://files.pythonhosted.org/packages/05/ac/605c20b8e059a0bc4b42360414baa4892ff278cec1c91fff4be0dceedefd/ruff-0.15.2-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2dcc987551952d73cbf5c88d9fdee815618d497e4df86cd4c4824cc59d5dd75f", size = 11045791, upload-time = "2026-02-19T22:32:31.642Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/52/db6e419908f45a894924d410ac77d64bdd98ff86901d833364251bd08e22/ruff-0.15.2-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:42a47fd785cbe8c01b9ff45031af875d101b040ad8f4de7bbb716487c74c9a77", size = 11879271, upload-time = "2026-02-19T22:32:29.305Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/d8/7992b18f2008bdc9231d0f10b16df7dda964dbf639e2b8b4c1b4e91b83af/ruff-0.15.2-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cbe9f49354866e575b4c6943856989f966421870e85cd2ac94dccb0a9dcb2fea", size = 11303707, upload-time = "2026-02-19T22:32:22.492Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/02/849b46184bcfdd4b64cde61752cc9a146c54759ed036edd11857e9b8443b/ruff-0.15.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b7a672c82b5f9887576087d97be5ce439f04bbaf548ee987b92d3a7dede41d3a", size = 11149151, upload-time = "2026-02-19T22:32:44.234Z" },
-    { url = "https://files.pythonhosted.org/packages/70/04/f5284e388bab60d1d3b99614a5a9aeb03e0f333847e2429bebd2aaa1feec/ruff-0.15.2-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:72ecc64f46f7019e2bcc3cdc05d4a7da958b629a5ab7033195e11a438403d956", size = 11091132, upload-time = "2026-02-19T22:32:24.691Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/ae/88d844a21110e14d92cf73d57363fab59b727ebeabe78009b9ccb23500af/ruff-0.15.2-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:8dcf243b15b561c655c1ef2f2b0050e5d50db37fe90115507f6ff37d865dc8b4", size = 10504717, upload-time = "2026-02-19T22:32:26.75Z" },
-    { url = "https://files.pythonhosted.org/packages/64/27/867076a6ada7f2b9c8292884ab44d08fd2ba71bd2b5364d4136f3cd537e1/ruff-0.15.2-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dab6941c862c05739774677c6273166d2510d254dac0695c0e3f5efa1b5585de", size = 10263122, upload-time = "2026-02-19T22:32:10.036Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/ef/faf9321d550f8ebf0c6373696e70d1758e20ccdc3951ad7af00c0956be7c/ruff-0.15.2-py3-none-musllinux_1_2_i686.whl", hash = "sha256:1b9164f57fc36058e9a6806eb92af185b0697c9fe4c7c52caa431c6554521e5c", size = 10735295, upload-time = "2026-02-19T22:32:39.227Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/55/e8089fec62e050ba84d71b70e7834b97709ca9b7aba10c1a0b196e493f97/ruff-0.15.2-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:80d24fcae24d42659db7e335b9e1531697a7102c19185b8dc4a028b952865fd8", size = 11241641, upload-time = "2026-02-19T22:32:34.617Z" },
-    { url = "https://files.pythonhosted.org/packages/23/01/1c30526460f4d23222d0fabd5888868262fd0e2b71a00570ca26483cd993/ruff-0.15.2-py3-none-win32.whl", hash = "sha256:fd5ff9e5f519a7e1bd99cbe8daa324010a74f5e2ebc97c6242c08f26f3714f6f", size = 10507885, upload-time = "2026-02-19T22:32:15.635Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/10/3d18e3bbdf8fc50bbb4ac3cc45970aa5a9753c5cb51bf9ed9a3cd8b79fa3/ruff-0.15.2-py3-none-win_amd64.whl", hash = "sha256:d20014e3dfa400f3ff84830dfb5755ece2de45ab62ecea4af6b7262d0fb4f7c5", size = 11623725, upload-time = "2026-02-19T22:32:04.947Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/78/097c0798b1dab9f8affe73da9642bb4500e098cb27fd8dc9724816ac747b/ruff-0.15.2-py3-none-win_arm64.whl", hash = "sha256:cabddc5822acdc8f7b5527b36ceac55cc51eec7b1946e60181de8fe83ca8876e", size = 10941649, upload-time = "2026-02-19T22:32:18.108Z" },
+    { url = "https://files.pythonhosted.org/packages/47/20/5369c3ce21588c708bcbe517a8fbe1a8dfdb5dfd5137e14790b1da71612c/ruff-0.15.5-py3-none-linux_armv6l.whl", hash = "sha256:4ae44c42281f42e3b06b988e442d344a5b9b72450ff3c892e30d11b29a96a57c", size = 10478185, upload-time = "2026-03-05T20:06:29.093Z" },
+    { url = "https://files.pythonhosted.org/packages/44/ed/e81dd668547da281e5dce710cf0bc60193f8d3d43833e8241d006720e42b/ruff-0.15.5-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:6edd3792d408ebcf61adabc01822da687579a1a023f297618ac27a5b51ef0080", size = 10859201, upload-time = "2026-03-05T20:06:32.632Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/8f/533075f00aaf19b07c5cd6aa6e5d89424b06b3b3f4583bfa9c640a079059/ruff-0.15.5-py3-none-macosx_11_0_arm64.whl", hash = "sha256:89f463f7c8205a9f8dea9d658d59eff49db05f88f89cc3047fb1a02d9f344010", size = 10184752, upload-time = "2026-03-05T20:06:40.312Z" },
+    { url = "https://files.pythonhosted.org/packages/66/0e/ba49e2c3fa0395b3152bad634c7432f7edfc509c133b8f4529053ff024fb/ruff-0.15.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba786a8295c6574c1116704cf0b9e6563de3432ac888d8f83685654fe528fd65", size = 10534857, upload-time = "2026-03-05T20:06:19.581Z" },
+    { url = "https://files.pythonhosted.org/packages/59/71/39234440f27a226475a0659561adb0d784b4d247dfe7f43ffc12dd02e288/ruff-0.15.5-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fd4b801e57955fe9f02b31d20375ab3a5c4415f2e5105b79fb94cf2642c91440", size = 10309120, upload-time = "2026-03-05T20:06:00.435Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/87/4140aa86a93df032156982b726f4952aaec4a883bb98cb6ef73c347da253/ruff-0.15.5-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:391f7c73388f3d8c11b794dbbc2959a5b5afe66642c142a6effa90b45f6f5204", size = 11047428, upload-time = "2026-03-05T20:05:51.867Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/f7/4953e7e3287676f78fbe85e3a0ca414c5ca81237b7575bdadc00229ac240/ruff-0.15.5-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8dc18f30302e379fe1e998548b0f5e9f4dff907f52f73ad6da419ea9c19d66c8", size = 11914251, upload-time = "2026-03-05T20:06:22.887Z" },
+    { url = "https://files.pythonhosted.org/packages/77/46/0f7c865c10cf896ccf5a939c3e84e1cfaeed608ff5249584799a74d33835/ruff-0.15.5-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1cc6e7f90087e2d27f98dc34ed1b3ab7c8f0d273cc5431415454e22c0bd2a681", size = 11333801, upload-time = "2026-03-05T20:05:57.168Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/01/a10fe54b653061585e655f5286c2662ebddb68831ed3eaebfb0eb08c0a16/ruff-0.15.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c1cb7169f53c1ddb06e71a9aebd7e98fc0fea936b39afb36d8e86d36ecc2636a", size = 11206821, upload-time = "2026-03-05T20:06:03.441Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/0d/2132ceaf20c5e8699aa83da2706ecb5c5dcdf78b453f77edca7fb70f8a93/ruff-0.15.5-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9b037924500a31ee17389b5c8c4d88874cc6ea8e42f12e9c61a3d754ff72f1ca", size = 11133326, upload-time = "2026-03-05T20:06:25.655Z" },
+    { url = "https://files.pythonhosted.org/packages/72/cb/2e5259a7eb2a0f87c08c0fe5bf5825a1e4b90883a52685524596bfc93072/ruff-0.15.5-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:65bb414e5b4eadd95a8c1e4804f6772bbe8995889f203a01f77ddf2d790929dd", size = 10510820, upload-time = "2026-03-05T20:06:37.79Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/20/b67ce78f9e6c59ffbdb5b4503d0090e749b5f2d31b599b554698a80d861c/ruff-0.15.5-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:d20aa469ae3b57033519c559e9bc9cd9e782842e39be05b50e852c7c981fa01d", size = 10302395, upload-time = "2026-03-05T20:05:54.504Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/e5/719f1acccd31b720d477751558ed74e9c88134adcc377e5e886af89d3072/ruff-0.15.5-py3-none-musllinux_1_2_i686.whl", hash = "sha256:15388dd28c9161cdb8eda68993533acc870aa4e646a0a277aa166de9ad5a8752", size = 10754069, upload-time = "2026-03-05T20:06:06.422Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/9c/d1db14469e32d98f3ca27079dbd30b7b44dbb5317d06ab36718dee3baf03/ruff-0.15.5-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b30da330cbd03bed0c21420b6b953158f60c74c54c5f4c1dabbdf3a57bf355d2", size = 11304315, upload-time = "2026-03-05T20:06:10.867Z" },
+    { url = "https://files.pythonhosted.org/packages/28/3a/950367aee7c69027f4f422059227b290ed780366b6aecee5de5039d50fa8/ruff-0.15.5-py3-none-win32.whl", hash = "sha256:732e5ee1f98ba5b3679029989a06ca39a950cced52143a0ea82a2102cb592b74", size = 10551676, upload-time = "2026-03-05T20:06:13.705Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/00/bf077a505b4e649bdd3c47ff8ec967735ce2544c8e4a43aba42ee9bf935d/ruff-0.15.5-py3-none-win_amd64.whl", hash = "sha256:821d41c5fa9e19117616c35eaa3f4b75046ec76c65e7ae20a333e9a8696bc7fe", size = 11678972, upload-time = "2026-03-05T20:06:45.379Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/4e/cd76eca6db6115604b7626668e891c9dd03330384082e33662fb0f113614/ruff-0.15.5-py3-none-win_arm64.whl", hash = "sha256:b498d1c60d2fe5c10c45ec3f698901065772730b411f164ae270bb6bfcc4740b", size = 10965572, upload-time = "2026-03-05T20:06:16.984Z" },
 ]

 [[package]]
@@ -1177,26 +1177,26 @@ wheels = [

 [[package]]
 name = "ty"
-version = "0.0.18"
+version = "0.0.21"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/74/15/9682700d8d60fdca7afa4febc83a2354b29cdcd56e66e19c92b521db3b39/ty-0.0.18.tar.gz", hash = "sha256:04ab7c3db5dcbcdac6ce62e48940d3a0124f377c05499d3f3e004e264ae94b83", size = 5214774, upload-time = "2026-02-20T21:51:31.173Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ee/20/2ba8fd9493c89c41dfe9dbb73bc70a28b28028463bc0d2897ba8be36230a/ty-0.0.21.tar.gz", hash = "sha256:a4c2ba5d67d64df8fcdefd8b280ac1149d24a73dbda82fa953a0dff9d21400ed", size = 5297967, upload-time = "2026-03-06T01:57:13.809Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ae/d8/920460d4c22ea68fcdeb0b2fb53ea2aeb9c6d7875bde9278d84f2ac767b6/ty-0.0.18-py3-none-linux_armv6l.whl", hash = "sha256:4e5e91b0a79857316ef893c5068afc4b9872f9d257627d9bc8ac4d2715750d88", size = 10280825, upload-time = "2026-02-20T21:51:25.03Z" },
-    { url = "https://files.pythonhosted.org/packages/83/56/62587de582d3d20d78fcdddd0594a73822ac5a399a12ef512085eb7a4de6/ty-0.0.18-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ee0e578b3f8416e2d5416da9553b78fd33857868aa1384cb7fefeceee5ff102d", size = 10118324, upload-time = "2026-02-20T21:51:22.27Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/2d/dbdace8d432a0755a7417f659bfd5b8a4261938ecbdfd7b42f4c454f5aa9/ty-0.0.18-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3f7a0487d36b939546a91d141f7fc3dbea32fab4982f618d5b04dc9d5b6da21e", size = 9605861, upload-time = "2026-02-20T21:51:16.066Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/d9/de11c0280f778d5fc571393aada7fe9b8bc1dd6a738f2e2c45702b8b3150/ty-0.0.18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d5e2fa8d45f57ca487a470e4bf66319c09b561150e98ae2a6b1a97ef04c1a4eb", size = 10092701, upload-time = "2026-02-20T21:51:26.862Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/94/068d4d591d791041732171e7b63c37a54494b2e7d28e88d2167eaa9ad875/ty-0.0.18-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d75652e9e937f7044b1aca16091193e7ef11dac1c7ec952b7fb8292b7ba1f5f2", size = 10109203, upload-time = "2026-02-20T21:51:11.59Z" },
-    { url = "https://files.pythonhosted.org/packages/34/e4/526a4aa56dc0ca2569aaa16880a1ab105c3b416dd70e87e25a05688999f3/ty-0.0.18-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:563c868edceb8f6ddd5e91113c17d3676b028f0ed380bdb3829b06d9beb90e58", size = 10614200, upload-time = "2026-02-20T21:51:20.298Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/3d/b68ab20a34122a395880922587fbfc3adf090d22e0fb546d4d20fe8c2621/ty-0.0.18-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:502e2a1f948bec563a0454fc25b074bf5cf041744adba8794d024277e151d3b0", size = 11153232, upload-time = "2026-02-20T21:51:14.121Z" },
-    { url = "https://files.pythonhosted.org/packages/68/ea/678243c042343fcda7e6af36036c18676c355878dcdcd517639586d2cf9e/ty-0.0.18-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cc881dea97021a3aa29134a476937fd8054775c4177d01b94db27fcfb7aab65b", size = 10832934, upload-time = "2026-02-20T21:51:32.92Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/bd/7f8d647cef8b7b346c0163230a37e903c7461c7248574840b977045c77df/ty-0.0.18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:421fcc3bc64cab56f48edb863c7c1c43649ec4d78ff71a1acb5366ad723b6021", size = 10700888, upload-time = "2026-02-20T21:51:09.673Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/06/cb3620dc48c5d335ba7876edfef636b2f4498eff4a262ff90033b9e88408/ty-0.0.18-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0fe5038a7136a0e638a2fb1ad06e3d3c4045314c6ba165c9c303b9aeb4623d6c", size = 10078965, upload-time = "2026-02-20T21:51:07.678Z" },
-    { url = "https://files.pythonhosted.org/packages/60/27/c77a5a84533fa3b685d592de7b4b108eb1f38851c40fac4e79cc56ec7350/ty-0.0.18-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:d123600a52372677613a719bbb780adeb9b68f47fb5f25acb09171de390e0035", size = 10134659, upload-time = "2026-02-20T21:51:18.311Z" },
-    { url = "https://files.pythonhosted.org/packages/43/6e/60af6b88c73469e628ba5253a296da6984e0aa746206f3034c31f1a04ed1/ty-0.0.18-py3-none-musllinux_1_2_i686.whl", hash = "sha256:bb4bc11d32a1bf96a829bf6b9696545a30a196ac77bbc07cc8d3dfee35e03723", size = 10297494, upload-time = "2026-02-20T21:51:39.631Z" },
-    { url = "https://files.pythonhosted.org/packages/33/90/612dc0b68224c723faed6adac2bd3f930a750685db76dfe17e6b9e534a83/ty-0.0.18-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:dda2efbf374ba4cd704053d04e32f2f784e85c2ddc2400006b0f96f5f7e4b667", size = 10791944, upload-time = "2026-02-20T21:51:37.13Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/da/f4ada0fd08a9e4138fe3fd2bcd3797753593f423f19b1634a814b9b2a401/ty-0.0.18-py3-none-win32.whl", hash = "sha256:c5768607c94977dacddc2f459ace6a11a408a0f57888dd59abb62d28d4fee4f7", size = 9677964, upload-time = "2026-02-20T21:51:42.039Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/fa/090ed9746e5c59fc26d8f5f96dc8441825171f1f47752f1778dad690b08b/ty-0.0.18-py3-none-win_amd64.whl", hash = "sha256:b78d0fa1103d36fc2fce92f2092adace52a74654ab7884d54cdaec8eb5016a4d", size = 10636576, upload-time = "2026-02-20T21:51:29.159Z" },
-    { url = "https://files.pythonhosted.org/packages/92/4f/5dd60904c8105cda4d0be34d3a446c180933c76b84ae0742e58f02133713/ty-0.0.18-py3-none-win_arm64.whl", hash = "sha256:01770c3c82137c6b216aa3251478f0b197e181054ee92243772de553d3586398", size = 10095449, upload-time = "2026-02-20T21:51:34.914Z" },
+    { url = "https://files.pythonhosted.org/packages/36/70/edf38bb37517531681d1c37f5df64744e5ad02673c02eb48447eae4bea08/ty-0.0.21-py3-none-linux_armv6l.whl", hash = "sha256:7bdf2f572378de78e1f388d24691c89db51b7caf07cf90f2bfcc1d6b18b70a76", size = 10299222, upload-time = "2026-03-06T01:57:16.64Z" },
+    { url = "https://files.pythonhosted.org/packages/72/62/0047b0bd19afeefbc7286f20a5f78a2aa39f92b4d89853f0d7185ab89edc/ty-0.0.21-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7e9613994610431ab8625025bd2880dbcb77c5c9fabdd21134cda12d840a529d", size = 10130513, upload-time = "2026-03-06T01:57:29.93Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/20/0b93a9e91aaed23155780258cdfdb4726ef68b6985378ac069bc427291a0/ty-0.0.21-py3-none-macosx_11_0_arm64.whl", hash = "sha256:56d3b198b64dd0a19b2b66e257deaed2ecea568e722ae5352f3c6fb62027f89d", size = 9605425, upload-time = "2026-03-06T01:57:27.115Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/fd/9945e2fa2996a1287b1e1d7ce050e97e1f420233b271e770934bfa0880a0/ty-0.0.21-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d23d2c34f7a77d974bb08f0860ef700addc8a683d81a0319f71c08f87506cfd0", size = 10108298, upload-time = "2026-03-06T01:57:35.429Z" },
+    { url = "https://files.pythonhosted.org/packages/52/e7/4ec52fcb15f3200826c9f048472c062549a05b0d1ef0b51f32d527b513c4/ty-0.0.21-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:56b01fd2519637a4ca88344f61c96225f540c98ff18bca321d4eaa7bb0f7aa2f", size = 10121556, upload-time = "2026-03-06T01:57:03.242Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/c0/ad457be2a8abea0f25549598bd098554540ced66229488daa0d558dad3c8/ty-0.0.21-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e9de7e11c63c6afc40f3e9ba716374add171aee7fabc70b5146a510705c6d41b", size = 10603264, upload-time = "2026-03-06T01:56:52.134Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/5b/2ecc7a2175243a4bcb72f5298ae41feabbb93b764bb0dc45722f3752c2c2/ty-0.0.21-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:62f7f5b235c4f7876db305c36997aea07b7af29b1a068f373d0e2547e25f32ff", size = 11196428, upload-time = "2026-03-06T01:57:32.94Z" },
+    { url = "https://files.pythonhosted.org/packages/37/f5/aff507d6a901f328ef96a298032b0c11aaaf950a146ed7dd3b5bf2cd3acf/ty-0.0.21-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ee8399f7c453a425291e6688efe430cfae7ab0ac4ffd50eba9f872bf878b54f6", size = 10866355, upload-time = "2026-03-06T01:56:57.831Z" },
+    { url = "https://files.pythonhosted.org/packages/be/30/822bbcb92d55b65989aa7ed06d9585f28ade9c9447369194ed4b0fb3b5b9/ty-0.0.21-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:210e7568c9f886c4d01308d751949ee714ad7ad9d7d928d2ba90d329dd880367", size = 10738177, upload-time = "2026-03-06T01:57:11.256Z" },
+    { url = "https://files.pythonhosted.org/packages/57/cc/46e7991b6469e93ac2c7e533a028983e402485580150ac864c56352a3a82/ty-0.0.21-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:53508e345b11569f78b21ba8e2b4e61df38a9754947fb3cd9f2ef574367338fb", size = 10079158, upload-time = "2026-03-06T01:57:00.516Z" },
+    { url = "https://files.pythonhosted.org/packages/15/c2/0bbdadfbd008240f8f1a87dc877433cb3884436097926107ccf06e618199/ty-0.0.21-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:553e43571f4a35604c36cfd07d8b61a5eb7a714e3c67f8c4ff2cf674fefbaef9", size = 10150535, upload-time = "2026-03-06T01:57:08.815Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/b5/2dbdb7b57b5362200ef0a39738ebd31331726328336def0143ac097ee59d/ty-0.0.21-py3-none-musllinux_1_2_i686.whl", hash = "sha256:666f6822e3b9200abfa7e95eb0ddd576460adb8d66b550c0ad2c70abc84a2048", size = 10319803, upload-time = "2026-03-06T01:57:19.106Z" },
+    { url = "https://files.pythonhosted.org/packages/72/84/70e52c0b7abc7c2086f9876ef454a73b161d3125315536d8d7e911c94ca4/ty-0.0.21-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:a0854d008347ce4a5fb351af132f660a390ab2a1163444d075251d43e6f74b9b", size = 10826239, upload-time = "2026-03-06T01:57:21.727Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/8a/1f72480fd013bbc6cd1929002abbbcde9a0b08ead6a15154de9d7f7fa37e/ty-0.0.21-py3-none-win32.whl", hash = "sha256:bef3ab4c7b966bcc276a8ac6c11b63ba222d21355b48d471ea782c4104eee4e0", size = 9693196, upload-time = "2026-03-06T01:57:24.126Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/f8/1104808b875c26c640e536945753a78562d606bef4e241d9dbf3d92477f6/ty-0.0.21-py3-none-win_amd64.whl", hash = "sha256:a709d576e5bea84b745d43058d8b9cd4f27f74a0b24acb4b0cbb7d3d41e0d050", size = 10668660, upload-time = "2026-03-06T01:56:55.06Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/b8/25e0adc404bbf986977657b25318991f93097b49f8aea640d93c0b0db68e/ty-0.0.21-py3-none-win_arm64.whl", hash = "sha256:f72047996598ac20553fb7e21ba5741e3c82dee4e9eadf10d954551a5fe09391", size = 10104161, upload-time = "2026-03-06T01:57:06.072Z" },
 ]

 [[package]]
@@ -1264,7 +1264,7 @@ wheels = [

 [[package]]
 name = "zensical"
-version = "0.0.23"
+version = "0.0.26"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "click" },
@@ -1274,18 +1274,18 @@ dependencies = [
    { name = "pymdown-extensions" },
    { name = "pyyaml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a3/ab/a65452b4e769552fd5a78c4996d6cf322630d896ddfd55c5433d96485e8b/zensical-0.0.23.tar.gz", hash = "sha256:5c4fc3aaf075df99d8cf41b9f2566e4d588180d9a89493014d3607dfe50ac4bc", size = 3822451, upload-time = "2026-02-11T21:24:38.373Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d5/1f/0a0b1ce8e0553a9dabaedc736d0f34b11fc33d71ff46bce44d674996d41f/zensical-0.0.26.tar.gz", hash = "sha256:f4d9c8403df25fbb3d6dd9577122dc2f23c73a2d16ab778bb7d40370dd71e987", size = 3841473, upload-time = "2026-03-11T09:51:38.838Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/66/86/035aa02bd36d26a03a1885bc22a73d4fe61ba0e21d0033cc42baf13d24f6/zensical-0.0.23-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:35d6d3eb803fe73a67187a1a25443408bd02a8dd50e151f4a4bafd40de3f0928", size = 12242966, upload-time = "2026-02-11T21:24:05.894Z" },
-    { url = "https://files.pythonhosted.org/packages/be/68/335dfbb7efc972964f0610736a0ad243dd8a5dcc2ec76b9ddb84c847a4a4/zensical-0.0.23-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:5973267460a190f348f24d445ff0c01e8ed334fd075947687b305e68257f6b18", size = 12125173, upload-time = "2026-02-11T21:24:08.507Z" },
-    { url = "https://files.pythonhosted.org/packages/25/9c/d567da04fbeb077df5cf06a94f947af829ebef0ff5ca7d0ba4910a6cbdf6/zensical-0.0.23-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:953adf1f0b346a6c65fc6e05e6cc1c38a6440fec29c50c76fb29700cc1927006", size = 12489636, upload-time = "2026-02-11T21:24:10.91Z" },
-    { url = "https://files.pythonhosted.org/packages/fe/6e/481a3ecf8a7b63a35c67f5be1ea548185d55bb1dacead54f76a9550197b2/zensical-0.0.23-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:49c1cbd6131dafa056be828e081759184f9b8dd24b99bf38d1e77c8c31b0c720", size = 12421313, upload-time = "2026-02-11T21:24:13.9Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/aa/a95481547f708432636f5f8155917c90d877c244c62124a084f7448b60b2/zensical-0.0.23-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f5b7fe22c5d33b2b91899c5df7631ad4ce9cccfabac2560cc92ba73eafe2d297", size = 12761031, upload-time = "2026-02-11T21:24:17.016Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/9f/ce1c5af9afd11fe3521a90441aba48c484f98730c6d833d69ee4387ae2e9/zensical-0.0.23-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9a3679d6bf6374f503afb74d9f6061da5de83c25922f618042b63a30b16f0389", size = 12527415, upload-time = "2026-02-11T21:24:19.558Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/b8/13a5d4d99f3b77e7bf4e791ef991a611ca2f108ed7eddf20858544ab0a91/zensical-0.0.23-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:54d981e21a19c3dcec6e7fa77c4421db47389dfdff20d29fea70df8e1be4062e", size = 12665352, upload-time = "2026-02-11T21:24:22.703Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/84/3d0a187ed941826ca26b19a661c41685d8017b2a019afa0d353eb2ebbdba/zensical-0.0.23-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:afde7865cc3c79c99f6df4a911d638fb2c3b472a1b81367d47163f8e3c36f910", size = 12689042, upload-time = "2026-02-11T21:24:26.118Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/65/12466408f428f2cf7140b32d484753db0891debae3c956f4c076b51eeb17/zensical-0.0.23-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:c484674d7b0a3e6d39db83914db932249bccdef2efaf8a5669671c66c16f584d", size = 12834779, upload-time = "2026-02-11T21:24:28.788Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/ab/0771ac6ffb30e4f04c20374e3beca9e71c3f81112219cdbd86cdc0e3d337/zensical-0.0.23-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:927d12fe2851f355fb3206809e04641d6651bdd2ff4afe9c205721aa3a32aa82", size = 12797057, upload-time = "2026-02-11T21:24:31.383Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/ce/fbd45c00a1cba15508ea3c29b121b4be010254eb65c1512bf11f4478496c/zensical-0.0.23-cp310-abi3-win32.whl", hash = "sha256:ffb79db4244324e9cc063d16adff25a40b145153e5e76d75e0012ba3c05af25d", size = 11837823, upload-time = "2026-02-11T21:24:33.869Z" },
-    { url = "https://files.pythonhosted.org/packages/37/82/0aebaa8e7d2e6314a85d9b7ff3f7fc74837a94086b56a9d5d8f2240e9b9c/zensical-0.0.23-cp310-abi3-win_amd64.whl", hash = "sha256:a8cfe240dca75231e8e525985366d010d09ee73aec0937930e88f7230694ce01", size = 12036837, upload-time = "2026-02-11T21:24:36.163Z" },
+    { url = "https://files.pythonhosted.org/packages/41/58/fa3d9538ff1ea8cf4a193edbf47254f374fa7983fcfa876bb4336d72c53a/zensical-0.0.26-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:7823b25afe7d36099253aa59d643abaac940f80fd015d4a37954210c87d3da56", size = 12263607, upload-time = "2026-03-11T09:50:49.202Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/6e/44a3b21bd3569b9cad203364d73a956768d28a879e4c2be91bd889f74d2c/zensical-0.0.26-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:c0254814382cdd3769bc7689180d09bf41de8879871dd736dc52d5f141e8ada7", size = 12144562, upload-time = "2026-03-11T09:50:53.685Z" },
+    { url = "https://files.pythonhosted.org/packages/07/ae/31b9885745b3e7ef23a3ae7f175b879807288d11b3fb7e2d3c119c916258/zensical-0.0.26-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1c8e601b2bbd239e564b04cf235eefb9777e7dfc7e1857b8871d6cdcfb577aa0", size = 12506728, upload-time = "2026-03-11T09:50:57.775Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/93/f5291e2c47076474f181f6eef35ef0428117d3f192da4358c0511e2ce09e/zensical-0.0.26-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:2dc43c7e6c25d9724fc0450f0273ca4e5e2506eeb7f89f52f1405a592896ca3b", size = 12454975, upload-time = "2026-03-11T09:51:01.514Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/2e/61cac4f2ebad31dab768eb02753ffde9e56d4d34b8f876b949bf516fbd50/zensical-0.0.26-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:24ed236d1254cc474c19227eaa3670a1ccf921af53134ec5542b05853bdcd59c", size = 12791930, upload-time = "2026-03-11T09:51:05.162Z" },
+    { url = "https://files.pythonhosted.org/packages/02/86/51995d1ed2dd6ad8a1a70bcdf3c5eb16b50e62ea70e638d454a6b9061c4d/zensical-0.0.26-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1110147710d1dd025d932c4a7eada836bdf079c91b70fb0ae5b202e14b094617", size = 12548166, upload-time = "2026-03-11T09:51:09.218Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/93/decbafdbfc77170cbc3851464632390846e9aaf45e743c8dd5a24d5673e9/zensical-0.0.26-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7d21596a785428cdebc20859bd94a05334abe14ad24f1bb9cd80d19219e3c220", size = 12682103, upload-time = "2026-03-11T09:51:12.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/e2/391d2d08dde621177da069a796a886b549fefb15734aeeb6e696af99b662/zensical-0.0.26-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:680a3c7bb71499b4da784d6072e44b3d7b8c0df3ce9bbd9974e24bd8058c2736", size = 12724219, upload-time = "2026-03-11T09:51:17.32Z" },
+    { url = "https://files.pythonhosted.org/packages/80/2a/21b40c5c40a67da8a841f278d61dbd8d5e035e489de6fe1cef5f4e211b4f/zensical-0.0.26-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:e3294a79f98218b6fc2219232e166aa0932ae4dad58f6c8dbc0dbe0ecbff9c25", size = 12862117, upload-time = "2026-03-11T09:51:22.161Z" },
+    { url = "https://files.pythonhosted.org/packages/51/76/e1910d6d75d207654c867b8efbda6822dedda9fed3601bf4a864a1f4fe26/zensical-0.0.26-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:630229587df1fb47be184a4a69d0772ce59a44cd2c481ae9f7e8852fffaff11e", size = 12815714, upload-time = "2026-03-11T09:51:26.24Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/eb/34b042542cd949192535f8bac172d33b3da5a0ec0853eed008a6ad3242e3/zensical-0.0.26-cp310-abi3-win32.whl", hash = "sha256:e0756581541aad2e63dd8b4abae47e6ff12229a474b4eede5b4da5cc183c5101", size = 11856425, upload-time = "2026-03-11T09:51:31.087Z" },
+    { url = "https://files.pythonhosted.org/packages/92/a5/30f6a88bb125c2bbeae3ae80a0812131614ab30e9b0b199d75d4199e5b66/zensical-0.0.26-cp310-abi3-win_amd64.whl", hash = "sha256:9ca07f5c75b5eac4d273d887100bbccd6eb8ba4959c904e2ab61971a0017c172", size = 12059895, upload-time = "2026-03-11T09:51:35.226Z" },
 ]
--- a/zensical.toml
+++ b/zensical.toml
@@ -77,6 +77,10 @@ md_in_html = {}
 "pymdownx.tasklist" = {custom_checkbox = true}
 "pymdownx.tilde" = {}

+[project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
+
 [project.markdown_extensions."pymdownx.highlight"]
 anchor_linenums = true
 line_spans = "__span"
@@ -95,3 +99,49 @@ permalink = true
 [project.markdown_extensions."pymdownx.snippets"]
 base_path = ["."]
 check_paths = true
+
+[[project.nav]]
+Home = "index.md"
+
+[[project.nav]]
+Modules = [
+    {CLI = "module/cli.md"},
+    {CRUD = "module/crud.md"},
+    {Database = "module/db.md"},
+    {Dependencies = "module/dependencies.md"},
+    {Exceptions = "module/exceptions.md"},
+    {Fixtures = "module/fixtures.md"},
+    {Logger = "module/logger.md"},
+    {Metrics = "module/metrics.md"},
+    {Models = "module/models.md"},
+    {Pytest = "module/pytest.md"},
+    {Schemas = "module/schemas.md"},
+]
+
+[[project.nav]]
+Reference = [
+    {CLI = "reference/cli.md"},
+    {CRUD = "reference/crud.md"},
+    {Database = "reference/db.md"},
+    {Dependencies = "reference/dependencies.md"},
+    {Exceptions = "reference/exceptions.md"},
+    {Fixtures = "reference/fixtures.md"},
+    {Logger = "reference/logger.md"},
+    {Metrics = "reference/metrics.md"},
+    {Models = "reference/models.md"},
+    {Pytest = "reference/pytest.md"},
+    {Schemas = "reference/schemas.md"},
+]
+
+[[project.nav]]
+Examples = [
+    {"Pagination & Search" = "examples/pagination-search.md"},
+]
+
+[[project.nav]]
+Migration = [
+    {"v2.0" = "migration/v2.md"},
+]
+
+[[project.nav]]
+"Changelog ↗" = "https://github.com/d3vyce/fastapi-toolsets/releases"
Author	SHA1	Message	Date
d3vyce	1a863b7032	fix: add tests	2026-03-14 07:04:29 -04:00
d3vyce	aca6dd298a	docs: unified paginate() endpoint	2026-03-14 06:53:28 -04:00
d3vyce	2e7f879544	feat: unified paginate() endpoint with typed pagination responses	2026-03-14 06:47:03 -04:00
d3vyce	19232d3436	feat: add AsyncCrud subclass style and base_class param to CrudFactory (#132 )	2026-03-12 22:46:51 +01:00
d3vyce	1eafcb3873	Version 2.2.1	2026-03-12 15:39:44 -04:00
dependabot[bot]	0d67fbb58d	⬆ Bump ty from 0.0.20 to 0.0.21 (#127 ) * ⬆ Bump ty from 0.0.20 to 0.0.21 Bumps [ty](https://github.com/astral-sh/ty) from 0.0.20 to 0.0.21. - [Release notes](https://github.com/astral-sh/ty/releases) - [Changelog](https://github.com/astral-sh/ty/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ty/compare/0.0.20...0.0.21) --- updated-dependencies: - dependency-name: ty dependency-version: 0.0.21 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> * fix: ty warnings --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: d3vyce <nicolas.sudres@proton.me>	2026-03-12 20:29:02 +01:00
dependabot[bot]	a59f098930	⬆ Bump zensical from 0.0.24 to 0.0.26 (#126 ) Bumps [zensical](https://github.com/zensical/zensical) from 0.0.24 to 0.0.26. - [Release notes](https://github.com/zensical/zensical/releases) - [Commits](https://github.com/zensical/zensical/compare/v0.0.24...v0.0.26) --- updated-dependencies: - dependency-name: zensical dependency-version: 0.0.26 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-12 20:22:02 +01:00
dependabot[bot]	96e34ba8af	⬆ Bump ruff from 0.15.4 to 0.15.5 (#128 ) Bumps [ruff](https://github.com/astral-sh/ruff) from 0.15.4 to 0.15.5. - [Release notes](https://github.com/astral-sh/ruff/releases) - [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ruff/compare/0.15.4...0.15.5) --- updated-dependencies: - dependency-name: ruff dependency-version: 0.15.5 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-12 20:21:50 +01:00
d3vyce	26d649791f	feat: auto-include primary key in CrudFactory searchable_fields (#130 )	2026-03-12 20:21:32 +01:00
d3vyce	dde5183e68	Version 2.2.0	2026-03-10 14:53:55 -04:00
d3vyce	e4250a9910	feat: bring first() to parity with get()/get_or_none() — add with_for_update and schema support (#123 )	2026-03-10 19:34:18 +01:00
d3vyce	4800941934	fix: cascade delete M2M association rows via ORM session (#121 )	2026-03-10 19:18:16 +01:00
d3vyce	0cc21d2012	Version 2.1.0	2026-03-09 12:45:52 -04:00
d3vyce	a3245d50f0	docs: clarify metrics module usage (#117 )	2026-03-09 17:17:11 +01:00
d3vyce	baebf022f6	feat: move db related function from pytest to db module (#119 )	2026-03-09 17:15:50 +01:00
dependabot[bot]	96d445e3f3	⬆ Bump zensical from 0.0.23 to 0.0.24 (#112 ) Bumps [zensical](https://github.com/zensical/zensical) from 0.0.23 to 0.0.24. - [Release notes](https://github.com/zensical/zensical/releases) - [Commits](https://github.com/zensical/zensical/compare/v0.0.23...v0.0.24) --- updated-dependencies: - dependency-name: zensical dependency-version: 0.0.24 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-05 14:57:58 +01:00
dependabot[bot]	80306e1af3	⬆ Bump ruff from 0.15.2 to 0.15.4 (#113 ) Bumps [ruff](https://github.com/astral-sh/ruff) from 0.15.2 to 0.15.4. - [Release notes](https://github.com/astral-sh/ruff/releases) - [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ruff/compare/0.15.2...0.15.4) --- updated-dependencies: - dependency-name: ruff dependency-version: 0.15.4 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-05 14:57:48 +01:00
dependabot[bot]	fd999b63f1	⬆ Bump ty from 0.0.18 to 0.0.20 (#114 ) Bumps [ty](https://github.com/astral-sh/ty) from 0.0.18 to 0.0.20. - [Release notes](https://github.com/astral-sh/ty/releases) - [Changelog](https://github.com/astral-sh/ty/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ty/compare/0.0.18...0.0.20) --- updated-dependencies: - dependency-name: ty dependency-version: 0.0.20 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-05 14:57:37 +01:00
dependabot[bot]	c0f352b914	⬆ Bump fastapi from 0.133.1 to 0.135.1 (#115 ) Bumps [fastapi](https://github.com/fastapi/fastapi) from 0.133.1 to 0.135.1. - [Release notes](https://github.com/fastapi/fastapi/releases) - [Commits](https://github.com/fastapi/fastapi/compare/0.133.1...0.135.1) --- updated-dependencies: - dependency-name: fastapi dependency-version: 0.135.1 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-03-05 14:57:26 +01:00
d3vyce	c4c760484b	Version 2.0.0	2026-03-04 11:20:46 -05:00
d3vyce	432e0722e0	refactor: remove deprecated parameter and function/cleanup code (#101 ) * refactor: remove deprecated parameter and function * refactor: centralize type aliases in types.py and simplify crud layer * test: add missing tests for fixtures/utils.py * refactor: simplify and deduplicate across crud, metrics, cli, and exceptions * docs: fix old Paginate references * docs: add migration + fix icon * docs: update README/migration to v2	2026-03-04 17:19:38 +01:00
d3vyce	e732e54518	feat: add models module (#109 ) * feat: add models module * docs: add models module	2026-03-04 15:14:55 +01:00
d3vyce	05b5a2c876	feat: rework Exception/ApiError (#107 ) * feat: rework Exception/ApiError * docs: update exceptions module * fix: docstring	2026-03-02 16:34:29 +01:00
d3vyce	4a020c56d1	feat: Raise NotFoundError instead of LookupError in wait_for_row_change (#105 )	2026-03-02 14:28:37 +01:00