pulse-framework 0.1.40__py3-none-any.whl → 0.1.42__py3-none-any.whl

pulse/queries/common.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+from typing import (
+	Any,
+	Concatenate,
+	ParamSpec,
+	TypeVar,
+)
+
+from pulse.state import State
+
+T = TypeVar("T")
+TState = TypeVar("TState", bound="State")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+OnSuccessFn = Callable[[TState], Any] | Callable[[TState, T], Any]
+OnErrorFn = Callable[[TState], Any] | Callable[[TState, Exception], Any]
+
+
+def bind_state(
+	state: TState, fn: Callable[Concatenate[TState, P], R]
+) -> Callable[P, R]:
+	"Type-safe helper to bind a method to a state"
+	return fn.__get__(state, state.__class__)

pulse/queries/mutation.py

@@ -0,0 +1,142 @@
+from collections.abc import Awaitable, Callable
+from typing import (
+	Any,
+	Concatenate,
+	Generic,
+	ParamSpec,
+	TypeVar,
+	override,
+)
+
+from pulse.helpers import call_flexible, maybe_await
+from pulse.queries.common import OnErrorFn, OnSuccessFn, bind_state
+from pulse.reactive import Signal
+from pulse.state import InitializableProperty, State
+
+T = TypeVar("T")
+TState = TypeVar("TState", bound=State)
+R = TypeVar("R")
+P = ParamSpec("P")
+
+
+class MutationResult(Generic[T, P]):
+	"""
+	Result object for mutations that provides reactive access to mutation state
+	and is callable to execute the mutation.
+	"""
+
+	_data: Signal[T | None]
+	_is_running: Signal[bool]
+	_error: Signal[Exception | None]
+	_fn: Callable[P, Awaitable[T]]
+	_on_success: Callable[[T], Any] | None
+	_on_error: Callable[[Exception], Any] | None
+
+	def __init__(
+		self,
+		fn: Callable[P, Awaitable[T]],
+		on_success: Callable[[T], Any] | None = None,
+		on_error: Callable[[Exception], Any] | None = None,
+	):
+		self._data = Signal(None, name="mutation.data")
+		self._is_running = Signal(False, name="mutation.is_running")
+		self._error = Signal(None, name="mutation.error")
+		self._fn = fn
+		self._on_success = on_success
+		self._on_error = on_error
+
+	@property
+	def data(self) -> T | None:
+		return self._data()
+
+	@property
+	def is_running(self) -> bool:
+		return self._is_running()
+
+	@property
+	def error(self) -> Exception | None:
+		return self._error()
+
+	async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+		self._is_running.write(True)
+		self._error.write(None)
+		try:
+			mutation_result = await self._fn(*args, **kwargs)
+			self._data.write(mutation_result)
+			if self._on_success:
+				await maybe_await(call_flexible(self._on_success, mutation_result))
+			return mutation_result
+		except Exception as e:
+			self._error.write(e)
+			if self._on_error:
+				await maybe_await(call_flexible(self._on_error, e))
+			raise e
+		finally:
+			self._is_running.write(False)
+
+
+class MutationProperty(Generic[T, TState, P], InitializableProperty):
+	_on_success_fn: Callable[[TState, T], Any] | None
+	_on_error_fn: Callable[[TState, Exception], Any] | None
+	name: str
+	fn: Callable[Concatenate[TState, P], Awaitable[T]]
+
+	def __init__(
+		self,
+		name: str,
+		fn: Callable[Concatenate[TState, P], Awaitable[T]],
+		on_success: OnSuccessFn[TState, T] | None = None,
+		on_error: OnErrorFn[TState] | None = None,
+	):
+		self.name = name
+		self.fn = fn
+		self._on_success_fn = on_success  # pyright: ignore[reportAttributeAccessIssue]
+		self._on_error_fn = on_error  # pyright: ignore[reportAttributeAccessIssue]
+
+	# Decorator to attach an on-success handler (sync or async)
+	def on_success(self, fn: OnSuccessFn[TState, T]):
+		if self._on_success_fn is not None:
+			raise RuntimeError(
+				f"Duplicate on_success() decorator for mutation '{self.name}'. Only one is allowed."
+			)
+		self._on_success_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
+		return fn
+
+	# Decorator to attach an on-error handler (sync or async)
+	def on_error(self, fn: OnErrorFn[TState]):
+		if self._on_error_fn is not None:
+			raise RuntimeError(
+				f"Duplicate on_error() decorator for mutation '{self.name}'. Only one is allowed."
+			)
+		self._on_error_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
+		return fn
+
+	def __get__(self, obj: Any, objtype: Any = None) -> MutationResult[T, P]:
+		if obj is None:
+			return self  # pyright: ignore[reportReturnType]
+
+		# Cache the result on the instance
+		cache_key = f"__mutation_{self.name}"
+		if not hasattr(obj, cache_key):
+			# Bind methods to state
+			bound_fn = bind_state(obj, self.fn)
+			bound_on_success = (
+				bind_state(obj, self._on_success_fn) if self._on_success_fn else None
+			)
+			bound_on_error = (
+				bind_state(obj, self._on_error_fn) if self._on_error_fn else None
+			)
+
+			result = MutationResult[T, P](
+				fn=bound_fn,
+				on_success=bound_on_success,
+				on_error=bound_on_error,
+			)
+			setattr(obj, cache_key, result)
+
+		return getattr(obj, cache_key)
+
+	@override
+	def initialize(self, state: State, name: str) -> MutationResult[T, P]:
+		# For compatibility with InitializableProperty, but mutations don't need special initialization
+		return self.__get__(state, state.__class__)

