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

pulse/reactive.py

@@ -1,18 +1,24 @@
 import asyncio
 import copy
 import inspect
-from collections.abc import Callable, Coroutine
+from collections.abc import Awaitable, Callable
 from contextvars import ContextVar, Token
 from typing import (
 	Any,
 	Generic,
+	Literal,
 	ParamSpec,
 	TypeVar,
-	cast,
 	override,
 )
 
-from pulse.helpers import create_task, schedule_on_loop, values_equal
+from pulse.helpers import (
+	Disposable,
+	create_task,
+	maybe_await,
+	schedule_on_loop,
+	values_equal,
+)
 
 T = TypeVar("T")
 P = ParamSpec("P")
@@ -94,6 +100,7 @@ class Computed(Generic[T]):
 	name: str | None
 	dirty: bool
 	on_stack: bool
+	accepts_prev_value: bool
 
 	def __init__(self, fn: Callable[..., T], name: str | None = None):
 		self.fn = fn
@@ -106,6 +113,18 @@ class Computed(Generic[T]):
 		self.deps: dict[Signal[Any] | Computed[Any], int] = {}
 		self.obs: list[Computed[Any] | Effect] = []
 		self._obs_change_listeners: list[Callable[[int], None]] = []
+		sig = inspect.signature(self.fn)
+		params = list(sig.parameters.values())
+		# Check if function has at least one positional parameter
+		# (excluding *args and **kwargs, and keyword-only params)
+		self.accepts_prev_value = any(
+			p.kind
+			in (
+				inspect.Parameter.POSITIONAL_ONLY,
+				inspect.Parameter.POSITIONAL_OR_KEYWORD,
+			)
+			for p in params
+		)
 
 	def read(self) -> T:
 		if self.on_stack:
@@ -156,7 +175,10 @@ class Computed(Generic[T]):
 			self.on_stack = True
 			try:
 				execution_epoch = epoch()
