pulse-framework 0.1.62__tar.gz → 0.1.64__tar.gz

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.62
+Version: 0.1.64
 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.62 → pulse_framework-0.1.64}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pulse-framework"
-version = "0.1.62"
+version = "0.1.64"
 description = "Pulse - Full-stack framework for building real-time React applications in Python"
 readme = "README.md"
 requires-python = ">=3.11"

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/__init__.py

@@ -1410,6 +1410,7 @@ from pulse.render_session import run_js as run_js
 
 # Request
 from pulse.request import PulseRequest as PulseRequest
+from pulse.requirements import require as require
 from pulse.routing import Layout as Layout
 from pulse.routing import Route as Route
 from pulse.routing import RouteInfo as RouteInfo

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/cli/dependencies.py

@@ -11,11 +11,10 @@ from pulse.cli.packages import (
 	is_workspace_spec,
 	load_package_json,
 	parse_dependency_spec,
-	parse_install_spec,
 	resolve_versions,
 	spec_satisfies,
 )
-from pulse.transpiler.imports import get_registered_imports
+from pulse.requirements import get_requirements
 
 
 def convert_pep440_to_semver(python_version: str) -> str:
@@ -98,20 +97,12 @@ def get_required_dependencies(
 		"pulse-ui-client": [pulse_version],
 	}
 
-	# New transpiler v2 imports
-	for imp in get_registered_imports():
-		if imp.src:
-			try:
-				spec = parse_install_spec(imp.src)
-			except ValueError as exc:
-				# We might want to be more lenient here or at least log it,
-				# but following existing pattern of raising DependencyError
-				raise DependencyError(str(exc)) from None
-			if spec:
-				name_only, ver = parse_dependency_spec(spec)
-				constraints.setdefault(name_only, []).append(ver)
-				if imp.version:
-					constraints.setdefault(name_only, []).append(imp.version)
+	for src, version in get_requirements():
+		name_only, ver_in_src = parse_dependency_spec(src)
+		if ver_in_src:
+			constraints.setdefault(name_only, []).append(ver_in_src)
+		if version:
+			constraints.setdefault(name_only, []).append(version)
 
 	try:
 		resolved = resolve_versions(constraints)

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/component.py

@@ -112,7 +112,7 @@ class Component(Generic[P]):
 			flattened = flatten_children(
 				args,  # pyright: ignore[reportArgumentType]
 				parent_name=f"<{self.name}>",
-				warn_stacklevel=4,
+				warn_stacklevel=None,
 			)
 			args = tuple(flattened)  # pyright: ignore[reportAssignmentType]
 

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/queries/infinite_query.py

@@ -152,6 +152,61 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 			)
 		return self._observers[0]._fetch_fn  # pyright: ignore[reportPrivateUsage]
 
+	@property
+	def has_interval(self) -> bool:
+		return self._interval is not None
+
+	def _select_interval_observer(
+		self,
+	) -> tuple[float | None, "InfiniteQueryResult[T, TParam] | None"]:
+		min_interval: float | None = None
+		selected: "InfiniteQueryResult[T, TParam] | None" = None
+
+		for obs in reversed(self._observers):
+			interval = obs._refetch_interval  # pyright: ignore[reportPrivateUsage]
+			if interval is None:
+				continue
+			if not obs._enabled.value:  # pyright: ignore[reportPrivateUsage]
+				continue
+			if min_interval is None or interval < min_interval:
+				min_interval = interval
+				selected = obs
+
+		return min_interval, selected
+
+	def _create_interval_effect(self, interval: float) -> Effect:
+		def interval_fn():
+			observer = self._interval_observer
+			if observer is None:
+				return
+			self.invalidate(fetch_fn=observer._fetch_fn, observer=observer)  # pyright: ignore[reportPrivateUsage]
+
+		return Effect(
+			interval_fn,
+			name=f"inf_query_interval({self.key})",
+			interval=interval,
+			immediate=True,
+		)
+
+	def _update_interval(self) -> None:
+		new_interval, new_observer = self._select_interval_observer()
+		interval_changed = new_interval != self._interval
+
+		self._interval = new_interval
+		self._interval_observer = new_observer
+
+		if not interval_changed:
+			if self._interval_effect is None and new_interval is not None:
+				self._interval_effect = self._create_interval_effect(new_interval)
+			return
+
+		if self._interval_effect is not None:
+			self._interval_effect.dispose()
+			self._interval_effect = None
+
+		if new_interval is not None:
+			self._interval_effect = self._create_interval_effect(new_interval)
+
 	# Reactive state
 	pages: ReactiveList[Page[T, TParam]]
 	error: Signal[Exception | None]
