"""Definition of JsonRepositoryInterface abstract base class."""

from abc import ABC, abstractmethod
from collections.abc import Iterator
from typing import Any


class JsonRepositoryInterface(ABC):
    """Interface that defines JSON document CRUD methods."""

    @abstractmethod
    def get(self, key: str) -> dict[str, Any] | None:
        """Get a JSON object by key.

        Returns ``None`` when the key is absent. Returns ``{}`` when the key
        exists with an empty JSON object. Use ``value is not None`` to test
        existence; avoid truthiness checks (``{}`` is falsy).
        """
        ...

    @abstractmethod
    def set(self, key: str, data: dict[str, Any]) -> None:
        """Set a JSON object by key.

        Accepts any dict, including ``{}``. An empty dict creates a key that
        ``get()`` returns as ``{}``, not ``None``. Use ``delete()`` to remove a
        key entirely.
        """
        ...

    @abstractmethod
    def delete(self, key: str) -> None:
        """Delete a JSON object by key, removing it entirely."""
        ...

    @abstractmethod
    def list_keys(self, pattern: str) -> list[str]:
        """List keys matching a glob pattern."""
        ...

    def scan_keys(
        self,
        pattern: str,
        *,
        count: int | None = None,
    ) -> Iterator[str]:
        """Yield keys matching a glob pattern incrementally."""
        del count
        yield from self.list_keys(pattern)