Add FirestoreStore backend (aio + generated sync)

AGENTS.md

@@ -249,7 +249,7 @@ type annotation issues to maintain type safety guarantees.
 ## Make Commands Reference
 
 | Command | Purpose |
-|---------|---------|
+| ------- | ------- |
 | `make sync` | Install all dependencies |
 | `make install` | Alias for `make sync` |
 | `make lint` | Lint Python + Markdown |

README.md

@@ -18,7 +18,7 @@ This monorepo contains two libraries:
 ## Why use this library?
 
 - **Multiple backends**: DynamoDB, Elasticsearch, Memcached, MongoDB, Redis,
-  RocksDB, Valkey, and In-memory, Disk, etc
+  RocksDB, Valkey, Firestore, and In-memory, Disk, etc
 - **TTL support**: Automatic expiration handling across all store types
 - **Type-safe**: Full type hints with Protocol-based interfaces
 - **Adapters**: Pydantic model support, raise-on-missing behavior, etc
@@ -132,6 +132,8 @@ pip install py-key-value-aio[memory]
 pip install py-key-value-aio[disk]
 pip install py-key-value-aio[dynamodb]
 pip install py-key-value-aio[elasticsearch]
+# Firestore support
+pip install py-key-value-aio[firestore]
 # or: redis, mongodb, memcached, valkey, vault, registry, rocksdb, see below for all options
 ```
 

docs/adapters.md

@@ -7,7 +7,7 @@ provide alternative APIs tailored for specific use cases.
 ## Available Adapters
 
 | Adapter | Description |
-|---------|-------------|
+| ------- | ----------- |
 | [DataclassAdapter](#dataclassadapter) | Type-safe storage/retrieval of dataclass models with transparent serialization |
 | [PydanticAdapter](#pydanticadapter) | Type-safe storage/retrieval of Pydantic models with transparent serialization |
 | [RaiseOnMissingAdapter](#raiseonmissingadapter) | Optional raise-on-missing behavior for get operations |

docs/getting-started.md

@@ -30,6 +30,9 @@ pip install py-key-value-aio[elasticsearch]
 # MongoDB support
 pip install py-key-value-aio[mongodb]
 
+# Firestore support
+pip install py-key-value-aio[firestore]
+
 # All backends
 pip install py-key-value-aio[all]
 ```

docs/stores.md

@@ -30,7 +30,7 @@ long-term storage, prefer stable stores.
 Local stores are stored in memory or on disk, local to the application.
 
 | Store | Stability | Async | Sync | Description |
-|-------|:---------:|:-----:|:----:|:------------|
+| ----- | :-------: | :---: | :--: | ----------- |
 | Memory | N/A | ✅ | ✅ | Fast in-memory storage for development and caching |
 | Disk | Stable | ☑️ | ✅ | Persistent file-based storage in a single file |
 | Disk (Per-Collection) | Stable | ☑️ | ✅ | Persistent storage with separate files per collection |
@@ -315,7 +315,7 @@ Secret stores provide secure storage for sensitive data, typically using
 operating system secret management facilities.
 
 | Store | Stability | Async | Sync | Description |
-|-------|:---------:|:-----:|:----:|:------------|
+| ----- | :-------: | :---: | :--: | ----------- |
 | Keyring | Stable | ✅ | ✅ | OS-level secure storage (Keychain, Credential Manager, etc.) |
 | Vault | Unstable | ✅ | ✅ | HashiCorp Vault integration for enterprise secrets |
 
@@ -395,9 +395,10 @@ pip install py-key-value-aio[vault]
 Distributed stores provide network-based storage for multi-node applications.
 
 | Store | Stability | Async | Sync | Description |
-|-------|:---------:|:-----:|:----:|:------------|
+| ----- | :-------: | :---: | :--: | ----------- |
 | DynamoDB | Unstable | ✅ | ✖️ | AWS DynamoDB key-value storage |
 | Elasticsearch | Unstable | ✅ | ✅ | Full-text search with key-value capabilities |
+| Firestore | Unstable | ✅ | ✅ | Google Cloud Firestore key-value storage |
 | Memcached | Unstable | ✅ | ✖️ | High-performance distributed memory cache |
 | MongoDB | Unstable | ✅ | ✅ | Document database used as key-value store |
 | Redis | Stable | ✅ | ✅ | Popular in-memory data structure store |
@@ -467,6 +468,36 @@ pip install py-key-value-aio[valkey]
 
 ---
 
+### FirestoreStore
+
+Google Cloud Firestore used as a key-value store.
+
+```python
+from key_value.aio.stores.firestore import FirestoreStore
+
+store = FirestoreStore(credentials=google_credentials, database="firestore-db")
+```
+
+**Installation:**
+
+```bash
+pip install py-key-value-aio[firestore]
+```
+
+**Use Cases:**
+
+- Google Cloud-native applications
+- Serverless / managed infrastructure
+- Existing Firestore deployments
+
+**Characteristics:**
+
+- Managed cloud database
+- Document/collection model
+- Stable storage format: **Unstable**
+
+---
+
 ### DynamoDBStore
 
 AWS DynamoDB integration for serverless and cloud-native applications.

docs/wrappers.md

@@ -7,7 +7,7 @@ protocol, so they can be used anywhere a store can be used.
 ## Available Wrappers
 
 | Wrapper | Description |
