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

{pulse_framework-0.1.40.dist-info → pulse_framework-0.1.42.dist-info}/METADATA

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

{pulse_framework-0.1.40.dist-info → pulse_framework-0.1.42.dist-info}/RECORD

@@ -1,22 +1,22 @@
-pulse/__init__.py,sha256=P2CLvFxP8IPiUsy3Z-hZD-1tbsvhd4eVlMNYg5WOPjE,31709
-pulse/app.py,sha256=VwalJMondhPfhCaqXpEQH6vBezX7jmm9e24GZNr21M0,29726
-pulse/channel.py,sha256=DuD1mg_xWvkpAWSKZ-EtBYdUzJ8IuKH0fxdgGOvFXpg,13041
+pulse/__init__.py,sha256=w7LVrYNiho18v9JyDQ8DZGdBYV4dZYtlEFiRi32ICiw,32166
+pulse/app.py,sha256=cVEqazFcgSnmZSxqqz6HWk2QsI8rnKbO7Y_L88BcHSc,32082
+pulse/channel.py,sha256=d9eLxgyB0P9UBVkPkXV7MHkC4LWED1Cq3GKsEu_SYy4,13056
 pulse/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/cli/cmd.py,sha256=jA1kgw6Dibj8jC_amcRL4mCzfboszLTnVAQtJA3_G-4,14011
+pulse/cli/cmd.py,sha256=UBT7OoqWRU-idLOKkA9TDN8m8ugi1gwRMiUJTUmkVfU,14853
 pulse/cli/dependencies.py,sha256=ZBqBAfMvMBQUvh4THdPDztTMQ_dyR52S1IuotP_eEZs,5623
 pulse/cli/folder_lock.py,sha256=kvUmZBg869lwCTIZFoge9dhorv8qPXHTWwVv_jQg1k8,3477
 pulse/cli/helpers.py,sha256=8bRlV3d7w3w-jHaFvFYt9Pzue6_CbKOq_Z3jBsBOeUk,8820
-pulse/cli/models.py,sha256=hRmIWmhXmGf2otzVm1do4Dm19rkWkmTwAA3Am3kw2tE,692
+pulse/cli/models.py,sha256=NBV5byBDNoAQSk0vKwibLjoxuA85XBYIyOVJn64L8oU,858
 pulse/cli/packages.py,sha256=e7ycwwJfdmB4pzrai4DHos6-JzyUgmE4DCZp0BqjdeI,6792
-pulse/cli/processes.py,sha256=yJg2hHY2JggLkvQS9XrVwdl7reQhF333qxATPnPkmrU,5727
+pulse/cli/processes.py,sha256=C1xU72oUanj-1Mkc9WmqESTsVUn_aUHG8URiPyRHSFM,7016
 pulse/cli/secrets.py,sha256=dNfQe6AzSYhZuWveesjCRHIbvaPd3-F9lEJ-kZA7ROw,921
-pulse/cli/uvicorn_log_config.py,sha256=Ip0iCeMUoY1ruv3Amf2SF84lW2DDpJFqdsLflZNxmeY,2407
+pulse/cli/uvicorn_log_config.py,sha256=f7ikDc5foXh3TmFMrnfnW8yev48ZAdlo8F4F_aMVoVk,2391
 pulse/codegen/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/codegen/codegen.py,sha256=RMc2NkldX0dmxRG59gdulCMEzywvHMo2akeiHQMTu4I,10681
+pulse/codegen/codegen.py,sha256=lPhgl57Ag3ChEDdhFD7wUCaU6lFiTQ1cD_vpSUgMfKg,11093
 pulse/codegen/imports.py,sha256=13f0uzJsotw069aP_COUUPMuTXXhRKRwUzfxsSCq_6A,6070
 pulse/codegen/js.py,sha256=7MuiECSJ-DulSqKuMZ8z1q_d7e3AbK6MYiNTYALZCLA,881
 pulse/codegen/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/codegen/templates/layout.py,sha256=Et9e8zZ6xN5vhxlhwDVOFcdAP1Odl8oHz4eYO3iyhc4,4396
