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

pulse/queries/common.py

@@ -13,7 +13,7 @@ from typing import (
 	override,
 )
 
-from pulse.state import State
+from pulse.state.state import State
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound="State")
@@ -34,19 +34,31 @@ class Key(tuple[Hashable, ...]):
 			parts = tuple(key)
 			try:
 				key_hash = hash(parts)
-			except TypeError:
-				raise TypeError("QueryKey values must be hashable") from None
+			except TypeError as e:
+				raise TypeError(
+					f"Query key contains unhashable value: {e}.\n\n"
+					+ "Keys must contain only hashable values (strings, numbers, tuples).\n"
+					+ f"Got: {key!r}\n\n"
+					+ "If using a dict or list inside the key, convert it to a tuple:\n"
+					+ "    key=('users', tuple(user_ids))  # instead of list"
+				) 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")
+		raise TypeError(
+			f"Query key must be a tuple or list, got {type(key).__name__}: {key!r}\n\n"
+			+ "Examples of valid keys:\n"
+			+ "    key=('users',)           # single-element tuple\n"
+			+ "    key=('user', user_id)    # tuple with dynamic value\n"
+			+ "    key=['posts', 'feed']    # list form also works"
+		)
 
 	@override
 	def __hash__(self) -> int:
 		return self._hash
 
 
