pulse-framework 0.1.69__py3-none-any.whl → 0.1.71__py3-none-any.whl

pulse/__init__.py

@@ -1328,8 +1328,12 @@ from pulse.queries.client import queries as queries
 from pulse.queries.common import ActionError as ActionError
 from pulse.queries.common import ActionResult as ActionResult
 from pulse.queries.common import ActionSuccess as ActionSuccess
+from pulse.queries.common import Key as Key
 from pulse.queries.common import QueryKey as QueryKey
+from pulse.queries.common import QueryKeys as QueryKeys
 from pulse.queries.common import QueryStatus as QueryStatus
+from pulse.queries.common import keys as keys
+from pulse.queries.common import normalize_key as normalize_key
 from pulse.queries.infinite_query import infinite_query as infinite_query
 from pulse.queries.mutation import mutation as mutation
 from pulse.queries.protocol import QueryResult as QueryResult

pulse/queries/client.py

@@ -4,7 +4,7 @@ from typing import Any, TypeVar, overload
 
 from pulse.context import PulseContext
 from pulse.helpers import MISSING
-from pulse.queries.common import ActionResult, QueryKey
+from pulse.queries.common import ActionResult, Key, QueryKey, QueryKeys, normalize_key
 from pulse.queries.infinite_query import InfiniteQuery, Page
 from pulse.queries.query import KeyedQuery
 from pulse.queries.store import QueryStore
@@ -13,34 +13,32 @@ T = TypeVar("T")
 
 # Query filter types
 QueryFilter = (
-	QueryKey  # exact key match
-	| list[QueryKey]  # explicit list of keys
-	| Callable[[QueryKey], bool]  # predicate function
+	QueryKey  # exact key match (tuple or list)
+	| QueryKeys  # explicit set of keys
+	| Callable[[Key], bool]  # predicate function
 )
 
 
 def _normalize_filter(
 	filter: QueryFilter | None,
-) -> Callable[[QueryKey], bool] | None:
-	"""Convert any QueryFilter to a predicate function."""
+) -> tuple[Key | None, Callable[[Key], bool] | None]:
+	"""Return normalized exact key (if any) and a predicate for filtering."""
 	if filter is None:
-		return None
-	if isinstance(filter, tuple):
-		# Exact key match
-		exact_key = filter
-		return lambda k: k == exact_key
-	if isinstance(filter, list):
-		# List of keys
-		key_set = set(filter)
-		return lambda k: k in key_set
-	# Already a callable predicate
-	return filter
-
-
-def _prefix_filter(prefix: tuple[Any, ...]) -> Callable[[QueryKey], bool]:
+		return None, None
+	if callable(filter):
+		return None, filter
+	if isinstance(filter, QueryKeys):
+		key_set = set(filter.keys)
+		return None, lambda k: k in key_set
+	exact_key = normalize_key(filter)
+	return exact_key, lambda k: k == exact_key
+
+
+def _prefix_filter(prefix: QueryKey) -> Callable[[Key], bool]:
 	"""Create a predicate that matches keys starting with the given prefix."""
-	prefix_len = len(prefix)
-	return lambda k: len(k) >= prefix_len and k[:prefix_len] == prefix
+	normalized = normalize_key(prefix)
+	prefix_len = len(normalized)
+	return lambda k: len(k) >= prefix_len and k[:prefix_len] == normalized
 
 
 class QueryClient:
@@ -120,7 +118,7 @@ class QueryClient:
 		Get all queries matching the filter.
 
 		Args:
-			filter: Optional filter - can be an exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all queries.
 			include_infinite: Whether to include infinite queries (default True).
 
@@ -128,9 +126,16 @@ class QueryClient:
 			List of matching Query or InfiniteQuery instances.
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[KeyedQuery[Any] | InfiniteQuery[Any, Any]] = []
 
