from __future__ import annotations

from typing import TYPE_CHECKING, Any, TypeVar

if TYPE_CHECKING:
    from collections.abc import Callable, Sequence

T = TypeVar("T")


def summarize_items(
    items: Sequence[T],
    *,
    sample_size: int = 5,
    formatter: Callable[[T], str] = str,
) -> dict[str, Any]:
    """Summarize a sequence for debug logging."""
    total = len(items)
    sample = [formatter(item) for item in items[:sample_size]]
    return {
        "rows": total,
        "sample": sample,
    }