@@ -171,6 +226,9 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 	_observers: "list[InfiniteQueryResult[T, TParam]]"
 	_gc_handle: asyncio.TimerHandle | None
+	_interval_effect: Effect | None
+	_interval: float | None
+	_interval_observer: "InfiniteQueryResult[T, TParam] | None"
 
 	def __init__(
 		self,
@@ -232,6 +290,9 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		self._queue_task = None
 		self._observers = []
 		self._gc_handle = None
+		self._interval_effect = None
+		self._interval = None
+		self._interval_observer = None
 
 	# ─────────────────────────────────────────────────────────────────────────
 	# Commit functions - update state after pages have been modified
@@ -326,13 +387,7 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		fetch_fn: Callable[[TParam], Awaitable[T]] | None = None,
 		observer: "InfiniteQueryResult[T, TParam] | None" = None,
 	) -> ActionResult[list[Page[T, TParam]]]:
-		"""Wait for initial data or until queue is empty."""
-		# If no data and loading, enqueue initial fetch (unless already processing)
-		if len(self.pages) == 0 and self.status() == "loading":
-			if self._queue_task is None or self._queue_task.done():
-				# Use provided fetch_fn or fall back to first observer's fetch_fn
-				fn = fetch_fn if fetch_fn is not None else self.fn
-				self._enqueue(Refetch(fetch_fn=fn, observer=observer))
+		"""Wait for any in-flight queue processing to complete."""
 		# Wait for any in-progress queue processing
 		if self._queue_task and not self._queue_task.done():
 			await self._queue_task
@@ -341,17 +396,31 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 			return ActionError(cast(Exception, self.error()))
 		return ActionSuccess(list(self.pages))
 
+	async def ensure(
+		self,
+		fetch_fn: Callable[[TParam], Awaitable[T]] | None = None,
+		observer: "InfiniteQueryResult[T, TParam] | None" = None,
+	) -> ActionResult[list[Page[T, TParam]]]:
+		"""Ensure an initial fetch has started, then wait for completion."""
+		if len(self.pages) == 0 and self.status() == "loading":
+			if self._queue_task is None or self._queue_task.done():
+				fn = fetch_fn if fetch_fn is not None else self.fn
+				self._enqueue(Refetch(fetch_fn=fn, observer=observer))
+		return await self.wait()
+
 	def observe(self, observer: Any):
 		self._observers.append(observer)
 		self.cancel_gc()
 		gc_time = getattr(observer, "_gc_time", 0)
 		if gc_time and gc_time > 0:
 			self.cfg.gc_time = max(self.cfg.gc_time, gc_time)
+		self._update_interval()
 
 	def unobserve(self, observer: "InfiniteQueryResult[T, TParam]"):
 		"""Unregister an observer. Cancels pending actions. Schedules GC if no observers remain."""
 		if observer in self._observers:
 			self._observers.remove(observer)
+		self._update_interval()
 
 		# Cancel pending actions from this observer
 		self._cancel_observer_actions(observer)
@@ -630,11 +699,17 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 			(i for i, p in enumerate(self.pages) if p.param == action.param),
 			None,
 		)
-		if idx is None:
-			return None
 
 		page = await action.fetch_fn(action.param)
-		self.pages[idx] = Page(page, action.param)
+
+		if idx is None:
+			# Page doesn't exist - jump to this page, clearing existing pages
+			self.pages.clear()
+			self.pages.append(Page(page, action.param))
+		else:
+			# Page exists, update it
+			self.pages[idx] = Page(page, action.param)
+
 		await self.commit()
 		return page
 