-|---------|-------------|
+| ------- | ----------- |
 | [CompressionWrapper](#compressionwrapper) | Compress values before storing and decompress on retrieval |
 | [FernetEncryptionWrapper](#fernetencryptionwrapper) | Encrypt values before storing and decrypt on retrieval |
 | [FallbackWrapper](#fallbackwrapper) | Fallback to a secondary store when the primary store fails |

key-value/key-value-aio/pyproject.toml

@@ -50,6 +50,7 @@ rocksdb = [
     "rocksdict>=0.3.2 ; python_version < '3.12'"
 ]
 duckdb = ["duckdb>=1.1.1", "pytz>=2025.2"]
+firestore = ["google-cloud-firestore>=2.13.0", "google-auth>=2.24.0"]
 wrappers-encryption = ["cryptography>=45.0.0"]
 
 [tool.pytest.ini_options]
@@ -70,7 +71,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb]",
+    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb,firestore]",
     "py-key-value-aio[valkey]; platform_system != 'Windows'",
     "py-key-value-aio[keyring]",
     "py-key-value-aio[pydantic]",

key-value/key-value-aio/src/key_value/aio/stores/firestore/__init__.py

@@ -0,0 +1,5 @@
+"""Firestore key-value store."""
+
+from key_value.aio.stores.firestore.store import FirestoreStore
+
+__all__ = ["FirestoreStore"]

key-value/key-value-aio/src/key_value/aio/stores/firestore/store.py

@@ -0,0 +1,121 @@
+from typing import overload
+
+from key_value.shared.utils.managed_entry import ManagedEntry
+from typing_extensions import override
+
+from key_value.aio.stores.base import (
+    BaseContextManagerStore,
+    BaseStore,
+    BasicSerializationAdapter,
+)
+
+try:
+    from google.cloud import firestore
+    from google.oauth2.service_account import Credentials
+except ImportError as e:
+    msg = "FirestoreStore requires py-key-value-aio[firestore]"
+    raise ImportError(msg) from e
+
+
+class FirestoreStore(BaseContextManagerStore, BaseStore):
+    """Firestore-based key-value store.
+
+    This store uses Firebase DB as the key-value storage.
+    The data is stored in collections.
+    """
+
+    _client: firestore.AsyncClient | None
+
+    @overload
+    def __init__(self, client: firestore.AsyncClient, *, default_collection: str | None = None) -> None:
+        """Initialize the Firestore store with a client. It defers project and database from client instance.
+
+        Args:
+            client: The initialized Firestore client to use.
+            default_collection: The default collection to use if no collection is provided.
+        """
+
+    @overload
+    def __init__(
+        self, *, credentials: Credentials, project: str | None = None, database: str | None = None, default_collection: str | None = None
+    ) -> None:
+        """Initialize the Firestore store with Google service account credentials.
+
+        Args:
+            credentials: Google service account credentials from google-cloud-auth module.
+            project: Google project name.
+            database: database name, defaults to '(default)' if not provided.
+            default_collection: The default collection to use if no collection is provided.
+        """
+
+    def __init__(
+        self,
+        client: firestore.AsyncClient | None = None,
+        *,
+        credentials: Credentials | None = None,
+        project: str | None = None,
+        database: str | None = None,
+        default_collection: str | None = None,
+    ) -> None:
+        """Initialize the Firestore store with Google client or Google service account credentials.
+        If provided with a client, uses it, otherwise connects using credentials.
+
+        Args:
+            client: The initialized Firestore client to use. Chosen by default if provided.
+            credentials: Google service account credentials from google-cloud-auth module.
+            project: Google project name.
+            database: database name, defaults to '(default)' if not provided.
+            default_collection: The default collection to use if no collection is provided.
+        """
+        self._credentials = credentials
+        self._project = project
+        self._database = database
+        serialization_adapter = BasicSerializationAdapter(value_format="string")
+
+        if client:
+            self._client = client
+            client_provided_by_user = True
+        else:
+            self._client = firestore.AsyncClient(credentials=self._credentials, project=self._project, database=self._database)
+            client_provided_by_user = False
+        super().__init__(
+            default_collection=default_collection,
+            client_provided_by_user=client_provided_by_user,
+            serialization_adapter=serialization_adapter,
+        )
+
+    @property
+    def _connected_client(self) -> firestore.AsyncClient:
+        if not self._client:
+            msg = "Client not connected"
+            raise ValueError(msg)
+        return self._client
+
+    @override
+    async def _get_managed_entry(self, *, key: str, collection: str | None = None) -> ManagedEntry | None:
+        """Get a managed entry from Firestore."""
+        collection = collection or self.default_collection
+        response = await self._connected_client.collection(collection).document(key).get()  # pyright: ignore[reportUnknownMemberType]
+        doc = response.to_dict()
+        if doc is None:
+            return None
+        return self._serialization_adapter.load_dict(data=doc)
+
+    @override
+    async def _put_managed_entry(self, *, key: str, managed_entry: ManagedEntry, collection: str | None = None) -> None:
+        """Store a managed entry in Firestore."""
+        collection = collection or self.default_collection
+        item = self._serialization_adapter.dump_dict(entry=managed_entry)
+        await self._connected_client.collection(collection).document(key).set(item)  # pyright: ignore[reportUnknownMemberType]
+
+    @override
+    async def _delete_managed_entry(self, *, key: str, collection: str | None = None) -> bool:
+        """Delete a managed entry from Firestore."""
+        collection = collection or self.default_collection
+        await self._connected_client.collection(collection).document(key).delete()
+        return True
+
+    async def _close(self) -> None:
+        """Close the Firestore client."""
+        if self._client and not self._client_provided_by_user:
+            self._client.close()

key-value/key-value-aio/tests/stores/firestore/__init__.py

@@ -0,0 +1 @@
+"""Tests for Firestore store."""