"""Utility helper functions."""

import re
import uuid as _uuid
from typing import Any

from sqlalchemy.orm import Query


def generate_uuid() -> str:
    """Generate a UUID4 string."""
    return str(_uuid.uuid4())


def slugify(text: str) -> str:
    """Convert text to a URL-friendly slug."""
    text = text.lower().strip()
    text = re.sub(r"[^\w\s一-鿿-]", "", text)
    text = re.sub(r"[-\s]+", "-", text)
    return text.strip("-")


def paginate(query: Query, page: int = 1, size: int = 20) -> dict[str, Any]:
    """Paginate a SQLAlchemy query.

    Args:
        query: The SQLAlchemy query to paginate.
        page: The page number (1-indexed).
        size: Number of items per page.

    Returns:
        dict with items, total, page, size, pages
    """
    total = query.count()
    items = query.offset((page - 1) * size).limit(size).all()
    pages = (total + size - 1) // size if total > 0 else 0

    return {
        "items": items,
        "total": total,
        "page": page,
        "size": size,
        "pages": pages,
    }