feat: expose sort_columns in paginated response (#225)

tests/test_crud.py

@@ -247,6 +247,45 @@ class TestResolveSearchColumns:
         assert "username" not in result
 
 
+class TestResolveSortColumns:
+    """Tests for _resolve_sort_columns logic."""
+
+    def test_returns_none_when_no_order_fields(self):
+        """Returns None when cls.order_fields is None and no order_fields passed."""
+
+        class AbstractCrud(AsyncCrud[User]):
+            pass
+
+        assert AbstractCrud._resolve_sort_columns(None) is None
+
+    def test_returns_none_when_empty_order_fields_passed(self):
+        """Returns None when an empty list is passed explicitly."""
+        crud = CrudFactory(User)
+        assert crud._resolve_sort_columns([]) is None
+
+    def test_returns_keys_from_class_order_fields(self):
+        """Returns sorted column keys from cls.order_fields when no override passed."""
+        crud = CrudFactory(User, order_fields=[User.username])
+        result = crud._resolve_sort_columns(None)
+        assert result is not None
+        assert "username" in result
+
+    def test_order_fields_override_takes_priority(self):
+        """Explicit order_fields override cls.order_fields."""
+        crud = CrudFactory(User, order_fields=[User.username])
+        result = crud._resolve_sort_columns([User.email])
+        assert result is not None
+        assert "email" in result
+        assert "username" not in result
+
+    def test_returns_sorted_keys(self):
+        """Keys are returned in sorted order."""
+        crud = CrudFactory(User, order_fields=[User.email, User.username])
+        result = crud._resolve_sort_columns(None)
+        assert result is not None
+        assert result == sorted(result)
+
+
 class TestDefaultLoadOptionsIntegration:
     """Integration tests for default_load_options with real DB queries."""
 

tests/test_crud_search.py

@@ -1516,6 +1516,101 @@ class TestSearchColumns:
         assert result.data[0].username == "bob"
 
 
+class TestSortColumns:
+    """Tests for sort_columns in paginated responses."""
+
+    @pytest.mark.anyio
+    async def test_sort_columns_returned_in_offset_paginate(
+        self, db_session: AsyncSession
+    ):
+        """offset_paginate response includes sort_columns."""
+        UserSortCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.sort_columns is not None
+        assert "username" in result.sort_columns
+        assert "email" in result.sort_columns
+
+    @pytest.mark.anyio
+    async def test_sort_columns_returned_in_cursor_paginate(
+        self, db_session: AsyncSession
+    ):
+        """cursor_paginate response includes sort_columns."""
+        UserSortCursorCrud = CrudFactory(
+            User,
+            cursor_column=User.id,
+            order_fields=[User.username, User.email],
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCursorCrud.cursor_paginate(db_session, schema=UserRead)
+
+        assert result.sort_columns is not None
+        assert "username" in result.sort_columns
+        assert "email" in result.sort_columns
+
+    @pytest.mark.anyio
+    async def test_sort_columns_none_when_no_order_fields(
+        self, db_session: AsyncSession
+    ):
+        """sort_columns is None when no order_fields are configured."""
+        result = await UserCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.sort_columns is None
+
+    @pytest.mark.anyio
+    async def test_sort_columns_override_in_offset_paginate(
+        self, db_session: AsyncSession
+    ):
+        """order_fields override in offset_paginate is reflected in sort_columns."""
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserCrud.offset_paginate(
+            db_session, order_fields=[User.email], schema=UserRead
+        )
+
+        assert result.sort_columns == ["email"]
+
+    @pytest.mark.anyio
+    async def test_sort_columns_override_in_cursor_paginate(
+        self, db_session: AsyncSession
+    ):
+        """order_fields override in cursor_paginate is reflected in sort_columns."""
+        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, order_fields=[User.username], schema=UserRead
+        )
+
+        assert result.sort_columns == ["username"]
+
+    @pytest.mark.anyio
+    async def test_sort_columns_are_sorted_alphabetically(
+        self, db_session: AsyncSession
+    ):
+        """sort_columns keys are returned in alphabetical order."""
+        UserSortCrud = CrudFactory(User, order_fields=[User.email, User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.sort_columns is not None
+        assert result.sort_columns == sorted(result.sort_columns)
+
+
 class TestOrderParamsViaConsolidated:
     """Tests for order params via consolidated offset_paginate_params()."""