@@ -708,7 +783,10 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		cancel_fetch: bool = False,
 	) -> ActionResult[T | None]:
 		"""
-		Refetch an existing page by its param. Queued for sequential execution.
+		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.
 
 		Note: Prefer calling refetch_page() on InfiniteQueryResult to ensure the
 		correct fetch function is used. When called directly on InfiniteQuery, uses
@@ -725,6 +803,9 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		self._cancel_queue()
 		if self._queue_task and not self._queue_task.done():
 			self._queue_task.cancel()
+		if self._interval_effect is not None:
+			self._interval_effect.dispose()
+			self._interval_effect = None
 		if self.cfg.on_dispose:
 			self.cfg.on_dispose(self)
 
@@ -778,7 +859,6 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 	_on_success: Callable[[list[Page[T, TParam]]], Awaitable[None] | None] | None
 	_on_error: Callable[[Exception], Awaitable[None] | None] | None
 	_observe_effect: Effect
-	_interval_effect: Effect | None
 	_data_computed: Computed[list[Page[T, TParam]] | None]
 	_enabled: Signal[bool]
 	_fetch_on_mount: bool
@@ -801,13 +881,17 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 		self._fetch_fn = fetch_fn
 		self._stale_time = stale_time
 		self._gc_time = gc_time
-		self._refetch_interval = refetch_interval
+		interval = (
+			refetch_interval
+			if refetch_interval is not None and refetch_interval > 0
+			else None
+		)
+		self._refetch_interval = interval
 		self._keep_previous_data = keep_previous_data
 		self._on_success = on_success
 		self._on_error = on_error
 		self._enabled = Signal(enabled, name=f"inf_query.enabled({query().key})")
 		self._fetch_on_mount = fetch_on_mount
-		self._interval_effect = None
 
 		def observe_effect():
 			q = self._query()
@@ -816,8 +900,13 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 			with Untrack():
 				q.observe(self)
 
-				if enabled and fetch_on_mount and self.is_stale():
-					q.invalidate()
+				# Skip if query interval is active - interval effect handles initial fetch
+				if enabled and fetch_on_mount and not q.has_interval:
+					# Fetch if no data loaded yet or if existing data is stale
+					if not q.is_fetching() and (
+						q.status() == "loading" or self.is_stale()
+					):
+						q.invalidate()
 
 			# Return cleanup function that captures the query (old query on key change)
 			def cleanup():
@@ -834,25 +923,6 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 			self._data_computed_fn, name=f"inf_query_data({self._query().key})"
 		)
 
-		# Set up interval effect if interval is specified
-		if refetch_interval is not None and refetch_interval > 0:
-			self._setup_interval_effect(refetch_interval)
-
-	def _setup_interval_effect(self, interval: float):
-		"""Create an effect that invalidates the query at the specified interval."""
-
-		def interval_fn():
-			# Read enabled to make this effect reactive to enabled changes
-			if self._enabled():
-				self._query().invalidate()
-
-		self._interval_effect = Effect(
-			interval_fn,
-			name=f"inf_query_interval({self._query().key})",
-			interval=interval,
-			immediate=True,
-		)
-
 	@property
 	def status(self) -> QueryStatus:
 		return self._query().status()
@@ -985,15 +1055,20 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 	async def wait(self) -> ActionResult[list[Page[T, TParam]]]:
 		return await self._query().wait(fetch_fn=self._fetch_fn, observer=self)
 
+	async def ensure(self) -> ActionResult[list[Page[T, TParam]]]:
+		return await self._query().ensure(fetch_fn=self._fetch_fn, observer=self)
+
 	def invalidate(self):
 		query = self._query()
 		query.invalidate(fetch_fn=self._fetch_fn, observer=self)
 
 	def enable(self):
 		self._enabled.write(True)
+		self._query()._update_interval()  # pyright: ignore[reportPrivateUsage]
 
 	def disable(self):
 		self._enabled.write(False)
+		self._query()._update_interval()  # pyright: ignore[reportPrivateUsage]
 
 	def set_error(self, error: Exception):
 		query = self._query()
@@ -1002,8 +1077,6 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 	@override
 	def dispose(self):
 		"""Clean up the result and its observe effect."""
-		if self._interval_effect is not None:
-			self._interval_effect.dispose()
 		self._observe_effect.dispose()
 
 

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/queries/protocol.py

@@ -90,6 +90,15 @@ class QueryResult(Protocol[T]):
 		"""
 		...
 
