Version 1.3.0

* feat: add sort_params helper in CrudFactory

* docs: add sorting

* fix: change sort_by to order_by

README.md

@@ -44,7 +44,7 @@ uv add "fastapi-toolsets[all]"
 
 ### Core
 
-- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in search with relationship traversal
+- **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

docs/examples/pagination-search.md

@@ -0,0 +1,134 @@
+# Pagination & search
+
+This example builds an articles listing endpoint that supports **offset pagination**, **cursor pagination**, **full-text search**, **faceted filtering**, and **sorting** — all from a single `CrudFactory` definition.
+
+## Models
+
+```python title="models.py"
+--8<-- "docs_src/examples/pagination_search/models.py"
+```
+
+## Schemas
+
+```python title="schemas.py"
+--8<-- "docs_src/examples/pagination_search/schemas.py"
+```
+
+## Crud
+
+Declare `searchable_fields`, `facet_fields`, and `order_fields` once on [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory). All endpoints built from this class share the same defaults and can override them per call.
+
+```python title="crud.py"
+--8<-- "docs_src/examples/pagination_search/crud.py"
+```
+
+## Session dependency
+
+```python title="db.py"
+--8<-- "docs_src/examples/pagination_search/db.py"
+```
+
+!!! info "Deploy a Postgres DB with docker"
+    ```bash
+    docker run -d --name postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres -p 5432:5432 postgres:18-alpine
+    ```
+
+
+## App
+
+```python title="app.py"
+--8<-- "docs_src/examples/pagination_search/app.py"
+```
+
+
+## Routes
+### 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"
+```
+
+**Example request**
+
+```
+GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&order_by=title&order=asc
+```
+
+**Example response**
+
+```json
+{
+  "status": "SUCCESS",
+  "data": [
+    { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
+  ],
+  "pagination": {
+    "total_count": 42,
+    "page": 2,
+    "items_per_page": 10,
+    "has_more": true
+  },
+  "filter_attributes": {
+    "status": ["archived", "draft", "published"],
+    "name": ["backend", "frontend", "python"]
+  }
+}
+```
+
+`filter_attributes` always reflects the values visible **after** applying the active filters. Use it to populate filter dropdowns on the client.
+
+### Cursor pagination
+
+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"
+```
+
+**Example request**
+
+```
+GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&order=desc
+```
+
+**Example response**
+
+```json
+{
+  "status": "SUCCESS",
+  "data": [
+    { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
+  ],
+  "pagination": {
+    "next_cursor": "eyJ2YWx1ZSI6ICIzZjQ3YWM2OS0uLi4ifQ==",
+    "prev_cursor": null,
+    "items_per_page": 10,
+    "has_more": true
+  },
+  "filter_attributes": {
+    "status": ["published"],
+    "name": ["backend", "python"]
+  }
+}
+```
+
+Pass `next_cursor` as the `cursor` query parameter on the next request to advance to the next page.
+
+## Search behaviour
+
+Both endpoints inherit the same `searchable_fields` declared on `ArticleCrud`:
+
+Search is **case-insensitive** and uses a `LIKE %query%` pattern. Pass a [`SearchConfig`](../reference/crud.md#fastapi_toolsets.crud.search.SearchConfig) instead of a plain string to control case sensitivity or switch to `match_mode="all"` (AND across all fields instead of OR).
+
+```python
+from fastapi_toolsets.crud import SearchConfig
+
+# Both title AND body must contain "fastapi"
+result = await ArticleCrud.offset_paginate(
+    session,
+    search=SearchConfig(query="fastapi", case_sensitive=True, match_mode="all"),
+    search_fields=[Article.title, Article.body],
+)
+```

docs/index.md

@@ -44,7 +44,7 @@ uv add "fastapi-toolsets[all]"
 
 ### Core
 
-- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in search with relationship traversal
+- **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

docs/module/crud.md

@@ -148,6 +148,16 @@ The cursor column is set once on [`CrudFactory`](../reference/crud.md#fastapi_to
 !!! note
     `cursor_column` is required. Calling [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate) on a CRUD class that has no `cursor_column` configured raises a `ValueError`.
 
+The cursor value is base64-encoded when returned to the client and decoded back to the correct Python type on the next request. The following SQLAlchemy column types are supported:
+
+| SQLAlchemy type | Python type |
+|---|---|
+| `Integer`, `BigInteger`, `SmallInteger` | `int` |
+| `Uuid` | `uuid.UUID` |
+| `DateTime` | `datetime.datetime` |
+| `Date` | `datetime.date` |
+| `Float`, `Numeric` | `decimal.Decimal` |
+
 ```python
 # Paginate by the primary key
 PostCrud = CrudFactory(model=Post, cursor_column=Post.id)
@@ -158,7 +168,19 @@ PostCrud = CrudFactory(model=Post, cursor_column=Post.created_at)
 
 ## Search
 
-Declare searchable fields on the CRUD class. Relationship traversal is supported via tuples:
+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).
+
+| | Full-text search | Faceted search |
+|---|---|---|
+| Input | Free-text string | Exact column values |
+| Relationship support | Yes | Yes |
+| Use case | Search bars | Filter dropdowns |
+
+!!! info "You can use both search strategies in the same endpoint!"
+
+### Full-text search
+
+Declare `searchable_fields` on the CRUD class. Relationship traversal is supported via tuples:
 
 ```python
 PostCrud = CrudFactory(
@@ -171,6 +193,15 @@ PostCrud = CrudFactory(
 )
 ```
 
+You can override `searchable_fields` per call with `search_fields`:
+
+```python
+result = await UserCrud.offset_paginate(
+    session=session,
+    search_fields=[User.country],
+)
+```
+
 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
@@ -211,6 +242,141 @@ async def get_users(
     )
 ```
 
+### Faceted search
+
+!!! info "Added in `v1.2`"
+
+Declare `facet_fields` on the CRUD class to return distinct column values alongside paginated results. This is useful for populating filter dropdowns or building faceted search UIs.
+
+Facet fields use the same syntax as `searchable_fields` — direct columns or relationship tuples:
+
+```python
+UserCrud = CrudFactory(
+    model=User,
+    facet_fields=[
+        User.status,
+        User.country,
+        (User.role, Role.name),  # value from a related model
+    ],
+)
+```
+
+You can override `facet_fields` per call:
+
+```python
+result = await UserCrud.offset_paginate(
+    session=session,
+    facet_fields=[User.country],
+)
+```
+
+The distinct values are returned in the `filter_attributes` field of [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse):
+
+```json
+{
+  "status": "SUCCESS",
+  "data": ["..."],
+  "pagination": { "..." },
+  "filter_attributes": {
+    "status": ["active", "inactive"],
+    "country": ["DE", "FR", "US"],
+    "name": ["admin", "editor", "viewer"]
+  }
+}
+```
+
+Use `filter_by` to pass the client's chosen filter values directly — no need to build SQLAlchemy conditions by hand. Any unknown key raises [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError).
+
+!!! info "The keys in `filter_by` are the same keys the client received in `filter_attributes`."
+    Keys are normally the terminal `column.key` (e.g. `"name"` for `Role.name`). When two facet fields share the same column key (e.g. `(Build.project, Project.name)` and `(Build.os, Os.name)`), the relationship name is prepended automatically: `"project__name"` and `"os__name"`.
+
+`filter_by` and `filters` can be combined — both are applied with AND logic.
+
+Use [`filter_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.filter_params) to generate a dict with the facet filter values from the query parameters:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+
+UserCrud = CrudFactory(
+    model=User,
+    facet_fields=[User.status, User.country, (User.role, Role.name)],
+)
+
+@router.get("", response_model_exclude_none=True)
+async def list_users(
+    session: SessionDep,
+    page: int = 1,
+    filter_by: Annotated[dict[str, list[str]], Depends(UserCrud.filter_params())],
+) -> PaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(
+        session=session,
+        page=page,
+        filter_by=filter_by,
+    )
+```
+
+Both single-value and multi-value query parameters work:
+
+```
+GET /users?status=active              → filter_by={"status": ["active"]}
+GET /users?status=active&country=FR   → filter_by={"status": ["active"], "country": ["FR"]}
+GET /users?role=admin&role=editor     → filter_by={"role": ["admin", "editor"]}  (IN clause)
+```
+
+## Sorting
+
+!!! info "Added in `v1.3`"
+
+Declare `order_fields` on the CRUD class to expose client-driven column ordering via `order_by` and `order` query parameters.
+
+```python
+UserCrud = CrudFactory(
+    model=User,
+    order_fields=[
+        User.name,
+        User.created_at,
+    ],
+)
+```
+
+Call [`order_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.order_params) to generate a FastAPI dependency that maps the query parameters to an [`OrderByClause`](../reference/crud.md#fastapi_toolsets.crud.factory.OrderByClause) expression:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi_toolsets.crud import OrderByClause
+
+@router.get("")
+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)
+```
+
+The dependency adds two query parameters to the endpoint:
+
+| Parameter  | Type            |
+| ---------- | --------------- |
+| `order_by` | `str | null`   |
+| `order`    | `asc` or `desc` |
+
+```
+GET /users?order_by=name&order=asc   → ORDER BY users.name ASC
+GET /users?order_by=name&order=desc  → ORDER BY users.name DESC
+```
+
+An unknown `order_by` value raises [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) (HTTP 422).
+
+You can also pass `order_fields` directly to `order_params()` to override the class-level defaults without modifying them:
+
+```python
+UserOrderParams = UserCrud.order_params(order_fields=[User.name])
+```
+
 ## Relationship loading
 
 !!! info "Added in `v1.1`"
@@ -272,7 +438,7 @@ await UserCrud.upsert(
 )
 ```
 
-## `schema` — typed response serialization
+## Response serialization
 
 !!! info "Added in `v1.1`"
 

docs/module/exceptions.md

@@ -34,6 +34,7 @@ This registers handlers for:
 | [`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 |
 
 ```python
 from fastapi_toolsets.exceptions import NotFoundError

docs/module/schemas.md

@@ -22,7 +22,7 @@ async def get_user(user: User = UserDep) -> Response[UserSchema]:
 
 ### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
 
-Wraps a list of items with pagination metadata.
+Wraps a list of items with pagination metadata and optional facet values.
 
 ```python
 from fastapi_toolsets.schemas import PaginatedResponse, Pagination
@@ -40,6 +40,8 @@ async def list_users() -> PaginatedResponse[UserSchema]:
     )
 ```
 
+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)
 
 Returned automatically by the exceptions handler.

docs/reference/exceptions.md

@@ -12,6 +12,8 @@ from fastapi_toolsets.exceptions import (
     NotFoundError,
     ConflictError,
     NoSearchableFieldsError,
+    InvalidFacetFilterError,
+    InvalidOrderFieldError,
     generate_error_responses,
     init_exceptions_handlers,
 )
@@ -29,6 +31,10 @@ from fastapi_toolsets.exceptions import (
 
 ## ::: fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError
 
+## ::: fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError
+
+## ::: fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError
+
 ## ::: fastapi_toolsets.exceptions.exceptions.generate_error_responses
 
 ## ::: fastapi_toolsets.exceptions.handler.init_exceptions_handlers

docs_src/examples/pagination_search/app.py

@@ -0,0 +1,9 @@
+from fastapi import FastAPI
+
+from fastapi_toolsets.exceptions import init_exceptions_handlers
+
+from .routes import router
+
+app = FastAPI()
+init_exceptions_handlers(app=app)
+app.include_router(router=router)

docs_src/examples/pagination_search/crud.py

@@ -0,0 +1,21 @@
+from fastapi_toolsets.crud import CrudFactory
+
+from .models import Article, Category
+
+ArticleCrud = CrudFactory(
+    model=Article,
+    cursor_column=Article.created_at,
+    searchable_fields=[  # default fields for full-text search
+        Article.title,
+        Article.body,
+        (Article.category, Category.name),
+    ],
+    facet_fields=[  # fields exposed as filter dropdowns
+        Article.status,
+        (Article.category, Category.name),
+    ],
+    order_fields=[  # fields exposed for client-driven ordering
+        Article.title,
+        Article.created_at,
+    ],
+)

docs_src/examples/pagination_search/db.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from fastapi_toolsets.db import create_db_context, create_db_dependency
+
+DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/postgres"
+
+engine = create_async_engine(url=DATABASE_URL, future=True)
+async_session_maker = async_sessionmaker(bind=engine, expire_on_commit=False)
+
+get_db = create_db_dependency(session_maker=async_session_maker)
+get_db_context = create_db_context(session_maker=async_session_maker)
+
+
+SessionDep = Annotated[AsyncSession, Depends(get_db)]

docs_src/examples/pagination_search/models.py

@@ -0,0 +1,36 @@
+import datetime
+import uuid
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Category(Base):
+    __tablename__ = "categories"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(64), unique=True)
+
+    articles: Mapped[list["Article"]] = relationship(back_populates="category")
+
+
+class Article(Base):
+    __tablename__ = "articles"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    title: Mapped[str] = mapped_column(String(256))
+    body: Mapped[str] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(32))
+    published: Mapped[bool] = mapped_column(Boolean, default=False)
+    category_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("categories.id"), nullable=True
+    )
+
+    category: Mapped["Category | None"] = relationship(back_populates="articles")

docs_src/examples/pagination_search/routes.py

@@ -0,0 +1,59 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from fastapi_toolsets.crud import OrderByClause
+from fastapi_toolsets.schemas import PaginatedResponse
+
+from .crud import ArticleCrud
+from .db import SessionDep
+from .models import Article
+from .schemas import ArticleRead
+
+router = APIRouter(prefix="/articles")
+
+
+@router.get("/offset")
+async def list_articles_offset(
+    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)),
+    ],
+    page: int = Query(1, ge=1),
+    items_per_page: int = Query(20, ge=1, le=100),
+    search: str | None = None,
+) -> PaginatedResponse[ArticleRead]:
+    return await ArticleCrud.offset_paginate(
+        session=session,
+        page=page,
+        items_per_page=items_per_page,
+        search=search,
+        filter_by=filter_by or None,
+        order_by=order_by,
+        schema=ArticleRead,
+    )
+
+
+@router.get("/cursor")
+async def list_articles_cursor(
+    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)),
+    ],
+    cursor: str | None = None,
+    items_per_page: int = Query(20, ge=1, le=100),
+    search: str | None = None,
+) -> PaginatedResponse[ArticleRead]:
+    return await ArticleCrud.cursor_paginate(
+        session=session,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        search=search,
+        filter_by=filter_by or None,
+        order_by=order_by,
+        schema=ArticleRead,
+    )

docs_src/examples/pagination_search/schemas.py

@@ -0,0 +1,13 @@
+import datetime
+import uuid
+
+from fastapi_toolsets.schemas import PydanticBase
+
+
+class ArticleRead(PydanticBase):
+    id: uuid.UUID
+    created_at: datetime.datetime
+    title: str
+    status: str
+    published: bool
+    category_id: uuid.UUID | None

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fastapi-toolsets"
-version = "1.1.0"
+version = "1.3.0"
-description = "Reusable tools for FastAPI: async CRUD, fixtures, CLI, and standardized responses for SQLAlchemy + PostgreSQL"
+description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -11,7 +11,7 @@ authors = [
 ]
 keywords = ["fastapi", "sqlalchemy", "postgresql"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: AsyncIO",
     "Framework :: FastAPI",
     "Framework :: Pydantic",

src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"

src/fastapi_toolsets/cli/config.py

@@ -1,5 +1,7 @@
 """CLI configuration and dynamic imports."""
 
+from __future__ import annotations
+
 import importlib
 import sys
 from typing import TYPE_CHECKING, Any, Literal, overload

src/fastapi_toolsets/crud/__init__.py

@@ -1,17 +1,21 @@
 """Generic async CRUD operations for SQLAlchemy models."""
 
-from ..exceptions import NoSearchableFieldsError
+from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
-from .factory import CrudFactory, JoinType, M2MFieldType
+from .factory import CrudFactory, JoinType, M2MFieldType, OrderByClause
 from .search import (
+    FacetFieldType,
     SearchConfig,
     get_searchable_fields,
 )
 
 __all__ = [
     "CrudFactory",
+    "FacetFieldType",
     "get_searchable_fields",
+    "InvalidFacetFilterError",
     "JoinType",
     "M2MFieldType",
     "NoSearchableFieldsError",
+    "OrderByClause",
     "SearchConfig",
 ]

src/fastapi_toolsets/crud/factory.py

@@ -3,31 +3,45 @@
 from __future__ import annotations
 
 import base64
+import inspect
 import json
 import uuid as uuid_module
 import warnings
-from collections.abc import Mapping, Sequence
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from datetime import date, datetime
+from decimal import Decimal
 from typing import Any, ClassVar, Generic, Literal, Self, TypeVar, cast, overload
 
+from fastapi import Query
 from pydantic import BaseModel
-from sqlalchemy import Integer, Uuid, and_, func, select
+from sqlalchemy import Date, DateTime, Float, Integer, Numeric, Uuid, and_, func, select
 from sqlalchemy import delete as sql_delete
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
 from sqlalchemy.sql.base import ExecutableOption
+from sqlalchemy.sql.elements import ColumnElement
 from sqlalchemy.sql.roles import WhereHavingRole
 
 from ..db import get_transaction
-from ..exceptions import NotFoundError
+from ..exceptions import InvalidOrderFieldError, NotFoundError
 from ..schemas import CursorPagination, OffsetPagination, PaginatedResponse, Response
-from .search import SearchConfig, SearchFieldType, build_search_filters
+from .search import (
+    FacetFieldType,
+    SearchConfig,
+    SearchFieldType,
+    build_facets,
+    build_filter_by,
+    build_search_filters,
+    facet_keys,
+)
 
 ModelType = TypeVar("ModelType", bound=DeclarativeBase)
 SchemaType = TypeVar("SchemaType", bound=BaseModel)
 JoinType = list[tuple[type[DeclarativeBase], Any]]
 M2MFieldType = Mapping[str, QueryableAttribute[Any]]
+OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]
 
 
 def _encode_cursor(value: Any) -> str:
@@ -48,6 +62,8 @@ class AsyncCrud(Generic[ModelType]):
 
     model: ClassVar[type[DeclarativeBase]]
     searchable_fields: ClassVar[Sequence[SearchFieldType] | None] = None
+    facet_fields: ClassVar[Sequence[FacetFieldType] | None] = None
+    order_fields: ClassVar[Sequence[QueryableAttribute[Any]] | None] = None
     m2m_fields: ClassVar[M2MFieldType | None] = None
     default_load_options: ClassVar[list[ExecutableOption] | None] = None
     cursor_column: ClassVar[Any | None] = None
@@ -117,6 +133,109 @@ class AsyncCrud(Generic[ModelType]):
             return set()
         return set(cls.m2m_fields.keys())
 
+    @classmethod
+    def filter_params(
+        cls: type[Self],
+        *,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+    ) -> Callable[..., Awaitable[dict[str, list[str]]]]:
+        """Return a FastAPI dependency that collects facet filter values from query parameters.
+        Args:
+            facet_fields: Override the facet fields for this dependency. Falls back to the
+                class-level ``facet_fields`` if not provided.
+
+        Returns:
+            An async dependency function named ``{Model}FilterParams`` that resolves to a
+            ``dict[str, list[str]]`` containing only the keys that were supplied in the
+            request (absent/``None`` parameters are excluded).
+
+        Raises:
+            ValueError: If no facet fields are configured on this CRUD class and none are
+                provided via ``facet_fields``.
+        """
+        fields = facet_fields if facet_fields is not None else cls.facet_fields
+        if not fields:
+            raise ValueError(
+                f"{cls.__name__} has no facet_fields configured. "
+                "Pass facet_fields= or set them on CrudFactory."
+            )
+        keys = facet_keys(fields)
+
+        async def dependency(**kwargs: Any) -> dict[str, list[str]]:
+            return {k: v for k, v in kwargs.items() if v is not None}
+
+        dependency.__name__ = f"{cls.model.__name__}FilterParams"
+        dependency.__signature__ = inspect.Signature(  # type: ignore[attr-defined]
+            parameters=[
+                inspect.Parameter(
+                    k,
+                    inspect.Parameter.KEYWORD_ONLY,
+                    annotation=list[str] | None,
+                    default=Query(default=None),
+                )
+                for k in keys
+            ]
+        )
+
+        return dependency
+
+    @classmethod
+    def order_params(
+        cls: type[Self],
+        *,
+        order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+        default_field: QueryableAttribute[Any] | None = None,
+        default_order: Literal["asc", "desc"] = "asc",
+    ) -> Callable[..., Awaitable[OrderByClause | None]]:
+        """Return a FastAPI dependency that resolves order query params into an order_by clause.
+
+        Args:
+            order_fields: Override the allowed order fields. Falls back to the class-level
+                ``order_fields`` if not provided.
+            default_field: Field to order by when ``order_by`` query param is absent.
+                If ``None`` and no ``order_by`` is provided, no ordering is applied.
+            default_order: Default order direction when ``order`` is absent
+                (``"asc"`` or ``"desc"``).
+
+        Returns:
+            An async dependency function named ``{Model}OrderParams`` that resolves to an
+            ``OrderByClause`` (or ``None``). Pass it to ``Depends()`` in your route.
+
+        Raises:
+            ValueError: If no order fields are configured on this CRUD class and none are
+                provided via ``order_fields``.
+            InvalidOrderFieldError: When the request provides an unknown ``order_by`` value.
+        """
+        fields = order_fields if order_fields is not None else cls.order_fields
+        if not fields:
+            raise ValueError(
+                f"{cls.__name__} has no order_fields configured. "
+                "Pass order_fields= or set them on CrudFactory."
+            )
+        field_map: dict[str, QueryableAttribute[Any]] = {f.key: f for f in fields}
+        valid_keys = sorted(field_map.keys())
+
+        async def dependency(
+            order_by: str | None = Query(
+                None, description=f"Field to order by. Valid values: {valid_keys}"
+            ),
+            order: Literal["asc", "desc"] = Query(
+                default_order, description="Sort direction"
+            ),
+        ) -> OrderByClause | None:
+            if order_by is None:
+                if default_field is None:
+                    return None
+                field = default_field
+            elif order_by not in field_map:
+                raise InvalidOrderFieldError(order_by, valid_keys)
+            else:
+                field = field_map[order_by]
+            return field.asc() if order == "asc" else field.desc()
+
+        dependency.__name__ = f"{cls.model.__name__}OrderParams"
+        return dependency
+
     @overload
     @classmethod
     async def create(  # pragma: no cover
@@ -356,7 +475,7 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         limit: int | None = None,
         offset: int | None = None,
     ) -> Sequence[ModelType]:
@@ -686,11 +805,13 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         page: int = 1,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[SchemaType],
     ) -> PaginatedResponse[SchemaType]: ...
 
@@ -705,11 +826,13 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         page: int = 1,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: None = ...,
     ) -> PaginatedResponse[ModelType]: ...
 
@@ -722,11 +845,13 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         page: int = 1,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel] | None = None,
     ) -> PaginatedResponse[ModelType] | PaginatedResponse[Any]:
         """Get paginated results using offset-based pagination.
@@ -742,6 +867,10 @@ class AsyncCrud(Generic[ModelType]):
             items_per_page: Number of items per page
             search: Search query string or SearchConfig object
             search_fields: Fields to search in (overrides class default)
+            facet_fields: Columns to compute distinct values for (overrides class default)
+            filter_by: Dict of {column_key: value} to filter by declared facet fields.
+                Keys must match the column.key of a facet field. Scalar → equality,
+                list → IN clause. Raises InvalidFacetFilterError for unknown keys.
             schema: Optional Pydantic schema to serialize each item into.
 
         Returns:
@@ -751,6 +880,20 @@ class AsyncCrud(Generic[ModelType]):
         offset = (page - 1) * items_per_page
         search_joins: list[Any] = []
 
+        if isinstance(filter_by, BaseModel):
+            filter_by = filter_by.model_dump(exclude_none=True) or None
+
+        # Build filter_by conditions from declared facet fields
+        if filter_by:
+            resolved_facets_for_filter = (
+                facet_fields if facet_fields is not None else cls.facet_fields
+            )
+            fb_filters, fb_joins = build_filter_by(
+                filter_by, resolved_facets_for_filter or []
+            )
+            filters.extend(fb_filters)
+            search_joins.extend(fb_joins)
+
         # Build search filters
         if search:
             search_filters, search_joins = build_search_filters(
@@ -815,6 +958,20 @@ class AsyncCrud(Generic[ModelType]):
         count_result = await session.execute(count_q)
         total_count = count_result.scalar_one()
 
+        # Build facets
+        resolved_facet_fields = (
+            facet_fields if facet_fields is not None else cls.facet_fields
+        )
+        filter_attributes: dict[str, list[Any]] | None = None
+        if resolved_facet_fields:
+            filter_attributes = await build_facets(
+                session,
+                cls.model,
+                resolved_facet_fields,
+                base_filters=filters or None,
+                base_joins=search_joins or None,
+            )
+
         return PaginatedResponse(
             data=items,
             pagination=OffsetPagination(
@@ -823,6 +980,7 @@ class AsyncCrud(Generic[ModelType]):
                 page=page,
                 has_more=page * items_per_page < total_count,
             ),
+            filter_attributes=filter_attributes,
         )
 
     # Backward-compatible - will be removed in v2.0
@@ -839,10 +997,12 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[SchemaType],
     ) -> PaginatedResponse[SchemaType]: ...
 
@@ -858,10 +1018,12 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: None = ...,
     ) -> PaginatedResponse[ModelType]: ...
 
@@ -875,10 +1037,12 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
+        facet_fields: Sequence[FacetFieldType] | None = None,
+        filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel] | None = None,
     ) -> PaginatedResponse[ModelType] | PaginatedResponse[Any]:
         """Get paginated results using cursor-based pagination.
@@ -897,6 +1061,10 @@ class AsyncCrud(Generic[ModelType]):
             items_per_page: Number of items per page (default 20).
             search: Search query string or SearchConfig object.
             search_fields: Fields to search in (overrides class default).
+            facet_fields: Columns to compute distinct values for (overrides class default).
+            filter_by: Dict of {column_key: value} to filter by declared facet fields.
+                Keys must match the column.key of a facet field. Scalar → equality,
+                list → IN clause. Raises InvalidFacetFilterError for unknown keys.
             schema: Optional Pydantic schema to serialize each item into.
 
         Returns:
@@ -905,6 +1073,20 @@ class AsyncCrud(Generic[ModelType]):
         filters = list(filters) if filters else []
         search_joins: list[Any] = []
 
+        if isinstance(filter_by, BaseModel):
+            filter_by = filter_by.model_dump(exclude_none=True) or None
+
+        # Build filter_by conditions from declared facet fields
+        if filter_by:
+            resolved_facets_for_filter = (
+                facet_fields if facet_fields is not None else cls.facet_fields
+            )
+            fb_filters, fb_joins = build_filter_by(
+                filter_by, resolved_facets_for_filter or []
+            )
+            filters.extend(fb_filters)
+            search_joins.extend(fb_joins)
+
         if cls.cursor_column is None:
             raise ValueError(
                 f"{cls.__name__}.cursor_column is not set. "
@@ -920,8 +1102,18 @@ class AsyncCrud(Generic[ModelType]):
                 cursor_val: Any = int(raw_val)
             elif isinstance(col_type, Uuid):
                 cursor_val = uuid_module.UUID(raw_val)
+            elif isinstance(col_type, DateTime):
+                cursor_val = datetime.fromisoformat(raw_val)
+            elif isinstance(col_type, Date):
+                cursor_val = date.fromisoformat(raw_val)
+            elif isinstance(col_type, (Float, Numeric)):
+                cursor_val = Decimal(raw_val)
             else:
-                cursor_val = raw_val
+                raise ValueError(
+                    f"Unsupported cursor column type: {type(col_type).__name__!r}. "
+                    "Supported types: Integer, BigInteger, SmallInteger, Uuid, "
+                    "DateTime, Date, Float, Numeric."
+                )
             filters.append(cursor_column > cursor_val)
 
         # Build search filters
@@ -984,6 +1176,20 @@ class AsyncCrud(Generic[ModelType]):
             else items_page
         )
 
+        # Build facets
+        resolved_facet_fields = (
+            facet_fields if facet_fields is not None else cls.facet_fields
+        )
+        filter_attributes: dict[str, list[Any]] | None = None
+        if resolved_facet_fields:
+            filter_attributes = await build_facets(
+                session,
+                cls.model,
+                resolved_facet_fields,
+                base_filters=filters or None,
+                base_joins=search_joins or None,
+            )
+
         return PaginatedResponse(
             data=items,
             pagination=CursorPagination(
@@ -992,6 +1198,7 @@ class AsyncCrud(Generic[ModelType]):
                 items_per_page=items_per_page,
                 has_more=has_more,
             ),
+            filter_attributes=filter_attributes,
         )
 
 
@@ -999,6 +1206,8 @@ def CrudFactory(
     model: type[ModelType],
     *,
     searchable_fields: Sequence[SearchFieldType] | None = None,
+    facet_fields: Sequence[FacetFieldType] | None = None,
+    order_fields: Sequence[QueryableAttribute[Any]] | None = None,
     m2m_fields: M2MFieldType | None = None,
     default_load_options: list[ExecutableOption] | None = None,
     cursor_column: Any | None = None,
@@ -1008,6 +1217,11 @@ def CrudFactory(
     Args:
         model: SQLAlchemy model class
         searchable_fields: Optional list of searchable fields
+        facet_fields: Optional list of columns to compute distinct values for in paginated
+            responses. Supports direct columns (``User.status``) and relationship tuples
+            (``(User.role, Role.name)``). Can be overridden per call.
+        order_fields: Optional list of model attributes that callers are allowed to order by
+            via ``order_params()``. Can be overridden per call.
         m2m_fields: Optional mapping for many-to-many relationships.
             Maps schema field names (containing lists of IDs) to
             SQLAlchemy relationship attributes.
@@ -1016,8 +1230,9 @@ def CrudFactory(
             instead of ``lazy="selectin"`` on the model so that loading
             strategy is explicit and per-CRUD. Overridden entirely (not
             merged) when ``load_options`` is provided at call-site.
-        cursor_column: Required to call ``cursor_paginate``
+        cursor_column: Required to call ``cursor_paginate``.
             Must be monotonically ordered (e.g. integer PK, UUID v7, timestamp).
+            See the cursor pagination docs for supported column types.
 
     Returns:
         AsyncCrud subclass bound to the model
@@ -1043,6 +1258,12 @@ def CrudFactory(
             m2m_fields={"tag_ids": Post.tags},
         )
 
+        # With facet fields for filter dropdowns / faceted search:
+        UserCrud = CrudFactory(
+            User,
+            facet_fields=[User.status, User.country, (User.role, Role.name)],
+        )
+
         # With a fixed cursor column for cursor_paginate:
         PostCrud = CrudFactory(
             Post,
@@ -1093,6 +1314,8 @@ def CrudFactory(
         {
             "model": model,
             "searchable_fields": searchable_fields,
+            "facet_fields": facet_fields,
+            "order_fields": order_fields,
             "m2m_fields": m2m_fields,
             "default_load_options": default_load_options,
             "cursor_column": cursor_column,

src/fastapi_toolsets/crud/search.py

@@ -1,19 +1,23 @@
 """Search utilities for AsyncCrud."""
 
+import asyncio
+from collections import Counter
 from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
-from sqlalchemy import String, or_
+from sqlalchemy import String, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm.attributes import InstrumentedAttribute
 
-from ..exceptions import NoSearchableFieldsError
+from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
 
 if TYPE_CHECKING:
     from sqlalchemy.sql.elements import ColumnElement
 
 SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
+FacetFieldType = SearchFieldType
 
 
 @dataclass
@@ -89,6 +93,9 @@ def build_search_filters(
 
     Returns:
         Tuple of (filter_conditions, joins_needed)
+
+    Raises:
+        NoSearchableFieldsError: If no searchable field has been configured
     """
     # Normalize input
     if isinstance(search, str):
@@ -136,7 +143,7 @@ def build_search_filters(
         else:
             filters.append(column_as_string.ilike(f"%{query}%"))
 
-    if not filters:
+    if not filters:  # pragma: no cover
         return [], []
 
     # Combine based on match_mode
@@ -144,3 +151,145 @@ def build_search_filters(
         return [or_(*filters)], joins
     else:
         return filters, joins
+
+
+def facet_keys(facet_fields: Sequence[FacetFieldType]) -> list[str]:
+    """Return a key for each facet field, disambiguating duplicate column keys.
+
+    Args:
+        facet_fields: Sequence of facet fields — either direct columns or
+            relationship tuples ``(rel, ..., column)``.
+
+    Returns:
+        A list of string keys, one per facet field, in the same order.
+    """
+    raw: list[tuple[str, str | None]] = []
+    for field in facet_fields:
+        if isinstance(field, tuple):
+            rel = field[-2]
+            column = field[-1]
+            raw.append((column.key, rel.key))
+        else:
+            raw.append((field.key, None))
+
+    counts = Counter(col_key for col_key, _ in raw)
+    keys: list[str] = []
+    for col_key, rel_key in raw:
+        if counts[col_key] > 1 and rel_key is not None:
+            keys.append(f"{rel_key}__{col_key}")
+        else:
+            keys.append(col_key)
+    return keys
+
+
+async def build_facets(
+    session: "AsyncSession",
+    model: type[DeclarativeBase],
+    facet_fields: Sequence[FacetFieldType],
+    *,
+    base_filters: "list[ColumnElement[bool]] | None" = None,
+    base_joins: list[InstrumentedAttribute[Any]] | None = None,
+) -> dict[str, list[Any]]:
+    """Return distinct values for each facet field, respecting current filters.
+
+    Args:
+        session: DB async session
+        model: SQLAlchemy model class
+        facet_fields: Columns or relationship tuples to facet on
+        base_filters: Filter conditions already applied to the main query (search + caller filters)
+        base_joins: Relationship joins already applied to the main query
+
+    Returns:
+        Dict mapping column key to sorted list of distinct non-None values
+    """
+    existing_join_keys: set[str] = {str(j) for j in (base_joins or [])}
+
+    keys = facet_keys(facet_fields)
+
+    async def _query_facet(field: FacetFieldType, key: str) -> tuple[str, list[Any]]:
+        if isinstance(field, tuple):
+            # Relationship chain: (User.role, Role.name) — last element is the column
+            rels = field[:-1]
+            column = field[-1]
+        else:
+            rels = ()
+            column = field
+
+        q = select(column).select_from(model).distinct()
+
+        # Apply base joins (already done on main query, but needed here independently)
+        for rel in base_joins or []:
+            q = q.outerjoin(rel)
+
+        # Add any extra joins required by this facet field that aren't already in base_joins
+        for rel in rels:
+            if str(rel) not in existing_join_keys:
+                q = q.outerjoin(rel)
+
+        if base_filters:
+            from sqlalchemy import and_
+
+            q = q.where(and_(*base_filters))
+
+        q = q.order_by(column)
+        result = await session.execute(q)
+        values = [row[0] for row in result.all() if row[0] is not None]
+        return key, values
+
+    pairs = await asyncio.gather(
+        *[_query_facet(f, k) for f, k in zip(facet_fields, keys)]
+    )
+    return dict(pairs)
+
+
+def build_filter_by(
+    filter_by: dict[str, Any],
+    facet_fields: Sequence[FacetFieldType],
+) -> tuple["list[ColumnElement[bool]]", list[InstrumentedAttribute[Any]]]:
+    """Translate a {column_key: value} dict into SQLAlchemy filter conditions.
+
+    Args:
+        filter_by: Mapping of column key to scalar value or list of values
+        facet_fields: Declared facet fields to validate keys against
+
+    Returns:
+        Tuple of (filter_conditions, joins_needed)
+
+    Raises:
+        InvalidFacetFilterError: If a key in filter_by is not a declared facet field
+    """
+    index: dict[
+        str, tuple[InstrumentedAttribute[Any], list[InstrumentedAttribute[Any]]]
+    ] = {}
+    for key, field in zip(facet_keys(facet_fields), facet_fields):
+        if isinstance(field, tuple):
+            rels = list(field[:-1])
+            column = field[-1]
+        else:
+            rels = []
+            column = field
+        index[key] = (column, rels)
+
+    valid_keys = set(index)
+    filters: list[ColumnElement[bool]] = []
+    joins: list[InstrumentedAttribute[Any]] = []
+    added_join_keys: set[str] = set()
+
+    for key, value in filter_by.items():
+        if key not in index:
+            raise InvalidFacetFilterError(key, valid_keys)
+
+        column, rels = index[key]
+
+        for rel in rels:
+            rel_key = str(rel)
+            if rel_key not in added_join_keys:
+                joins.append(rel)
+                added_join_keys.add(rel_key)
+
+        if isinstance(value, list):
+            filters.append(column.in_(value))
+        else:
+            filters.append(column == value)
+
+    return filters, joins

src/fastapi_toolsets/exceptions/__init__.py

@@ -5,6 +5,8 @@ from .exceptions import (
     ApiException,
     ConflictError,
     ForbiddenError,
+    InvalidFacetFilterError,
+    InvalidOrderFieldError,
     NoSearchableFieldsError,
     NotFoundError,
     UnauthorizedError,
@@ -19,6 +21,8 @@ __all__ = [
     "ForbiddenError",
     "generate_error_responses",
     "init_exceptions_handlers",
+    "InvalidFacetFilterError",
+    "InvalidOrderFieldError",
     "NoSearchableFieldsError",
     "NotFoundError",
     "UnauthorizedError",

src/fastapi_toolsets/exceptions/exceptions.py

@@ -102,6 +102,57 @@ class NoSearchableFieldsError(ApiException):
         super().__init__(detail)
 
 
+class InvalidFacetFilterError(ApiException):
+    """Raised when filter_by contains a key not declared in facet_fields."""
+
+    api_error = ApiError(
+        code=400,
+        msg="Invalid Facet Filter",
+        desc="One or more filter_by keys are not declared as facet fields.",
+        err_code="FACET-400",
+    )
+
+    def __init__(self, key: str, valid_keys: set[str]) -> None:
+        """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
+        """
+        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__(detail)
+
+
+class InvalidOrderFieldError(ApiException):
+    """Raised when order_by contains a field not in the allowed order fields."""
+
+    api_error = ApiError(
+        code=422,
+        msg="Invalid Order Field",
+        desc="The requested order field is not allowed for this resource.",
+        err_code="SORT-422",
+    )
+
+    def __init__(self, field: str, valid_fields: list[str]) -> None:
+        """Initialize the exception.
+
+        Args:
+            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__(detail)
+
+
 def generate_error_responses(
     *errors: type[ApiException],
 ) -> dict[int | str, dict[str, Any]]:

src/fastapi_toolsets/schemas.py

@@ -133,3 +133,4 @@ class PaginatedResponse(BaseResponse, Generic[DataT]):
 
     data: list[DataT]
     pagination: OffsetPagination | CursorPagination
+    filter_attributes: dict[str, list[Any]] | None = None

tests/conftest.py

@@ -5,7 +5,20 @@ import uuid
 
 import pytest
 from pydantic import BaseModel
-from sqlalchemy import Column, ForeignKey, Integer, String, Table, Uuid
+import datetime
+import decimal
+
+from sqlalchemy import (
+    Column,
+    Date,
+    DateTime,
+    ForeignKey,
+    Integer,
+    Numeric,
+    String,
+    Table,
+    Uuid,
+)
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
@@ -79,6 +92,27 @@ class IntRole(Base):
     name: Mapped[str] = mapped_column(String(50), unique=True)
 
 
+class Event(Base):
+    """Test model with DateTime and Date cursor columns."""
+
+    __tablename__ = "events"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(100))
+    occurred_at: Mapped[datetime.datetime] = mapped_column(DateTime)
+    scheduled_date: Mapped[datetime.date] = mapped_column(Date)
+
+
+class Product(Base):
+    """Test model with Numeric cursor column."""
+
+    __tablename__ = "products"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(100))
+    price: Mapped[decimal.Decimal] = mapped_column(Numeric(10, 2))
+
+
 class Post(Base):
     """Test post model."""
 
@@ -190,6 +224,21 @@ class IntRoleCreate(BaseModel):
     name: str
 
 
+class EventCreate(BaseModel):
+    """Schema for creating an Event."""
+
+    name: str
+    occurred_at: datetime.datetime
+    scheduled_date: datetime.date
+
+
+class ProductCreate(BaseModel):
+    """Schema for creating a Product."""
+
+    name: str
+    price: decimal.Decimal
+
+
 RoleCrud = CrudFactory(Role)
 RoleCursorCrud = CrudFactory(Role, cursor_column=Role.id)
 IntRoleCursorCrud = CrudFactory(IntRole, cursor_column=IntRole.id)
@@ -198,6 +247,11 @@ UserCursorCrud = CrudFactory(User, cursor_column=User.id)
 PostCrud = CrudFactory(Post)
 TagCrud = CrudFactory(Tag)
 PostM2MCrud = CrudFactory(Post, m2m_fields={"tag_ids": Post.tags})
+EventCrud = CrudFactory(Event)
+EventDateTimeCursorCrud = CrudFactory(Event, cursor_column=Event.occurred_at)
+EventDateCursorCrud = CrudFactory(Event, cursor_column=Event.scheduled_date)
+ProductCrud = CrudFactory(Product)
+ProductNumericCursorCrud = CrudFactory(Product, cursor_column=Product.price)
 
 
 @pytest.fixture

tests/test_crud.py

@@ -11,6 +11,10 @@ from fastapi_toolsets.crud.factory import AsyncCrud
 from fastapi_toolsets.exceptions import NotFoundError
 
 from .conftest import (
+    EventCreate,
+    EventCrud,
+    EventDateCursorCrud,
+    EventDateTimeCursorCrud,
     IntRoleCreate,
     IntRoleCursorCrud,
     Post,
@@ -19,6 +23,9 @@ from .conftest import (
     PostM2MCreate,
     PostM2MCrud,
     PostM2MUpdate,
+    ProductCreate,
+    ProductCrud,
+    ProductNumericCursorCrud,
     Role,
     RoleCreate,
     RoleCrud,
@@ -1935,32 +1942,31 @@ class TestCursorPaginateExtraOptions:
         assert page2.pagination.has_more is False
 
     @pytest.mark.anyio
-    async def test_string_cursor_column(self, db_session: AsyncSession):
+    async def test_unsupported_cursor_column_type_raises(
-        """cursor_paginate decodes non-UUID/non-Integer cursor values (string branch)."""
+        self, db_session: AsyncSession
+    ):
+        """cursor_paginate raises ValueError when cursor column type is not supported."""
         from fastapi_toolsets.crud import CrudFactory
         from fastapi_toolsets.schemas import CursorPagination
 
         RoleNameCursorCrud = CrudFactory(Role, cursor_column=Role.name)
 
-        for i in range(5):
+        await RoleCrud.create(db_session, RoleCreate(name="role00"))
-            await RoleCrud.create(db_session, RoleCreate(name=f"role{i:02d}"))
+        await RoleCrud.create(db_session, RoleCreate(name="role01"))
 
-        page1 = await RoleNameCursorCrud.cursor_paginate(db_session, items_per_page=3)
+        # First page succeeds (no cursor to decode)
-
+        page1 = await RoleNameCursorCrud.cursor_paginate(db_session, items_per_page=1)
-        assert isinstance(page1.pagination, CursorPagination)
-        assert len(page1.data) == 3
         assert page1.pagination.has_more is True
+        assert isinstance(page1.pagination, CursorPagination)
 
-        page2 = await RoleNameCursorCrud.cursor_paginate(
+        # Second page fails because String type is unsupported
+        with pytest.raises(ValueError, match="Unsupported cursor column type"):
+            await RoleNameCursorCrud.cursor_paginate(
                 db_session,
                 cursor=page1.pagination.next_cursor,
-            items_per_page=3,
+                items_per_page=1,
             )
 
-        assert isinstance(page2.pagination, CursorPagination)
-        assert len(page2.data) == 2
-        assert page2.pagination.has_more is False
-
 
 class TestCursorPaginateSearchJoins:
     """Tests for cursor_paginate() search that traverses relationships (search_joins)."""
@@ -2019,3 +2025,120 @@ class TestGetWithForUpdate:
 
         assert result.id == role.id
         assert result.name == "locked"
+
+
+class TestCursorPaginateColumnTypes:
+    """Tests for cursor_paginate() covering DateTime, Date and Numeric column types."""
+
+    @pytest.mark.anyio
+    async def test_datetime_cursor_column(self, db_session: AsyncSession):
+        """cursor_paginate decodes DateTime cursor values to datetime objects."""
+        import datetime
+
+        from fastapi_toolsets.schemas import CursorPagination
+
+        base = datetime.datetime(2024, 1, 1, 0, 0, 0)
+        for i in range(5):
+            await EventCrud.create(
+                db_session,
+                EventCreate(
+                    name=f"event{i}",
+                    occurred_at=base + datetime.timedelta(hours=i),
+                    scheduled_date=datetime.date(2024, 1, i + 1),
+                ),
+            )
+
+        page1 = await EventDateTimeCursorCrud.cursor_paginate(
+            db_session, items_per_page=3
+        )
+
+        assert isinstance(page1.pagination, CursorPagination)
+        assert len(page1.data) == 3
+        assert page1.pagination.has_more is True
+
+        page2 = await EventDateTimeCursorCrud.cursor_paginate(
+            db_session,
+            cursor=page1.pagination.next_cursor,
+            items_per_page=3,
+        )
+
+        assert isinstance(page2.pagination, CursorPagination)
+        assert len(page2.data) == 2
+        assert page2.pagination.has_more is False
+        # No overlap between pages
+        page1_ids = {e.id for e in page1.data}
+        page2_ids = {e.id for e in page2.data}
+        assert page1_ids.isdisjoint(page2_ids)
+
+    @pytest.mark.anyio
+    async def test_date_cursor_column(self, db_session: AsyncSession):
+        """cursor_paginate decodes Date cursor values to date objects."""
+        import datetime
+
+        from fastapi_toolsets.schemas import CursorPagination
+
+        for i in range(5):
+            await EventCrud.create(
+                db_session,
+                EventCreate(
+                    name=f"event{i}",
+                    occurred_at=datetime.datetime(2024, 1, 1),
+                    scheduled_date=datetime.date(2024, 1, i + 1),
+                ),
+            )
+
+        page1 = await EventDateCursorCrud.cursor_paginate(db_session, items_per_page=3)
+
+        assert isinstance(page1.pagination, CursorPagination)
+        assert len(page1.data) == 3
+        assert page1.pagination.has_more is True
+
+        page2 = await EventDateCursorCrud.cursor_paginate(
+            db_session,
+            cursor=page1.pagination.next_cursor,
+            items_per_page=3,
+        )
+
+        assert isinstance(page2.pagination, CursorPagination)
+        assert len(page2.data) == 2
+        assert page2.pagination.has_more is False
+        page1_ids = {e.id for e in page1.data}
+        page2_ids = {e.id for e in page2.data}
+        assert page1_ids.isdisjoint(page2_ids)
+
+    @pytest.mark.anyio
+    async def test_numeric_cursor_column(self, db_session: AsyncSession):
+        """cursor_paginate decodes Numeric cursor values to Decimal objects."""
+        import decimal
+
+        from fastapi_toolsets.schemas import CursorPagination
+
+        for i in range(5):
+            await ProductCrud.create(
+                db_session,
+                ProductCreate(
+                    name=f"product{i}",
+                    price=decimal.Decimal(f"{i + 1}.99"),
+                ),
+            )
+
+        page1 = await ProductNumericCursorCrud.cursor_paginate(
+            db_session, items_per_page=3
+        )
+
+        assert isinstance(page1.pagination, CursorPagination)
+        assert len(page1.data) == 3
+        assert page1.pagination.has_more is True
+
+        page2 = await ProductNumericCursorCrud.cursor_paginate(
+            db_session,
+            cursor=page1.pagination.next_cursor,
+            items_per_page=3,
+        )
+
+        assert isinstance(page2.pagination, CursorPagination)
+        assert len(page2.data) == 2
+        assert page2.pagination.has_more is False
+        page1_ids = {p.id for p in page1.data}
+        page2_ids = {p.id for p in page2.data}
+        assert page1_ids.isdisjoint(page2_ids)

tests/test_crud_search.py

@@ -1,11 +1,19 @@
 """Tests for CRUD search functionality."""
 
+import inspect
 import uuid
 
 import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql.elements import ColumnElement, UnaryExpression
 
-from fastapi_toolsets.crud import SearchConfig, get_searchable_fields
+from fastapi_toolsets.crud import (
+    CrudFactory,
+    InvalidFacetFilterError,
+    SearchConfig,
+    get_searchable_fields,
+)
+from fastapi_toolsets.exceptions import InvalidOrderFieldError
 from fastapi_toolsets.schemas import OffsetPagination
 
 from .conftest import (
@@ -313,9 +321,35 @@ class TestPaginateSearch:
         assert result.data[0].id == user_id
 
 
+class TestBuildSearchFilters:
+    """Unit tests for build_search_filters."""
+
+    def test_deduplicates_relationship_join(self):
+        """Two tuple fields sharing the same relationship do not add the join twice."""
+        from fastapi_toolsets.crud.search import build_search_filters
+
+        # Both fields traverse User.role — the second must not re-add the join.
+        filters, joins = build_search_filters(
+            User,
+            "admin",
+            search_fields=[(User.role, Role.name), (User.role, Role.id)],
+        )
+
+        assert len(joins) == 1
+
+
 class TestSearchConfig:
     """Tests for SearchConfig options."""
 
+    def test_search_config_empty_query_returns_empty(self):
+        """SearchConfig with an empty/blank query returns empty filters without hitting the DB."""
+        from fastapi_toolsets.crud.search import build_search_filters
+
+        filters, joins = build_search_filters(User, SearchConfig(query="   "))
+
+        assert filters == []
+        assert joins == []
+
     @pytest.mark.anyio
     async def test_match_mode_all(self, db_session: AsyncSession):
         """match_mode='all' requires all fields to match (AND)."""
@@ -432,3 +466,695 @@ class TestGetSearchableFields:
         # Role.users is a collection, should not be included
         field_strs = [str(f) for f in fields]
         assert not any("users" in f for f in field_strs)
+
+
+class TestFacetsNotSet:
+    """filter_attributes is None when no facet_fields are configured."""
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_no_facets(self, db_session: AsyncSession):
+        """filter_attributes is None when facet_fields not set on factory or call."""
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserCrud.offset_paginate(db_session)
+
+        assert result.filter_attributes is None
+
+    @pytest.mark.anyio
+    async def test_cursor_paginate_no_facets(self, db_session: AsyncSession):
+        """filter_attributes is None for cursor_paginate when facet_fields not set."""
+        UserCursorCrud = CrudFactory(User, cursor_column=User.id)
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserCursorCrud.cursor_paginate(db_session)
+
+        assert result.filter_attributes is None
+
+
+class TestFacetsDirectColumn:
+    """Facets on direct model columns."""
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_direct_column(self, db_session: AsyncSession):
+        """Returns distinct values for a direct column via factory default."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCrud.offset_paginate(db_session)
+
+        assert result.filter_attributes is not None
+        # Distinct usernames, sorted
+        assert result.filter_attributes["username"] == ["alice", "bob"]
+
+    @pytest.mark.anyio
+    async def test_cursor_paginate_direct_column(self, db_session: AsyncSession):
+        """Returns distinct values for a direct column in cursor_paginate."""
+        UserFacetCursorCrud = CrudFactory(
+            User, cursor_column=User.id, facet_fields=[User.email]
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCursorCrud.cursor_paginate(db_session)
+
+        assert result.filter_attributes is not None
+        assert set(result.filter_attributes["email"]) == {"a@test.com", "b@test.com"}
+
+    @pytest.mark.anyio
+    async def test_multiple_facet_columns(self, db_session: AsyncSession):
+        """Returns distinct values for multiple columns."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username, User.email])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCrud.offset_paginate(db_session)
+
+        assert result.filter_attributes is not None
+        assert "username" in result.filter_attributes
+        assert "email" in result.filter_attributes
+        assert set(result.filter_attributes["username"]) == {"alice", "bob"}
+
+    @pytest.mark.anyio
+    async def test_per_call_override(self, db_session: AsyncSession):
+        """Per-call facet_fields overrides the factory default."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        # Override: ask for email instead of username
+        result = await UserFacetCrud.offset_paginate(
+            db_session, facet_fields=[User.email]
+        )
+
+        assert result.filter_attributes is not None
+        assert "email" in result.filter_attributes
+        assert "username" not in result.filter_attributes
+
+
+class TestFacetsRespectFilters:
+    """Facets reflect the active filter conditions."""
+
+    @pytest.mark.anyio
+    async def test_facets_respect_base_filters(self, db_session: AsyncSession):
+        """Facet values are scoped to the applied filters."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com", is_active=True)
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com", is_active=False)
+        )
+
+        # Filter to active users only — facets should only see "alice"
+        result = await UserFacetCrud.offset_paginate(
+            db_session,
+            filters=[User.is_active == True],  # noqa: E712
+        )
+
+        assert result.filter_attributes is not None
+        assert result.filter_attributes["username"] == ["alice"]
+
+
+class TestFacetsRelationship:
+    """Facets on relationship columns via tuple syntax."""
+
+    @pytest.mark.anyio
+    async def test_relationship_facet(self, db_session: AsyncSession):
+        """Returns distinct values from a related model column."""
+        UserRelFacetCrud = CrudFactory(User, facet_fields=[(User.role, Role.name)])
+
+        admin = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        editor = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=admin.id),
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="bob", email="b@test.com", role_id=editor.id),
+        )
+        # User without a role — their role.name should be excluded (None filtered out)
+        await UserCrud.create(
+            db_session, UserCreate(username="charlie", email="c@test.com")
+        )
+
+        result = await UserRelFacetCrud.offset_paginate(db_session)
+
+        assert result.filter_attributes is not None
+        assert set(result.filter_attributes["name"]) == {"admin", "editor"}
+
+    @pytest.mark.anyio
+    async def test_relationship_facet_none_excluded(self, db_session: AsyncSession):
+        """None values (e.g. NULL role) are excluded from facet results."""
+        UserRelFacetCrud = CrudFactory(User, facet_fields=[(User.role, Role.name)])
+
+        # Only user with no role
+        await UserCrud.create(
+            db_session, UserCreate(username="norole", email="n@test.com")
+        )
+
+        result = await UserRelFacetCrud.offset_paginate(db_session)
+
+        assert result.filter_attributes is not None
+        assert result.filter_attributes["name"] == []
+
+    @pytest.mark.anyio
+    async def test_relationship_facet_deduplicates_join_with_search(
+        self, db_session: AsyncSession
+    ):
+        """Facet join is not duplicated when search already added the same relationship join."""
+        # Both search and facet use (User.role, Role.name) — join should not be doubled
+        UserSearchFacetCrud = CrudFactory(
+            User,
+            searchable_fields=[(User.role, Role.name)],
+            facet_fields=[(User.role, Role.name)],
+        )
+
+        admin = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=admin.id),
+        )
+
+        result = await UserSearchFacetCrud.offset_paginate(
+            db_session, search="admin", search_fields=[(User.role, Role.name)]
+        )
+
+        assert result.filter_attributes is not None
+        assert result.filter_attributes["name"] == ["admin"]
+
+
+class TestFilterBy:
+    """Tests for the filter_by parameter on offset_paginate and cursor_paginate."""
+
+    @pytest.mark.anyio
+    async def test_scalar_filter(self, db_session: AsyncSession):
+        """filter_by with a scalar value produces an equality filter."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by={"username": "alice"}
+        )
+
+        assert len(result.data) == 1
+        assert result.data[0].username == "alice"
+        # facet also scoped to the filter
+        assert result.filter_attributes == {"username": ["alice"]}
+
+    @pytest.mark.anyio
+    async def test_list_filter_produces_in_clause(self, db_session: AsyncSession):
+        """filter_by with a list value produces an IN filter."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="charlie", email="c@test.com")
+        )
+
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by={"username": ["alice", "bob"]}
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+        returned_names = {u.username for u in result.data}
+        assert returned_names == {"alice", "bob"}
+
+    @pytest.mark.anyio
+    async def test_relationship_filter_by(self, db_session: AsyncSession):
+        """filter_by works with relationship tuple facet fields."""
+        UserRelFacetCrud = CrudFactory(User, facet_fields=[(User.role, Role.name)])
+
+        admin = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        editor = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=admin.id),
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="bob", email="b@test.com", role_id=editor.id),
+        )
+
+        result = await UserRelFacetCrud.offset_paginate(
+            db_session, filter_by={"name": "admin"}
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_filter_by_combined_with_filters(self, db_session: AsyncSession):
+        """filter_by and filters= are combined (AND logic)."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com", is_active=True)
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice2", email="a2@test.com", is_active=False),
+        )
+
+        result = await UserFacetCrud.offset_paginate(
+            db_session,
+            filters=[User.is_active == True],  # noqa: E712
+            filter_by={"username": ["alice", "alice2"]},
+        )
+
+        # Only alice passes both: is_active=True AND username IN [alice, alice2]
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_invalid_key_raises(self, db_session: AsyncSession):
+        """filter_by with an undeclared key raises InvalidFacetFilterError."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+
+        with pytest.raises(InvalidFacetFilterError) as exc_info:
+            await UserFacetCrud.offset_paginate(
+                db_session, filter_by={"nonexistent": "value"}
+            )
+
+        assert exc_info.value.key == "nonexistent"
+        assert "username" in exc_info.value.valid_keys
+
+    @pytest.mark.anyio
+    async def test_filter_by_deduplicates_relationship_join(
+        self, db_session: AsyncSession
+    ):
+        """Two filter_by keys through the same relationship do not duplicate the join."""
+        # Both (User.role, Role.name) and (User.role, Role.id) traverse User.role —
+        # the second key must not re-add the join (exercises the dedup branch in build_filter_by).
+        UserRoleFacetCrud = CrudFactory(
+            User,
+            facet_fields=[(User.role, Role.name), (User.role, Role.id)],
+        )
+
+        admin = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        editor = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=admin.id),
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="bob", email="b@test.com", role_id=editor.id),
+        )
+
+        result = await UserRoleFacetCrud.offset_paginate(
+            db_session,
+            filter_by={"name": "admin", "id": str(admin.id)},
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_cursor_paginate_filter_by(self, db_session: AsyncSession):
+        """filter_by works with cursor_paginate."""
+        UserFacetCursorCrud = CrudFactory(
+            User, cursor_column=User.id, facet_fields=[User.username]
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCursorCrud.cursor_paginate(
+            db_session, filter_by={"username": "alice"}
+        )
+
+        assert len(result.data) == 1
+        assert result.data[0].username == "alice"
+        assert result.filter_attributes == {"username": ["alice"]}
+
+    @pytest.mark.anyio
+    async def test_basemodel_filter_by_offset_paginate(self, db_session: AsyncSession):
+        """filter_by accepts a BaseModel instance (model_dump path) in offset_paginate."""
+        from pydantic import BaseModel as PydanticBaseModel
+
+        class UserFilter(PydanticBaseModel):
+            username: str | None = None
+
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by=UserFilter(username="alice")
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_basemodel_filter_by_cursor_paginate(self, db_session: AsyncSession):
+        """filter_by accepts a BaseModel instance (model_dump path) in cursor_paginate."""
+        from pydantic import BaseModel as PydanticBaseModel
+
+        class UserFilter(PydanticBaseModel):
+            username: str | None = None
+
+        UserFacetCursorCrud = CrudFactory(
+            User, cursor_column=User.id, facet_fields=[User.username]
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        result = await UserFacetCursorCrud.cursor_paginate(
+            db_session, filter_by=UserFilter(username="alice")
+        )
+
+        assert len(result.data) == 1
+        assert result.data[0].username == "alice"
+
+
+class TestFilterParamsSchema:
+    """Tests for AsyncCrud.filter_params()."""
+
+    def test_generates_fields_from_facet_fields(self):
+        """Returned dependency has one keyword param per facet field."""
+        import inspect
+
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username, User.email])
+        dep = UserFacetCrud.filter_params()
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert param_names == {"username", "email"}
+
+    def test_relationship_facet_uses_column_key(self):
+        """Relationship tuple uses the terminal column's key."""
+        import inspect
+
+        UserRoleCrud = CrudFactory(User, facet_fields=[(User.role, Role.name)])
+        dep = UserRoleCrud.filter_params()
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert param_names == {"name"}
+
+    def test_raises_when_no_facet_fields(self):
+        """ValueError raised when no facet_fields are configured or provided."""
+        with pytest.raises(ValueError, match="no facet_fields"):
+            UserCrud.filter_params()
+
+    def test_facet_fields_override(self):
+        """facet_fields= parameter overrides the class-level default."""
+        import inspect
+
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username, User.email])
+        dep = UserFacetCrud.filter_params(facet_fields=[User.email])
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert param_names == {"email"}
+
+    @pytest.mark.anyio
+    async def test_awaiting_dep_returns_dict_with_values(self):
+        """Awaiting the dependency returns a dict with only the supplied keys."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username, User.email])
+        dep = UserFacetCrud.filter_params()
+
+        result = await dep(username=["alice"])
+        assert result == {"username": ["alice"]}
+
+    @pytest.mark.anyio
+    async def test_multi_value_list_field(self):
+        """Multiple values are accepted as a list."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        dep = UserFacetCrud.filter_params()
+
+        result = await dep(username=["alice", "bob"])
+        assert result == {"username": ["alice", "bob"]}
+
+    def test_disambiguates_duplicate_column_keys(self):
+        """Two relationship tuples sharing a terminal column key get prefixed names."""
+        from unittest.mock import MagicMock
+
+        from fastapi_toolsets.crud.search import facet_keys
+
+        col_a = MagicMock()
+        col_a.key = "name"
+        rel_a = MagicMock()
+        rel_a.key = "project"
+
+        col_b = MagicMock()
+        col_b.key = "name"
+        rel_b = MagicMock()
+        rel_b.key = "os"
+
+        keys = facet_keys([(rel_a, col_a), (rel_b, col_b)])
+        assert keys == ["project__name", "os__name"]
+
+    def test_unique_column_keys_kept_plain(self):
+        """Fields with unique column keys are not prefixed."""
+        from fastapi_toolsets.crud.search import facet_keys
+
+        keys = facet_keys([User.username, User.email])
+        assert keys == ["username", "email"]
+
+    def test_dependency_name_includes_model_name(self):
+        """Returned dependency is named {Model}FilterParams."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        dep = UserFacetCrud.filter_params()
+
+        assert dep.__name__ == "UserFilterParams"  # type: ignore[union-attr]
+
+    @pytest.mark.anyio
+    async def test_integration_with_offset_paginate(self, db_session: AsyncSession):
+        """Dependency result can be passed directly to offset_paginate via filter_by."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        dep = UserFacetCrud.filter_params()
+        f = await dep(username=["alice"])
+        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_dep_result_passed_to_cursor_paginate(self, db_session: AsyncSession):
+        """Dependency result can be passed directly to cursor_paginate via filter_by."""
+        UserFacetCursorCrud = CrudFactory(
+            User, cursor_column=User.id, facet_fields=[User.username]
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        dep = UserFacetCursorCrud.filter_params()
+        f = await dep(username=["alice"])
+        result = await UserFacetCursorCrud.cursor_paginate(db_session, filter_by=f)
+
+        assert len(result.data) == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_all_none_dep_result_passes_no_filter(self, db_session: AsyncSession):
+        """All-None dependency result results in no filter (returns all rows)."""
+        UserFacetCrud = CrudFactory(User, facet_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com")
+        )
+
+        dep = UserFacetCrud.filter_params()
+        f = await dep()  # all fields None
+        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+
+
+class TestOrderParamsSchema:
+    """Tests for AsyncCrud.order_params()."""
+
+    def test_generates_order_by_and_order_params(self):
+        """Returned dependency has order_by and order query params."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert param_names == {"order_by", "order"}
+
+    def test_dependency_name_includes_model_name(self):
+        """Dependency function is named after the model."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        assert getattr(dep, "__name__") == "UserOrderParams"
+
+    def test_raises_when_no_order_fields(self):
+        """ValueError raised when no order_fields are configured or provided."""
+        with pytest.raises(ValueError, match="no order_fields"):
+            UserCrud.order_params()
+
+    def test_order_fields_override(self):
+        """order_fields= parameter overrides the class-level default."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params(order_fields=[User.email])
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert "order_by" in param_names
+        # description should only mention email, not username
+        sig = inspect.signature(dep)
+        description = sig.parameters["order_by"].default.description
+        assert "email" in description
+        assert "username" not in description
+
+    def test_order_by_description_lists_valid_fields(self):
+        """order_by query param description mentions each allowed field."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+
+        sig = inspect.signature(dep)
+        description = sig.parameters["order_by"].default.description
+        assert "username" in description
+        assert "email" in description
+
+    def test_default_order_reflected_in_order_default(self):
+        """default_order is used as the default value for order."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep_asc = UserOrderCrud.order_params(default_order="asc")
+        dep_desc = UserOrderCrud.order_params(default_order="desc")
+
+        sig_asc = inspect.signature(dep_asc)
+        sig_desc = inspect.signature(dep_desc)
+        assert sig_asc.parameters["order"].default.default == "asc"
+        assert sig_desc.parameters["order"].default.default == "desc"
+
+    @pytest.mark.anyio
+    async def test_no_order_by_no_default_returns_none(self):
+        """Returns None when order_by is absent and no default_field is set."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by=None, order="asc")
+        assert result is None
+
+    @pytest.mark.anyio
+    async def test_no_order_by_with_default_field_returns_asc_expression(self):
+        """Returns default_field.asc() when order_by absent and order=asc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params(default_field=User.username)
+        result = await dep(order_by=None, order="asc")
+        assert isinstance(result, UnaryExpression)
+        assert "ASC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_no_order_by_with_default_field_returns_desc_expression(self):
+        """Returns default_field.desc() when order_by absent and order=desc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params(default_field=User.username)
+        result = await dep(order_by=None, order="desc")
+        assert isinstance(result, UnaryExpression)
+        assert "DESC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_valid_order_by_asc(self):
+        """Returns field.asc() for a valid order_by with order=asc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by="username", order="asc")
+        assert isinstance(result, UnaryExpression)
+        assert "ASC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_valid_order_by_desc(self):
+        """Returns field.desc() for a valid order_by with order=desc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by="username", order="desc")
+        assert isinstance(result, UnaryExpression)
+        assert "DESC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_raises_invalid_order_field_error(self):
+        """Raises InvalidOrderFieldError for an unknown order_by value."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        with pytest.raises(InvalidOrderFieldError) as exc_info:
+            await dep(order_by="nonexistent", order="asc")
+        assert exc_info.value.field == "nonexistent"
+        assert "username" in exc_info.value.valid_fields
+
+    @pytest.mark.anyio
+    async def test_multiple_fields_all_resolve(self):
+        """All configured fields resolve correctly via order_by."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+        result_username = await dep(order_by="username", order="asc")
+        result_email = await dep(order_by="email", order="desc")
+        assert isinstance(result_username, ColumnElement)
+        assert isinstance(result_email, ColumnElement)
+
+    @pytest.mark.anyio
+    async def test_order_params_integrates_with_get_multi(
+        self, db_session: AsyncSession
+    ):
+        """order_params output is accepted by get_multi(order_by=...)."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="charlie", email="c@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        dep = UserOrderCrud.order_params()
+        order_by = await dep(order_by="username", order="asc")
+        results = await UserOrderCrud.get_multi(db_session, order_by=order_by)
+
+        assert results[0].username == "alice"
+        assert results[1].username == "charlie"

tests/test_example_pagination_search.py

@@ -0,0 +1,395 @@
+"""Live test for the docs/examples/pagination-search.md example.
+
+Spins up the exact FastAPI app described in the example (sourced from
+docs_src/examples/pagination_search/) and exercises it through a real HTTP
+client against a real PostgreSQL database.
+"""
+
+import datetime
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from docs_src.examples.pagination_search.db import get_db
+from docs_src.examples.pagination_search.models import Article, Base, Category
+from docs_src.examples.pagination_search.routes import router
+from fastapi_toolsets.exceptions import init_exceptions_handlers
+
+from .conftest import DATABASE_URL
+
+
+def build_app(session: AsyncSession) -> FastAPI:
+    app = FastAPI()
+    init_exceptions_handlers(app)
+
+    async def override_get_db():
+        yield session
+
+    app.dependency_overrides[get_db] = override_get_db
+    app.include_router(router)
+    return app
+
+
+@pytest.fixture(scope="function")
+async def ex_db_session():
+    """Isolated session for the example models (separate tables from conftest)."""
+    engine = create_async_engine(DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.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(Base.metadata.drop_all)
+        await engine.dispose()
+
+
+@pytest.fixture
+async def client(ex_db_session: AsyncSession):
+    app = build_app(ex_db_session)
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        yield ac
+
+
+async def seed(session: AsyncSession):
+    """Insert representative fixture data."""
+    python = Category(name="python")
+    backend = Category(name="backend")
+    session.add_all([python, backend])
+    await session.flush()
+
+    now = datetime.datetime(2024, 1, 1, tzinfo=datetime.timezone.utc)
+    session.add_all(
+        [
+            Article(
+                title="FastAPI tips",
+                body="Ten useful tips for FastAPI.",
+                status="published",
+                published=True,
+                category_id=python.id,
+                created_at=now,
+            ),
+            Article(
+                title="SQLAlchemy async",
+                body="How to use async SQLAlchemy.",
+                status="published",
+                published=True,
+                category_id=backend.id,
+                created_at=now + datetime.timedelta(seconds=1),
+            ),
+            Article(
+                title="Draft notes",
+                body="Work in progress.",
+                status="draft",
+                published=False,
+                category_id=None,
+                created_at=now + datetime.timedelta(seconds=2),
+            ),
+        ]
+    )
+    await session.commit()
+
+
+class TestAppSessionDep:
+    @pytest.mark.anyio
+    async def test_get_db_yields_async_session(self):
+        """get_db yields a real AsyncSession when called directly."""
+        from docs_src.examples.pagination_search.db import get_db
+
+        gen = get_db()
+        session = await gen.__anext__()
+        assert isinstance(session, AsyncSession)
+        await session.close()
+
+
+class TestOffsetPagination:
+    @pytest.mark.anyio
+    async def test_returns_all_articles(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 3
+        assert len(body["data"]) == 3
+
+    @pytest.mark.anyio
+    async def test_pagination_page_size(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?items_per_page=2&page=1")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["data"]) == 2
+        assert body["pagination"]["total_count"] == 3
+        assert body["pagination"]["has_more"] is True
+
+    @pytest.mark.anyio
+    async def test_full_text_search(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?search=fastapi")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 1
+        assert body["data"][0]["title"] == "FastAPI tips"
+
+    @pytest.mark.anyio
+    async def test_search_traverses_relationship(
+        self, client: AsyncClient, ex_db_session
+    ):
+        await seed(ex_db_session)
+
+        # "python" matches Category.name, not Article.title or body
+        resp = await client.get("/articles/offset?search=python")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 1
+        assert body["data"][0]["title"] == "FastAPI tips"
+
+    @pytest.mark.anyio
+    async def test_facet_filter_scalar(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?status=published")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 2
+        assert all(a["status"] == "published" for a in body["data"])
+
+    @pytest.mark.anyio
+    async def test_facet_filter_multi_value(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?status=published&status=draft")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 3
+
+    @pytest.mark.anyio
+    async def test_filter_attributes_in_response(
+        self, client: AsyncClient, ex_db_session
+    ):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        fa = body["filter_attributes"]
+        assert set(fa["status"]) == {"draft", "published"}
+        # "name" is unique across all facet fields — no prefix needed
+        assert set(fa["name"]) == {"backend", "python"}
+
+    @pytest.mark.anyio
+    async def test_filter_attributes_scoped_to_filter(
+        self, client: AsyncClient, ex_db_session
+    ):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?status=published")
+
+        body = resp.json()
+        # draft is filtered out → should not appear in filter_attributes
+        assert "draft" not in body["filter_attributes"]["status"]
+
+    @pytest.mark.anyio
+    async def test_search_and_filter_combined(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?search=async&status=published")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination"]["total_count"] == 1
+        assert body["data"][0]["title"] == "SQLAlchemy async"
+
+
+class TestCursorPagination:
+    @pytest.mark.anyio
+    async def test_first_page(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?items_per_page=2")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["data"]) == 2
+        assert body["pagination"]["has_more"] is True
+        assert body["pagination"]["next_cursor"] is not None
+        assert body["pagination"]["prev_cursor"] is None
+
+    @pytest.mark.anyio
+    async def test_second_page(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        first = await client.get("/articles/cursor?items_per_page=2")
+        next_cursor = first.json()["pagination"]["next_cursor"]
+
+        resp = await client.get(
+            f"/articles/cursor?items_per_page=2&cursor={next_cursor}"
+        )
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["data"]) == 1
+        assert body["pagination"]["has_more"] is False
+
+    @pytest.mark.anyio
+    async def test_facet_filter(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?status=draft")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["data"]) == 1
+        assert body["data"][0]["status"] == "draft"
+
+    @pytest.mark.anyio
+    async def test_full_text_search(self, client: AsyncClient, ex_db_session):
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?search=sqlalchemy")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["data"]) == 1
+        assert body["data"][0]["title"] == "SQLAlchemy async"
+
+
+class TestOffsetSorting:
+    """Tests for order_by / order query parameters on the offset endpoint."""
+
+    @pytest.mark.anyio
+    async def test_default_order_uses_created_at_asc(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """No order_by → default field (created_at) ASC."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["FastAPI tips", "SQLAlchemy async", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_asc(self, client: AsyncClient, ex_db_session):
+        """order_by=title&order=asc returns alphabetical order."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=title&order=asc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["Draft notes", "FastAPI tips", "SQLAlchemy async"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_desc(self, client: AsyncClient, ex_db_session):
+        """order_by=title&order=desc returns reverse alphabetical order."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=title&order=desc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["SQLAlchemy async", "FastAPI tips", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_created_at_desc(self, client: AsyncClient, ex_db_session):
+        """order_by=created_at&order=desc returns newest-first."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=created_at&order=desc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["Draft notes", "SQLAlchemy async", "FastAPI tips"]
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_returns_422(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Unknown order_by field returns 422 with SORT-422 error code."""
+        resp = await client.get("/articles/offset?order_by=nonexistent_field")
+
+        assert resp.status_code == 422
+        body = resp.json()
+        assert body["error_code"] == "SORT-422"
+        assert body["status"] == "FAIL"
+
+
+class TestCursorSorting:
+    """Tests for order_by / order query parameters on the cursor endpoint.
+
+    In cursor_paginate the cursor_column is always the primary sort; order_by
+    acts as a secondary tiebreaker. With the seeded articles (all having unique
+    created_at values) the overall ordering is always created_at ASC regardless
+    of the order_by value — only the valid/invalid field check and the response
+    shape are meaningful here.
+    """
+
+    @pytest.mark.anyio
+    async def test_default_order_uses_created_at_asc(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """No order_by → default field (created_at) ASC."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["FastAPI tips", "SQLAlchemy async", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_asc_accepted(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """order_by=title is a valid field — request succeeds and returns all articles."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?order_by=title&order=asc")
+
+        assert resp.status_code == 200
+        assert len(resp.json()["data"]) == 3
+
+    @pytest.mark.anyio
+    async def test_order_by_title_desc_accepted(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """order_by=title&order=desc is valid — request succeeds and returns all articles."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?order_by=title&order=desc")
+
+        assert resp.status_code == 200
+        assert len(resp.json()["data"]) == 3
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_returns_422(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Unknown order_by field returns 422 with SORT-422 error code."""
+        resp = await client.get("/articles/cursor?order_by=nonexistent_field")
+
+        assert resp.status_code == 422
+        body = resp.json()
+        assert body["error_code"] == "SORT-422"
+        assert body["status"] == "FAIL"

tests/test_exceptions.py

@@ -8,6 +8,7 @@ from fastapi_toolsets.exceptions import (
     ApiException,
     ConflictError,
     ForbiddenError,
+    InvalidOrderFieldError,
     NotFoundError,
     UnauthorizedError,
     generate_error_responses,
@@ -334,3 +335,43 @@ class TestExceptionIntegration:
 
         assert response.status_code == 200
         assert response.json() == {"id": 1}
+
+
+class TestInvalidOrderFieldError:
+    """Tests for InvalidOrderFieldError exception."""
+
+    def test_api_error_attributes(self):
+        """InvalidOrderFieldError has correct api_error metadata."""
+        assert InvalidOrderFieldError.api_error.code == 422
+        assert InvalidOrderFieldError.api_error.err_code == "SORT-422"
+        assert InvalidOrderFieldError.api_error.msg == "Invalid Order Field"
+
+    def test_stores_field_and_valid_fields(self):
+        """InvalidOrderFieldError stores field and valid_fields on the instance."""
+        error = InvalidOrderFieldError("unknown", ["name", "created_at"])
+        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."""
+        error = InvalidOrderFieldError("bad_field", ["name", "email"])
+        assert "bad_field" in str(error)
+        assert "name" in str(error)
+        assert "email" in str(error)
+
+    def test_handled_as_422_by_exception_handler(self):
+        """init_exceptions_handlers turns InvalidOrderFieldError into a 422 response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items")
+        async def list_items():
+            raise InvalidOrderFieldError("bad", ["name"])
+
+        client = TestClient(app)
+        response = client.get("/items")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["error_code"] == "SORT-422"
+        assert data["status"] == "FAIL"

uv.lock

@@ -235,7 +235,7 @@ wheels = [
 
 [[package]]
 name = "fastapi"
-version = "0.129.0"
+version = "0.133.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/48/47/75f6bea02e797abff1bca968d5997793898032d9923c1935ae2efdece642/fastapi-0.129.0.tar.gz", hash = "sha256:61315cebd2e65df5f97ec298c888f9de30430dd0612d59d6480beafbc10655af", size = 375450, upload-time = "2026-02-12T13:54:52.541Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9e/dd/d0ee25348ac58245ee9f90b6f3cbb666bf01f69be7e0911f9851bddbda16/fastapi-0.129.0-py3-none-any.whl", hash = "sha256:b4946880e48f462692b31c083be0432275cbfb6e2274566b1be91479cc1a84ec", size = 102950, upload-time = "2026-02-12T13:54:54.528Z" },
+    { 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" },
 ]
 
 [[package]]
 name = "fastapi-toolsets"
-version = "1.1.0"
+version = "1.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },
@@ -413,30 +413,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e1/2b/98c7f93e6db9977aaee07eb1e51ca63bd5f779b900d362791d3252e60558/greenlet-3.3.1-cp314-cp314t-win_amd64.whl", hash = "sha256:301860987846c24cb8964bdec0e31a96ad4a2a801b41b4ef40963c1b44f33451", size = 233181, upload-time = "2026-01-23T15:33:00.29Z" },
 ]
 
-[[package]]
-name = "griffe"
-version = "2.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "griffecli" },
-    { name = "griffelib" },
-]
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/8b/94/ee21d41e7eb4f823b94603b9d40f86d3c7fde80eacc2c3c71845476dddaa/griffe-2.0.0-py3-none-any.whl", hash = "sha256:5418081135a391c3e6e757a7f3f156f1a1a746cc7b4023868ff7d5e2f9a980aa", size = 5214, upload-time = "2026-02-09T19:09:44.105Z" },
-]
-
-[[package]]
-name = "griffecli"
-version = "2.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "colorama" },
-    { name = "griffelib" },
-]
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ed/d93f7a447bbf7a935d8868e9617cbe1cadf9ee9ee6bd275d3040fbf93d60/griffecli-2.0.0-py3-none-any.whl", hash = "sha256:9f7cd9ee9b21d55e91689358978d2385ae65c22f307a63fb3269acf3f21e643d", size = 9345, upload-time = "2026-02-09T19:09:42.554Z" },
-]
-
 [[package]]
 name = "griffelib"
 version = "2.0.0"
@@ -696,16 +672,16 @@ wheels = [
 
 [[package]]
 name = "mkdocstrings-python"
-version = "2.0.2"
+version = "2.0.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "griffe" },
+    { name = "griffelib" },
     { name = "mkdocs-autorefs" },
     { name = "mkdocstrings" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/25/84/78243847ad9d5c21d30a2842720425b17e880d99dfe824dee11d6b2149b4/mkdocstrings_python-2.0.2.tar.gz", hash = "sha256:4a32ccfc4b8d29639864698e81cfeb04137bce76bb9f3c251040f55d4b6e1ad8", size = 199124, upload-time = "2026-02-09T15:12:01.543Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/29/33/c225eaf898634bdda489a6766fc35d1683c640bffe0e0acd10646b13536d/mkdocstrings_python-2.0.3.tar.gz", hash = "sha256:c518632751cc869439b31c9d3177678ad2bfa5c21b79b863956ad68fc92c13b8", size = 199083, upload-time = "2026-02-20T10:38:36.368Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f3/31/7ee938abbde2322e553a2cb5f604cdd1e4728e08bba39c7ee6fae9af840b/mkdocstrings_python-2.0.2-py3-none-any.whl", hash = "sha256:31241c0f43d85a69306d704d5725786015510ea3f3c4bdfdb5a5731d83cdc2b0", size = 104900, upload-time = "2026-02-09T15:12:00.166Z" },
+    { url = "https://files.pythonhosted.org/packages/32/28/79f0f8de97cce916d5ae88a7bee1ad724855e83e6019c0b4d5b3fabc80f3/mkdocstrings_python-2.0.3-py3-none-any.whl", hash = "sha256:0b83513478bdfd803ff05aa43e9b1fca9dd22bcd9471f09ca6257f009bc5ee12", size = 104779, upload-time = "2026-02-20T10:38:34.517Z" },
 ]
 
 [[package]]
@@ -1037,27 +1013,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.1"
+version = "0.15.2"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/04/dc/4e6ac71b511b141cf626357a3946679abeba4cf67bc7cc5a17920f31e10d/ruff-0.15.1.tar.gz", hash = "sha256:c590fe13fb57c97141ae975c03a1aedb3d3156030cabd740d6ff0b0d601e203f", size = 4540855, upload-time = "2026-02-12T23:09:09.998Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/23/bf/e6e4324238c17f9d9120a9d60aa99a7daaa21204c07fcd84e2ef03bb5fd1/ruff-0.15.1-py3-none-linux_armv6l.whl", hash = "sha256:b101ed7cf4615bda6ffe65bdb59f964e9f4a0d3f85cbf0e54f0ab76d7b90228a", size = 10367819, upload-time = "2026-02-12T23:09:03.598Z" },
+    { 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/b3/ea/c8f89d32e7912269d38c58f3649e453ac32c528f93bb7f4219258be2e7ed/ruff-0.15.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:939c995e9277e63ea632cc8d3fae17aa758526f49a9a850d2e7e758bfef46602", size = 10798618, upload-time = "2026-02-12T23:09:22.928Z" },
+    { 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/5e/0f/1d0d88bc862624247d82c20c10d4c0f6bb2f346559d8af281674cf327f15/ruff-0.15.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:1d83466455fdefe60b8d9c8df81d3c1bbb2115cede53549d3b522ce2bc703899", size = 10148518, upload-time = "2026-02-12T23:08:58.339Z" },
+    { 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/f5/c8/291c49cefaa4a9248e986256df2ade7add79388fe179e0691be06fae6f37/ruff-0.15.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a9457e3c3291024866222b96108ab2d8265b477e5b1534c7ddb1810904858d16", size = 10518811, upload-time = "2026-02-12T23:09:31.865Z" },
+    { 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/c3/1a/f5707440e5ae43ffa5365cac8bbb91e9665f4a883f560893829cf16a606b/ruff-0.15.1-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:92c92b003e9d4f7fbd33b1867bb15a1b785b1735069108dfc23821ba045b29bc", size = 10196169, upload-time = "2026-02-12T23:09:17.306Z" },
+    { 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/2a/ff/26ddc8c4da04c8fd3ee65a89c9fb99eaa5c30394269d424461467be2271f/ruff-0.15.1-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1fe5c41ab43e3a06778844c586251eb5a510f67125427625f9eb2b9526535779", size = 10990491, upload-time = "2026-02-12T23:09:25.503Z" },
+    { 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/fc/00/50920cb385b89413f7cdb4bb9bc8fc59c1b0f30028d8bccc294189a54955/ruff-0.15.1-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:66a6dd6df4d80dc382c6484f8ce1bcceb55c32e9f27a8b94c32f6c7331bf14fb", size = 11843280, upload-time = "2026-02-12T23:09:19.88Z" },
+    { 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/5d/6d/2f5cad8380caf5632a15460c323ae326f1e1a2b5b90a6ee7519017a017ca/ruff-0.15.1-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6a4a42cbb8af0bda9bcd7606b064d7c0bc311a88d141d02f78920be6acb5aa83", size = 11274336, upload-time = "2026-02-12T23:09:14.907Z" },
+    { 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/a3/1d/5f56cae1d6c40b8a318513599b35ea4b075d7dc1cd1d04449578c29d1d75/ruff-0.15.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4ab064052c31dddada35079901592dfba2e05f5b1e43af3954aafcbc1096a5b2", size = 11137288, upload-time = "2026-02-12T23:09:07.475Z" },
+    { 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/cd/20/6f8d7d8f768c93b0382b33b9306b3b999918816da46537d5a61635514635/ruff-0.15.1-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:5631c940fe9fe91f817a4c2ea4e81f47bee3ca4aa646134a24374f3c19ad9454", size = 11070681, upload-time = "2026-02-12T23:08:55.43Z" },
+    { 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/9a/67/d640ac76069f64cdea59dba02af2e00b1fa30e2103c7f8d049c0cff4cafd/ruff-0.15.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:68138a4ba184b4691ccdc39f7795c66b3c68160c586519e7e8444cf5a53e1b4c", size = 10486401, upload-time = "2026-02-12T23:09:27.927Z" },
+    { 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/65/3d/e1429f64a3ff89297497916b88c32a5cc88eeca7e9c787072d0e7f1d3e1e/ruff-0.15.1-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:518f9af03bfc33c03bdb4cb63fabc935341bb7f54af500f92ac309ecfbba6330", size = 10197452, upload-time = "2026-02-12T23:09:12.147Z" },
+    { 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/78/83/e2c3bade17dad63bf1e1c2ffaf11490603b760be149e1419b07049b36ef2/ruff-0.15.1-py3-none-musllinux_1_2_i686.whl", hash = "sha256:da79f4d6a826caaea95de0237a67e33b81e6ec2e25fc7e1993a4015dffca7c61", size = 10693900, upload-time = "2026-02-12T23:09:34.418Z" },
+    { 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/a1/27/fdc0e11a813e6338e0706e8b39bb7a1d61ea5b36873b351acee7e524a72a/ruff-0.15.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:3dd86dccb83cd7d4dcfac303ffc277e6048600dfc22e38158afa208e8bf94a1f", size = 11227302, upload-time = "2026-02-12T23:09:36.536Z" },
+    { 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/f6/58/ac864a75067dcbd3b95be5ab4eb2b601d7fbc3d3d736a27e391a4f92a5c1/ruff-0.15.1-py3-none-win32.whl", hash = "sha256:660975d9cb49b5d5278b12b03bb9951d554543a90b74ed5d366b20e2c57c2098", size = 10462555, upload-time = "2026-02-12T23:09:29.899Z" },
+    { 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/e0/5e/d4ccc8a27ecdb78116feac4935dfc39d1304536f4296168f91ed3ec00cd2/ruff-0.15.1-py3-none-win_amd64.whl", hash = "sha256:c820fef9dd5d4172a6570e5721704a96c6679b80cf7be41659ed439653f62336", size = 11599956, upload-time = "2026-02-12T23:09:01.157Z" },
+    { 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/2a/07/5bda6a85b220c64c65686bc85bd0bbb23b29c62b3a9f9433fa55f17cda93/ruff-0.15.1-py3-none-win_arm64.whl", hash = "sha256:5ff7d5f0f88567850f45081fac8f4ec212be8d0b963e385c3f7d0d2eb4899416", size = 10874604, upload-time = "2026-02-12T23:09:05.515Z" },
+    { 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" },
 ]
 
 [[package]]
@@ -1201,31 +1177,31 @@ wheels = [
 
 [[package]]
 name = "ty"
-version = "0.0.17"
+version = "0.0.18"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/66/c3/41ae6346443eedb65b96761abfab890a48ce2aa5a8a27af69c5c5d99064d/ty-0.0.17.tar.gz", hash = "sha256:847ed6c120913e280bf9b54d8eaa7a1049708acb8824ad234e71498e8ad09f97", size = 5167209, upload-time = "2026-02-13T13:26:36.835Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c0/01/0ef15c22a1c54b0f728ceff3f62d478dbf8b0dcf8ff7b80b954f79584f3e/ty-0.0.17-py3-none-linux_armv6l.whl", hash = "sha256:64a9a16555cc8867d35c2647c2f1afbd3cae55f68fd95283a574d1bb04fe93e0", size = 10192793, upload-time = "2026-02-13T13:27:13.943Z" },
+    { 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/0f/2c/f4c322d9cded56edc016b1092c14b95cf58c8a33b4787316ea752bb9418e/ty-0.0.17-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:eb2dbd8acd5c5a55f4af0d479523e7c7265a88542efe73ed3d696eb1ba7b6454", size = 10051977, upload-time = "2026-02-13T13:26:57.741Z" },
+    { 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/4c/a5/43746c1ff81e784f5fc303afc61fe5bcd85d0fcf3ef65cb2cef78c7486c7/ty-0.0.17-py3-none-macosx_11_0_arm64.whl", hash = "sha256:f18f5fd927bc628deb9ea2df40f06b5f79c5ccf355db732025a3e8e7152801f6", size = 9564639, upload-time = "2026-02-13T13:26:42.781Z" },
+    { 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/d6/b8/280b04e14a9c0474af574f929fba2398b5e1c123c1e7735893b4cd73d13c/ty-0.0.17-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5383814d1d7a5cc53b3b07661856bab04bb2aac7a677c8d33c55169acdaa83df", size = 10061204, upload-time = "2026-02-13T13:27:00.152Z" },
+    { 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/2a/d7/493e1607d8dfe48288d8a768a2adc38ee27ef50e57f0af41ff273987cda0/ty-0.0.17-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9c20423b8744b484f93e7bf2ef8a9724bca2657873593f9f41d08bd9f83444c9", size = 10013116, upload-time = "2026-02-13T13:26:34.543Z" },
+    { 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/80/ef/22f3ed401520afac90dbdf1f9b8b7755d85b0d5c35c1cb35cf5bd11b59c2/ty-0.0.17-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e6f5b1aba97db9af86517b911674b02f5bc310750485dc47603a105bd0e83ddd", size = 10533623, upload-time = "2026-02-13T13:26:31.449Z" },
+    { 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/75/ce/744b15279a11ac7138832e3a55595706b4a8a209c9f878e3ab8e571d9032/ty-0.0.17-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:488bce1a9bea80b851a97cd34c4d2ffcd69593d6c3f54a72ae02e5c6e47f3d0c", size = 11069750, upload-time = "2026-02-13T13:26:48.638Z" },
+    { 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/f2/be/1133c91f15a0e00d466c24f80df486d630d95d1b2af63296941f7473812f/ty-0.0.17-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8df66b91ec84239420985ec215e7f7549bfda2ac036a3b3c065f119d1c06825a", size = 10870862, upload-time = "2026-02-13T13:26:54.715Z" },
+    { 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/3e/4a/a2ed209ef215b62b2d3246e07e833081e07d913adf7e0448fc204be443d6/ty-0.0.17-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:002139e807c53002790dfefe6e2f45ab0e04012e76db3d7c8286f96ec121af8f", size = 10628118, upload-time = "2026-02-13T13:26:45.439Z" },
+    { 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/b3/0c/87476004cb5228e9719b98afffad82c3ef1f84334bde8527bcacba7b18cb/ty-0.0.17-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:6c4e01f05ce82e5d489ab3900ca0899a56c4ccb52659453780c83e5b19e2b64c", size = 10038185, upload-time = "2026-02-13T13:27:02.693Z" },
+    { 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/46/4b/98f0b3ba9aef53c1f0305519536967a4aa793a69ed72677b0a625c5313ac/ty-0.0.17-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:2b226dd1e99c0d2152d218c7e440150d1a47ce3c431871f0efa073bbf899e881", size = 10047644, upload-time = "2026-02-13T13:27:05.474Z" },
+    { 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/93/e0/06737bb80aa1a9103b8651d2eb691a7e53f1ed54111152be25f4a02745db/ty-0.0.17-py3-none-musllinux_1_2_i686.whl", hash = "sha256:8b11f1da7859e0ad69e84b3c5ef9a7b055ceed376a432fad44231bdfc48061c2", size = 10231140, upload-time = "2026-02-13T13:27:10.844Z" },
+    { 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/7c/79/e2a606bd8852383ba9abfdd578f4a227bd18504145381a10a5f886b4e751/ty-0.0.17-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:c04e196809ff570559054d3e011425fd7c04161529eb551b3625654e5f2434cb", size = 10718344, upload-time = "2026-02-13T13:26:51.66Z" },
+    { 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/c5/2d/2663984ac11de6d78f74432b8b14ba64d170b45194312852b7543cf7fd56/ty-0.0.17-py3-none-win32.whl", hash = "sha256:305b6ed150b2740d00a817b193373d21f0767e10f94ac47abfc3b2e5a5aec809", size = 9672932, upload-time = "2026-02-13T13:27:08.522Z" },
+    { 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/de/b5/39be78f30b31ee9f5a585969930c7248354db90494ff5e3d0756560fb731/ty-0.0.17-py3-none-win_amd64.whl", hash = "sha256:531828267527aee7a63e972f54e5eee21d9281b72baf18e5c2850c6b862add83", size = 10542138, upload-time = "2026-02-13T13:27:17.084Z" },
+    { 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/40/b7/f875c729c5d0079640c75bad2c7e5d43edc90f16ba242f28a11966df8f65/ty-0.0.17-py3-none-win_arm64.whl", hash = "sha256:de9810234c0c8d75073457e10a84825b9cd72e6629826b7f01c7a0b266ae25b1", size = 10023068, upload-time = "2026-02-13T13:26:39.637Z" },
+    { 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" },
 ]
 
 [[package]]
 name = "typer"
-version = "0.24.0"
+version = "0.24.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
@@ -1233,9 +1209,9 @@ dependencies = [
     { name = "rich" },
     { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/5a/b6/3e681d3b6bb22647509bdbfdd18055d5adc0dce5c5585359fa46ff805fdc/typer-0.24.0.tar.gz", hash = "sha256:f9373dc4eff901350694f519f783c29b6d7a110fc0dcc11b1d7e353b85ca6504", size = 118380, upload-time = "2026-02-16T22:08:48.496Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/85/d0/4da85c2a45054bb661993c93524138ace4956cb075a7ae0c9d1deadc331b/typer-0.24.0-py3-none-any.whl", hash = "sha256:5fc435a9c8356f6160ed6e85a6301fdd6e3d8b2851da502050d1f92c5e9eddc8", size = 56441, upload-time = "2026-02-16T22:08:47.535Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
 ]
 
 [[package]]

zensical.toml

@@ -1,265 +1,35 @@
-# ============================================================================
-#
-# The configuration produced by default is meant to highlight the features
-# that Zensical provides and to serve as a starting point for your own
-# projects.
-#
-# ============================================================================
-
 [project]
-
-# The site_name is shown in the page header and the browser window title
-#
-# Read more: https://zensical.org/docs/setup/basics/#site_name
 site_name = "FastAPI Toolsets"
-
-# The site_description is included in the HTML head and should contain a
-# meaningful description of the site content for use by search engines.
-#
-# Read more: https://zensical.org/docs/setup/basics/#site_description
 site_description = "Production-ready utilities for FastAPI applications."
-
-# The site_author attribute. This is used in the HTML head element.
-#
-# Read more: https://zensical.org/docs/setup/basics/#site_author
 site_author = "d3vyce"
-
-# The site_url is the canonical URL for your site. When building online
-# documentation you should set this.
-# Read more: https://zensical.org/docs/setup/basics/#site_url
 site_url = "https://fastapi-toolsets.d3vyce.fr"
-
+copyright = "Copyright © 2026 d3vyce"
-# The copyright notice appears in the page footer and can contain an HTML
-# fragment.
-#
-# Read more: https://zensical.org/docs/setup/basics/#copyright
-copyright = """
-Copyright © 2026 d3vyce
-"""
-
 repo_url = "https://github.com/d3vyce/fastapi-toolsets"
 
-# Zensical supports both implicit navigation and explicitly defined navigation.
-# If you decide not to define a navigation here then Zensical will simply
-# derive the navigation structure from the directory structure of your
-# "docs_dir". The definition below demonstrates how a navigation structure
-# can be defined using TOML syntax.
-#
-# Read more: https://zensical.org/docs/setup/navigation/
-# nav = [
-#   { "Get started" = "index.md" },
-#   { "Markdown in 5min" = "markdown.md" },
-# ]
-
-# With the "extra_css" option you can add your own CSS styling to customize
-# your Zensical project according to your needs. You can add any number of
-# CSS files.
-#
-# The path provided should be relative to the "docs_dir".
-#
-# Read more: https://zensical.org/docs/customization/#additional-css
-#
-#extra_css = ["stylesheets/extra.css"]
-
-# With the `extra_javascript` option you can add your own JavaScript to your
-# project to customize the behavior according to your needs.
-#
-# The path provided should be relative to the "docs_dir".
-#
-# Read more: https://zensical.org/docs/customization/#additional-javascript
-#extra_javascript = ["javascripts/extra.js"]
-
-# ----------------------------------------------------------------------------
-# Section for configuring theme options
-# ----------------------------------------------------------------------------
 [project.theme]
-
-# change this to "classic" to use the traditional Material for MkDocs look.
-#variant = "classic"
-
-# Zensical allows you to override specific blocks, partials, or whole
-# templates as well as to define your own templates. To do this, uncomment
-# the custom_dir setting below and set it to a directory in which you
-# keep your template overrides.
-#
-# Read more:
-# - https://zensical.org/docs/customization/#extending-the-theme
-#
 custom_dir = "docs/overrides"
-
-# With the "favicon" option you can set your own image to use as the icon
-# browsers will use in the browser title bar or tab bar. The path provided
-# must be relative to the "docs_dir".
-#
-# Read more:
-# - https://zensical.org/docs/setup/logo-and-icons/#favicon
-# - https://developer.mozilla.org/en-US/docs/Glossary/Favicon
-#
-#favicon = "images/favicon.png"
-
-# Zensical supports more than 60 different languages. This means that the
-# labels and tooltips that Zensical's templates produce are translated.
-# The "language" option allows you to set the language used. This language
-# is also indicated in the HTML head element to help with accessibility
-# and guide search engines and translation tools.
-#
-# The default language is "en" (English). It is possible to create
-# sites with multiple languages and configure a language selector. See
-# the documentation for details.
-#
-# Read more:
-# - https://zensical.org/docs/setup/language/
-#
 language = "en"
-
-# Zensical provides a number of feature toggles that change the behavior
-# of the documentation site.
 features = [
-    # Zensical includes an announcement bar. This feature allows users to
-    # dismiss it when they have read the announcement.
-    # https://zensical.org/docs/setup/header/#announcement-bar
     "announce.dismiss",
-
-    # If you have a repository configured and turn on this feature, Zensical
-    # will generate an edit button for the page. This works for common
-    # repository hosting services.
-    # https://zensical.org/docs/setup/repository/#content-actions
-    #"content.action.edit",
-
-    # If you have a repository configured and turn on this feature, Zensical
-    # will generate a button that allows the user to view the Markdown
-    # code for the current page.
-    # https://zensical.org/docs/setup/repository/#content-actions
     "content.action.view",
-
-    # Code annotations allow you to add an icon with a tooltip to your
-    # code blocks to provide explanations at crucial points.
-    # https://zensical.org/docs/authoring/code-blocks/#code-annotations
     "content.code.annotate",
-
-    # This feature turns on a button in code blocks that allow users to
-    # copy the content to their clipboard without first selecting it.
-    # https://zensical.org/docs/authoring/code-blocks/#code-copy-button
     "content.code.copy",
-
-    # Code blocks can include a button to allow for the selection of line
-    # ranges by the user.
-    # https://zensical.org/docs/authoring/code-blocks/#code-selection-button
     "content.code.select",
-
-    # Zensical can render footnotes as inline tooltips, so the user can read
-    # the footnote without leaving the context of the document.
-    # https://zensical.org/docs/authoring/footnotes/#footnote-tooltips
     "content.footnote.tooltips",
-
-    # If you have many content tabs that have the same titles (e.g., "Python",
-    # "JavaScript", "Cobol"), this feature causes all of them to switch to
-    # at the same time when the user chooses their language in one.
-    # https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs
     "content.tabs.link",
-
-    # With this feature enabled users can add tooltips to links that will be
-    # displayed when the mouse pointer hovers the link.
-    # https://zensical.org/docs/authoring/tooltips/#improved-tooltips
     "content.tooltips",
-
-    # With this feature enabled, Zensical will automatically hide parts
-    # of the header when the user scrolls past a certain point.
-    # https://zensical.org/docs/setup/header/#automatic-hiding
-    # "header.autohide",
-
-    # Turn on this feature to expand all collapsible sections in the
-    # navigation sidebar by default.
-    # https://zensical.org/docs/setup/navigation/#navigation-expansion
-    # "navigation.expand",
-
-    # This feature turns on navigation elements in the footer that allow the
-    # user to navigate to a next or previous page.
-    # https://zensical.org/docs/setup/footer/#navigation
     "navigation.footer",
-
-    # When section index pages are enabled, documents can be directly attached
-    # to sections, which is particularly useful for providing overview pages.
-    # https://zensical.org/docs/setup/navigation/#section-index-pages
     "navigation.indexes",
-
-    # When instant navigation is enabled, clicks on all internal links will be
-    # intercepted and dispatched via XHR without fully reloading the page.
-    # https://zensical.org/docs/setup/navigation/#instant-navigation
     "navigation.instant",
-
-    # With instant prefetching, your site will start to fetch a page once the
-    # user hovers over a link. This will reduce the perceived loading time
-    # for the user.
-    # https://zensical.org/docs/setup/navigation/#instant-prefetching
     "navigation.instant.prefetch",
-
-    # In order to provide a better user experience on slow connections when
-    # using instant navigation, a progress indicator can be enabled.
-    # https://zensical.org/docs/setup/navigation/#progress-indicator
-    #"navigation.instant.progress",
-
-    # When navigation paths are activated, a breadcrumb navigation is rendered
-    # above the title of each page
-    # https://zensical.org/docs/setup/navigation/#navigation-path
     "navigation.path",
-
-    # When pruning is enabled, only the visible navigation items are included
-    # in the rendered HTML, reducing the size of the built site by 33% or more.
-    # https://zensical.org/docs/setup/navigation/#navigation-pruning
-    #"navigation.prune",
-
-    # When sections are enabled, top-level sections are rendered as groups in
-    # the sidebar for viewports above 1220px, but remain as-is on mobile.
-    # https://zensical.org/docs/setup/navigation/#navigation-sections
     "navigation.sections",
-
-    # When tabs are enabled, top-level sections are rendered in a menu layer
-    # below the header for viewports above 1220px, but remain as-is on mobile.
-    # https://zensical.org/docs/setup/navigation/#navigation-tabs
     "navigation.tabs",
-
-    # When sticky tabs are enabled, navigation tabs will lock below the header
-    # and always remain visible when scrolling down.
-    # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs
-    #"navigation.tabs.sticky",
-
-    # A back-to-top button can be shown when the user, after scrolling down,
-    # starts to scroll up again.
-    # https://zensical.org/docs/setup/navigation/#back-to-top-button
     "navigation.top",
-
-    # When anchor tracking is enabled, the URL in the address bar is
-    # automatically updated with the active anchor as highlighted in the table
-    # of contents.
-    # https://zensical.org/docs/setup/navigation/#anchor-tracking
     "navigation.tracking",
-
-    # When search highlighting is enabled and a user clicks on a search result,
-    # Zensical will highlight all occurrences after following the link.
-    # https://zensical.org/docs/setup/search/#search-highlighting
     "search.highlight",
-
-    # When anchor following for the table of contents is enabled, the sidebar
-    # is automatically scrolled so that the active anchor is always visible.
-    # https://zensical.org/docs/setup/navigation/#anchor-following
-    # "toc.follow",
-
-    # When navigation integration for the table of contents is enabled, it is
-    # always rendered as part of the navigation sidebar on the left.
-    # https://zensical.org/docs/setup/navigation/#navigation-integration
-    #"toc.integrate",
 ]
 
-# ----------------------------------------------------------------------------
-# In the "palette" subsection you can configure options for the color scheme.
-# You can configure different color # schemes, e.g., to turn on dark mode,
-# that the user can switch between. Each color scheme can be further
-# customized.
-#
-# Read more:
-# - https://zensical.org/docs/setup/colors/
-# ----------------------------------------------------------------------------
 [[project.theme.palette]]
 scheme = "default"
 toggle.icon = "lucide/sun"
@@ -270,43 +40,13 @@ scheme = "slate"
 toggle.icon = "lucide/moon"
 toggle.name = "Switch to light mode"
 
-# ----------------------------------------------------------------------------
-# In the "font" subsection you can configure the fonts used. By default, fonts
-# are loaded from Google Fonts, giving you a wide range of choices from a set
-# of suitably licensed fonts. There are options for a normal text font and for
-# a monospaced font used in code blocks.
-# ----------------------------------------------------------------------------
 [project.theme.font]
 text = "Inter"
 code = "Jetbrains Mono"
 
-# ----------------------------------------------------------------------------
-# You can configure your own logo to be shown in the header using the "logo"
-# option in the "icons" subsection. The logo can be a path to a file in your
-# "docs_dir" or it can be a path to an icon.
-#
-# Likewise, you can customize the logo used for the repository section of the
-# header. Zensical derives the default logo for this from the repository URL.
-# See below...
-#
-# There are other icons you can customize. See the documentation for details.
-#
-# Read more:
-# - https://zensical.org/docs/setup/logo-and-icons
-# - https://zensical.org/docs/authoring/icons-emojis/#search
-# ----------------------------------------------------------------------------
 [project.theme.icon]
-#logo = "lucide/smile"
 repo = "fontawesome/brands/github"
 
-# ----------------------------------------------------------------------------
-# The "extra" section contains miscellaneous settings.
-# ----------------------------------------------------------------------------
-#[[project.extra.social]]
-#icon = "fontawesome/brands/github"
-#link = "https://github.com/user/repo"
-
-
 [project.plugins.mkdocstrings.handlers.python]
 inventories = ["https://docs.python.org/3/objects.inv"]
 paths = ["src"]
@@ -316,3 +56,42 @@ docstring_style = "google"
 inherited_members = true
 show_source = false
 show_root_heading = true
+
+[project.markdown_extensions]
+abbr = {}
+admonition = {}
+attr_list = {}
+def_list = {}
+footnotes = {}
+md_in_html = {}
+"pymdownx.arithmatex" = {generic = true}
+"pymdownx.betterem" = {}
+"pymdownx.caret" = {}
+"pymdownx.details" = {}
+"pymdownx.emoji" = {}
+"pymdownx.inlinehilite" = {}
+"pymdownx.keys" = {}
+"pymdownx.magiclink" = {}
+"pymdownx.mark" = {}
+"pymdownx.smartsymbols" = {}
+"pymdownx.tasklist" = {custom_checkbox = true}
+"pymdownx.tilde" = {}
+
+[project.markdown_extensions."pymdownx.highlight"]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+
+[project.markdown_extensions."pymdownx.superfences"]
+custom_fences = [{name = "mermaid", class = "mermaid"}]
+
+[project.markdown_extensions."pymdownx.tabbed"]
+alternate_style = true
+combine_header_slug = true
+
+[project.markdown_extensions."toc"]
+permalink = true
+
+[project.markdown_extensions."pymdownx.snippets"]
+base_path = ["."]
+check_paths = true