"""Definition of TableRepositoryInterface protocol."""

from abc import abstractmethod
from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class TableRepositoryInterface(Protocol):
    """Interface that defines relational table CRUD methods."""

    @abstractmethod
    def fetch_one(self, pk: Any) -> dict[str, Any] | None:
        """Fetch a single row by primary key.

        Returns ``None`` when no row matches. Use ``value is not None`` to test
        existence; avoid truthiness checks.
        """
        ...

    @abstractmethod
    def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
        """Fetch all rows from the configured table.

        Returns an empty list when the table has no rows.
        """
        ...

    @abstractmethod
    def upsert(self, row: dict[str, Any]) -> None:
        """Insert or update a row by primary key.

        ``row`` must include the configured primary key column. Raises
        ``ValueError`` for a non-dict row or a missing primary key.
        """
        ...

    @abstractmethod
    def delete(self, pk: Any) -> None:
        """Delete a row by primary key.

        Idempotent: no error when the row is already absent.
        """
        ...

    @abstractmethod
    def execute(
        self,
        sql: str,
        params: tuple[Any, ...] = (),
    ) -> list[dict[str, Any]]:
        """Run a read SQL statement and return rows as dicts.

        Escape hatch for joins, filters, and other queries in subclasses.
        """
        ...