+pulse/codegen/templates/layout.py,sha256=nmWPQcO9SRXc3mCCVLCmykreSF96TqQfdDY7dvUBxRg,4737
 pulse/codegen/templates/route.py,sha256=cwmNHYkuecZ5M986hmm6SxisIoVSc656dtpqAvPjMjM,7824
 pulse/codegen/templates/routes_ts.py,sha256=nPgKCvU0gzue2k6KlOL1TJgrBqqRLmyy7K_qKAI8zAE,1129
 pulse/codegen/utils.py,sha256=QoXcV-h-DLLmq_t03hDNUePS0fNnofUQLoR-TXzDFCY,539
@@ -24,20 +24,21 @@ pulse/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,
 pulse/components/for_.py,sha256=LUyJEUlDM6b9oPjvUFgSsddxu6b6usF4BQdXe8FIiGI,1302
 pulse/components/if_.py,sha256=rQywsmdirNpkb-61ZEdF-tgzUh-37JWd4YFGblkzIdQ,1624
 pulse/components/react_router.py,sha256=TbRec-NVliUqrvAMeFXCrnDWV1rh6TGTPfRhqLuLubk,1129
-pulse/context.py,sha256=x_nCbCEUGygAdCZiTfko5uuYxVSAeCNhYa59zBq015M,1692
+pulse/context.py,sha256=fMK6GdQY4q_3452v5DJli2f2_urVihnpzb-O-O9cJ1Q,1734
 pulse/cookies.py,sha256=c7ua1Lv6mNe1nYnA4SFVvewvRQAbYy9fN5G3Hr_Dr5c,5000
 pulse/css.py,sha256=-FyQQQ0EZI1Ins30qiF3l4z9yDb1V9qWuJKWxHcKGkw,3910
-pulse/decorators.py,sha256=8At1HQTFs9KG7nd83miGMe3KkhTBVGDviaqZaY62bHI,6651
+pulse/decorators.py,sha256=hRfgb9XU1yizmtdhuBln_3Gy-Cz2Smo4rYvAqlURrLQ,9348
 pulse/env.py,sha256=p3XI8KG1ZCcXPD3LJP7fW8JPYfyvoYY5ENwae2o0PiA,2889
-pulse/form.py,sha256=M87QwG4KFOrI8Nba7BTDoJ_wZ1-jzJW7QN4JweYCpuM,9004
-pulse/helpers.py,sha256=q54JGen1lBIEGyLnNKvmW_7nnTFqFZBDMYXsoXvth7o,11628
+pulse/form.py,sha256=P7W8guUdGbgqNOk8cSUCWuY6qWre0me6_fypv1qOvqw,8987
+pulse/helpers.py,sha256=BBtf--LZxvfpwJU8p92QrZWtOKIWfB3DOiAtGxhet90,13232
 pulse/hooks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/hooks/core.py,sha256=Ksb-vSYbigL2GnUooxdLVUTfnT7cHOlYEKgKtrihvJo,7344
+pulse/hooks/core.py,sha256=JTZbVxNOEs_GAeK6Bh6hemSTkgwZPtEi_wt55cvOdik,7381
 pulse/hooks/effects.py,sha256=CQvt5viAweGLSxaGGlWm155GlEQiwQnGussw7OfiCGc,2393
+pulse/hooks/init.py,sha256=snTy3PJtkSnnKBrAjcNOJbem2896xJzHD0DHLVVeyAo,11924
 pulse/hooks/runtime.py,sha256=k5LZ8hnlNBMKOiEkQcAvs8BKwYxV6gwea2WCfju5K7Y,5106
 pulse/hooks/setup.py,sha256=GJLSE6hLBNKHR9aLhvsS6KXwpOXQiSx1V3E2IkGADWM,4461
 pulse/hooks/stable.py,sha256=uHEJ2E22r2kHx4uFjWjDepQ6OtPjLd7tT5ju-yKlkCU,1702
