pyferro 2.0.0__tar.gz → 2.0.1__tar.gz

{pyferro-2.0.0 → pyferro-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyferro
-Version: 2.0.0
+Version: 2.0.1
 Summary: High-performance reactive fullstack Python framework on Rust RSGI (Granian) with symmetric WSRPC (JSON-RPC 2.0) and Tabular Data Compression.
 Author-email: Alex Titoff <a.tit.off@gmail.com>
 License: MIT
@@ -252,3 +252,13 @@ example.com {
 | `POST /upload` | Потоковая закачка файлов во временную транзакцию (`O(1)` RAM) |
 | `GET /files/<folder>/<name>` | Защищенная раздача файлов (поддержка `X-Accel-Redirect` и файловых JWT) |
 | `GET /pyferro_admin` | Встроенная панель управления RBAC и CRUD (маршрут `/admin` свободен для вашего приложения) |
+
+---
+
+## 6. Табличная пагинация и сжатие трафика ($tabular)
+
+PyFerro 2.0 включает высокопроизводительную подсистему пагинации для SQLAlchemy и фронтенда:
+
+- **Бэкенд:** `paginate_tabular(db, Model, **params)` — выполняет поиск, фильтры, сортировку, умный `count(*)` и пакует ответ в сжатый протокол `$tabular` за **1 строчку кода**.
+- **Фронтенд:** `createPaginator("Model.read")` + компонент `<Pagination />` — полностью берут на себя состояние, номера страниц `[1, '...', 4, 5, 6, '...', 25]`, стрелки «Назад/Вперед» и живой поиск.
+- **Подробное руководство:** см. [PAGINATION.md](PAGINATION.md).

{pyferro-2.0.0 → pyferro-2.0.1}/README.md

@@ -230,3 +230,13 @@ example.com {
 | `POST /upload` | Потоковая закачка файлов во временную транзакцию (`O(1)` RAM) |
 | `GET /files/<folder>/<name>` | Защищенная раздача файлов (поддержка `X-Accel-Redirect` и файловых JWT) |
 | `GET /pyferro_admin` | Встроенная панель управления RBAC и CRUD (маршрут `/admin` свободен для вашего приложения) |
+
+---
+
+## 6. Табличная пагинация и сжатие трафика ($tabular)
+
+PyFerro 2.0 включает высокопроизводительную подсистему пагинации для SQLAlchemy и фронтенда:
+
+- **Бэкенд:** `paginate_tabular(db, Model, **params)` — выполняет поиск, фильтры, сортировку, умный `count(*)` и пакует ответ в сжатый протокол `$tabular` за **1 строчку кода**.
+- **Фронтенд:** `createPaginator("Model.read")` + компонент `<Pagination />` — полностью берут на себя состояние, номера страниц `[1, '...', 4, 5, 6, '...', 25]`, стрелки «Назад/Вперед» и живой поиск.
+- **Подробное руководство:** см. [PAGINATION.md](PAGINATION.md).

{pyferro-2.0.0 → pyferro-2.0.1}/core/tabular.py

@@ -12,11 +12,12 @@ from typing import Any
 
 
 def pack_tabular(
-    items: Sequence[dict[str, Any] | tuple[Any, ...] | list[Any]],
+    items: Sequence[Any],
     fields: Sequence[str] | None = None,
 ) -> dict[str, Any] | Any:
     """
-    Упаковывает список словарей или кортежей в табличный пакет `{"$tabular": True, "fields": [...], "rows": [...]}`.
+    Упаковывает список словарей, кортежей или SQLAlchemy Row в табличный пакет
+    `{"$tabular": True, "fields": [...], "rows": [...]}`.
     """
     if not items:
         return {
@@ -26,6 +27,17 @@ def pack_tabular(
         }
 
     first = items[0]
+
+    # Поддержка SQLAlchemy Row / RowMapping (объектов с атрибутом _mapping)
+    if hasattr(first, "_mapping"):
+        field_list = list(fields) if fields is not None else list(first._mapping.keys())
+        rows = [[getattr(item, "_mapping").get(f) for f in field_list] for item in items]
+        return {
+            "$tabular": True,
+            "fields": field_list,
+            "rows": rows,
+        }
+
     if isinstance(first, dict):
         field_list = list(fields) if fields is not None else list(first.keys())
         rows = [[item.get(f) for f in field_list] for item in items]  # type: ignore[union-attr]
@@ -86,9 +98,12 @@ def is_tabular(data: Any) -> bool:
 def apply_tabular_result(result: Any, fields: Sequence[str] | None = None) -> Any:
     """
     Автоматически упаковывает результат RPC-метода (если включен `@rpc_method(tabular=True)`):
+    - Если уже передан готовый `$tabular` пакет -> возвращает как есть.
     - Если возвращен `list[dict]` -> упаковывает сам список.
     - Если возвращен `dict` с ключом `"items"` (или `"rows"`, `"records"`, `"data"`) -> упаковывает вложенный список.
     """
+    if is_tabular(result):
+        return result
     if isinstance(result, list):
         return pack_tabular(result, fields=fields)
     if isinstance(result, dict) and not is_tabular(result):

{pyferro-2.0.0 → pyferro-2.0.1}/db/__init__.py

@@ -4,10 +4,14 @@
 
 from pyferro2.db.base import Base, RowSecureModel
 from pyferro2.db.engine import DEFAULT_DB_URL, Database
+from pyferro2.db.pagination import decode_cursor, encode_cursor, paginate_tabular
 
 __all__ = [
     "Base",
     "RowSecureModel",
     "Database",
     "DEFAULT_DB_URL",
+    "paginate_tabular",
+    "encode_cursor",
+    "decode_cursor",
 ]

pyferro-2.0.1/db/pagination.py

@@ -0,0 +1,333 @@
+"""
+Высокопроизводительная пагинация для SQLAlchemy 2.0 с автоматической упаковкой в Tabular Data ($tabular).
+
+Поддерживает:
+- Вызов от модели или `Select`: `paginate_tabular(db, Book, **params)` или `paginate_tabular(db, select(Book).where(...), **params)`.
+- Два режима:
+    1. Offset-пагинация (`page=1, limit=20`) с оптимизированным `count(*)` (очистка `order_by`).
+    2. Keyset / Cursor-пагинация (`cursor="...", limit=20`) с выборкой $O(1)$ по индексу без подсчета `count`.
+- Авто-трансляцию фильтров (`filters={"genre": "fiction"}`) и поиска (`search="текст"`).
+- Zero-Hydration: извлечение чистых кортежей или атрибутов с конвертацией `datetime`, `UUID`, `Enum`, `Decimal`.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+import json
+import math
+from typing import Any, TypeVar
+import uuid
+
+from sqlalchemy import Select, String, Text, Unicode, UnicodeText, func, inspect, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from pyferro2.db.base import Base
+
+T = TypeVar("T", bound=Base)
+
+
+def _serialize_val(val: Any) -> Any:
+    """Безопасно преобразует значение ячейки базы данных в сериализуемый JSON-вид."""
+    if val is None or isinstance(val, (int, float, str, bool)):
+        return val
+    if isinstance(val, (datetime, date, time)):
+        return val.isoformat()
+    if isinstance(val, uuid.UUID):
+        return str(val)
+    if isinstance(val, Decimal):
+        return float(val)
+    if isinstance(val, Enum):
+        return val.value
+    if isinstance(val, (list, tuple)):
+        return [_serialize_val(v) for v in val]
+    if isinstance(val, dict):
+        return {k: _serialize_val(v) for k, v in val.items()}
+    return str(val)
+
+
+def encode_cursor(val: Any, col: str = "id", direction: str = "desc") -> str:
+    """Кодирует значение граничной записи в URL-safe base64 токен курсора."""
+    payload = {
+        "v": _serialize_val(val),
+        "c": col,
+        "d": direction.lower(),
+    }
+    dumped = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+    return base64.urlsafe_b64encode(dumped.encode("utf-8")).decode("ascii")
+
+
+def decode_cursor(cursor: str) -> dict[str, Any]:
+    """Декодирует строку курсора обратно в словарь параметров."""
+    try:
+        raw = base64.urlsafe_b64decode(cursor.encode("ascii")).decode("utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict) or "v" not in data:
+            raise ValueError("Некорректная структура курсора")
+        return data
+    except Exception as e:
+        raise ValueError(f"Невалидный токен курсора: {cursor}") from e
+
+
+def _find_model_class(target: type[Base] | Select) -> type[Base] | None:
+    """Определяет модель DeclarativeBase из аргумента target (класса или Select-запроса)."""
+    if isinstance(target, type) and issubclass(target, Base):
+        return target
+    if isinstance(target, Select):
+        for desc in target.column_descriptions:
+            entity = desc.get("entity")
+            if isinstance(entity, type) and issubclass(entity, Base):
+                return entity
+    return None
+
+
+async def paginate_tabular(
+    db: AsyncSession,
+    target: type[Base] | Select,
+    *,
+    page: int | None = 1,
+    limit: int = 20,
+    cursor: str | None = None,
+    cursor_column: str = "id",
+    search: str | None = None,
+    search_fields: Sequence[str] | None = None,
+    filters: dict[str, Any] | None = None,
+    sort_by: str | None = None,
+    order: str = "desc",
+    fields: Sequence[str] | None = None,
+    count: bool = True,
+    max_limit: int = 500,
+    **extra_params: Any,
+) -> dict[str, Any]:
+    """
+    Высокопроизводительная пагинация запроса SQLAlchemy с отдачей сжатого пакета `$tabular`.
+
+    Параметры:
+    - `db`: сессия SQLAlchemy (`AsyncSession`).
+    - `target`: модель `Book` или сформированный `select(Book).where(...)`.
+    - `page`: номер страницы (1-indexed). Приоритет отдается `cursor`, если он передан.
+    - `limit`: максимальное количество строк (по умолчанию 20, ограничено `max_limit`).
+    - `cursor`: строковый токен для курсорной пагинации ($O(1)$ по индексу).
+    - `cursor_column`: колонка для курсора (по умолчанию "id").
+    - `search`: поисковая строка (автоматически транслируется в `ILIKE` по строковым полям).
+    - `search_fields`: явный список полей для поиска (если `None` — используются строковые поля модели).
+    - `filters`: словарь точных совпадений `{"status": "published", "category_id": 5}`.
+    - `sort_by`: имя колонки для сортировки.
+    - `order`: направление сортировки (`"asc"` или `"desc"`).
+    - `fields`: список желаемых колонок для вывода (если `None` — берутся все колонки модели).
+    - `count`: вычислять ли точный `total` в режиме `page` (по умолчанию `True`).
+    - `max_limit`: защитный максимум строк на страницу (по умолчанию 500).
+    """
+    safe_limit = max(1, min(int(limit or 20), max_limit))
+    model_cls = _find_model_class(target)
+
+    # 1. Приведение к Select
+    if isinstance(target, Select):
+        stmt = target
+    elif model_cls is not None:
+        stmt = select(model_cls)
+    else:
+        raise ValueError("Параметр 'target' должен быть моделью Base или объектом Select")
+
+    # 2. Авто-фильтрация по точному совпадению
+    if filters and isinstance(filters, dict) and model_cls is not None:
+        for fname, fval in filters.items():
+            if hasattr(model_cls, fname):
+                col = getattr(model_cls, fname)
+                if hasattr(col, "__clause_element__"):
+                    if isinstance(fval, (list, tuple, set)):
+                        stmt = stmt.where(col.in_(list(fval)))
+                    elif fval is not None:
+                        stmt = stmt.where(col == fval)
+
+    # 3. Авто-поиск по подстроке (ILIKE)
+    if search and str(search).strip():
+        search_term = f"%{str(search).strip()}%"
+        cols_to_search = []
+        if search_fields:
+            cols_to_search = [
+                getattr(model_cls, sf)
+                for sf in search_fields
+                if hasattr(model_cls, sf) and hasattr(getattr(model_cls, sf), "__clause_element__")
+            ]
+        elif model_cls is not None:
+            mapper = inspect(model_cls)
+            cols_to_search = [
+                col
+                for col in mapper.columns
+                if isinstance(col.type, (String, Text, Unicode, UnicodeText))
+            ]
+
+        if cols_to_search:
+            stmt = stmt.where(or_(*[c.ilike(search_term) for c in cols_to_search]))
+
+    # 4. Сортировка
+    current_direction = order.lower() if order else "desc"
+    active_sort_col_name = cursor_column
+    if sort_by and model_cls is not None and hasattr(model_cls, sort_by):
+        sort_col = getattr(model_cls, sort_by)
+        if hasattr(sort_col, "__clause_element__"):
+            active_sort_col_name = sort_by
+            stmt = stmt.order_by(sort_col.desc() if current_direction == "desc" else sort_col.asc())
+    elif not stmt._order_by_clauses and model_cls is not None and hasattr(model_cls, "id"):
+        stmt = stmt.order_by(model_cls.id.desc() if current_direction == "desc" else model_cls.id.asc())
+
+    # 5. Выполнение пагинации (Cursor vs Offset)
+    total: int | None = None
+    pages: int | None = None
+    has_prev = False
+    has_next = False
+    next_cursor: str | None = None
+    prev_cursor: str | None = None
+    safe_page: int | None = None
+
+    if cursor is not None:
+        # ─── РЕЖИМ КУРСОРА (Keyset) ───
+        decoded = decode_cursor(cursor)
+        c_val = decoded.get("v")
+        c_col = decoded.get("c", cursor_column)
+        c_dir = decoded.get("d", current_direction)
+
+        if model_cls is not None and hasattr(model_cls, c_col):
+            col_target = getattr(model_cls, c_col)
+            if hasattr(col_target, "__clause_element__"):
+                if c_dir == "desc":
+                    stmt = stmt.where(col_target < c_val)
+                else:
+                    stmt = stmt.where(col_target > c_val)
+
+        # Берем limit + 1 для определения has_next без вызова COUNT
+        exec_stmt = stmt.limit(safe_limit + 1)
+        res = await db.execute(exec_stmt)
+        raw_items = res.scalars().all() if _is_entity_select(stmt) else res.all()
+
+        has_prev = True
+        if len(raw_items) > safe_limit:
+            has_next = True
+            raw_items = raw_items[:safe_limit]
+        else:
+            has_next = False
+
+        if raw_items and has_next:
+            last_item = raw_items[-1]
+            last_val = _extract_item_value(last_item, c_col)
+            if last_val is not None:
+                next_cursor = encode_cursor(last_val, col=c_col, direction=c_dir)
+
+    else:
+        # ─── РЕЖИМ OFFSET ───
+        safe_page = max(1, int(page or 1))
+        offset = (safe_page - 1) * safe_limit
+
+        if count:
+            # Очищаем order_by в подзапросе подсчета для максимальной скорости СУБД
+            count_stmt = select(func.count()).select_from(stmt.order_by(None).subquery())
+            total = int((await db.execute(count_stmt)).scalar() or 0)
+            pages = max(1, math.ceil(total / safe_limit)) if total > 0 else 1
+            has_prev = safe_page > 1
+            has_next = (offset + safe_limit) < total
+
+            exec_stmt = stmt.offset(offset).limit(safe_limit)
+            res = await db.execute(exec_stmt)
+            raw_items = res.scalars().all() if _is_entity_select(stmt) else res.all()
+        else:
+            has_prev = safe_page > 1
+            exec_stmt = stmt.offset(offset).limit(safe_limit + 1)
+            res = await db.execute(exec_stmt)
+            raw_items = res.scalars().all() if _is_entity_select(stmt) else res.all()
+            if len(raw_items) > safe_limit:
+                has_next = True
+                raw_items = raw_items[:safe_limit]
+            else:
+                has_next = False
+
+        if raw_items and has_next and model_cls is not None and hasattr(model_cls, active_sort_col_name):
+            last_item = raw_items[-1]
+            last_val = _extract_item_value(last_item, active_sort_col_name)
+            if last_val is not None:
+                next_cursor = encode_cursor(last_val, col=active_sort_col_name, direction=current_direction)
+
+    # 6. Извлечение колонок и формирование tabular строк
+    out_fields, tabular_rows = _format_tabular_rows(raw_items, stmt, model_cls, fields)
+
+    return {
+        "$tabular": True,
+        "fields": out_fields,
+        "rows": tabular_rows,
+        "limit": safe_limit,
+        "page": safe_page,
+        "total": total,
+        "pages": pages,
+        "has_next": has_next,
+        "has_prev": has_prev,
+        "next_cursor": next_cursor,
+        "prev_cursor": prev_cursor,
+    }
+
+
+def _is_entity_select(stmt: Select) -> bool:
+    """Проверяет, выбирает ли Select полноценные ORM-сущности (`scalars`) или плоские колонки."""
+    if not stmt.column_descriptions:
+        return False
+    first = stmt.column_descriptions[0]
+    entity = first.get("entity")
+    expr = first.get("expr")
+    return entity is not None and expr is entity
+
+
+def _extract_item_value(item: Any, col_name: str) -> Any:
+    """Извлекает значение поля из ORM-инстанса или Row-кортежа."""
+    if hasattr(item, col_name):
+        return getattr(item, col_name)
+    if hasattr(item, "_mapping") and col_name in item._mapping:
+        return item._mapping[col_name]
+    return None
+
+
+def _format_tabular_rows(
+    items: Sequence[Any],
+    stmt: Select,
+    model_cls: type[Base] | None,
+    desired_fields: Sequence[str] | None,
+) -> tuple[list[str], list[list[Any]]]:
+    """Формирует итоговый список полей и сериализованные массивы значений."""
+    if not items:
+        if desired_fields:
+            return list(desired_fields), []
+        if model_cls is not None:
+            mapper = inspect(model_cls)
+            return [col.key for col in mapper.columns], []
+        if stmt.column_descriptions:
+            return [desc["name"] for desc in stmt.column_descriptions], []
+        return [], []
+
+    first = items[0]
+
+    # Вариант 1: Строки Row (когда делался select(Book.id, Book.title))
+    if hasattr(first, "_mapping"):
+        row_fields = list(first._mapping.keys())
+        out_fields = list(desired_fields) if desired_fields else row_fields
+        tabular_rows = [
+            [_serialize_val(row._mapping.get(f)) for f in out_fields]
+            for row in items
+        ]
+        return out_fields, tabular_rows
+
+    # Вариант 2: ORM-инстансы (когда делался select(Book) или передан класс Book)
+    if model_cls is not None:
+        mapper = inspect(model_cls)
+        all_cols = [col.key for col in mapper.columns]
+        out_fields = list(desired_fields) if desired_fields else all_cols
+    elif desired_fields:
+        out_fields = list(desired_fields)
+    else:
+        out_fields = [k for k in dir(first) if not k.startswith("_")]
+
+    tabular_rows = [
+        [_serialize_val(getattr(item, f, None)) for f in out_fields]
+        for item in items
+    ]
+    return out_fields, tabular_rows

{pyferro-2.0.0 → pyferro-2.0.1}/pyferro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyferro
-Version: 2.0.0
+Version: 2.0.1
 Summary: High-performance reactive fullstack Python framework on Rust RSGI (Granian) with symmetric WSRPC (JSON-RPC 2.0) and Tabular Data Compression.
 Author-email: Alex Titoff <a.tit.off@gmail.com>
 License: MIT
@@ -252,3 +252,13 @@ example.com {
 | `POST /upload` | Потоковая закачка файлов во временную транзакцию (`O(1)` RAM) |
 | `GET /files/<folder>/<name>` | Защищенная раздача файлов (поддержка `X-Accel-Redirect` и файловых JWT) |
 | `GET /pyferro_admin` | Встроенная панель управления RBAC и CRUD (маршрут `/admin` свободен для вашего приложения) |
+
+---
+
+## 6. Табличная пагинация и сжатие трафика ($tabular)
+
+PyFerro 2.0 включает высокопроизводительную подсистему пагинации для SQLAlchemy и фронтенда:
+
+- **Бэкенд:** `paginate_tabular(db, Model, **params)` — выполняет поиск, фильтры, сортировку, умный `count(*)` и пакует ответ в сжатый протокол `$tabular` за **1 строчку кода**.
+- **Фронтенд:** `createPaginator("Model.read")` + компонент `<Pagination />` — полностью берут на себя состояние, номера страниц `[1, '...', 4, 5, 6, '...', 25]`, стрелки «Назад/Вперед» и живой поиск.
+- **Подробное руководство:** см. [PAGINATION.md](PAGINATION.md).

{pyferro-2.0.0 → pyferro-2.0.1}/pyferro.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ crud/spec.py
 db/__init__.py
 db/base.py
 db/engine.py
+db/pagination.py
 files/__init__.py
 files/models.py
 files/rpc.py
@@ -34,4 +35,5 @@ server/app.py
 server/auth_rpc.py
 server/test_client.py
 server/tokens.py
-tests/test_e2e_lifecycle.py
+tests/test_e2e_lifecycle.py
+tests/test_pagination.py

{pyferro-2.0.0 → pyferro-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyferro"
-version = "2.0.0"
+version = "2.0.1"
 description = "High-performance reactive fullstack Python framework on Rust RSGI (Granian) with symmetric WSRPC (JSON-RPC 2.0) and Tabular Data Compression."
 readme = "README.md"
 requires-python = ">=3.11"

pyferro-2.0.1/tests/test_pagination.py

@@ -0,0 +1,180 @@
+"""
+Тесты для системы пагинации PyFerro 2.0 (paginate_tabular, encode_cursor, decode_cursor).
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+import uuid
+
+import pytest
+from sqlalchemy import DateTime, Integer, String, select
+from sqlalchemy.orm import Mapped, mapped_column
+
+from pyferro2.core.tabular import unpack_tabular
+from pyferro2.db.base import Base
+from pyferro2.db.engine import Database
+from pyferro2.db.pagination import decode_cursor, encode_cursor, paginate_tabular
+
+
+class BookGenre(str, Enum):
+    FICTION = "fiction"
+    SCIENCE = "science"
+    FANTASY = "fantasy"
+
+
+class DemoBook(Base):
+    __tablename__ = "demo_books"
+
+    title: Mapped[str] = mapped_column(String(100), nullable=False)
+    author: Mapped[str] = mapped_column(String(100), nullable=False)
+    genre: Mapped[str] = mapped_column(String(50), default=BookGenre.FICTION.value)
+    price: Mapped[int] = mapped_column(Integer, default=100)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+    )
+
+
+@pytest.fixture
+async def db_session():
+    db = Database("sqlite+aiosqlite:///:memory:")
+    async with db.engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    async with db.session() as session:
+        # Наполняем тестовыми данными (5 книг)
+        books = [
+            DemoBook(title="Book Alpha", author="Author 1", genre=BookGenre.FICTION.value, price=100),
+            DemoBook(title="Book Beta", author="Author 2", genre=BookGenre.SCIENCE.value, price=200),
+            DemoBook(title="Book Gamma", author="Author 1", genre=BookGenre.FICTION.value, price=150),
+            DemoBook(title="Book Delta", author="Author 3", genre=BookGenre.FANTASY.value, price=300),
+            DemoBook(title="Book Epsilon", author="Author 2", genre=BookGenre.SCIENCE.value, price=250),
+        ]
+        session.add_all(books)
+        await session.commit()
+        yield session
+
+    await db.engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_offset_pagination_first_page(db_session):
+    res = await paginate_tabular(db_session, DemoBook, page=1, limit=2)
+    assert res["$tabular"] is True
+    assert res["total"] == 5
+    assert res["pages"] == 3
+    assert res["page"] == 1
+    assert res["limit"] == 2
+    assert res["has_next"] is True
+    assert res["has_prev"] is False
+    assert len(res["rows"]) == 2
+    assert "title" in res["fields"]
+    assert res["next_cursor"] is not None
+
+    unpacked = unpack_tabular(res)
+    assert len(unpacked["items"]) == 2
+    # По умолчанию сортировка id.desc()
+    assert unpacked["items"][0]["title"] == "Book Epsilon"
+    assert unpacked["items"][1]["title"] == "Book Delta"
+
+
+@pytest.mark.asyncio
+async def test_offset_pagination_second_page(db_session):
+    res = await paginate_tabular(db_session, DemoBook, page=2, limit=2)
+    assert res["page"] == 2
+    assert res["has_next"] is True
+    assert res["has_prev"] is True
+    assert len(res["rows"]) == 2
+
+    unpacked = unpack_tabular(res)
+    assert unpacked["items"][0]["title"] == "Book Gamma"
+    assert unpacked["items"][1]["title"] == "Book Beta"
+
+
+@pytest.mark.asyncio
+async def test_offset_pagination_last_page(db_session):
+    res = await paginate_tabular(db_session, DemoBook, page=3, limit=2)
+    assert res["page"] == 3
+    assert res["has_next"] is False
+    assert res["has_prev"] is True
+    assert len(res["rows"]) == 1
+
+    unpacked = unpack_tabular(res)
+    assert unpacked["items"][0]["title"] == "Book Alpha"
+
+
+@pytest.mark.asyncio
+async def test_cursor_pagination(db_session):
+    # Страница 1 (Offset с получением next_cursor)
+    p1 = await paginate_tabular(db_session, DemoBook, page=1, limit=2)
+    cursor = p1["next_cursor"]
+    assert cursor is not None
+
+    # Страница 2 по курсору
+    p2 = await paginate_tabular(db_session, DemoBook, cursor=cursor, limit=2)
+    assert p2["$tabular"] is True
+    assert p2["total"] is None  # В режиме курсора count(*) не вызывается!
+    assert p2["has_next"] is True
+    assert p2["has_prev"] is True
+    assert len(p2["rows"]) == 2
+
+    unpacked2 = unpack_tabular(p2)
+    assert unpacked2["items"][0]["title"] == "Book Gamma"
+    assert unpacked2["items"][1]["title"] == "Book Beta"
+
+    # Страница 3 по следующему курсору
+    cursor2 = p2["next_cursor"]
+    p3 = await paginate_tabular(db_session, DemoBook, cursor=cursor2, limit=2)
+    assert p3["has_next"] is False
+    assert len(p3["rows"]) == 1
+    unpacked3 = unpack_tabular(p3)
+    assert unpacked3["items"][0]["title"] == "Book Alpha"
+
+
+@pytest.mark.asyncio
+async def test_search_and_filters(db_session):
+    # Поиск по подстроке
+    res_search = await paginate_tabular(db_session, DemoBook, search="Gamma")
+    assert res_search["total"] == 1
+    unpacked = unpack_tabular(res_search)
+    assert unpacked["items"][0]["title"] == "Book Gamma"
+
+    # Фильтрация по жанру
+    res_filter = await paginate_tabular(
+        db_session, DemoBook, filters={"genre": BookGenre.SCIENCE.value}
+    )
+    assert res_filter["total"] == 2
+    unpacked_filter = unpack_tabular(res_filter)
+    genres = {item["genre"] for item in unpacked_filter["items"]}
+    assert genres == {BookGenre.SCIENCE.value}
+
+
+@pytest.mark.asyncio
+async def test_custom_select_and_column_projection(db_session):
+    # Передаем готовый Select с проекцией колонок
+    stmt = select(DemoBook.id, DemoBook.title).where(DemoBook.price > 150)
+    res = await paginate_tabular(db_session, stmt, limit=10)
+
+    assert res["$tabular"] is True
+    assert res["fields"] == ["id", "title"]
+    assert res["total"] == 3
+    assert len(res["rows"]) == 3
+
+
+@pytest.mark.asyncio
+async def test_count_false_mode(db_session):
+    # Режим без COUNT (для бесконечного скролла)
+    res = await paginate_tabular(db_session, DemoBook, page=1, limit=2, count=False)
+    assert res["total"] is None
+    assert res["pages"] is None
+    assert res["has_next"] is True
+    assert len(res["rows"]) == 2
+
+
+@pytest.mark.asyncio
+def test_cursor_encode_decode():
+    token = encode_cursor(42, col="id", direction="desc")
+    decoded = decode_cursor(token)
+    assert decoded["v"] == 42
+    assert decoded["c"] == "id"
+    assert decoded["d"] == "desc"