feat: add RoutingWrapper and CollectionRoutingWrapper

Add routing wrapper functionality that allows routing requests to different
stores based on a routing function. This enables flexible multi-backend
storage strategies.

Features:
- RoutingWrapper: Base wrapper with custom routing function support
- CollectionRoutingWrapper: Convenience wrapper for collection-based routing
- Comprehensive test coverage with 11 tests covering all operations
- Support for all AsyncKeyValue protocol methods (get, put, delete, ttl, and _many variants)

Use cases:
- Route different collections to different backends (e.g., sessions to Redis, users to DynamoDB)
- Cost optimization by routing hot/cold data to different storage tiers
- Compliance requirements (e.g., PII data to encrypted stores)
- Development/testing with selective mock stores

Closes #114

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: William Easton <[email protected]>

Author: github-actions[bot]

key-value/key-value-aio/src/key_value/aio/wrappers/routing/__init__.py

@@ -0,0 +1,4 @@
+from key_value.aio.wrappers.routing.collection_routing import CollectionRoutingWrapper
+from key_value.aio.wrappers.routing.wrapper import RoutingFunction, RoutingWrapper
+
+__all__ = ["CollectionRoutingWrapper", "RoutingFunction", "RoutingWrapper"]

key-value/key-value-aio/src/key_value/aio/wrappers/routing/collection_routing.py

@@ -0,0 +1,55 @@
+from key_value.aio.protocols.key_value import AsyncKeyValue
+from key_value.aio.wrappers.routing.wrapper import RoutingWrapper
+
+
+class CollectionRoutingWrapper(RoutingWrapper):
+    """Routes operations based on collection name using a simple map.
+
+    This is a convenience wrapper that provides collection-based routing using a
+    dictionary mapping collection names to stores. This is useful for directing
+    different data types to different backing stores.
+
+    Example:
+        router = CollectionRoutingWrapper(
+            collection_map={
+                "sessions": redis_store,
+                "users": dynamo_store,
+                "cache": memory_store,
+            },
+            default_store=disk_store
+        )
+
+        # Gets from redis_store
+        await router.get("session_id", collection="sessions")
+
+        # Gets from dynamo_store
+        await router.get("user_id", collection="users")
+
+        # Gets from disk_store (default)
+        await router.get("other_key", collection="unmapped_collection")
+    """
+
+    def __init__(
+        self,
+        collection_map: dict[str, AsyncKeyValue],
+        default_store: AsyncKeyValue | None = None,
+    ) -> None:
+        """Initialize collection-based routing.
+
+        Args:
+            collection_map: Mapping from collection name to store. Each collection
+                           name is mapped to its corresponding backing store.
+            default_store: Store to use for unmapped collections. If None and a
+                          collection is not in the map, operations will raise ValueError.
+        """
+        self.collection_map = collection_map
+
+        def route_by_collection(collection: str | None) -> AsyncKeyValue | None:
+            if collection is None:
+                return default_store
+            return self.collection_map.get(collection, default_store)
+
+        super().__init__(
+            routing_function=route_by_collection,
+            default_store=default_store,
+        )

key-value/key-value-aio/src/key_value/aio/wrappers/routing/wrapper.py

@@ -0,0 +1,115 @@
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, SupportsFloat
+
+from typing_extensions import override
+
+from key_value.aio.protocols.key_value import AsyncKeyValue
+from key_value.aio.wrappers.base import BaseWrapper
+
+RoutingFunction = Callable[[str | None], AsyncKeyValue | None]
+
+
+class RoutingWrapper(BaseWrapper):
+    """Routes operations to different stores based on a routing function.
+
+    The routing function receives the collection name and returns the appropriate store.
+    This allows dynamic routing of requests to different backing stores based on
+    collection name, key patterns, or any other custom logic.
+
+    Example:
+        def route_by_collection(collection: str | None) -> AsyncKeyValue | None:
+            if collection == "sessions":
+                return redis_store
+            elif collection == "users":
+                return dynamo_store
+            return None
+
+        router = RoutingWrapper(
+            routing_function=route_by_collection,
+            default_store=memory_store
+        )
+    """
+
+    def __init__(
+        self,
+        routing_function: RoutingFunction,
+        default_store: AsyncKeyValue | None = None,
+    ) -> None:
+        """Initialize the routing wrapper.
+
+        Args:
+            routing_function: Function that takes a collection name and returns the store to use.
+                             Should return None if no specific store is found.
+            default_store: Optional fallback store if routing_function returns None.
+                          If both routing_function returns None and default_store is None,
+                          operations will raise ValueError.
+        """
+        self.routing_function = routing_function
+        self.default_store = default_store
+
+    def _get_store(self, collection: str | None) -> AsyncKeyValue:
+        """Get the appropriate store for the given collection.
+
+        Args:
+            collection: The collection name to route.
+
+        Returns:
+            The AsyncKeyValue store to use for this collection.
+
+        Raises:
+            ValueError: If no store is found for the collection and no default store is configured.
+        """
+        store = self.routing_function(collection)
+        if store is None and self.default_store is not None:
+            return self.default_store
+        if store is None:
+            msg = f"No store found for collection: {collection}"
+            raise ValueError(msg)
+        return store
+
+    @override
+    async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
+        store = self._get_store(collection)
+        return await store.get(key=key, collection=collection)
+
+    @override
+    async def get_many(self, keys: list[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
+        store = self._get_store(collection)
+        return await store.get_many(keys=keys, collection=collection)
+
+    @override
+    async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
+        store = self._get_store(collection)
+        return await store.ttl(key=key, collection=collection)
+
+    @override
+    async def ttl_many(self, keys: list[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
+        store = self._get_store(collection)
+        return await store.ttl_many(keys=keys, collection=collection)
+
+    @override
+    async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
+        store = self._get_store(collection)
+        return await store.put(key=key, value=value, collection=collection, ttl=ttl)
+
+    @override
+    async def put_many(
+        self,
+        keys: list[str],
+        values: Sequence[Mapping[str, Any]],
+        *,
+        collection: str | None = None,
+        ttl: Sequence[SupportsFloat | None] | None = None,
+    ) -> None:
+        store = self._get_store(collection)
+        return await store.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
+
+    @override
+    async def delete(self, key: str, *, collection: str | None = None) -> bool:
+        store = self._get_store(collection)
+        return await store.delete(key=key, collection=collection)
+
+    @override
+    async def delete_many(self, keys: list[str], *, collection: str | None = None) -> int:
+        store = self._get_store(collection)
+        return await store.delete_many(keys=keys, collection=collection)