-pulse/hooks/states.py,sha256=WVQxOMkktyNG0nXQ75PMoNqFDDJ1nc0NSVV8UWUggxk,5427
+pulse/hooks/states.py,sha256=e9vO8ig8vaw6guY711S6rlY9WXCjDYXsjiR7IvyKrXU,6708
 pulse/html/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/html/elements.py,sha256=YHXkVpfMAC4-0o61fK-E0LGTOM3KMCtBfpHHAwLx7dw,23241
 pulse/html/events.py,sha256=SiZxaQV340hc5YGoKWXC5uCmbLsuijuEgnQz1hmdqYg,14700
@@ -45,27 +46,32 @@ pulse/html/props.py,sha256=XatI6N4Hyef3MAql7jCxCIm6iuusgUXKkwHwIGm_dcc,26646
 pulse/html/svg.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/html/tags.py,sha256=dyG4BY9qthBbO-ihcy9F8mLY6WqQxKFXfpqNYcSMKN0,5182
 pulse/html/tags.pyi,sha256=I8dFoft9w4RvneZ3li1weAdijY1krj9jfO_p2SU6e04,13953
-pulse/messages.py,sha256=Vz6pXUcBlQxHVEzP8jtA4ZBwn0P30oJzU07lzESP2JI,3625
-pulse/middleware.py,sha256=aMcfkQ2XUT-SMFNa51GYlQp5tnXQwkfbcGlqO4DGcKk,7874
-pulse/plugin.py,sha256=T1HLucOJekRfWMGF17arI3z7qfH-rBw_zPOQEV8v2mw,640
-pulse/proxy.py,sha256=XR2jV5NTLTdiYuJLMBWx2_aMB7Odoa63XQRHSOgA7jM,2709
+pulse/messages.py,sha256=Z7iYkOacwca5tU1UgZHt96iojT5Hd7VDc0PkEcru_2Q,3619
+pulse/middleware.py,sha256=9uyAhVUEGMSwqWC3WXqs7x5JMMNEcSTTu3g7DjsR8w8,9812
+pulse/plugin.py,sha256=RfGl6Vtr7VRHb8bp4Ob4dOX9dVzvc4Riu7HWnStMPpk,580
+pulse/proxy.py,sha256=zh4v5lmYNg5IBE_xdHHmGPwbMQNSXb2npeLXvw_O1Oc,6591
 pulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/query.py,sha256=u0KVFNt0d36sfmoxpQXvJ8DjctIHZaM_szlEonRiyRg,12849
-pulse/react_component.py,sha256=Rw1J6cHOX8-K3BnkswVOu2COgneVvRz1OYmyXkX17RM,25993
-pulse/reactive.py,sha256=MPIlG2zdYT2vQUWbi5EYbxezA3lBqf1oe1hMr20sQT4,18239
+pulse/queries/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pulse/queries/common.py,sha256=2_11SEOFrDbe_ULNSA9EWeOkvz-xym5hCuX4bW455t0,556
+pulse/queries/mutation.py,sha256=_0-o2g2yux52hTsRLGuWwFUdGrBx9YJqi67oBw9iNcc,4209
+pulse/queries/query.py,sha256=WxBEaEjtzDGWWKpSi8-xl9xBvPvREYH1Tonl_lOY-VQ,7347
+pulse/queries/query_observer.py,sha256=Wd3pk5OsZB_ze6DnpOkASv4Ny5EuSbwUlUEPXIXxSgk,10229
+pulse/queries/store.py,sha256=ylSCOHiXp8vEyEWc5Et8zLWkyHj5OQYKOVfs0OehpX8,1465
+pulse/react_component.py,sha256=hPibKBEkVdpBKNSpMQ6bZ-7GnJQcNQwcw2SvfY1chHA,26026
+pulse/reactive.py,sha256=cKZDafbUQFdnNRAxI71THnsFZEbWZ5mU06pMuP6spo8,21187
 pulse/reactive_extensions.py,sha256=gTLkQ0urwANjWNHWMkg-P9zvpevHCnNKd5BSM8G0pno,31521
-pulse/render_session.py,sha256=Z5_01H-J71k_Y7zuS3tFpi4cycl6AaG8fne8q0ovhvM,14467
+pulse/render_session.py,sha256=kqLfZ9AxCrB2mIJqegATL1KA7CI-LZSBQwRYr7Uxo9g,14581
 pulse/renderer.py,sha256=dJiX9VeHr9kC1UBw5oaKB8Mv-3OCMGTrHiKgLJ5FL50,16759
 pulse/request.py,sha256=sPsSRWi5KvReSPBLIs_kzqomn1wlRk1BTLZ5s0chQr4,4979