+		if exact_key is not None:
+			if include_infinite:
+				entry = store.get_any(exact_key)
+			else:
+				entry = store.get(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if predicate is not None and not predicate(key):
 				continue
@@ -144,16 +149,20 @@ class QueryClient:
 		"""Get all regular queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all regular queries.
 
 		Returns:
 			List of matching KeyedQuery instances (excludes infinite queries).
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[KeyedQuery[Any]] = []
 
+		if exact_key is not None:
+			entry = store.get(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if isinstance(entry, InfiniteQuery):
 				continue
@@ -169,16 +178,20 @@ class QueryClient:
 		"""Get all infinite queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all infinite queries.
 
 		Returns:
 			List of matching InfiniteQuery instances.
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[InfiniteQuery[Any, Any]] = []
 
+		if exact_key is not None:
+			entry = store.get_infinite(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if not isinstance(entry, InfiniteQuery):
 				continue
@@ -239,7 +252,7 @@ class QueryClient:
 	@overload
 	def set_data(
 		self,
-		key_or_filter: list[QueryKey] | Callable[[QueryKey], bool],
+		key_or_filter: QueryKeys | Callable[[Key], bool],
 		data: Callable[[Any], Any],
 		*,
 		updated_at: float | dt.datetime | None = None,
@@ -247,7 +260,7 @@ class QueryClient:
 
 	def set_data(
 		self,
-		key_or_filter: QueryKey | list[QueryKey] | Callable[[QueryKey], bool],
+		key_or_filter: QueryKey | QueryKeys | Callable[[Key], bool],
 		data: Any | Callable[[Any], Any],
 		*,
 		updated_at: float | dt.datetime | None = None,
@@ -266,16 +279,15 @@ class QueryClient:
 		Returns:
 			bool if exact key, int count if filter.
 		"""
-		# Single key case
-		if isinstance(key_or_filter, tuple):
-			query = self.get(key_or_filter)
+		exact_key, predicate = _normalize_filter(key_or_filter)
+		if exact_key is not None:
+			query = self.get(exact_key)
 			if query is None:
 				return False
 			query.set_data(data, updated_at=updated_at)
 			return True
 
-		# Filter case
-		queries = self.get_queries(key_or_filter)
+		queries = self.get_queries(predicate)
 		for q in queries:
 			q.set_data(data, updated_at=updated_at)
 		return len(queries)
@@ -319,17 +331,14 @@ class QueryClient:
 	@overload
 	def invalidate(
 		self,
-		key_or_filter: list[QueryKey] | Callable[[QueryKey], bool] | None = None,
+		key_or_filter: QueryKeys | Callable[[Key], bool] | None = None,
 		*,
 		cancel_refetch: bool = False,
 	) -> int: ...
 
 	def invalidate(
 		self,
-		key_or_filter: QueryKey
-		| list[QueryKey]
-		| Callable[[QueryKey], bool]
-		| None = None,
+		key_or_filter: QueryKey | QueryKeys | Callable[[Key], bool] | None = None,
 		*,
 		cancel_refetch: bool = False,
 	) -> bool | int:
@@ -346,20 +355,19 @@ class QueryClient:
 		Returns:
 			bool if exact key, int count if filter/None.
 		"""
-		# Single key case
-		if isinstance(key_or_filter, tuple):
-			query = self.get(key_or_filter)
+		exact_key, predicate = _normalize_filter(key_or_filter)
+		if exact_key is not None:
+			query = self.get(exact_key)
 			if query is not None:
 				query.invalidate(cancel_refetch=cancel_refetch)
 				return True
-			inf_query = self.get_infinite(key_or_filter)
+			inf_query = self.get_infinite(exact_key)
 			if inf_query is not None:
 				inf_query.invalidate(cancel_fetch=cancel_refetch)
 				return True
 			return False
 
-		# Filter case
-		queries = self.get_all(key_or_filter)
+		queries = self.get_all(predicate)
 		for q in queries:
 			if isinstance(q, InfiniteQuery):
 				q.invalidate(cancel_fetch=cancel_refetch)
@@ -369,14 +377,14 @@ class QueryClient:
 
 	def invalidate_prefix(
 		self,
-		prefix: tuple[Any, ...],
+		prefix: QueryKey,
 		*,
 		cancel_refetch: bool = False,
 	) -> int:
 		"""Invalidate all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 			cancel_refetch: Cancel in-flight requests before refetch.
 
 		Returns:
@@ -429,7 +437,7 @@ class QueryClient:
 		"""Refetch all queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, refetches all queries.
 			cancel_refetch: Cancel in-flight requests before refetching.
 
@@ -450,14 +458,14 @@ class QueryClient:
 
 	async def refetch_prefix(
 		self,
-		prefix: tuple[Any, ...],
+		prefix: QueryKey,
 		*,
 		cancel_refetch: bool = True,
 	) -> list[ActionResult[Any]]:
 		"""Refetch all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 			cancel_refetch: Cancel in-flight requests before refetching.
 
 		Returns:
@@ -524,7 +532,7 @@ class QueryClient:
 		"""Remove all queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, removes all queries.
 
 		Returns:
@@ -535,11 +543,11 @@ class QueryClient:
 			q.dispose()
 		return len(queries)
 
-	def remove_prefix(self, prefix: tuple[Any, ...]) -> int:
+	def remove_prefix(self, prefix: QueryKey) -> int:
 		"""Remove all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 
 		Returns:
 			Count of removed queries.
@@ -554,7 +562,7 @@ class QueryClient:
 		"""Check if any query matching the filter is currently fetching.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, checks all queries.
 
 		Returns:
@@ -570,7 +578,7 @@ class QueryClient:
 		"""Check if any query matching the filter is in loading state.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, checks all queries.
 
 		Returns:

pulse/queries/common.py

@@ -9,6 +9,8 @@ from typing import (
 	ParamSpec,
 	TypeAlias,
 	TypeVar,
+	final,
+	override,
 )
 
 from pulse.state import State
@@ -18,13 +20,62 @@ TState = TypeVar("TState", bound="State")
 P = ParamSpec("P")
 R = TypeVar("R")
 
-QueryKey: TypeAlias = tuple[Hashable, ...]
-"""Tuple of hashable values identifying a query in the store.
+
+@final
+class Key(tuple[Hashable, ...]):
+	"""Normalized query key with a precomputed hash."""
+
+	_hash: int = 0
+
+	def __new__(cls, key: "QueryKey"):
+		if isinstance(key, Key):
+			return key
+		if isinstance(key, (list, tuple)):
+			parts = tuple(key)
+			try:
+				key_hash = hash(parts)
+			except TypeError:
+				raise TypeError("QueryKey values must be hashable") from None
+			obj = super().__new__(cls, parts)
+			obj._hash = key_hash
+			return obj
+		raise TypeError("QueryKey must be a list or tuple of hashable values")
+
+	@override
+	def __hash__(self) -> int:
+		return self._hash
+
+
+QueryKey: TypeAlias = tuple[Hashable, ...] | list[Hashable] | Key
+"""List/tuple of hashable values identifying a query in the store.
 
 Used to uniquely identify queries for caching, deduplication, and invalidation.
-Keys are hierarchical tuples like ``("user", user_id)`` or ``("posts", "feed")``.
+Keys are hierarchical lists/tuples like ``("user", user_id)`` or ``["posts", "feed"]``.
+Lists are normalized to a tuple-backed Key internally.
 """
 
+
+def normalize_key(key: QueryKey) -> Key:
+	"""Convert a query key to a normalized key for use as a dict key."""
+	return Key(key)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class QueryKeys:
+	"""Wrapper for selecting multiple query keys."""
+
+	keys: tuple[Key, ...]
+
+	def __init__(self, *keys: QueryKey):
+		object.__setattr__(self, "keys", tuple(normalize_key(key) for key in keys))
+
+
+def keys(*query_keys: QueryKey) -> QueryKeys:
+	"""Create a QueryKeys wrapper for filtering by multiple keys."""
+	return QueryKeys(*query_keys)
+
+
 QueryStatus: TypeAlias = Literal["loading", "success", "error"]
 """Current status of a query.
 

pulse/queries/infinite_query.py

@@ -27,11 +27,13 @@ from pulse.queries.common import (
 	ActionError,
 	ActionResult,
 	ActionSuccess,
+	Key,
 	OnErrorFn,
 	OnSuccessFn,
 	QueryKey,
 	QueryStatus,
 	bind_state,
+	normalize_key,
 )
 from pulse.queries.query import RETRY_DELAY_DEFAULT, QueryConfig
 from pulse.reactive import Computed, Effect, Signal, Untrack
@@ -115,6 +117,7 @@ class RefetchPage(Generic[T, TParam]):
 	fetch_fn: Callable[[TParam], Awaitable[T]]
 	param: TParam
 	observer: "InfiniteQueryResult[T, TParam] | None" = None
+	clear: bool = False
 	future: "asyncio.Future[ActionResult[T | None]]" = field(
 		default_factory=asyncio.Future
 	)
@@ -141,7 +144,7 @@ class InfiniteQueryConfig(QueryConfig[list[Page[T, TParam]]], Generic[T, TParam]
 class InfiniteQuery(Generic[T, TParam], Disposable):
 	"""Paginated query that stores data as a list of Page(data, param)."""
 
-	key: QueryKey
+	key: Key
 	cfg: InfiniteQueryConfig[T, TParam]
 
 	@property
@@ -248,7 +251,7 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		gc_time: float = 300.0,
 		on_dispose: Callable[[Any], None] | None = None,
 	):
-		self.key = key
+		self.key = normalize_key(key)
 
 		self.cfg = InfiniteQueryConfig(
 			retries=retries,
@@ -305,7 +308,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		for obs in self._observers:
 			if obs._on_success is not None:  # pyright: ignore[reportPrivateUsage]
-				await maybe_await(call_flexible(obs._on_success, self.pages))  # pyright: ignore[reportPrivateUsage]
+				with Untrack():
+					await maybe_await(call_flexible(obs._on_success, self.pages))  # pyright: ignore[reportPrivateUsage]
 
 	async def _commit_error(self, error: Exception):
 		"""Commit error state and run error callbacks."""
@@ -313,7 +317,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		for obs in self._observers:
 			if obs._on_error is not None:  # pyright: ignore[reportPrivateUsage]
-				await maybe_await(call_flexible(obs._on_error, error))  # pyright: ignore[reportPrivateUsage]
+				with Untrack():
+					await maybe_await(call_flexible(obs._on_error, error))  # pyright: ignore[reportPrivateUsage]
 
 	def _commit_sync(self):
 		"""Synchronous commit - updates state based on current pages."""
@@ -703,8 +708,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		page = await action.fetch_fn(action.param)
 
-		if idx is None:
-			# Page doesn't exist - jump to this page, clearing existing pages
+		if action.clear or idx is None:
+			# clear=True or page doesn't exist - replace all pages with just this one
 			self.pages.clear()
 			self.pages.append(Page(page, action.param))
 		else:
@@ -782,12 +787,13 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		*,
 		observer: "InfiniteQueryResult[T, TParam] | None" = None,
 		cancel_fetch: bool = False,
+		clear: bool = False,
 	) -> ActionResult[T | None]:
 		"""
 		Refetch a page by its param. Queued for sequential execution.
 
-		If the page doesn't exist, clears existing pages and loads the requested
-		page as the new starting point.
+		If the page doesn't exist or clear=True, clears existing pages and loads
+		the requested page as the new starting point.
 
 		Note: Prefer calling refetch_page() on InfiniteQueryResult to ensure the
 		correct fetch function is used. When called directly on InfiniteQuery, uses
@@ -795,12 +801,13 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		"""
 		fn = fetch_fn if fetch_fn is not None else self.fn
 		action: RefetchPage[T, TParam] = RefetchPage(
-			fetch_fn=fn, param=param, observer=observer
+			fetch_fn=fn, param=param, observer=observer, clear=clear
 		)
 		return await self._enqueue(action, cancel_fetch=cancel_fetch)
 
 	@override
 	def dispose(self):
+		self.cancel_gc()
 		self._cancel_queue()
 		if self._queue_task and not self._queue_task.done():
 			self._queue_task.cancel()
@@ -1018,12 +1025,22 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 		page_param: TParam,
 		*,
 		cancel_fetch: bool = False,
+		clear: bool = False,
 	) -> ActionResult[T | None]:
+		"""Fetch a specific page by its param.
+
+		Args:
+			page_param: The page parameter to fetch.
+			cancel_fetch: Cancel any in-flight fetches before starting.
+			clear: If True, clears all other pages and keeps only the fetched page.
+				Useful for resetting pagination to a specific page.
+		"""
 		return await self._query().refetch_page(
 			page_param,
 			fetch_fn=self._fetch_fn,
 			observer=self,
 			cancel_fetch=cancel_fetch,
+			clear=clear,
 		)
 
 	def set_initial_data(
@@ -1148,7 +1165,7 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		Callable[[TState, list[Page[T, TParam]]], TParam | None] | None
 	)
 	_max_pages: int
-	_key: QueryKey | Callable[[TState], QueryKey] | None
+	_key: Key | Callable[[TState], Key] | None
 	# Not using OnSuccessFn and OnErrorFn since unions of callables are not well
 	# supported in the type system. We just need to be careful to use
 	# call_flexible to invoke these functions.
@@ -1192,7 +1209,17 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		self._on_success_fn = None
 		self._on_error_fn = None
 		self._initial_data = MISSING
-		self._key = key
+		if key is None:
+			self._key = None
+		elif callable(key):
+			key_fn = key
+
+			def normalized_key(state: TState) -> Key:
+				return normalize_key(key_fn(state))
+
+			self._key = normalized_key
+		else:
+			self._key = normalize_key(key)
 		self._initial_data_updated_at = initial_data_updated_at
 		self._enabled = enabled
 		self._fetch_on_mount = fetch_on_mount
@@ -1203,7 +1230,11 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 			raise RuntimeError(
 				f"Cannot use @{self.name}.key decorator when a key is already provided to @infinite_query(key=...)."
 			)
-		self._key = fn
+
+		def normalized_key(state: TState) -> Key:
+			return normalize_key(fn(state))
+
+		self._key = normalized_key
 		return fn
 
 	def on_success(self, fn: OnSuccessFn[TState, list[T]]):
@@ -1383,6 +1414,7 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 def infinite_query(
 	fn: Callable[[TState, TParam], Awaitable[T]],
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1394,7 +1426,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> InfiniteQueryProperty[T, TParam, TState]: ...
 
 
@@ -1402,6 +1433,7 @@ def infinite_query(
 def infinite_query(
 	fn: None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1413,7 +1445,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> Callable[
 	[Callable[[TState, Any], Awaitable[T]]],
 	InfiniteQueryProperty[T, TParam, TState],
@@ -1423,6 +1454,7 @@ def infinite_query(
 def infinite_query(
 	fn: Callable[[TState, TParam], Awaitable[T]] | None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1434,7 +1466,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> (
 	InfiniteQueryProperty[T, TParam, TState]
 	| Callable[
@@ -1448,7 +1479,8 @@ def infinite_query(
 	pagination. Data is stored as a list of pages, each with its data and the
 	parameter used to fetch it.
 
-	Requires ``@query_prop.key`` and ``@query_prop.get_next_page_param`` decorators.
+	Requires a key (``key=`` or ``@query_prop.key``) and
+	``@query_prop.get_next_page_param`` decorator.
 
 	Args:
 		fn: The async method to decorate (when used without parentheses).

pulse/queries/query.py

@@ -26,11 +26,13 @@ from pulse.queries.common import (
 	ActionError,
 	ActionResult,
 	ActionSuccess,
+	Key,
 	OnErrorFn,
 	OnSuccessFn,
 	QueryKey,
 	QueryStatus,
 	bind_state,
+	normalize_key,
 )
 from pulse.queries.effect import AsyncQueryEffect
 from pulse.reactive import Computed, Effect, Signal, Untrack
@@ -239,7 +241,8 @@ async def run_fetch_with_retries(
 				result = await fetch_fn()
 			state.set_success(result)
 			if on_success:
-				await maybe_await(call_flexible(on_success, result))
+				with Untrack():
+					await maybe_await(call_flexible(on_success, result))
 			return
 		except asyncio.CancelledError:
 			raise
@@ -252,7 +255,8 @@ async def run_fetch_with_retries(
 				state.retry_reason.write(e)
 				state.apply_error(e)
 				if on_error:
-					await maybe_await(call_flexible(on_error, e))
+					with Untrack():
+						await maybe_await(call_flexible(on_error, e))
 				return
 
 
@@ -263,7 +267,7 @@ class KeyedQuery(Generic[T], Disposable):
 	Multiple observers can share the same query.
 	"""
 
-	key: QueryKey
+	key: Key
 	state: QueryState[T]
 	observers: "list[KeyedQueryResult[T]]"
 	_task: asyncio.Task[None] | None
@@ -283,7 +287,7 @@ class KeyedQuery(Generic[T], Disposable):
 		gc_time: float = 300.0,
 		on_dispose: Callable[[Any], None] | None = None,
 	):
-		self.key = key
+		self.key = normalize_key(key)
 		self.state = QueryState(
 			name=str(key),
 			retries=retries,
@@ -576,6 +580,7 @@ class KeyedQuery(Generic[T], Disposable):
 	@override
 	def dispose(self):
 		"""Clean up the query, cancelling any in-flight fetch."""
+		self.cancel_gc()
 		self.cancel()
 		if self._interval_effect is not None:
 			self._interval_effect.dispose()
@@ -1054,7 +1059,7 @@ class QueryProperty(Generic[T, TState], InitializableProperty):
 	_initial_data_updated_at: float | dt.datetime | None
 	_enabled: bool
 	_initial_data: T | Callable[[TState], T] | Missing | None
-	_key: QueryKey | Callable[[TState], QueryKey] | None
+	_key: Key | Callable[[TState], Key] | None
 	# Not using OnSuccessFn and OnErrorFn since unions of callables are not well
 	# supported in the type system. We just need to be careful to use
 	# call_flexible to invoke these functions.
@@ -1080,7 +1085,17 @@ class QueryProperty(Generic[T, TState], InitializableProperty):
 	):
 		self.name = name
 		self._fetch_fn = fetch_fn
-		self._key = key
+		if key is None:
+			self._key = None
+		elif callable(key):
+			key_fn = key
+
+			def normalized_key(state: TState) -> Key:
+				return normalize_key(key_fn(state))
+
+			self._key = normalized_key
+		else:
+			self._key = normalize_key(key)
 		self._on_success_fn = None
 		self._on_error_fn = None
 		self._keep_previous_data = keep_previous_data
@@ -1101,7 +1116,11 @@ class QueryProperty(Generic[T, TState], InitializableProperty):
 			raise RuntimeError(
 				f"Cannot use @{self.name}.key decorator when a key is already provided to @query(key=...)."
 			)
-		self._key = fn
+
+		def normalized_key(state: TState) -> Key:
+			return normalize_key(fn(state))
+
+		self._key = normalized_key
 		return fn
 
 	# Decorator to attach a function providing initial data
@@ -1269,6 +1288,7 @@ class QueryProperty(Generic[T, TState], InitializableProperty):
 def query(
 	fn: Callable[[TState], Awaitable[T]],
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	stale_time: float = 0.0,
 	gc_time: float | None = 300.0,
 	refetch_interval: float | None = None,
@@ -1278,7 +1298,6 @@ def query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> QueryProperty[T, TState]: ...
 
 
@@ -1286,6 +1305,7 @@ def query(
 def query(
 	fn: None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	stale_time: float = 0.0,
 	gc_time: float | None = 300.0,
 	refetch_interval: float | None = None,
@@ -1295,13 +1315,13 @@ def query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> Callable[[Callable[[TState], Awaitable[T]]], QueryProperty[T, TState]]: ...
 
 
 def query(
 	fn: Callable[[TState], Awaitable[T]] | None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	stale_time: float = 0.0,
 	gc_time: float | None = 300.0,
 	refetch_interval: float | None = None,
@@ -1311,7 +1331,6 @@ def query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> (
 	QueryProperty[T, TState]
 	| Callable[[Callable[[TState], Awaitable[T]]], QueryProperty[T, TState]]

pulse/queries/store.py

@@ -3,7 +3,7 @@ from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
 from pulse.helpers import MISSING, Missing
-from pulse.queries.common import QueryKey
+from pulse.queries.common import Key, QueryKey, normalize_key
 from pulse.queries.infinite_query import InfiniteQuery, Page
 from pulse.queries.query import RETRY_DELAY_DEFAULT, KeyedQuery
 
@@ -16,7 +16,7 @@ class QueryStore:
 	"""
 
 	def __init__(self):
-		self._entries: dict[QueryKey, KeyedQuery[Any] | InfiniteQuery[Any, Any]] = {}
+		self._entries: dict[Key, KeyedQuery[Any] | InfiniteQuery[Any, Any]] = {}
 
 	def items(self):
 		"""Iterate over all (key, query) pairs in the store."""
@@ -24,7 +24,7 @@ class QueryStore:
 
 	def get_any(self, key: QueryKey):
 		"""Get any query (regular or infinite) by key, or None if not found."""
-		return self._entries.get(key)
+		return self._entries.get(normalize_key(key))
 
 	def ensure(
 		self,
@@ -35,8 +35,9 @@ class QueryStore:
 		retries: int = 3,
 		retry_delay: float = RETRY_DELAY_DEFAULT,
 	) -> KeyedQuery[T]:
+		nkey = normalize_key(key)
 		# Return existing entry if present
-		existing = self._entries.get(key)
+		existing = self._entries.get(nkey)
 		if existing:
 			if isinstance(existing, InfiniteQuery):
 				raise TypeError(
@@ -49,7 +50,7 @@ class QueryStore:
 				del self._entries[e.key]
 
 		entry = KeyedQuery(
-			key,
+			nkey,
 			initial_data=initial_data,
 			initial_data_updated_at=initial_data_updated_at,
 			gc_time=gc_time,
@@ -57,14 +58,14 @@ class QueryStore:
 			retry_delay=retry_delay,
 			on_dispose=_on_dispose,
 		)
-		self._entries[key] = entry
+		self._entries[nkey] = entry
 		return entry
 
 	def get(self, key: QueryKey) -> KeyedQuery[Any] | None:
 		"""
 		Get an existing regular query by key, or None if not found.
 		"""
-		existing = self._entries.get(key)
+		existing = self._entries.get(normalize_key(key))
 		if existing and isinstance(existing, InfiniteQuery):
 			return None
 		return existing
@@ -73,7 +74,7 @@ class QueryStore:
 		"""
 		Get an existing infinite query by key, or None if not found.
 		"""
-		existing = self._entries.get(key)
+		existing = self._entries.get(normalize_key(key))
 		if existing and isinstance(existing, InfiniteQuery):
 			return existing
 		return None
@@ -93,7 +94,8 @@ class QueryStore:
 		retries: int = 3,
 		retry_delay: float = RETRY_DELAY_DEFAULT,
 	) -> InfiniteQuery[Any, Any]:
-		existing = self._entries.get(key)
+		nkey = normalize_key(key)
+		existing = self._entries.get(nkey)
 		if existing:
 			if not isinstance(existing, InfiniteQuery):
 				raise TypeError(
@@ -106,7 +108,7 @@ class QueryStore:
 				del self._entries[e.key]
 
 		entry = InfiniteQuery(
-			key,
+			nkey,
 			initial_page_param=initial_page_param,
 			get_next_page_param=get_next_page_param,
 			get_previous_page_param=get_previous_page_param,
@@ -118,7 +120,7 @@ class QueryStore:
 			retry_delay=retry_delay,
 			on_dispose=_on_dispose,
 		)
-		self._entries[key] = entry
+		self._entries[nkey] = entry
 		return entry
 
 	def dispose_all(self) -> None:

{pulse_framework-0.1.69.dist-info → pulse_framework-0.1.71.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.69
+Version: 0.1.71
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: websockets>=12.0
 Requires-Dist: fastapi>=0.128.0

{pulse_framework-0.1.69.dist-info → pulse_framework-0.1.71.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pulse/__init__.py,sha256=cXNVXz0aizbkOG1aj2zytgzodyVNv7nNylsXcWmH-Lc,32183
+pulse/__init__.py,sha256=yeGbAC9Nkp5ug4sfi3U1epaRfI1_D0zBbMtPQpPEBHA,32393
 pulse/_examples.py,sha256=dFuhD2EVXsbvAeexoG57s4VuN4gWLaTMOEMNYvlPm9A,561
 pulse/app.py,sha256=TjMP21lpwYpRnkMkeKL8EA22V9xSKTA6_5GQI9Btw_o,36059
 pulse/channel.py,sha256=ePpvD2mDbddt_LMxxxDjNRgOLbVi8Ed6TmJFgkrALB0,15790
@@ -77,14 +77,14 @@ pulse/plugin.py,sha256=bu90qaUVFtZsIsW41dpshVK1vvIGHUsg6mFoiF0Wfso,2370
 pulse/proxy.py,sha256=tj30GIJJVNKMxMwPNJ39-gn3PAXbx5wua4PiQ7XupvQ,7857
 pulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/queries/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/queries/client.py,sha256=52T4MvorDr-T5UsJlndcEgnrPDs3QxIYP-MZtBSEuvc,18583
-pulse/queries/common.py,sha256=TYhn6LyldfmOKYYurxINgCEr3C3WSEwB0cIki1a5iBM,2488
+pulse/queries/client.py,sha256=KMGT92dESMrzpLlhd701fyh7Wrs3VKmM5cZoRQ0AEzg,18994
+pulse/queries/common.py,sha256=24EK5AWeunTeC7xObG3xufOjqLUNvnLN7PEECtlgqGU,3705
 pulse/queries/effect.py,sha256=1ePUi2TwP49L9LhlkKI2qV_HhIO4jKj1r5jyPaWiUn8,1508
-pulse/queries/infinite_query.py,sha256=xWmFl5UqW7DXkquR-8EUPqlS6Z-ZF4l7qarEUUXjdN0,49091
+pulse/queries/infinite_query.py,sha256=sfZ_nwznD8kO_zWOvJ9uiyhJRb8slN1QMYWgzUnRvVQ,50025
 pulse/queries/mutation.py,sha256=fhEpOZ7CuHImH4Y02QapYdTJrwe6K52-keb0d67wmms,8274
 pulse/queries/protocol.py,sha256=TOrUiI4QK55xuh0i4ch1u96apNl12QeYafkf6RVDd08,3544
-pulse/queries/query.py,sha256=2VlYMeLqHfEokoEtocKjld8zi6Oy-_lieV4baTfF5DU,41332
-pulse/queries/store.py,sha256=4pWTDSl71LUM7YqhWanKjZkFh3t8F_04o48js_H4ttQ,3728
+pulse/queries/query.py,sha256=R5XXQ32pCSNX5tpedietIlI4saT1MVIJnR6ElnKQyVk,41819
+pulse/queries/store.py,sha256=iw05_EFpyfiXv5_FV_x4aHtCo00mk0dDPFD461cajcg,3850
 pulse/react_component.py,sha256=8RLg4Bi7IcjqbnbEnp4hJpy8t1UsE7mG0UR1Q655LDk,2332
 pulse/reactive.py,sha256=GSh9wSH3THCBjDTafwWttyx7djeKBWV_KqjaKRYUNsA,31393
 pulse/reactive_extensions.py,sha256=yQ1PpdAh4kMvll7R15T72FOg8NFdG_HGBsGc63dawYk,33754
@@ -122,7 +122,7 @@ pulse/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/types/event_handler.py,sha256=psQCydj-WEtBcFU5JU4mDwvyzkW8V2O0g_VFRU2EOHI,1618
 pulse/user_session.py,sha256=nsnsMgqq2xGJZLpbHRMHUHcLrElMP8WcA4gjGMrcoBk,10208
 pulse/version.py,sha256=711vaM1jVIQPgkisGgKZqwmw019qZIsc_QTae75K2pg,1895
-pulse_framework-0.1.69.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-pulse_framework-0.1.69.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
-pulse_framework-0.1.69.dist-info/METADATA,sha256=X4vr-LRgEilEvL7pxzvDIz-mY7gq85oU6nVjaDILngc,8300
-pulse_framework-0.1.69.dist-info/RECORD,,
+pulse_framework-0.1.71.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pulse_framework-0.1.71.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
+pulse_framework-0.1.71.dist-info/METADATA,sha256=emzemQv95geCAUlozNCamUpuVbiVyo2REoNCYsAx3JI,8300
+pulse_framework-0.1.71.dist-info/RECORD,,