-				self.value = self.fn()
+				if self.accepts_prev_value:
+					self.value = self.fn(prev_value)
+				else:
+					self.value = self.fn()
 				if epoch() != execution_epoch:
 					raise RuntimeError(
 						f"Detected write to a signal in computed {self.name}. Computeds should be read-only."
@@ -231,10 +253,10 @@ class Computed(Generic[T]):
 EffectCleanup = Callable[[], None]
 # Split effect function types into sync and async for clearer typing
 EffectFn = Callable[[], EffectCleanup | None]
-AsyncEffectFn = Callable[[], Coroutine[Any, Any, EffectCleanup | None]]
+AsyncEffectFn = Callable[[], Awaitable[EffectCleanup | None]]
 
 
-class Effect:
+class Effect(Disposable):
 	"""
 	Synchronous effect and base class. Use AsyncEffect for async effects.
 	Both are isinstance(Effect).
@@ -247,6 +269,7 @@ class Effect:
 	last_run: int
 	immediate: bool
 	_lazy: bool
+	explicit_deps: bool
 	batch: "Batch | None"
 
 	def __init__(
@@ -269,13 +292,19 @@ class Effect:
 		self.last_run = -1
 		self.scope: Scope | None = None
 		self.batch = None
-		self._explicit_deps: list[Signal[Any] | Computed[Any]] | None = deps
+		self.explicit_deps = deps is not None
 		self.immediate = immediate
 		self._lazy = lazy
 
 		if immediate and lazy:
 			raise ValueError("An effect cannot be boht immediate and lazy")
 
+		# Register explicit dependencies immediately upon initialization
+		if deps is not None:
+			self.deps = {dep: dep.last_change for dep in deps}
+			for dep in deps:
+				dep.add_obs(self)
+
 		rc = REACTIVE_CONTEXT.get()
 		if rc.scope is not None:
 			rc.scope.register_effect(self)
@@ -291,6 +320,7 @@ class Effect:
 		if self.cleanup_fn:
 			self.cleanup_fn()
 
+	@override
 	def dispose(self):
 		self.unschedule()
 		for child in self.children.copy():
@@ -353,15 +383,24 @@ class Effect:
 			return
 		raise exc
 
-	def _apply_scope_results(self, scope: "Scope") -> None:
+	def _apply_scope_results(
+		self,
+		scope: "Scope",
+		captured_last_changes: dict[Signal[Any] | Computed[Any], int] | None = None,
+	) -> None:
+		# Apply captured last_change values at the end for explicit deps
+		if self.explicit_deps:
+			assert captured_last_changes is not None
+			for dep, last_change in captured_last_changes.items():
+				self.deps[dep] = last_change
+			return
+
 		self.children = scope.effects
 		for child in self.children:
 			child.parent = self
 
 		prev_deps = set(self.deps)
-		if self._explicit_deps is not None:
-			self.deps = {dep: dep.last_change for dep in self._explicit_deps}
-		else:
+		if not self.explicit_deps:
 			self.deps = scope.deps
 		new_deps = set(self.deps)
 		add_deps = new_deps - prev_deps
@@ -379,8 +418,8 @@ class Effect:
 
 	def _copy_kwargs(self) -> dict[str, Any]:
 		deps = None
-		if self._explicit_deps is not None:
-			deps = list(self._explicit_deps)
+		if self.explicit_deps:
+			deps = list(self.deps.keys())
 		return {
 			"fn": self.fn,
 			"name": self.name,
@@ -418,6 +457,10 @@ class Effect:
 
 	def _execute(self) -> None:
 		execution_epoch = epoch()
+		# Capture last_change for explicit deps before running
+		captured_last_changes: dict[Signal[Any] | Computed[Any], int] | None = None
+		if self.explicit_deps:
+			captured_last_changes = {dep: dep.last_change for dep in self.deps}
 		with Scope() as scope:
 			# Clear batch *before* running as we may update a signal that causes
 			# this effect to be rescheduled.
@@ -428,11 +471,13 @@ class Effect:
 				self.handle_error(e)
 			self.runs += 1
 			self.last_run = execution_epoch
-		self._apply_scope_results(scope)
+		self._apply_scope_results(scope, captured_last_changes)
 
 
 class AsyncEffect(Effect):
-	batch: "Batch | None"
+	fn: AsyncEffectFn  # pyright: ignore[reportIncompatibleMethodOverride]
+	batch: None  # pyright: ignore[reportIncompatibleVariableOverride]
+	_task: asyncio.Task[None] | None
 
 	def __init__(
 		self,
@@ -442,6 +487,8 @@ class AsyncEffect(Effect):
 		on_error: Callable[[Exception], None] | None = None,
 		deps: list[Signal[Any] | Computed[Any]] | None = None,
 	):
+		# Track an async task when running async effects
+		self._task = None
 		super().__init__(
 			fn=fn,  # pyright: ignore[reportArgumentType]
 			name=name,
@@ -450,12 +497,19 @@ class AsyncEffect(Effect):
 			on_error=on_error,
 			deps=deps,
 		)
-		# Track an async task when running async effects
-		self._task: asyncio.Task[Any] | None = None
 
-	def _task_name(self) -> str:
-		base = self.name or "effect"
-		return f"effect:{base}"
+	@override
+	def schedule(self):
+		"""
+		Schedule the async effect. Unlike synchronous effects, async effects do not
+		go through batches, they cancel the previous run and create a new task
+		immediately..
+		"""
+		self.run()
+
+	@property
+	def is_scheduled(self) -> bool:
+		return self._task is not None
 
 	@override
 	def _copy_kwargs(self):
@@ -464,48 +518,91 @@ class AsyncEffect(Effect):
 		return kwargs
 
 	@override
-	def _execute(self) -> None:
+	def run(self) -> asyncio.Task[Any]:  # pyright: ignore[reportIncompatibleMethodOverride]
+		"""
+		Run the async effect immediately, cancelling any previous run.
+		Returns the asyncio.Task.
+		"""
 		execution_epoch = epoch()
 
-		# Clear batch *before* running as we may update a signal that causes
-		# this effect to be rescheduled.
-		self.batch = None
-
 		# Cancel any previous run still in flight
 		self.cancel()
+		this_task: asyncio.Task[None] | None = None
 
 		async def _runner():
-			nonlocal execution_epoch
-			with Scope() as scope:
-				try:
-					result = cast(AsyncEffectFn, self.fn)()
-					if inspect.isawaitable(result):
-						self.cleanup_fn = await result
-					else:
-						# Support accidental non-async returns in async-annotated fns
-						self.cleanup_fn = result
-				except asyncio.CancelledError:
-					# Swallow cancellation
-					return
-				except Exception as e:
-					self.handle_error(e)
-				self.runs += 1
-				self.last_run = execution_epoch
-			self._apply_scope_results(scope)
-
-		self._task = create_task(_runner(), name=self._task_name())
+			nonlocal execution_epoch, this_task
+			try:
+				# Perform cleanups in the new task
+				with Untrack():
+					try:
+						self._cleanup_before_run()
+					except Exception as e:
+						self.handle_error(e)
+
+				# Capture last_change for explicit deps before running
+				captured_last_changes: dict[Signal[Any] | Computed[Any], int] | None = (
+					None
+				)
+				if self.explicit_deps:
+					captured_last_changes = {dep: dep.last_change for dep in self.deps}
+
+				with Scope() as scope:
+					try:
+						result = self.fn()
+						self.cleanup_fn = await maybe_await(result)
+					except asyncio.CancelledError:
+						# Re-raise so finally block executes to clear task reference
+						raise
+					except Exception as e:
+						self.handle_error(e)
+					self.runs += 1
+					self.last_run = execution_epoch
+				self._apply_scope_results(scope, captured_last_changes)
+			finally:
+				# Clear the task reference when it finishes
+				if self._task is this_task:
+					self._task = None
+
+		this_task = create_task(_runner(), name=f"effect:{self.name or 'unnamed'}")
+		self._task = this_task
+		return this_task
+
+	@override
+	async def __call__(self):  # pyright: ignore[reportIncompatibleMethodOverride]
+		await self.run()
 
 	def cancel(self) -> None:
-		self.unschedule()
-		if self._task and not self._task.done():
-			self._task.cancel()
+		# No batch removal needed as AsyncEffect is not batched
+		if self._task:
+			t = self._task
+			self._task = None
+			if not t.cancelled():
+				t.cancel()
+
+	async def wait(self) -> None:
+		"""
+		Wait until the completion of the current task if it's already running,
+		or start a run if it's not running. In case of cancellation, awaits
+		the new task by recursively calling itself.
+		"""
+		while True:
+			try:
+				await (self._task or self.run())
+				return
+			except asyncio.CancelledError:
+				# If wait() itself is cancelled, propagate it
+				current_task = asyncio.current_task()
+				if current_task is not None and (
+					current_task.cancelling() > 0 or current_task.cancelled()
+				):
+					raise
+				# Effect task was cancelled, continue waiting for new task
+				continue
 
 	@override
 	def dispose(self):
 		# Run children cleanups first, then cancel in-flight task
-		self.unschedule()
-		if self._task and not self._task.done():
-			self._task.cancel()
+		self.cancel()
 		for child in self.children.copy():
 			child.dispose()
 		if self.cleanup_fn:
@@ -579,11 +676,12 @@ class Batch:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_traceback: Any,
-	):
+	) -> Literal[False]:
 		self.flush()
 		# Restore previous reactive context
 		if self._token:
 			REACTIVE_CONTEXT.reset(self._token)
+		return False
 
 
 class GlobalBatch(Batch):
@@ -659,10 +757,11 @@ class Scope:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_traceback: Any,
-	):
+	) -> Literal[False]:
 		# Restore previous reactive context
 		if self._token:
 			REACTIVE_CONTEXT.reset(self._token)
+		return False
 
 
 class Untrack(Scope): ...
@@ -705,8 +804,9 @@ class ReactiveContext:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_tb: Any,
-	):
+	) -> Literal[False]:
 		REACTIVE_CONTEXT.reset(self._tokens.pop())
+		return False
 
 
 def epoch():

pulse/render_session.py

@@ -18,6 +18,7 @@ from pulse.messages import (
 	ServerNavigateToMessage,
 	ServerUpdateMessage,
 )
+from pulse.queries.store import QueryStore
 from pulse.reactive import Effect, flush_effects
 from pulse.renderer import RenderTree
 from pulse.routing import (
@@ -26,7 +27,7 @@ from pulse.routing import (
 	RouteContext,
 	RouteInfo,
 	RouteTree,
-	normalize_path,
+	ensure_absolute_path,
 )
 from pulse.state import State
 from pulse.vdom import Element
@@ -60,6 +61,7 @@ class RenderSession:
 	routes: RouteTree
 	channels: "ChannelsManager"
 	forms: "FormRegistry"
+	query_store: QueryStore
 
 	def __init__(
 		self,
@@ -85,6 +87,7 @@ class RenderSession:
 		self._pending_api: dict[str, asyncio.Future[dict[str, Any]]] = {}
 		# Registry of per-session global singletons (created via ps.global_state without id)
 		self._global_states: dict[str, State] = {}
+		self.query_store = QueryStore()
 		# Connection state
 		self.connected: bool = False
 		self.channels = ChannelsManager(self)
@@ -353,7 +356,7 @@ class RenderSession:
 		self,
 		path: str,
 	):
-		path = normalize_path(path)
+		path = ensure_absolute_path(path)
 		mount = self.route_mounts.get(path)
 		if not mount:
 			raise ValueError(f"No active route for '{path}'")

pulse/routing.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass, field
 from typing import TypedDict, cast, override
 
 from pulse.css import CssImport, CssModule
+from pulse.env import env
 from pulse.react_component import ReactComponent
 from pulse.reactive_extensions import ReactiveDict
 from pulse.vdom import Component
@@ -81,7 +82,7 @@ def parse_route_path(path: str) -> list[PathSegment]:
 
 # Normalize to react-router's convention: no leading and trailing slashes. Empty
 # string interpreted as the root.
-def normalize_path(path: str):
+def ensure_relative_path(path: str):
 	if path.startswith("/"):
 		path = path[1:]
 	if path.endswith("/"):
@@ -89,6 +90,12 @@ def normalize_path(path: str):
 	return path
 
 
+def ensure_absolute_path(path: str):
+	if not path.startswith("/"):
+		path = "/" + path
+	return path
+
+
 # ---- Shared helpers ----------------------------------------------------------
 def segments_are_dynamic(segments: list[PathSegment]) -> bool:
 	"""Return True if any segment is dynamic, optional, or a catch-all."""
@@ -157,6 +164,7 @@ class Route:
 	css_imports: Sequence[CssImport] | None
 	is_index: bool
 	is_dynamic: bool
+	dev: bool
 
 	def __init__(
 		self,
@@ -166,8 +174,9 @@ class Route:
 		components: "Sequence[ReactComponent[...]] | None" = None,
 		css_modules: Sequence[CssModule] | None = None,
 		css_imports: Sequence[CssImport] | None = None,
+		dev: bool = False,
 	):
-		self.path = normalize_path(path)
+		self.path = ensure_relative_path(path)
 		self.segments = parse_route_path(path)
 
 		self.render = render
@@ -175,6 +184,7 @@ class Route:
 		self.components = components
 		self.css_modules = css_modules
 		self.css_imports = css_imports
+		self.dev = dev
 		self.parent: Route | Layout | None = None
 
 		self.is_index = self.path == ""
@@ -191,8 +201,8 @@ class Route:
 		return [path]
 
 	def unique_path(self):
-		# Ensure consistent keys without accidental leading/trailing slashes
-		return normalize_path("/".join(self._path_list()))
+		# Return absolute path with leading '/'
+		return ensure_absolute_path("/".join(self._path_list()))
 
 	def file_path(self) -> str:
 		path = "/".join(self._path_list(include_layouts=False))
@@ -224,8 +234,7 @@ class Route:
 				f"Cannot build default RouteInfo for dynamic route '{self.path}'."
 			)
 
-		unique = self.unique_path()
-		pathname = "/" if unique == "" else f"/{unique}"
+		pathname = self.unique_path()
 		return {
 			"pathname": pathname,
 			"hash": "",
@@ -250,6 +259,7 @@ class Layout:
 	components: Sequence[ReactComponent[...]] | None
 	css_modules: Sequence[CssModule] | None
 	css_imports: Sequence[CssImport] | None
+	dev: bool
 
 	def __init__(
 		self,
@@ -258,12 +268,14 @@ class Layout:
 		components: "Sequence[ReactComponent[...]] | None" = None,
 		css_modules: Sequence[CssModule] | None = None,
 		css_imports: Sequence[CssImport] | None = None,
+		dev: bool = False,
 	):
 		self.render = render
 		self.children = children or []
 		self.components = components
 		self.css_modules = css_modules
 		self.css_imports = css_imports
+		self.dev = dev
 		self.parent: Route | Layout | None = None
 		# 1-based sibling index assigned by RouteTree at each level
 		self.idx: int = 1
@@ -280,7 +292,9 @@ class Layout:
 		return path_list
 
 	def unique_path(self):
-		return "/".join(self._path_list(include_layouts=True))
+		# Return absolute path with leading '/'
+		path = "/".join(self._path_list(include_layouts=True))
+		return f"/{path}"
 
 	def file_path(self) -> str:
 		path_list = self._path_list(include_layouts=True)
@@ -318,8 +332,7 @@ class Layout:
 
 		# Build pathname from ancestor route path segments (exclude layout indicators)
 		path_list = self._path_list(include_layouts=False)
-		unique = normalize_path("/".join(path_list))
-		pathname = "/" if unique == "" else f"/{unique}"
+		pathname = ensure_absolute_path("/".join(path_list))
 		return {
 			"pathname": pathname,
 			"hash": "",
@@ -330,6 +343,48 @@ class Layout:
 		}
 
 
+def filter_dev_routes(routes: Sequence[Route | Layout]) -> list[Route | Layout]:
+	"""
+	Filter out routes with dev=True.
+
+	This function removes all routes marked with dev=True from the route tree.
+	Should only be called when env != "dev".
+	"""
+	filtered: list[Route | Layout] = []
+	for route in routes:
+		# Skip dev-only routes
+		if route.dev:
+			continue
+
+		# Recursively filter children
+		if route.children:
+			filtered_children = filter_dev_routes(route.children)
+			# Create a copy of the route with filtered children
+			if isinstance(route, Route):
+				filtered_route = Route(
+					path=route.path,
+					render=route.render,
+					children=filtered_children,
+					components=route.components,
+					css_modules=route.css_modules,
+					css_imports=route.css_imports,
+					dev=route.dev,
+				)
+			else:  # Layout
+				filtered_route = Layout(
+					render=route.render,
+					children=filtered_children,
+					components=route.components,
+					css_modules=route.css_modules,
+					css_imports=route.css_imports,
+					dev=route.dev,
+				)
+			filtered.append(filtered_route)
+		else:
+			filtered.append(route)
+	return filtered
+
+
 class InvalidRouteError(Exception): ...
 
 
@@ -338,6 +393,9 @@ class RouteTree:
 	flat_tree: dict[str, Route | Layout]
 
 	def __init__(self, routes: Sequence[Route | Layout]) -> None:
+		# Filter out dev routes when not in dev environment
+		if env.pulse_env != "dev":
+			routes = filter_dev_routes(routes)
 		self.tree = list(routes)
 		self.flat_tree = {}
 
@@ -366,7 +424,7 @@ class RouteTree:
 			_flatten_route_tree(route)
 
 	def find(self, path: str):
-		path = normalize_path(path)
+		path = ensure_absolute_path(path)
 		route = self.flat_tree.get(path)
 		if not route:
 			raise ValueError(f"No route found for path '{path}'")

pulse/state.py

@@ -11,6 +11,7 @@ from collections.abc import Callable, Iterator
 from enum import IntEnum
 from typing import Any, Generic, Never, TypeVar, override
 
+from pulse.helpers import Disposable
 from pulse.reactive import (
 	AsyncEffect,
 	Computed,
@@ -185,7 +186,7 @@ class StateStatus(IntEnum):
 STATE_STATUS_FIELD = "__pulse_status__"
 
 
-class State(ABC, metaclass=StateMeta):
+class State(Disposable, metaclass=StateMeta):
 	"""
 	Base class for reactive state objects.
 
@@ -328,19 +329,19 @@ class State(ABC, metaclass=StateMeta):
 		"""
 		pass
 
+	@override
 	def dispose(self):
 		# Call user-defined cleanup hook first
-		self.on_dispose()
 
-		disposed = set()
+		self.on_dispose()
 		for value in self.__dict__.values():
-			if isinstance(value, Effect):
+			if isinstance(value, Disposable):
 				value.dispose()
-				disposed.add(value)
 
-		if len(set(self._scope.effects) - disposed) > 0:
+		undisposed_effects = [e for e in self._scope.effects if not e.__disposed__]
+		if len(undisposed_effects) > 0:
 			raise RuntimeError(
-				f"State.dispose() missed effects defined on its Scope: {[e.name for e in self._scope.effects]}"
+				f"State.dispose() missed effects defined on its Scope: {[e.name for e in undisposed_effects]}"
 			)
 
 	@override

pulse/types/event_handler.py

@@ -1,10 +1,9 @@
-from collections.abc import Callable, Coroutine
+from collections.abc import Awaitable, Callable
 from typing import (
-	Any,
 	TypeVar,
 )
 
-EventHandlerResult = None | Coroutine[Any, Any, None]
+EventHandlerResult = None | Awaitable[None]
 
 T1 = TypeVar("T1", contravariant=True)
 T2 = TypeVar("T2", contravariant=True)

pulse/user_session.py

@@ -12,6 +12,7 @@ from fastapi import Response
 
 from pulse.cookies import SetCookie
 from pulse.env import env
+from pulse.helpers import Disposable
 from pulse.reactive import AsyncEffect, Effect
 from pulse.reactive_extensions import ReactiveDict, reactive
 
@@ -23,7 +24,7 @@ Session = ReactiveDict[str, Any]
 logger = logging.getLogger(__name__)
 
 
-class UserSession:
+class UserSession(Disposable):
 	sid: str
 	data: Session
 	app: "App"
@@ -65,8 +66,8 @@ class UserSession:
 			max_age_seconds=app.cookie.max_age_seconds,
 		)
 
+	@override
 	def dispose(self):
-		print(f"Closing session {self.sid}")
 		self._effect.dispose()
 
 	def handle_response(self, res: Response):

pulse/vdom.py

@@ -23,6 +23,7 @@ from typing import (
 )
 
 from pulse.hooks.core import HookContext
+from pulse.hooks.init import rewrite_init_blocks
 
 # ============================================================================
 # Core VDOM
@@ -291,7 +292,8 @@ def component(
 	fn: "Callable[P, Element] | None" = None, *, name: str | None = None
 ) -> "Component[P] | Callable[[Callable[P, Element]], Component[P]]":
 	def decorator(fn: Callable[P, Element]):
-		return Component(fn, name)
+		rewritten = rewrite_init_blocks(fn)
+		return Component(rewritten, name)
 
 	if fn is not None:
 		return decorator(fn)