-pulse/routing.py,sha256=o3xmWpoMgJMkI1W7nFJpDkCT30ejTG2MnCV42OwgLaI,12492
+pulse/routing.py,sha256=RlrGHyK4F28_zUHMYNeKp4pNbvqrt4GY4t5xNdhzunI,13926
 pulse/serializer.py,sha256=8RAITNoSNm5-U38elHpWmkBpcM_rxZFMCluJSfldfk4,5420
-pulse/state.py,sha256=y9Z-KBYQVd63fb1wF8gQ4KilK7c2ElYLf6U-miWteM8,10560
+pulse/state.py,sha256=mytXlQjmLIBjB2XDgCg9E1fHCcyoNQ02cBqZ_vldxuc,10636
 pulse/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pulse/types/event_handler.py,sha256=OF7sOgYBb6iUs59RH1vQIH7aOrGPfs3nAaF7how-4PQ,1658
-pulse/user_session.py,sha256=kCZtQpYZe2keDXzusd6jsjjw075am0dXrb25jKLg5JU,7578
-pulse/vdom.py,sha256=KTNBh2dVvDy9eXRzhneBJgk7F35MyWec8R_puQ4tSRY,12420
+pulse/types/event_handler.py,sha256=tfKa6OEA5XvzuYbllQZJ03ooN7rGSYOtaPBstSL4OLU,1642
+pulse/user_session.py,sha256=Nn9ZZha1Rruw31OSoK14QaEL0erGVFbryFhJYrtMZsQ,7599
+pulse/vdom.py,sha256=1UAjOYSmpdZeSVELqejh47Jer4mA73T_q2HtAogOphs,12514
 pulse/version.py,sha256=711vaM1jVIQPgkisGgKZqwmw019qZIsc_QTae75K2pg,1895
-pulse_framework-0.1.40.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-pulse_framework-0.1.40.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
-pulse_framework-0.1.40.dist-info/METADATA,sha256=j481f-W5TtovwCzdxBioeaG-rTHLmY7uhMpKc4RP_WU,580
-pulse_framework-0.1.40.dist-info/RECORD,,
+pulse_framework-0.1.42.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pulse_framework-0.1.42.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
+pulse_framework-0.1.42.dist-info/METADATA,sha256=Pyy5qb02JHkAFwGpy6m8SkrlPH_mmL6BPxDfvQ41ly4,580
+pulse_framework-0.1.42.dist-info/RECORD,,

pulse/query.py

