"""
This module wraps the browser's
[IndexedDB persistent storage](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
to provide a familiar Python dictionary API. Data is automatically
serialized and persisted, surviving page reloads and browser restarts.

Storage is persistent per origin (domain), isolated between different sites
for security. Browsers typically allow each origin to store up to 10-60% of
total disk space, depending on browser and configuration.

What this module provides:

- A `dict`-like API (get, set, delete, iterate).
- Automatic serialization of common Python types.
- Background persistence with optional explicit `sync()`.
- Support for custom `Storage` subclasses.

```python
from pyscript import storage


# Create or open a named storage.
my_data = await storage("user-preferences")

# Use like a regular dictionary.
my_data["theme"] = "dark"
my_data["font_size"] = 14
my_data["settings"] = {"notifications": True, "sound": False}

# Changes are queued automatically.
# To ensure immediate write, sync explicitly.
await my_data.sync()

# Read values (survives page reload).
theme = my_data.get("theme", "light")
```

Common types are automatically serialized: `bool`, `int`, `float`, `str`, `None`,
`list`, `dict`, `tuple`. Binary data (`bytearray`, `memoryview`) can be stored as
single values but not nested in structures.

Tuples are deserialized as lists due to IndexedDB limitations.

!!! info
    Browsers typically allow 10-60% of total disk space per origin. Chrome
    and Edge allow up to 60%, Firefox up to 10 GiB (or 10% of disk, whichever
    is smaller). Safari varies by app type. These limits are unlikely to be
    reached in typical usage.
"""

from polyscript import storage as _polyscript_storage
from pyscript.flatted import parse as _parse
from pyscript.flatted import stringify as _stringify
from pyscript.ffi import is_none


def _convert_to_idb(value):
    """
    Convert a Python `value` to an IndexedDB-compatible format.

    Values are serialized using Flatted (for circular reference support)
    with type information to enable proper deserialization. It returns a
    JSON string representing the serialized value.

    Will raise a TypeError if the value type is not supported.
    """
    if is_none(value):
        return _stringify(["null", 0])
    if isinstance(value, (bool, float, int, str, list, dict, tuple)):
        return _stringify(["generic", value])
    if isinstance(value, bytearray):
        return _stringify(["bytearray", list(value)])
    if isinstance(value, memoryview):
        return _stringify(["memoryview", list(value)])
    raise TypeError(f"Cannot serialize type {type(value).__name__} for storage.")


def _convert_from_idb(value):
    """
    Convert an IndexedDB `value` back to its Python representation.

    Uses type information stored during serialization to reconstruct the
    original Python type.
    """
    kind, data = _parse(value)

    if kind == "null":
        return None
    if kind == "generic":
        return data
    if kind == "bytearray":
        return bytearray(data)
    if kind == "memoryview":
        return memoryview(bytearray(data))
    # Fallback for all other types.
    return value


class Storage(dict):
    """
    A persistent dictionary backed by the browser's IndexedDB.

    This class provides a dict-like interface with automatic persistence.
    Changes are queued for background writing, with optional explicit
    synchronization via `sync()`.

    Inherits from `dict`, so all standard dictionary methods work as expected.

    ```python
    from pyscript import storage


    # Open a storage.
    prefs = await storage("preferences")

    # Use as a dictionary.
    prefs["color"] = "blue"
    prefs["count"] = 42

    # Iterate like a dict.
    for key, value in prefs.items():
        print(f"{key}: {value}")

    # Ensure writes complete immediately.
    await prefs.sync()
    ```

    Sometimes you may need to subclass `Storage` to add custom behavior:

    ```python
    from pyscript import storage, Storage, window


    class LoggingStorage(Storage):
        def __setitem__(self, key, value):
            window.console.log(f"Setting {key} = {value}")
            super().__setitem__(key, value)

    my_store = await storage("app-data", storage_class=LoggingStorage)
    my_store["test"] = 123  # Logs to console.
    ```
    """

    def __init__(self, store):
        """
        Create a Storage instance wrapping an IndexedDB `store` (a JS
        proxy).
        """
        super().__init__(
            {key: _convert_from_idb(value) for key, value in store.entries()}
        )
        self._store = store

    def __delitem__(self, key):
        """
        Delete an item from storage via its `key`.

        The deletion is queued for persistence. Use `sync()` to ensure
        immediate completion.
        """
        self._store.delete(key)
        super().__delitem__(key)

    def __setitem__(self, key, value):
        """
        Set a `key` to a `value` in storage.

        The change is queued for persistence. Use `sync()` to ensure
        immediate completion. The `value` must be a supported type for
        serialization.
        """
        self._store.set(key, _convert_to_idb(value))
        super().__setitem__(key, value)

    def clear(self):
        """
        Remove all items from storage.

        The `clear()` operation is queued for persistence. Use `sync()` to ensure
        immediate completion.
        """
        self._store.clear()
        super().clear()

    async def sync(self):
        """
        Force immediate synchronization to IndexedDB.

        By default, storage operations are queued and written asynchronously.
        Call `sync()` when you need to guarantee changes are persisted immediately,
        such as before critical operations or page unload.

        ```python
        store = await storage("important-data")
        store["critical_value"] = data

        # Ensure it's written before proceeding.
        await store.sync()
        ```

        This is a blocking operation that waits for IndexedDB to complete
        the write.
        """
        await self._store.sync()


async def storage(name="", storage_class=Storage):
    """
    Open or create persistent storage with a unique `name` and optional
    `storage_class` (used to extend the default `Storage` based behavior).

    Each storage is isolated by name within the current origin (domain).
    If the storage doesn't exist, it will be created. If it does exist,
    its current contents will be loaded.

    This function returns a `Storage` instance (or custom subclass instance)
    acting as a persistent dictionary. A `ValueError` is raised if `name` is
    empty or not provided.

    ```python
    from pyscript import storage


    # Basic usage.
    user_data = await storage("user-profile")
    user_data["name"] = "Alice"
    user_data["age"] = 30

    # Multiple independent storages.
    settings = await storage("app-settings")
    cache = await storage("api-cache")

    # With custom Storage class.
    class ValidatingStorage(Storage):
        def __setitem__(self, key, value):
            if not isinstance(key, str):
                raise TypeError("Keys must be strings")
            super().__setitem__(key, value)

    validated = await storage("validated-data", ValidatingStorage)
    ```

    Storage names are automatically prefixed with `"@pyscript/"` to
    namespace them within IndexedDB.
    """
    if not name:
        raise ValueError("Storage name must be a non-empty string")

    underlying_store = await _polyscript_storage(f"@pyscript/{name}")
    return storage_class(underlying_store)