-QueryKey: TypeAlias = tuple[Hashable, ...] | list[Hashable] | Key
+QueryKey: TypeAlias = tuple[Hashable, ...] | list[Hashable] | Key  # pyright: ignore[reportImplicitStringConcatenation]
 """List/tuple of hashable values identifying a query in the store.
 
 Used to uniquely identify queries for caching, deduplication, and invalidation.

pulse/queries/infinite_query.py

@@ -39,7 +39,8 @@ from pulse.queries.query import RETRY_DELAY_DEFAULT, QueryConfig
 from pulse.reactive import Computed, Effect, Signal, Untrack
 from pulse.reactive_extensions import ReactiveList, unwrap
 from pulse.scheduling import TimerHandleLike, create_task, later
-from pulse.state import InitializableProperty, State
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 T = TypeVar("T")
 TParam = TypeVar("TParam")
@@ -432,7 +433,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		self._cancel_observer_actions(observer)
 
 		if len(self._observers) == 0:
-			self.schedule_gc()
+			if not self.__disposed__:
+				self.schedule_gc()
 
 	def invalidate(
 		self,
@@ -1308,8 +1310,17 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		)
 
 		if self._key is None:
+			# pyright: ignore[reportImplicitStringConcatenation]
 			raise RuntimeError(
-				f"key is required for infinite query '{self.name}'. Provide a key via @infinite_query(key=...) or @{self.name}.key decorator."
+				f"Missing query key for @infinite_query '{self.name}'. "
+				+ "A key is required to cache and share query results.\n\n"
+				+ f"Fix: Add key=(...) to the decorator or use the @{self.name}.key decorator:\n\n"
+				+ "    @ps.infinite_query(initial_page_param=..., key=('my_query',))\n"
+				+ f"    async def {self.name}(self, param): ...\n\n"
+				+ "Or with a dynamic key:\n\n"
+				+ f"    @{self.name}.key\n"
+				+ f"    def _{self.name}_key(self):\n"
+				+ "        return ('my_query', self.some_param)"
 			)
 		raw_initial = (
 			call_flexible(self._initial_data, state)

pulse/queries/mutation.py

@@ -13,7 +13,8 @@ from typing import (
 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
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound=State)

pulse/queries/query.py

@@ -37,7 +37,8 @@ from pulse.queries.common import (
 from pulse.queries.effect import AsyncQueryEffect
 from pulse.reactive import Computed, Effect, Signal, Untrack
 from pulse.scheduling import TimerHandleLike, create_task, is_pytest, later
-from pulse.state import InitializableProperty, State
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 if TYPE_CHECKING:
 	from pulse.queries.protocol import QueryResult
@@ -563,7 +564,8 @@ class KeyedQuery(Generic[T], Disposable):
 				)
 
 		if len(self.observers) == 0:
-			self.schedule_gc()
+			if not self.__disposed__:
+				self.schedule_gc()
 
 	def schedule_gc(self):
 		self.cancel_gc()

pulse/render_session.py

@@ -34,7 +34,7 @@ from pulse.scheduling import (
 	TimerRegistry,
 	create_future,
 )
-from pulse.state import State
+from pulse.state.state import State
 from pulse.transpiler.id import next_id
 from pulse.transpiler.nodes import Expr
 
@@ -111,7 +111,7 @@ class RouteMount:
 	) -> None:
 		self.render = render
 		self.path = ensure_absolute_path(path)
-		self.route = RouteContext(route_info, route)
+		self.route = RouteContext(route_info, route, render)
 		self.effect = None
 		self._pulse_ctx = None
 		self.tree = RenderTree(route.render())
@@ -285,7 +285,6 @@ class RenderSession:
 		self._send_message = None
 		self._global_states = {}
 		self._global_queue = []
-		self.query_store = QueryStore()
 		self.connected = False
 		self.channels = ChannelsManager(self)
 		self.forms = FormRegistry(self)
@@ -293,6 +292,7 @@ class RenderSession:
 		self._pending_js_results = {}
 		self._tasks = TaskRegistry(name=f"render:{id}")
 		self._timers = TimerRegistry(tasks=self._tasks, name=f"render:{id}")
+		self.query_store = QueryStore()
 		self.prerender_queue_timeout = prerender_queue_timeout
 		self.detach_queue_timeout = detach_queue_timeout
 		self.disconnect_queue_timeout = disconnect_queue_timeout
@@ -574,9 +574,10 @@ class RenderSession:
 	# ---- Helpers ----
 
 	def close(self):
+		# Close all pending timers at the start, to avoid anything firing while we clean up
+		self._timers.cancel_all()
 		self.forms.dispose()
 		self._tasks.cancel_all()
-		self._timers.cancel_all()
 		for path in list(self.route_mounts.keys()):
 			self.detach(path, timeout=0)
 		self.route_mounts.clear()
@@ -597,6 +598,8 @@ class RenderSession:
 			if not fut.done():
 				fut.cancel()
 		self._pending_js_results.clear()
+		# Close any timer that may have been scheduled during cleanup (ex: query GC)
+		self._timers.cancel_all()
 		self._global_queue = []
 		self._send_message = None
 		self.connected = False

pulse/renderer.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from types import NoneType
 from typing import Any, NamedTuple, TypeAlias, cast
 
+from pulse.debounce import Debounced
 from pulse.helpers import values_equal
 from pulse.hooks.core import HookContext
 from pulse.transpiler import Import
@@ -33,7 +34,7 @@ from pulse.transpiler.vdom import (
 	VDOMPropValue,
 )
 
-PropValue: TypeAlias = Node | Callable[..., Any]
+PropValue: TypeAlias = Node | Callable[..., Any] | Debounced[Any, Any]
 
 FRAGMENT_TAG = ""
 MOUNT_PREFIX = "$$"
@@ -404,6 +405,21 @@ class Renderer:
 					updated[key] = value.render()
 				continue
 
+			if isinstance(value, Debounced):
+				eval_keys.add(key)
+				if isinstance(old_value, (Element, PulseNode)):
+					unmount_element(old_value)
+				if normalized is None:
+					normalized = current.copy()
+				normalized[key] = value
+				register_callback(self.callbacks, prop_path, value.fn)
+				prev_delay = (
+					old_value.delay_ms if isinstance(old_value, Debounced) else None
+				)
+				if prev_delay != value.delay_ms:
+					updated[key] = format_callback_placeholder(value.delay_ms)
+				continue
+
 			if callable(value):
 				eval_keys.add(key)
 				if isinstance(old_value, (Element, PulseNode)):
@@ -412,7 +428,7 @@ class Renderer:
 					normalized = current.copy()
 				normalized[key] = value
 				register_callback(self.callbacks, prop_path, value)
-				if not callable(old_value):
+				if not callable(old_value) or isinstance(old_value, Debounced):
 					updated[key] = CALLBACK_PLACEHOLDER
 				continue
 
@@ -483,6 +499,8 @@ def prop_requires_eval(value: PropValue) -> bool:
 		return True
 	if isinstance(value, Expr):
 		return True
+	if isinstance(value, Debounced):
+		return True
 	return callable(value)
 
 
@@ -530,6 +548,16 @@ def normalize_children(children: Children | None) -> list[Node]:
 	return out
 
 
+def format_callback_placeholder(delay_ms: float | None) -> str:
+	if delay_ms is None:
+		return CALLBACK_PLACEHOLDER
+	if delay_ms.is_integer():
+		suffix = str(int(delay_ms))
+	else:
+		suffix = format(delay_ms, "g")
+	return f"{CALLBACK_PLACEHOLDER}:{suffix}"
+
+
 def register_callback(
 	callbacks: Callbacks,
 	path: str,

pulse/routing.py

@@ -1,12 +1,16 @@
 import re
 from collections.abc import Sequence
 from dataclasses import dataclass, field
-from typing import TypedDict, cast, override
+from typing import TYPE_CHECKING, TypedDict, cast, override
 
 from pulse.component import Component
 from pulse.env import env
 from pulse.reactive_extensions import ReactiveDict
 
+if TYPE_CHECKING:
+	from pulse.render_session import RenderSession
+	from pulse.state.query_param import QueryParamSync
+
 # angle brackets cannot appear in a regular URL path, this ensures no name conflicts
 LAYOUT_INDICATOR = "<layout>"
 
@@ -516,7 +520,8 @@ class RouteContext:
 	"""Runtime context for the current route.
 
 	Provides reactive access to the current route's URL components and