@@ -1,408 +0,0 @@
-import asyncio
-from collections.abc import Awaitable, Callable, Coroutine
-from typing import (
-	Any,
-	Generic,
-	TypeVar,
-	TypeVarTuple,
-	cast,
-	override,
-)
-
-from pulse.helpers import call_flexible, maybe_await
-from pulse.reactive import AsyncEffect, Computed, EffectCleanup, Signal
-from pulse.state import InitializableProperty, State
-
-T = TypeVar("T")
-TState = TypeVar("TState", bound="State")
-Args = TypeVarTuple("Args")
-R = TypeVar("R")
-
-# Type alias matching AsyncEffectFn from reactive.py
-AsyncEffectFn = Callable[[], Coroutine[Any, Any, EffectCleanup | None]]
-
-
-class QueryAsyncEffect(AsyncEffect):
-	"""
-	Specialized AsyncEffect for queries that synchronously clears query data
-	when rescheduled (if keep_previous_data is False).
-	"""
-
-	_result: "QueryResult[Any]"
-	_keep_previous_data: bool
-
-	def __init__(
-		self,
-		fn: AsyncEffectFn,
-		result: "QueryResult[Any]",
-		keep_previous_data: bool,
-		name: str | None = None,
-		deps: list[Signal[Any] | Computed[Any]] | None = None,
-	):
-		super().__init__(fn, name=name, deps=deps)
-		self._result = result
-		self._keep_previous_data = keep_previous_data
-
-	@override
-	def push_change(self):
-		# Synchronously clear data before scheduling the effect to run.
-		# This ensures renders see the loading state immediately, not stale data.
-		self._result._set_loading(clear_data=not self._keep_previous_data)  # pyright: ignore[reportPrivateUsage]
-		super().push_change()
-
-
-class QueryResult(Generic[T]):
-	def __init__(self, initial_data: T | None = None):
-		# print("[QueryResult] initialize")
-		self._is_loading: Signal[bool] = Signal(True, name="query.is_loading")
-		self._is_error: Signal[bool] = Signal(False, name="query.is_error")
-		self._error: Signal[Exception | None] = Signal(None, name="query.error")
-		# Store initial data so we can preserve non-None semantics when requested
-		self._initial_data: T | None = initial_data
-		self._data: Signal[T | None] = Signal(initial_data, name="query.data")
-		# Tracks whether at least one load cycle completed (success or error)
-		self._has_loaded: Signal[bool] = Signal(False, name="query.has_loaded")
-		# Effect driving this query (attached by QueryProperty)
-		self._effect: AsyncEffect | None = None
-
-	@property
-	def is_loading(self) -> bool:
-		# print(f"[QueryResult] Accessing is_loading = {self._is_loading.read()}")
-		return self._is_loading.read()
-
-	@property
-	def is_error(self) -> bool:
-		# print(f"[QueryResult] Accessing is_error = {self._is_error.read()}")
-		return self._is_error.read()
-
-	@property
-	def error(self) -> Exception | None:
-		# print(f"[QueryResult] Accessing error = {self._error.read()}")
-		return self._error.read()
-
-	@property
-	def data(self) -> T | None:
-		# print(f"[QueryResult] Accessing data = {self._data.read()}")
-		return self._data.read()
-
-	@property
-	def has_loaded(self) -> bool:
-		return self._has_loaded.read()
-
-	def attach_effect(self, effect: AsyncEffect) -> None:
-		self._effect = effect
-
-	def refetch(self) -> None:
-		if self._effect is None:
-			return
-		self._effect.cancel()
-		self._effect.run()
-
-	def dispose(self) -> None:
-		if self._effect is None:
-			return
-		self._effect.dispose()
-
-	# Internal setters used by the query machinery
-	def _set_loading(self, *, clear_data: bool = False):
-		# print("[QueryResult] set loading=True")
-		self._is_loading.write(True)
-		self._is_error.write(False)
-		self._error.write(None)
-		if clear_data:
-			# If there was an explicit initial value, reset to it; otherwise clear
-			self._data.write(self._initial_data)
-
-	def _set_success(self, data: T):
-		# print(f"[QueryResult] set success data={data!r}")
-		self._data.write(data)
-		self._is_loading.write(False)
-		self._is_error.write(False)
-		self._error.write(None)
-		self._has_loaded.write(True)
-
-	def _set_error(self, err: Exception):
-		# print(f"[QueryResult] set error err={err!r}")
-		self._error.write(err)
-		self._is_loading.write(False)
-		self._is_error.write(True)
-		self._has_loaded.write(True)
-
-	# Public mutator useful for optimistic updates; does not change loading/error flags
-	def set_data(self, data: T):
-		self._data.write(data)
-
-	# Public mutator to set initial data before the first load completes.
-	# If called after the first load, it is ignored.
-	def set_initial_data(self, data: T):
-		if self._has_loaded.read():
-			return
-		self._initial_data = data
-		self._data.write(data)
-
-	# Public helpers mirroring internal transitions
-	def set_loading(self, *, clear_data: bool = False) -> None:
-		self._set_loading(clear_data=clear_data)
-
-	def set_success(self, data: T) -> None:
-		self._set_success(data)
-
-	def set_error(self, err: Exception) -> None:
-		self._set_error(err)
-
-
-OnSuccessFn = Callable[[TState], Any] | Callable[[TState, T], Any]
-OnErrorFn = Callable[[TState], Any] | Callable[[TState, Exception], Any]
-
-
-class QueryProperty(Generic[T, TState], InitializableProperty):
-	"""
-	Descriptor for state-bound queries.
-
-	Usage:
-	    class S(ps.State):
-	        @ps.query()
-	        async def user(self) -> User: ...
-
-	        @user.key
-	        def _user_key(self):
-	            return ("user", self.user_id)
-	"""
-
-	name: str
-	_fetch_fn: "Callable[[TState], Awaitable[T]]"
-	_keep_alive: bool
-	_keep_previous_data: bool
-	_initial: T | None
-	_key_fn: Callable[[TState], tuple[Any, ...]] | None
-	_initial_data_fn: Callable[[TState], T] | 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.
-	_on_success_fn: Callable[[TState, Exception], Any] | None
-	_on_error_fn: Callable[[TState, T], Any] | None
-
-	_priv_query: str
-	_priv_effect: str
-	_priv_key_comp: str
-	_priv_initial_fn: str
-	_priv_initial_applied: str
-
-	def __init__(
-		self,
-		name: str,
-		fetch_fn: "Callable[[TState], Awaitable[T]]",
-		keep_alive: bool = False,
-		keep_previous_data: bool = False,
-		initial: T | None = None,
-	):
-		self.name = name
-		self._fetch_fn = fetch_fn
-		self._key_fn = None
-		self._initial_data_fn = None
-		# Single handlers; error if set more than once
-		self._on_success_fn = None
-		self._on_error_fn = None
-		self._keep_alive = keep_alive
-		self._keep_previous_data = keep_previous_data
-		self._initial = initial
-		self._priv_query = f"__query_{name}"
-		self._priv_effect = f"__query_effect_{name}"
-		self._priv_key_comp = f"__query_key_{name}"
-		self._priv_initial_fn = f"__query_initial_fn_{name}"
-		self._priv_initial_applied = f"__query_initial_applied_{name}"
-
-	# Decorator to attach a key function
-	def key(self, fn: Callable[[TState], tuple[Any, ...]]):
-		if self._key_fn is not None:
-			raise RuntimeError(
-				f"Duplicate key() decorator for query '{self.name}'. Only one is allowed."
-			)
-		self._key_fn = fn
-		return fn
-
-	# Decorator to attach a function providing initial data
-	def initial_data(self, fn: Callable[[TState], T]):
-		if self._initial_data_fn is not None:
-			raise RuntimeError(
-				f"Duplicate initial_data() decorator for query '{self.name}'. Only one is allowed."
-			)
-		self._initial_data_fn = fn
-		return fn
-
-	# 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 query '{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 query '{self.name}'. Only one is allowed."
-			)
-		self._on_error_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
-		return fn
-
-	@override
-	def initialize(self, state: Any, name: str) -> QueryResult[T]:
-		# Return cached query instance if present
-		query: QueryResult[T] | None = getattr(state, self._priv_query, None)
-		if query:
-			# print(f"[QueryProperty:{self.name}] return cached StateQuery")
-			return query
-
-		# key_fn being None means auto-tracked mode
-
-		# Bind methods to this instance
-		bound_fetch = bind_state(state, self._fetch_fn)
-		bound_on_success = (
-			bind_state(state, self._on_success_fn) if self._on_success_fn else None
-		)
-		bound_on_error = (
-			bind_state(state, self._on_error_fn) if self._on_error_fn else None
-		)
-		bound_initial_data = (
-			bind_state(state, self._initial_data_fn) if self._initial_data_fn else None
-		)
-		# print(f"[QueryProperty:{self.name}] bound fetch and key/handlers")
-
-		# Defer evaluating initial_data provider until after user __init__ by
-		# storing it on the instance and marking it unapplied. Use constructor
-		# `initial` as the initial visible value for now.
-		setattr(state, self._priv_initial_fn, bound_initial_data)
-		setattr(state, self._priv_initial_applied, False)
-		initial_value: T | None = self._initial
-
-		result = QueryResult[T](initial_data=initial_value)
-
-		key_computed: Computed[tuple[Any, ...]] | None = None
-		if self._key_fn:
-			bound_key_fn = bind_state(state, self._key_fn)
-			key_computed = Computed(bound_key_fn, name=f"query.key.{self.name}")
-			setattr(state, self._priv_key_comp, key_computed)
-
-		inflight_key: tuple[Any, ...] | None = None
-
-		async def run_effect():
-			# print(f"[QueryProperty:{self.name}] effect RUN")
-			# In key mode, deduplicate same-key concurrent reruns
-			if key_computed:
-				key = key_computed()
-
-				nonlocal inflight_key
-				# De-duplicate same-key concurrent reruns
-				if inflight_key == key:
-					return None
-				inflight_key = key
-
-			# Set loading immediately; optionally clear previous data
-			result.set_loading(clear_data=not self._keep_previous_data)
-
-			try:
-				data = await bound_fetch()
-			except asyncio.CancelledError:
-				# Cancellation is expected during reruns; swallow
-				return None
-			except Exception as e:
-				result.set_error(e)
-				# Invoke error handler if provided
-				if bound_on_error:
-					await maybe_await(call_flexible(bound_on_error, e))
-			else:
-				result.set_success(data)
-				# Invoke success handler if provided
-				if bound_on_success:
-					await maybe_await(call_flexible(bound_on_success, data))
-			finally:
-				inflight_key = None
-
-		# In key mode, depend only on key via explicit deps
-		if key_computed is not None:
-			effect = QueryAsyncEffect(
-				run_effect,
-				result=result,
-				keep_previous_data=self._keep_previous_data,
-				name=f"query.effect.{self.name}",
-				deps=[key_computed],
-			)
-		else:
-			effect = QueryAsyncEffect(
-				run_effect,
-				result=result,
-				keep_previous_data=self._keep_previous_data,
-				name=f"query.effect.{self.name}",
-			)
-		# print(f"[QueryProperty:{self.name}] created Effect name={effect.name}")
-
-		# Expose the effect on the instance so State.effects() sees it
-		setattr(state, self._priv_effect, effect)
-		# Attach effect to result and expose result directly
-		result.attach_effect(effect)
-		setattr(state, self._priv_query, result)
-
-		# if not self.keep_alive:
-
-		# 	def on_obs(count: int):
-		# 		if count == 0:
-		# 			# print("[QueryProperty] Disposing of effect due to no observers")
-		# 			effect.dispose()
-
-		# Stop when no one observes key or data
-		# result._data.on_observer_change(on_obs)
-		# result._is_error.on_observer_change(on_obs)
-		# result._is_loading.on_observer_change(on_obs)
-
-		return result
-
-	def __get__(self, obj: Any, objtype: Any = None) -> QueryResult[T]:
-		if obj is None:
-			return self  # pyright: ignore[reportReturnType]
-		query = self.initialize(obj, self.name)
-		# Apply initial_data provider once, after state __init__, before first load
-		try:
-			applied = bool(getattr(obj, self._priv_initial_applied, False))
-		except Exception:
-			applied = True  # fail safe: do not attempt if attribute missing
-		if not applied and not query.has_loaded:
-			bound_initial = getattr(obj, self._priv_initial_fn, None)
-			if callable(bound_initial):
-				try:
-					value = bound_initial()
-					if value is not None:
-						query.set_initial_data(value)  # pyright: ignore[reportArgumentType]
-				except Exception:
-					pass
-			try:
-				setattr(obj, self._priv_initial_applied, True)
-			except Exception:
-				pass
-		return query
-
-
-class QueryResultWithInitial(QueryResult[T]):
-	@property
-	@override
-	def data(self) -> T:
-		return cast(T, super().data)
-
-	@property
-	@override
-	def has_loaded(self) -> bool:  # mirror base for completeness
-		return super().has_loaded
-
-
-class QueryPropertyWithInitial(QueryProperty[T, TState]):
-	@override
-	def __get__(self, obj: Any, objtype: Any = None) -> QueryResultWithInitial[T]:
-		# Reuse base initialization but narrow the return type for type-checkers
-		return cast(QueryResultWithInitial[T], super().__get__(obj, objtype))
-
-
-def bind_state(state: TState, fn: Callable[[TState, *Args], R]) -> Callable[[*Args], R]:
-	"Type-safe helper to bind a method to a state"
-	return fn.__get__(state, state.__class__)