+	async def ensure(self) -> ActionResult[T]:
+		"""
+		Ensure an initial fetch has started, then wait for completion.
+
+		Returns:
+		    ActionResult containing either the data or an error.
+		"""
+		...
+
 	def invalidate(self) -> None:
 		"""Mark the query as stale and trigger a refetch if observed."""
 		...

{pulse_framework-0.1.62 → pulse_framework-0.1.64}/src/pulse/queries/query.py

@@ -268,6 +268,9 @@ class KeyedQuery(Generic[T], Disposable):
 	_task: asyncio.Task[None] | None
 	_task_initiator: "KeyedQueryResult[T] | None"
 	_gc_handle: asyncio.TimerHandle | None
+	_interval_effect: Effect | None
+	_interval: float | None
+	_interval_observer: "KeyedQueryResult[T] | None"
 
 	def __init__(
 		self,
@@ -293,6 +296,9 @@ class KeyedQuery(Generic[T], Disposable):
 		self._task = None
 		self._task_initiator = None
 		self._gc_handle = None
+		self._interval_effect = None
+		self._interval = None
+		self._interval_observer = None
 
 	# --- Delegate signal access to state ---
 	@property
@@ -438,6 +444,66 @@ class KeyedQuery(Generic[T], Disposable):
 			)
 		return self.observers[0]._fetch_fn  # pyright: ignore[reportPrivateUsage]
 
