"""Small cross-cutting helpers shared across modules (kept dependency-light on purpose)."""
import re
from datetime import date, datetime, timezone


def iso(dt: date | None) -> str | None:
    """Serialize a date/datetime for a JSON response: ISO-8601, or None when the column is
    NULL. Single source of truth for the `x.isoformat() if x else None` idiom the routes had
    hand-rolled ~17 times — so a future tz/format tweak lands in one place. Accepts `date`
    too (datetime is a subclass) — e.g. MediaAsset.upload_date is a plain `date`."""
    return dt.isoformat() if dt is not None else None

# Single source of truth for "looks like an email" — used by every endpoint that accepts an
# address (auth register/reset/demo, admin invites + demo whitelist, the setup wizard). Keep
# the strictness in one place so routes don't drift between this and a looser "@"-in check.
_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")


def valid_email(value: str | None) -> bool:
    return bool(value and _EMAIL_RE.match(value))


def now_utc() -> datetime:
    """Current time as a timezone-aware UTC datetime."""
    return datetime.now(timezone.utc)


def to_tsquery_str(q: str) -> str | None:
    """Turn free-text into a to_tsquery() string: word runs ANDed together, the LAST word
    prefix-matched (`:*`) for as-you-type search — e.g. "ti amo magyar" → "ti & amo & magyar:*".
    Only `\\w` runs containing an alphanumeric are kept, so no tsquery operators can leak in
    (the string is built from sanitised tokens, never the raw query). Shared by the YouTube feed
    search and the Plex library search, hence this neutral home rather than either domain module."""
    tokens = [t for t in re.findall(r"\w+", q, flags=re.UNICODE) if any(c.isalnum() for c in t)]
    if not tokens:
        return None
    tokens[-1] = tokens[-1] + ":*"
    return " & ".join(tokens)


def normalize_description(text: str | None) -> str | None:
    """Strip whitespace-only lines from a channel/video description before storing. YouTube
    descriptions pad contact/link blocks with runs of blank lines; keeping them wastes storage,
    bloats the About popover, and adds nothing to the search document. Drops purely-empty lines and
    right-strips each kept line. None stays None; all-blank collapses to "". Applied at the
    sync/store site so the DB (and the derived search_vector) holds the clean text."""
    if text is None:
        return None
    kept = [line.rstrip() for line in text.splitlines() if line.strip()]
    return "\n".join(kept)