pulse-framework 0.1.62__py3-none-any.whl

pulse/js/number.py

@@ -0,0 +1,57 @@
+"""
+JavaScript Number builtin module.
+
+Usage:
+
+```python
+from pulse.js import Number
+Number.isFinite(42)       # -> Number.isFinite(42)
+Number.MAX_SAFE_INTEGER   # -> Number.MAX_SAFE_INTEGER
+Number(x)                 # -> new Number(x)
+
+# Or import from module directly:
+from pulse.js.number import Number
+```
+"""
+
+from typing import Any as _Any
+from typing import ClassVar as _ClassVar
+
+from pulse.transpiler.js_module import JsModule
+
+
+class Number:
+	"""JavaScript Number constructor and namespace."""
+
+	def __init__(self, value: _Any) -> None: ...
+
+	EPSILON: _ClassVar[float]
+	MAX_SAFE_INTEGER: _ClassVar[int]
+	MAX_VALUE: _ClassVar[float]
+	MIN_SAFE_INTEGER: _ClassVar[int]
+	MIN_VALUE: _ClassVar[float]
+	NaN: _ClassVar[float]
+	NEGATIVE_INFINITY: _ClassVar[float]
+	POSITIVE_INFINITY: _ClassVar[float]
+
+	@staticmethod
+	def isFinite(value: float) -> bool: ...
+
+	@staticmethod
+	def isInteger(value: float) -> bool: ...
+
+	@staticmethod
+	def isNaN(value: float) -> bool: ...
+
+	@staticmethod
+	def isSafeInteger(value: float) -> bool: ...
+
+	@staticmethod
+	def parseFloat(string: str) -> float: ...
+
+	@staticmethod
+	def parseInt(string: str, radix: int = 10, /) -> int: ...
+
+
+# Self-register this module as a JS builtin (global identifier)
+JsModule.register(name=None)

pulse/js/obj.py