pulse/queries/query.py

@@ -0,0 +1,270 @@
+import asyncio
+import time
+from collections.abc import Awaitable, Callable, Hashable
+from dataclasses import dataclass
+from typing import (
+	TYPE_CHECKING,
+	Any,
+	Generic,
+	Literal,
+	TypeAlias,
+	TypeVar,
+	cast,
+	override,
+)
+
+from pulse.helpers import (
+	MISSING,
+	Disposable,
+	call_flexible,
+	is_pytest,
+	later,
+	maybe_await,
+)
+from pulse.reactive import AsyncEffect, Computed, Signal
+
+if TYPE_CHECKING:
+	from pulse.queries.query_observer import QueryResult
+
+T = TypeVar("T")
+QueryKey: TypeAlias = tuple[Hashable, ...]
+QueryStatus: TypeAlias = Literal["loading", "success", "error"]
+QueryFetchStatus: TypeAlias = Literal["idle", "fetching", "paused"]
+
+
+class AsyncQueryEffect(AsyncEffect):
+	"""
+	Specialized AsyncEffect for queries that synchronously sets loading state
+	when rescheduled/run.
+	"""
+
+	query: "Query[Any]"
+
+	def __init__(
+		self,
+		fn: Callable[[], Awaitable[None]],
+		query: "Query[Any]",
+		name: str | None = None,
+		lazy: bool = False,
+		deps: list[Signal[Any] | Computed[Any]] | None = None,
+	):
+		self.query = query
+		super().__init__(fn, name=name, lazy=lazy, deps=deps)
+
+	@override
+	def run(self) -> asyncio.Task[Any]:
+		# Immediately set loading state before running the effect
+		self.query.fetch_status.write("fetching")
+		return super().run()
+
+
+@dataclass(slots=True)
+class QueryConfig(Generic[T]):
+	retries: int
+	retry_delay: float
+	initial_data: T | Callable[[], T] | None
+	gc_time: float
+	on_dispose: Callable[[Any], None] | None
+
+
+RETRY_DELAY_DEFAULT = 2.0 if not is_pytest() else 0.01
+
+
+class Query(Generic[T], Disposable):
+	"""
+	Represents a single query instance in a store.
+	Manages the async effect, data/status signals, and observer tracking.
+	"""
+
+	key: QueryKey | None
+	fn: Callable[[], Awaitable[T]]
+	cfg: QueryConfig[T]
+
+	# Reactive signals for query state
+	data: Signal[T | None]
+	error: Signal[Exception | None]
+	last_updated: Signal[float]
+	status: Signal[QueryStatus]
+	fetch_status: Signal[QueryFetchStatus]
+	retries: Signal[int]
+	retry_reason: Signal[Exception | None]
+
+	_observers: "list[QueryResult[T]]"
+	_effect: AsyncEffect | None
+	_gc_handle: asyncio.TimerHandle | None
+
+	def __init__(
+		self,
+		key: QueryKey | None,
+		fn: Callable[[], Awaitable[T]],
+		retries: int = 3,
+		retry_delay: float = RETRY_DELAY_DEFAULT,
+		initial_data: T | None = MISSING,
+		gc_time: float = 300.0,
+		on_dispose: Callable[[Any], None] | None = None,
+	):
+		self.key = key
+		self.fn = fn
+		self.cfg = QueryConfig(
+			retries=retries,
+			retry_delay=retry_delay,
+			initial_data=initial_data,
+			gc_time=gc_time,
+			on_dispose=on_dispose,
+		)
+
+		# Initialize reactive signals
+		self.data = Signal(
+			None if initial_data is MISSING else initial_data, name=f"query.data({key})"
+		)
+		self.error = Signal(None, name=f"query.error({key})")
+		self.last_updated = Signal(
+			time.time() if initial_data is not MISSING else 0.0,
+			name=f"query.last_updated({key})",
+		)
+		self.status = Signal(
+			"loading" if initial_data is MISSING else "success",
+			name=f"query.status({key})",
+		)
+		self.fetch_status = Signal("idle", name=f"query.fetch_status({key})")
+		self.retries = Signal(0, name=f"query.retries({key})")
+		self.retry_reason = Signal(None, name=f"query.retry_reason({key})")
+
+		self._observers = []
+		self._gc_handle = None
+		# Effect is created lazily on first observation
+		self._effect = None
+
+	def set_data(self, data: T):
+		self._set_success(data, manual=True)
+
+	def set_error(self, error: Exception):
+		self._set_error(error, manual=True)
+
+	def _set_success(self, data: T, manual: bool = False):
+		self.data.write(data)
+		self.last_updated.write(time.time())
+		self.error.write(None)
+		self.status.write("success")
+		if not manual:
+			self.fetch_status.write("idle")
+			self.retries.write(0)
+			self.retry_reason.write(None)
+
+	def _set_error(self, error: Exception, manual: bool = False):
+		self.error.write(error)
+		self.last_updated.write(time.time())
+		self.status.write("error")
+		if not manual:
+			self.fetch_status.write("idle")
+			# Don't reset retries on final error - preserve for debugging
+			# retry_reason is updated to the final error in _run
+
+	def _failed_retry(self, reason: Exception):
+		self.retries.write(self.retries.read() + 1)
+		self.retry_reason.write(reason)
+
+	@property
+	def effect(self) -> AsyncEffect:
+		"""Lazy property that creates the query effect on first access."""
+		if self._effect is None:
+			self._effect = AsyncQueryEffect(
+				self._run,
+				query=self,
+				name=f"query_effect({self.key})",
+				deps=[] if self.key is not None else None,
+			)
+		return self._effect
+
+	async def _run(self):
+		# Reset retries at start of run
+		self.retries.write(0)
+		self.retry_reason.write(None)
+
+		while True:
+			try:
+				result = await self.fn()
+				self._set_success(result)
+				for obs in self._observers:
+					if obs._on_success:  # pyright: ignore[reportPrivateUsage]
+						await maybe_await(call_flexible(obs._on_success, result))  # pyright: ignore[reportPrivateUsage]
+				return
+			except asyncio.CancelledError:
+				raise
+			except Exception as e:
+				current_retries = self.retries.read()
+				if current_retries < self.cfg.retries:
+					# Record failed retry attempt and retry
+					self._failed_retry(e)
+					# Wait before retrying
+					await asyncio.sleep(self.cfg.retry_delay)
+				else:
+					# All retries exhausted - update retry_reason to final error
+					self.retry_reason.write(e)
+					self._set_error(e)
+					for obs in self._observers:
+						if obs._on_error:  # pyright: ignore[reportPrivateUsage]
+							await maybe_await(call_flexible(obs._on_error, e))  # pyright: ignore[reportPrivateUsage]
+					return
+
+	async def refetch(self, cancel_refetch: bool = True) -> T:
+		"""
+		Reruns the query and returns the result.
+		If cancel_refetch is True (default), cancels any in-flight request and starts a new one.
+		If cancel_refetch is False, deduplicates requests if one is already in flight.
+		"""
+		if cancel_refetch:
+			self.effect.cancel()
+		return await self.wait()
+
+	async def wait(self) -> T:
+		await self.effect.wait()
+		return cast(T, self.data.read())
+
+	def invalidate(self, cancel_refetch: bool = False):
+		"""
+		Marks query as stale. If there are active observers, triggers a refetch.
+		"""
+		should_schedule = not self.effect.is_scheduled or cancel_refetch
+		if should_schedule and len(self._observers) > 0:
+			self.effect.schedule()
+
+	def observe(
+		self,
+		observer: "QueryResult[T]",
+	):
+		_ = self.effect  # ensure effect is created
+		self._observers.append(observer)
+		self.cancel_gc()
+		if observer._gc_time > 0:  # pyright: ignore[reportPrivateUsage]
+			self.cfg.gc_time = max(self.cfg.gc_time, observer._gc_time)  # pyright: ignore[reportPrivateUsage]
+
+	def unobserve(self, observer: "QueryResult[T]"):
+		"""Unregister an observer. Schedules GC if no observers remain."""
+		if observer in self._observers:
+			self._observers.remove(observer)
+		if len(self._observers) == 0:
+			self.schedule_gc()
+
+	def schedule_gc(self):
+		self.cancel_gc()
+		if self.cfg.gc_time > 0:
+			self._gc_handle = later(self.cfg.gc_time, self.dispose)
+		else:
+			self.dispose()
+
+	def cancel_gc(self):
+		if self._gc_handle:
+			self._gc_handle.cancel()
+			self._gc_handle = None
+
+	@override
+	def dispose(self):
+		"""
+		Cleans up the query entry, removing it from the store.
+		"""
+		if self._effect:
+			self._effect.dispose()
+
+		if self.cfg.on_dispose:
+			self.cfg.on_dispose(self)