Add sort_params helper in CrudFactory (#103)

* feat: add sort_params helper in CrudFactory

* docs: add sorting

* fix: change sort_by to order_by

tests/test_crud_search.py

@@ -1,9 +1,11 @@
 """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 (
     CrudFactory,
@@ -11,6 +13,7 @@ from fastapi_toolsets.crud import (
     SearchConfig,
     get_searchable_fields,
 )
+from fastapi_toolsets.exceptions import InvalidOrderFieldError
 from fastapi_toolsets.schemas import OffsetPagination
 
 from .conftest import (
@@ -1014,3 +1017,144 @@ class TestFilterParamsSchema:
 
         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"