-	parameters. Accessible via `ps.route()` in components.
+	parameters. Available via `ps.route()` (route info) and `ps.pulse_route()`
+	(route definition) in components.
 
 	Attributes:
 		info: Current route info (reactive, auto-updates on navigation).
@@ -534,18 +539,27 @@ class RouteContext:
 		```python
 		@ps.component
 		def UserProfile():
-			ctx = ps.route()
-			user_id = ctx.pathParams.get("id")
+			info = ps.route()
+			user_id = info["pathParams"].get("id")
 			return ps.div(f"User: {user_id}")
 		```
 	"""
 
 	info: RouteInfo
 	pulse_route: Route | Layout
+	query_param_sync: "QueryParamSync"
 
-	def __init__(self, info: RouteInfo, pulse_route: Route | Layout):
+	def __init__(
+		self,
+		info: RouteInfo,
+		pulse_route: Route | Layout,
+		render: "RenderSession",
+	):
 		self.info = cast(RouteInfo, cast(object, ReactiveDict(info)))
 		self.pulse_route = pulse_route
+		from pulse.state.query_param import QueryParamSync
+
+		self.query_param_sync = QueryParamSync(render, self)
 
 	def update(self, info: RouteInfo) -> None:
 		"""Update the route info with new values.

pulse/serializer.py

@@ -1,4 +1,4 @@
-"""Pulse serializer v3 implementation (Python).
+"""Pulse serializer v4 implementation (Python).
 
 The format mirrors the TypeScript implementation in ``packages/pulse/js``.
 
@@ -13,8 +13,10 @@ Serialized payload structure::
   ``refs``, ``dates``, ``sets``, ``maps``.
 - ``refs``  – indices where the payload entry is an integer pointing to a
   previously visited node's index (shared refs/cycles).
-- ``dates`` – indices that should be materialised as ``datetime`` objects; the
-  payload entry is the millisecond timestamp since the Unix epoch (UTC).
+- ``dates`` – indices that should be materialised as temporal objects; the
+  payload entry is an ISO 8601 string:
+  - ``YYYY-MM-DD`` → ``datetime.date``
+  - ``YYYY-MM-DDTHH:MM:SS.SSSZ`` → ``datetime.datetime`` (UTC)
 - ``sets``  – indices that are ``set`` instances; payload is an array of their
   items.
 - ``maps``  – indices that are ``Map`` instances; payload is an object mapping
@@ -22,8 +24,8 @@ Serialized payload structure::
 
 Nodes are assigned a single global index as they are visited (non-primitives
 only). This preserves shared references and cycles across nested structures
-containing primitives, lists/tuples, ``dict``/plain objects, ``set`` and
-``datetime`` objects.
+containing primitives, lists/tuples, ``dict``/plain objects, ``set``, ``date``
+and ``datetime`` objects.
 """
 
 from __future__ import annotations
@@ -49,7 +51,7 @@ def serialize(data: Any) -> Serialized:
 	"""Serialize a Python value to wire format.
 
 	Converts Python values to a JSON-compatible format with metadata for
-	preserving types like datetime, set, and shared references.
+		preserving types like datetime, date, set, and shared references.
 
 	Args:
 		data: Value to serialize.
@@ -64,7 +66,8 @@ def serialize(data: Any) -> Serialized:
 	Supported types:
 		- Primitives: None, bool, int, float, str
 		- Collections: list, tuple, dict, set
-		- datetime.datetime (converted to milliseconds since Unix epoch)
+		- datetime.datetime (converted to ISO 8601 UTC)
+		- datetime.date (converted to ISO 8601 date string)
 		- Dataclasses (serialized as dict of fields)
 		- Objects with __dict__ (public attributes only)
 
@@ -123,7 +126,11 @@ def serialize(data: Any) -> Serialized:
 
 		if isinstance(value, dt.datetime):
 			dates.append(idx)