@@ -0,0 +1,81 @@
+"""
+JavaScript object literal creation.
+
+Usage:
+
+```python
+from pulse.js import obj
+
+# Create plain JS objects (not Maps):
+obj(a=1, b=2)          # -> { a: 1, b: 2 }
+
+# With spread syntax:
+obj(**base, c=3)       # -> { ...base, c: 3 }
+obj(a=1, **base)       # -> { a: 1, ...base }
+
+# Empty object:
+obj()                  # -> {}
+```
+
+Unlike `dict()` which transpiles to `new Map()`, `obj()` creates plain JavaScript
+object literals. Use this for React props, style objects, and anywhere you
+need a plain JS object.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.nodes import Expr, Object, Spread, spread_dict
+
+# TYPE_CHECKING avoids import cycle: Transpiler -> nodes -> Expr -> obj -> Transpiler
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+
+@dataclass(slots=True)
+class ObjTransformer(Expr):
+	"""Transformer for `obj()` with `**spread` support.
+
+	- `obj(key=value, ...)` -> `{ key: value, ... }`
+	- `obj(**base, key=value)` -> `{ ...base, key: value }`
+
+	Creates a plain JavaScript object literal.
+	Use this instead of `dict()` when you need a plain object (e.g., for React props).
+	"""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		raise TypeError("obj cannot be emitted directly - must be called")
+
+	@override
+	def render(self):
+		raise TypeError("obj cannot be rendered - must be called")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		if args:
+			raise TranspileError("obj() only accepts keyword arguments")
+
+		props: list[tuple[str, Expr] | Spread] = []
+		for kw in keywords:
+			if kw.arg is None:
+				# **spread syntax
+				props.append(spread_dict(ctx.emit_expr(kw.value)))
+			else:
+				# key=value
+				props.append((kw.arg, ctx.emit_expr(kw.value)))
+
+		return Object(props)
+
+
+# Create singleton instance for use as a callable
+obj = ObjTransformer()

pulse/js/object.py

@@ -0,0 +1,172 @@
+"""
+JavaScript Object builtin module.
+
+Usage:
+
+```python
+from pulse.js import Object
+Object.keys({"a": 1})         # -> Object.keys({"a": 1})
+Object.assign({}, {"a": 1})   # -> Object.assign({}, {"a": 1})
+Object.is_(x, y)              # -> Object.is(x, y)
+
+# Or import from module directly:
+from pulse.js.object import Object
+```
+"""
+
+from collections.abc import Iterable as _Iterable
+from typing import Any as _Any
+from typing import TypedDict as _TypedDict
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+K = _TypeVar("K", bound=str)  # Object keys are always strings in JS
+
+
+# Property descriptor type - JS uses a plain object with specific keys
+class PropertyDescriptor(_TypedDict, total=False):
+	"""Type for Object.defineProperty descriptor."""
+
+	value: _Any
+	writable: bool
+	get: _Any  # Callable[[], T] but we use _Any for flexibility
+	set: _Any  # Callable[[T], None]
+	configurable: bool
+	enumerable: bool
+
+
+class Object:
+	"""JavaScript Object namespace - static methods for object manipulation.
+
+	Note: Object is primarily used as a namespace for static methods.
+	The types here are as precise as JavaScript's dynamic nature allows.
+	"""
+
+	@staticmethod
+	def assign(target: T, *sources: _Any) -> T:
+		"""Copy properties from sources to target. Returns target."""
+		...
+
+	@staticmethod
+	def create(
+		proto: _Any | None,
+		propertiesObject: dict[str, PropertyDescriptor] | None = None,
+		/,
+	) -> _Any:
+		"""Create a new object with the specified prototype."""
+		...
+
+	@staticmethod
+	def defineProperty(
+		obj: T, prop: str, descriptor: PropertyDescriptor | dict[str, _Any]
+	) -> T:
+		"""Define a property on an object. Returns the object."""
+		...
+
+	@staticmethod
+	def defineProperties(
+		obj: T, props: dict[str, PropertyDescriptor | dict[str, _Any]]
+	) -> T:
+		"""Define multiple properties on an object. Returns the object."""
+		...
+
+	@staticmethod
+	def entries(obj: dict[str, T]) -> list[tuple[str, T]]:
+		"""Return an array of [key, value] pairs."""
+		...
+
+	@staticmethod
+	def freeze(obj: T) -> T:
+		"""Freeze an object (prevent modifications). Returns the object."""
+		...
+
+	@staticmethod
+	def fromEntries(entries: _Iterable[tuple[str, T]]) -> dict[str, T]:
+		"""Create an object from an iterable of [key, value] pairs."""
+		...
+
+	@staticmethod
+	def getOwnPropertyDescriptor(obj: _Any, prop: str) -> PropertyDescriptor | None:
+		"""Return the property descriptor for a property."""
+		...
+
+	@staticmethod
+	def getOwnPropertyDescriptors(obj: _Any) -> dict[str, PropertyDescriptor]:
+		"""Return all own property descriptors."""
+		...
+
+	@staticmethod
+	def getOwnPropertyNames(obj: _Any) -> list[str]:
+		"""Return all own property names (including non-enumerable)."""
+		...
+
+	@staticmethod
+	def getOwnPropertySymbols(obj: _Any) -> list[_Any]:
+		"""Return all own Symbol properties."""
+		...
+
+	@staticmethod
+	def getPrototypeOf(obj: _Any) -> _Any | None:
+		"""Return the prototype of an object."""
+		...
+
+	@staticmethod
+	def hasOwn(obj: _Any, prop: str) -> bool:
+		"""Return True if the object has the specified own property."""
+		...
+
+	@staticmethod
+	def is_(value1: _Any, value2: _Any) -> bool:
+		"""Determine if two values are the same value (SameValue algorithm)."""
+		...
+
+	@staticmethod
+	def isExtensible(obj: _Any) -> bool:
+		"""Return True if the object is extensible."""
+		...
+
+	@staticmethod
+	def isFrozen(obj: _Any) -> bool:
+		"""Return True if the object is frozen."""
+		...
+
+	@staticmethod
+	def isSealed(obj: _Any) -> bool:
+		"""Return True if the object is sealed."""
+		...
+
+	@staticmethod
+	def keys(obj: dict[str, _Any]) -> list[str]:
+		"""Return an array of enumerable property names."""
+		...
+
+	@staticmethod
+	def preventExtensions(obj: T) -> T:
+		"""Prevent new properties from being added. Returns the object."""
+		...
+
+	@staticmethod
+	def seal(obj: T) -> T:
+		"""Seal an object (prevent adding/removing properties). Returns the object."""
+		...
+
+	@staticmethod
+	def setPrototypeOf(obj: T, prototype: _Any | None) -> T:
+		"""Set the prototype of an object. Returns the object."""
+		...
+
+	@staticmethod
+	def values(obj: dict[str, T]) -> list[T]:
+		"""Return an array of enumerable property values."""
+		...
+
+	@staticmethod
+	def groupBy(items: _Iterable[T], keyFn: _Any) -> dict[str, list[T]]:
+		"""Group items by key function result (ES2024)."""
+		...
+
+
+# Self-register this module as a JS builtin (global identifier)
+JsModule.register(name=None)

pulse/js/promise.py

@@ -0,0 +1,172 @@
+"""
+JavaScript Promise builtin module.
+
+Usage:
+
+```python
+from pulse.js import Promise
+Promise(executor)             # -> new Promise(executor)
+Promise.resolve(value)        # -> Promise.resolve(value)
+Promise.reject(reason)        # -> Promise.reject(reason)
+
+# Or import from module directly:
+from pulse.js.promise import Promise
+```
+
+The `Promise` class is generic and supports async/await via the Awaitable protocol.
+"""
+
+from collections.abc import Callable as _Callable
+from collections.abc import Generator as _Generator
+from collections.abc import Iterable as _Iterable
+from typing import Any as _Any
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+from typing import overload as _overload
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+T_co = _TypeVar("T_co", covariant=True)
+U = _TypeVar("U")
+
+# Result types for allSettled
+PromiseFulfilledResult = dict[str, T | str]  # { status: "fulfilled", value: T }
+PromiseRejectedResult = dict[str, str]  # { status: "rejected", reason: any }
+PromiseSettledResult = PromiseFulfilledResult[T] | PromiseRejectedResult
+
+
+class Promise(_Generic[T_co]):
+	"""JavaScript Promise - a thenable that represents an async operation.
+
+	`Promise` is both generic over its resolved type and implements `Awaitable`,
+	allowing it to be used with Python's async/await syntax which transpiles
+	to JavaScript async/await.
+
+	Example:
+
+	```python
+	@javascript
+	async def fetch_data() -> str:
+	    response: Promise[Response] = fetch("/api/data")
+	    data = await response  # Awaits the promise
+	    return data.text()
+	```
+	"""
+
+	def __init__(
+		self,
+		executor: _Callable[
+			[_Callable[[T_co], None], _Callable[[Exception], None]], None
+		]
+		| None = None,
+		/,
+	) -> None:
+		"""Create a Promise.
+
+		Args:
+		    executor: Optional function receiving (resolve, reject) callbacks.
+		        If omitted, creates a pending promise (for use with Promise.resolve/reject).
+		"""
+		...
+
+	def then(
+		self,
+		on_fulfilled: _Callable[[T_co], U | "Promise[U]"] | None = None,
+		on_rejected: _Callable[[Exception], U | "Promise[U]"] | None = None,
+		/,
+	) -> "Promise[U]":
+		"""Attach callbacks to handle fulfillment and/or rejection."""
+		...
+
+	def catch(
+		self, on_rejected: _Callable[[Exception], U | "Promise[U]"]
+	) -> "Promise[T_co | U]":
+		"""Attach a rejection handler callback."""
+		...
+
+	def finally_(self, on_finally: _Callable[[], None]) -> "Promise[T_co]":
+		"""Attach a handler that is called when the promise settles (fulfilled or rejected)."""
+		...
+
+	def __await__(self) -> _Generator[None, None, T_co]:
+		"""Support await syntax - transpiles to JavaScript await."""
+		...
+
+	# Static methods for Promise construction
+	@staticmethod
+	@_overload
+	def resolve() -> "Promise[None]":
+		"""Create a Promise that resolves with None."""
+		...
+
+	@staticmethod
+	@_overload
+	def resolve(value: U, /) -> "Promise[U]":
+		"""Create a Promise that resolves with the given value."""
+		...
+
+	@staticmethod
+	def resolve(value: U | None = None, /) -> "Promise[U] | Promise[None]":
+		"""Create a Promise that resolves with the given value."""
+		...
+
+	@staticmethod
+	def reject(reason: Exception | str) -> "Promise[_Any]":
+		"""Create a Promise that rejects with the given reason."""
+		...
+
+	# Static methods for combining promises
+	@staticmethod
+	def all(iterable: _Iterable["Promise[T]"]) -> "Promise[list[T]]":
+		"""Wait for all promises to resolve, or reject on first rejection.
+
+		Returns a promise that resolves to a list of all resolved values.
+		"""
+		...
+
+	@staticmethod
+	def allSettled(
+		iterable: _Iterable["Promise[T]"],
+	) -> "Promise[list[PromiseSettledResult[T]]]":
+		"""Wait for all promises to settle (resolve or reject).
+
+		Returns a promise that resolves to a list of result objects.
+		"""
+		...
+
+	@staticmethod
+	def any(iterable: _Iterable["Promise[T]"]) -> "Promise[T]":
+		"""Return first fulfilled promise, or reject if all reject."""
+		...
+
+	@staticmethod
+	def race(iterable: _Iterable["Promise[T]"]) -> "Promise[T]":
+		"""Return first settled promise (fulfilled or rejected)."""
+		...
+
+	@staticmethod
+	def withResolvers() -> "PromiseWithResolvers[T]":
+		"""Create a promise with its resolve and reject functions exposed.
+
+		Returns an object with { promise, resolve, reject }.
+		ES2024 feature.
+		"""
+		...
+
+
+class PromiseWithResolvers(_Generic[T]):
+	"""Result type for Promise.withResolvers()."""
+
+	@property
+	def promise(self) -> Promise[T]: ...
+
+	@property
+	def resolve(self) -> _Callable[[T], None]: ...
+
+	@property
+	def reject(self) -> _Callable[[Exception | str], None]: ...
+
+
+# Self-register this module as a JS builtin (global identifier)
+JsModule.register(name=None)

pulse/js/pulse.py

@@ -0,0 +1,115 @@
+"""
+Pulse UI client bindings for channel communication.
+
+Usage:
+
+```python
+from pulse.js.pulse import usePulseChannel, ChannelBridge, PulseChannelResetError
+
+@ps.javascript(jsx=True)
+def MyChannelComponent(*, channel_id: str):
+    bridge = usePulseChannel(channel_id)
+
+    # Subscribe to events
+    useEffect(
+        lambda: bridge.on("server:notify", lambda payload: console.log(payload)),
+        [bridge],
+    )
+
+    # Emit events to server
+    def send_ping():
+        bridge.emit("client:ping", {"message": "hello"})
+
+    # Make requests to server
+    async def send_request():
+        response = await bridge.request("client:request", {"data": 123})
+        console.log(response)
+
+    return ps.div()[
+        ps.button(onClick=send_ping)["Send Ping"],
+        ps.button(onClick=send_request)["Send Request"],
+    ]
+```
+"""
+
+from collections.abc import Awaitable as _Awaitable
+from collections.abc import Callable as _Callable
+from typing import Any as _Any
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+
+
+class PulseChannelResetError(Exception):
+	"""Error raised when a channel is closed or reset."""
+
+	pass
+
+
+class ChannelBridge:
+	"""A bridge for bidirectional communication between client and server.
+
+	Provides methods for emitting events, making requests, and subscribing
+	to server events on a specific channel.
+	"""
+
+	@property
+	def id(self) -> str:
+		"""The unique channel identifier."""
+		...
+
+	def emit(self, event: str, payload: _Any = None) -> None:
+		"""Emit an event to the server.
+
+		Args:
+		    event: The event name to emit.
+		    payload: Optional data to send with the event.
+		"""
+		...
+
+	def request(self, event: str, payload: _Any = None) -> _Awaitable[_Any]:
+		"""Make a request to the server and await a response.
+
+		Args:
+		    event: The event name to send.
+		    payload: Optional data to send with the request.
+
+		Returns:
+		    A Promise that resolves with the server's response.
+		"""
+		...
+
+	def on(self, event: str, handler: _Callable[[_Any], _Any]) -> _Callable[[], None]:
+		"""Subscribe to events from the server.
+
+		Args:
+		    event: The event name to listen for.
+		    handler: A callback function that receives the event payload.
+		        May be sync or async. For request events, the return value
+		        is sent back to the server.
+
+		Returns:
+		    A cleanup function that unsubscribes the handler.
+		"""
+		...
+
+
+def usePulseChannel(channel_id: str) -> ChannelBridge:
+	"""React hook to connect to a Pulse channel.
+
+	Must be called from within a React component. The channel connection
+	is automatically managed based on component lifecycle.
+
+	Args:
+	    channel_id: The unique identifier for the channel to connect to.
+
+	Returns:
+	    A ChannelBridge instance for interacting with the channel.
+	"""
+	...
+
+
+# Register as a JS module with named imports from pulse-ui-client
+JsModule.register(name="pulse", src="pulse-ui-client", values="named_import")