+	@property
+	def has_interval(self) -> bool:
+		return self._interval is not None
+
+	def _select_interval_observer(
+		self,
+	) -> tuple[float | None, "KeyedQueryResult[T] | None"]:
+		min_interval: float | None = None
+		selected: "KeyedQueryResult[T] | None" = None
+
+		for obs in reversed(self.observers):
+			interval = obs._refetch_interval  # pyright: ignore[reportPrivateUsage]
+			if interval is None:
+				continue
+			if not obs._enabled.value:  # pyright: ignore[reportPrivateUsage]
+				continue
+			if min_interval is None or interval < min_interval:
+				min_interval = interval
+				selected = obs
+
+		return min_interval, selected
+
+	def _create_interval_effect(self, interval: float) -> Effect:
+		def interval_fn():
+			observer = self._interval_observer
+			if observer is None:
+				return
+			if not self.is_scheduled and len(self.observers) > 0:
+				self.run_fetch(
+					observer._fetch_fn,  # pyright: ignore[reportPrivateUsage]
+					cancel_previous=False,
+					initiator=observer,
+				)
+
+		return Effect(
+			interval_fn,
+			name=f"query_interval({self.key})",
+			interval=interval,
+			immediate=True,
+		)
+
+	def _update_interval(self) -> None:
+		new_interval, new_observer = self._select_interval_observer()
+		interval_changed = new_interval != self._interval
+
+		self._interval = new_interval
+		self._interval_observer = new_observer
+
+		if not interval_changed:
+			if self._interval_effect is None and new_interval is not None:
+				self._interval_effect = self._create_interval_effect(new_interval)
+			return
+
+		if self._interval_effect is not None:
+			self._interval_effect.dispose()
+			self._interval_effect = None
+
+		if new_interval is not None:
+			self._interval_effect = self._create_interval_effect(new_interval)
+
 	async def refetch(self, cancel_refetch: bool = True) -> ActionResult[T]:
 		"""
 		Reruns the query and returns the result.
@@ -468,11 +534,13 @@ class KeyedQuery(Generic[T], Disposable):
 		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]
+		self._update_interval()
 
 	def unobserve(self, observer: "KeyedQueryResult[T]"):
 		"""Unregister an observer. Schedules GC if no observers remain."""
 		if observer in self.observers:
 			self.observers.remove(observer)
+		self._update_interval()
 
 		# If the departing observer initiated the ongoing fetch, cancel it
 		if self._task_initiator is observer and self._task and not self._task.done():
@@ -505,6 +573,9 @@ class KeyedQuery(Generic[T], Disposable):
 	def dispose(self):
 		"""Clean up the query, cancelling any in-flight fetch."""
 		self.cancel()
+		if self._interval_effect is not None:
+			self._interval_effect.dispose()
+			self._interval_effect = None
 		if self.cfg.on_dispose:
 			self.cfg.on_dispose(self)
 
@@ -559,7 +630,12 @@ class UnkeyedQueryResult(Generic[T], Disposable):
 		self._on_success = on_success
 		self._on_error = on_error
 		self._stale_time = stale_time
-		self._refetch_interval = refetch_interval
+		interval = (
+			refetch_interval
+			if refetch_interval is not None and refetch_interval > 0
+			else None
+		)
+		self._refetch_interval = interval
 		self._keep_previous_data = keep_previous_data
 		self._enabled = Signal(enabled, name="query.enabled(unkeyed)")
 		self._interval_effect = None
@@ -581,12 +657,13 @@ class UnkeyedQueryResult(Generic[T], Disposable):
 
 		# Schedule initial fetch if stale (untracked to avoid reactive loop)
 		with Untrack():
-			if enabled and fetch_on_mount and self.is_stale():
+			# Skip if refetch_interval is active - interval effect handles initial fetch
+			if enabled and fetch_on_mount and interval is None and self.is_stale():
 				self.schedule()
 
 		# Set up interval effect if interval is specified
-		if refetch_interval is not None and refetch_interval > 0:
-			self._setup_interval_effect(refetch_interval)
+		if interval is not None:
+			self._setup_interval_effect(interval)
 
 	def _setup_interval_effect(self, interval: float):
 		"""Create an effect that invalidates the query at the specified interval."""
@@ -699,15 +776,18 @@ class UnkeyedQueryResult(Generic[T], Disposable):
 		return await self.wait()
 
 	async def wait(self) -> ActionResult[T]:
-		"""Wait for the current query to complete."""
-		# If loading and no task, schedule a fetch
-		if self.state.status() == "loading" and not self.state.is_fetching():
-			self.schedule()
+		"""Wait for the current in-flight fetch to complete."""
 		await self._effect.wait()
 		if self.state.status() == "error":
 			return ActionError(cast(Exception, self.state.error.read()))
 		return ActionSuccess(cast(T, self.state.data.read()))
 
+	async def ensure(self) -> ActionResult[T]:
+		"""Ensure an initial fetch has started, then wait for completion."""
+		if self.state.status() == "loading" and not self.state.is_fetching():
+			self.schedule()
+		return await self.wait()
+
 	def invalidate(self):
 		"""Mark the query as stale and refetch through the effect."""
 		if not self.is_scheduled:
@@ -740,7 +820,6 @@ class KeyedQueryResult(Generic[T], Disposable):
 	_on_success: Callable[[T], Awaitable[None] | None] | None
 	_on_error: Callable[[Exception], Awaitable[None] | None] | None
 	_observe_effect: Effect
-	_interval_effect: Effect | None
 	_data_computed: Computed[T | None]
 	_enabled: Signal[bool]
 	_fetch_on_mount: bool
@@ -762,12 +841,16 @@ class KeyedQueryResult(Generic[T], Disposable):
 		self._fetch_fn = fetch_fn
 		self._stale_time = stale_time
 		self._gc_time = gc_time
-		self._refetch_interval = refetch_interval
+		interval = (
+			refetch_interval
+			if refetch_interval is not None and refetch_interval > 0
+			else None
+		)
+		self._refetch_interval = interval
 		self._keep_previous_data = keep_previous_data
 		self._on_success = on_success
 		self._on_error = on_error
 		self._enabled = Signal(enabled, name=f"query.enabled({query().key})")
-		self._interval_effect = None
 
 		def observe_effect():
 			q = self._query()
@@ -776,9 +859,11 @@ class KeyedQueryResult(Generic[T], Disposable):
 			with Untrack():
 				q.observe(self)
 
-				# If stale or loading, schedule refetch (only when enabled)
-				if enabled and fetch_on_mount and self.is_stale():
-					self.invalidate()
+				# Skip if query interval is active - interval effect handles initial fetch
+				if enabled and fetch_on_mount and not q.has_interval:
+					# If stale, schedule refetch (only when enabled)
+					if not q.is_fetching() and self.is_stale():
+						self.invalidate()
 
 			# Return cleanup function that captures the query (old query on key change)
 			def cleanup():
@@ -795,25 +880,6 @@ class KeyedQueryResult(Generic[T], Disposable):
 			self._data_computed_fn, name=f"query_data({self._query().key})"
 		)
 
-		# Set up interval effect if interval is specified
-		if refetch_interval is not None and refetch_interval > 0:
-			self._setup_interval_effect(refetch_interval)
-
-	def _setup_interval_effect(self, interval: float):
-		"""Create an effect that invalidates the query at the specified interval."""
-
-		def interval_fn():
-			# Read enabled to make this effect reactive to enabled changes
-			if self._enabled():
-				self.invalidate()
-
-		self._interval_effect = Effect(
-			interval_fn,
-			name=f"query_interval({self._query().key})",
-			interval=interval,
-			immediate=True,
-		)
-
 	@property
 	def status(self) -> QueryStatus:
 		return self._query().status()
@@ -874,9 +940,12 @@ class KeyedQueryResult(Generic[T], Disposable):
 		return await self.wait()
 
 	async def wait(self) -> ActionResult[T]:
-		"""Wait for the current query to complete."""
+		"""Wait for the current in-flight fetch to complete."""
+		return await self._query().wait()
+
+	async def ensure(self) -> ActionResult[T]:
+		"""Ensure an initial fetch has started, then wait for completion."""
 		query = self._query()
-		# If loading and no task, start a fetch with this observer's fetch function
 		if query.status() == "loading" and not query.is_fetching():
 			query.run_fetch(self._fetch_fn, initiator=self)
 		return await query.wait()
@@ -910,16 +979,16 @@ class KeyedQueryResult(Generic[T], Disposable):
 	def enable(self):
 		"""Enable the query."""
 		self._enabled.write(True)
+		self._query()._update_interval()  # pyright: ignore[reportPrivateUsage]
 
 	def disable(self):
 		"""Disable the query, preventing it from fetching."""
 		self._enabled.write(False)
+		self._query()._update_interval()  # pyright: ignore[reportPrivateUsage]
 
 	@override
 	def dispose(self):
 		"""Clean up the result and its observe effect."""
-		if self._interval_effect is not None and not self._interval_effect.__disposed__:
-			self._interval_effect.dispose()
 		if not self._observe_effect.__disposed__:
 			self._observe_effect.dispose()
 

pulse_framework-0.1.64/src/pulse/requirements.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+_REQUIREMENTS: list[tuple[str, str]] = []
+
+
+def add_requirement(name: str, version: str) -> None:
+	if not name or not version:
+		return
+	_REQUIREMENTS.append((name, version))
+
+
+def register_requirements(packages: Mapping[str, str]) -> None:
+	for name, version in packages.items():
+		if not name or not version:
+			continue
+		add_requirement(name, version)
+
+
+def get_requirements() -> list[tuple[str, str]]:
+	return list(_REQUIREMENTS)
+
+
+def clear_requirements() -> None:
+	_REQUIREMENTS.clear()
+
+
+def require(packages: Mapping[str, str]) -> None:
+	"""Register npm package version requirements for dependency syncing."""
+	if not isinstance(packages, Mapping):
+		raise TypeError("require expects a mapping of package names to versions")
+	if not packages:
+		return
+
+	normalized: dict[str, str] = {}
+	for name, version in packages.items():
+		if not isinstance(name, str) or not name.strip():
+			raise TypeError("require expects non-empty package names")
+		if not isinstance(version, str) or not version.strip():
+			raise TypeError(f"require expects a version string for {name!r}")
+		normalized[name.strip()] = version.strip()
+
+	register_requirements(normalized)
+
+
+__all__ = ["require"]