-			return _datetime_to_millis(value)
+			return _datetime_to_iso(value)
+
+		if isinstance(value, dt.date):
+			dates.append(idx)
+			return value.isoformat()
 
 		if isinstance(value, dict):
 			result_dict: dict[str, PlainJSON] = {}
@@ -178,7 +185,7 @@ def deserialize(
 	"""Deserialize wire format back to Python values.
 
 	Reconstructs Python values from the serialized format, restoring
-	datetime objects, sets, and shared references.
+	date/datetime objects, sets, and shared references.
 
 	Args:
 		payload: Serialized tuple from serialize().
@@ -191,6 +198,7 @@ def deserialize(
 
 	Notes:
 		- datetime values are reconstructed as UTC-aware
+		- date values are reconstructed as ``datetime.date``
 		- set values are reconstructed as Python sets
 		- Shared references and cycles are restored
 
@@ -228,10 +236,12 @@ def deserialize(
 			return objects[target_index]
 
 		if idx in dates:
-			assert isinstance(value, (int, float)), (
-				"Date payload must be a numeric timestamp"
-			)
-			dt_value = _datetime_from_millis(value)
+			assert isinstance(value, str), "Date payload must be an ISO string"
+			if _is_date_literal(value):
+				date_value = dt.date.fromisoformat(value)
+				objects.append(date_value)
+				return date_value
+			dt_value = _datetime_from_iso(value)
 			objects.append(dt_value)
 			return dt_value
 
@@ -267,13 +277,22 @@ def deserialize(
 	return reconstruct(data)
 
 
-def _datetime_to_millis(value: dt.datetime) -> int:
+def _datetime_to_iso(value: dt.datetime) -> str:
 	if value.tzinfo is None:
-		ts = value.replace(tzinfo=dt.UTC).timestamp()
+		value = value.replace(tzinfo=dt.UTC)
 	else:
-		ts = value.astimezone(dt.UTC).timestamp()
-	return int(round(ts * 1000))
+		value = value.astimezone(dt.UTC)
+	return value.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _datetime_from_iso(value: str) -> dt.datetime:
+	if value.endswith("Z"):
+		value = value[:-1] + "+00:00"
+	parsed = dt.datetime.fromisoformat(value)
+	if parsed.tzinfo is None:
+		return parsed.replace(tzinfo=dt.UTC)
+	return parsed
 
 
-def _datetime_from_millis(value: int | float) -> dt.datetime:
-	return dt.datetime.fromtimestamp(value / 1000.0, tz=dt.UTC)
+def _is_date_literal(value: str) -> bool:
+	return len(value) == 10 and value[4] == "-" and value[7] == "-"

pulse/state/__init__.py

@@ -0,0 +1 @@
+"""State package modules."""

pulse/state/property.py

@@ -0,0 +1,218 @@
+"""
+Descriptors for reactive state classes.
+"""
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Generic, Never, TypeVar, override
+
+from pulse.reactive import AsyncEffect, Computed, Effect, Signal
+from pulse.reactive_extensions import ReactiveProperty
+
+T = TypeVar("T")
+
+if TYPE_CHECKING:
+	from pulse.state.state import State
+
+
+class StateProperty(ReactiveProperty[Any]):
+	"""
+	Descriptor for reactive properties on State classes.
+
+	StateProperty wraps a Signal and provides automatic reactivity for
+	class attributes. When a property is read, it subscribes to the underlying
+	Signal. When written, it updates the Signal and triggers re-renders.
+
+	This class is typically not used directly. Instead, declare typed attributes
+	on a State subclass, and the StateMeta metaclass will automatically convert
+	them into StateProperty instances.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0  # Automatically becomes a StateProperty
+	    name: str = "default"
+
+	state = MyState()
+	state.count = 5  # Updates the underlying Signal
+	print(state.count)  # Reads from the Signal, subscribes to changes
+	```
+	"""
+
+	pass
+
+
+class InitializableProperty(ABC):
+	@abstractmethod
+	def initialize(self, state: "State", name: str) -> Any: ...
+
+
+class ComputedProperty(Generic[T]):
+	"""
+	Descriptor for computed (derived) properties on State classes.
+
+	ComputedProperty wraps a method that derives its value from other reactive
+	properties. The computed value is cached and only recalculated when its
+	dependencies change. Reading a computed property subscribes to it.
+
+	Created automatically when using the @ps.computed decorator on a State method.
+
+	Args:
+		name: The property name (used for debugging and the private storage key).
+		fn: The method that computes the value. Must take only `self` as argument.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0
+
+	    @ps.computed
+	    def doubled(self):
+	        return self.count * 2
+
+	state = MyState()
+	print(state.doubled)  # 0
+	state.count = 5
+	print(state.doubled)  # 10 (automatically recomputed)
+	```
+	"""
+
+	name: str
+	private_name: str
+	fn: "Callable[[State], T]"
+
+	def __init__(self, name: str, fn: "Callable[[State], T]"):
+		self.name = name
+		self.private_name = f"__computed_{name}"
+		# The computed_template holds the original method
+		self.fn = fn
+
+	def get_computed(self, obj: Any) -> Computed[T]:
+		from pulse.state.state import State
+
+		if not isinstance(obj, State):
+			raise ValueError(
+				f"Computed property {self.name} defined on a non-State class"
+			)
+		if not hasattr(obj, self.private_name):
+			# Create the computed on first access for this instance
+			bound_method = self.fn.__get__(obj, obj.__class__)
+			new_computed = Computed(
+				bound_method,
+				name=f"{obj.__class__.__name__}.{self.name}",
+			)
+			setattr(obj, self.private_name, new_computed)
+		return getattr(obj, self.private_name)
+
+	def __get__(self, obj: Any, objtype: Any = None) -> T:
+		if obj is None:
+			return self  # pyright: ignore[reportReturnType]
+
+		return self.get_computed(obj).read()
+
+	def __set__(self, obj: Any, value: Any) -> Never:
+		raise AttributeError(f"Cannot set computed property '{self.name}'")
+
+
+class StateEffect(Generic[T], InitializableProperty):
+	"""
+	Descriptor for side effects on State classes.
+
+	StateEffect wraps a method that performs side effects when its dependencies
+	change. The effect is initialized when the State instance is created and
+	disposed when the State is disposed.
+
+	Created automatically when using the @ps.effect decorator on a State method.
+	Supports both sync and async methods.
+
+		Args:
+			fn: The effect function. Must take only `self` as argument.
+			        Can return a cleanup function that runs before the next execution
+			        or when the effect is disposed.
+		name: Debug name for the effect. Defaults to "ClassName.method_name".
+		immediate: If True, run synchronously when scheduled (sync effects only).
+		lazy: If True, don't run on creation; wait for first dependency change.
+		on_error: Callback for handling errors during effect execution.
+		deps: Explicit dependencies. If provided, auto-tracking is disabled.
+		interval: Re-run interval in seconds for polling effects.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0
+
+	    @ps.effect
+	    def log_count(self):
+	        print(f"Count changed to: {self.count}")
+
+	    @ps.effect
+	    async def fetch_data(self):
+	        data = await api.fetch(self.query)
+	        self.data = data
+
+	    @ps.effect
+	    def subscribe(self):
+	        unsub = event_bus.subscribe(self.handle_event)
+	        return unsub  # Cleanup function
+	```
+	"""
+
+	fn: "Callable[[State], T]"
+	name: str | None
+	immediate: bool
+	on_error: "Callable[[Exception], None] | None"
+	lazy: bool
+	deps: "list[Signal[Any] | Computed[Any]] | None"
+	update_deps: bool | None
+	interval: float | None
+
+	def __init__(
+		self,
+		fn: "Callable[[State], T]",
+		name: str | None = None,
+		immediate: bool = False,
+		lazy: bool = False,
+		on_error: "Callable[[Exception], None] | None" = None,
+		deps: "list[Signal[Any] | Computed[Any]] | None" = None,
+		update_deps: bool | None = None,
+		interval: float | None = None,
+	):
+		self.fn = fn
+		self.name = name
+		self.immediate = immediate
+		self.on_error = on_error
+		self.lazy = lazy
+		self.deps = deps
+		self.update_deps = update_deps
+		self.interval = interval
+
+	@override
+	def initialize(self, state: "State", name: str):
+		bound_method = self.fn.__get__(state, state.__class__)
+		# Select sync/async effect type based on bound method
+		if inspect.iscoroutinefunction(bound_method):
+			effect: Effect = AsyncEffect(
+				bound_method,  # type: ignore[arg-type]
+				name=self.name or f"{state.__class__.__name__}.{name}",
+				lazy=self.lazy,
+				on_error=self.on_error,
+				deps=self.deps,
+				update_deps=self.update_deps,
+				interval=self.interval,
+			)
+		else:
+			effect = Effect(
+				bound_method,  # type: ignore[arg-type]
+				name=self.name or f"{state.__class__.__name__}.{name}",
+				immediate=self.immediate,
+				lazy=self.lazy,
+				on_error=self.on_error,
+				deps=self.deps,
+				update_deps=self.update_deps,
+				interval=self.interval,
+			)
+		setattr(state, name, effect)