pulse-framework 0.1.46__py3-none-any.whl → 0.1.48__py3-none-any.whl

pulse/js/object.py

@@ -0,0 +1,173 @@
+"""
+JavaScript Object builtin module.
+
+Usage:
+    import pulse.js.object as 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)
+
+    # Note: For 'is' (Python keyword), use namespace import:
+    # import pulse.js.object as Object; Object.is(...)
+    # Or use the underscore version for direct import:
+    from pulse.js.object import keys, assign, is_
+    keys({"a": 1})                # -> Object.keys({"a": 1})
+    assign({}, {"a": 1})          # -> Object.assign({}, {"a": 1})
+    is_(x, y)                     # -> Object.is(x, y)
+"""
+
+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 register_js_module as _register_js_module
+
+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
+_register_js_module(name="Object", global_scope=True)

pulse/js/promise.py

@@ -0,0 +1,150 @@
+"""
+JavaScript Promise builtin module.
+
+Usage:
+    import pulse.js.promise as Promise
+    Promise.resolve(value)        # -> Promise.resolve(value)
+    Promise.reject(reason)        # -> Promise.reject(reason)
+
+    from pulse.js.promise import resolve, reject, all, allSettled, race, any
+    resolve(value)                # -> Promise.resolve(value)
+    reject(reason)                 # -> Promise.reject(reason)
+
+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 Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+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:
+	    @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
+	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[T]":
+		"""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
+_register_js_module(name="Promise", global_scope=True)

pulse/js/regexp.py

@@ -0,0 +1,54 @@
+"""
+JavaScript RegExp builtin module.
+
+Usage:
+    import pulse.js.regexp as RegExp
+    RegExp(pattern, flags)        # -> new RegExp(pattern, flags)
+
+    from pulse.js.regexp import RegExp
+    RegExp(pattern, flags)        # -> new RegExp(pattern, flags)
+"""
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+
+class RegExp:
+	"""Class for JavaScript RegExp instances."""
+
+	def __init__(self, pattern: str, flags: str | None = None): ...
+
+	def exec(self, string: str) -> list[str] | None: ...
+	def test(self, string: str) -> bool: ...
+
+	@property
+	def source(self) -> str: ...
+
+	@property
+	def flags(self) -> str: ...
+
+	@property
+	def glob(self) -> bool: ...  # JavaScript 'global' property
+
+	@property
+	def ignoreCase(self) -> bool: ...
+
+	@property
+	def multiline(self) -> bool: ...
+
+	@property
+	def dotAll(self) -> bool: ...
+
+	@property
+	def unicode(self) -> bool: ...
+
+	@property
+	def sticky(self) -> bool: ...
+
+	@property
+	def lastIndex(self) -> int: ...
+
+	def toString(self) -> str: ...
+
+
+# Self-register this module as a JS builtin
+_register_js_module(name="RegExp", global_scope=True)

pulse/js/set.py

@@ -0,0 +1,109 @@
+"""
+JavaScript Set builtin module.
+
+Usage:
+    import pulse.js.set as Set
+    Set()                         # -> new Set()
+    Set([1, 2, 3])               # -> new Set([1, 2, 3])
+
+    from pulse.js.set import Set
+    Set()                         # -> new Set()
+"""
+
+from collections.abc import Callable as _Callable
+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 pulse.transpiler.js_module import register_js_module as _register_js_module
+
+T = _TypeVar("T")
+
+
+class Set(_Generic[T]):
+	"""JavaScript Set - a collection of unique values.
+
+	Set[T] stores unique values of type T in insertion order.
+	"""
+
+	def __init__(self, iterable: _Iterable[T] | None = None) -> None: ...
+
+	@property
+	def size(self) -> int:
+		"""The number of values in the Set."""
+		...
+
+	def add(self, value: T) -> "Set[T]":
+		"""Add a value to the Set. Returns the Set for chaining."""
+		...
+
+	def clear(self) -> None:
+		"""Remove all values from the Set."""
+		...
+
+	def delete(self, value: T) -> bool:
+		"""Remove a value. Returns True if the value existed."""
+		...
+
+	def has(self, value: T) -> bool:
+		"""Return True if the value exists in the Set."""
+		...
+
+	def forEach(
+		self, callback: _Callable[[T, T, "Set[T]"], None], thisArg: _Any | None = None
+	) -> None:
+		"""Execute a function for each value.
+
+		Note: callback receives (value, value, set) for compatibility with Map.
+		"""
+		...
+
+	def keys(self) -> _Iterable[T]:
+		"""Return an iterator of values (same as values())."""
+		...
+
+	def values(self) -> _Iterable[T]:
+		"""Return an iterator of values."""
+		...
+
+	def entries(self) -> _Iterable[tuple[T, T]]:
+		"""Return an iterator of [value, value] pairs."""
+		...
+
+	def __iter__(self) -> _Iterable[T]:
+		"""Iterate over values."""
+		...
+
+	# ES2024 Set methods
+	def union(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values from both sets (ES2024)."""
+		...
+
+	def intersection(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in both sets (ES2024)."""
+		...
+
+	def difference(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in this but not other (ES2024)."""
+		...
+
+	def symmetricDifference(self, other: "Set[T]") -> "Set[T]":
+		"""Return a new Set with values in either but not both (ES2024)."""
+		...
+
+	def isSubsetOf(self, other: "Set[T]") -> bool:
+		"""Return True if all values are in other (ES2024)."""
+		...
+
+	def isSupersetOf(self, other: "Set[T]") -> bool:
+		"""Return True if all values of other are in this (ES2024)."""
+		...
+
+	def isDisjointFrom(self, other: "Set[T]") -> bool:
+		"""Return True if no values are in common (ES2024)."""
+		...
+
+
+# Self-register this module as a JS builtin in global scope
+_register_js_module(name="Set", global_scope=True)

pulse/js/string.py

@@ -0,0 +1,35 @@
+"""
+JavaScript String builtin module.
+
+Usage:
+    import pulse.js.string as String
+    String.fromCharCode(65)        # -> String.fromCharCode(65)
+    String.fromCodePoint(0x1F600)  # -> String.fromCodePoint(0x1F600)
+
+    from pulse.js.string import fromCharCode, fromCodePoint
+    fromCharCode(65)               # -> String.fromCharCode(65)
+    fromCodePoint(0x1F600)         # -> String.fromCodePoint(0x1F600)
+"""
+
+from typing import Any as _Any
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+
+class String:
+	"""JavaScript String constructor."""
+
+	def __init__(self, value: _Any) -> None: ...
+
+	@staticmethod
+	def fromCharCode(*codes: int) -> str: ...
+
+	@staticmethod
+	def fromCodePoint(*codePoints: int) -> str: ...
+
+	@staticmethod
+	def raw(template: str, *substitutions: str) -> str: ...
+
+
+# Self-register this module as a JS builtin
+_register_js_module(name="String", global_scope=True)

pulse/js/weakmap.py

@@ -0,0 +1,50 @@
+"""
+JavaScript WeakMap builtin module.
+
+Usage:
+    import pulse.js.weakmap as WeakMap
+    WeakMap()                     # -> new WeakMap()
+    WeakMap([[obj, "value"]])    # -> new WeakMap([[obj, "value"]])
+
+    from pulse.js.weakmap import WeakMap
+    WeakMap()                     # -> new WeakMap()
+"""
+
+from collections.abc import Iterable as _Iterable
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+K = _TypeVar("K")  # Keys must be objects in JS, but we can't enforce that statically
+V = _TypeVar("V")
+
+
+class WeakMap(_Generic[K, V]):
+	"""JavaScript WeakMap - a collection of key/value pairs with weak key references.
+
+	WeakMap[K, V] holds weak references to keys, allowing garbage collection.
+	Keys must be objects (not primitives).
+	"""
+
+	def __init__(self, iterable: _Iterable[tuple[K, V]] | None = None) -> None: ...
+
+	def delete(self, key: K) -> bool:
+		"""Remove a key and its value. Returns True if the key existed."""
+		...
+
+	def get(self, key: K) -> V | None:
+		"""Return the value for a key, or None if not present."""
+		...
+
+	def has(self, key: K) -> bool:
+		"""Return True if the key exists in the WeakMap."""
+		...
+
+	def set(self, key: K, value: V) -> "WeakMap[K, V]":
+		"""Set a key/value pair. Returns the WeakMap for chaining."""
+		...
+
+
+# Self-register this module as a JS builtin
+_register_js_module(name="WeakMap", global_scope=True)

pulse/js/weakset.py

@@ -0,0 +1,45 @@
+"""
+JavaScript WeakSet builtin module.
+
+Usage:
+    import pulse.js.weakset as WeakSet
+    WeakSet()                     # -> new WeakSet()
+    WeakSet([obj1, obj2])        # -> new WeakSet([obj1, obj2])
+
+    from pulse.js.weakset import WeakSet
+    WeakSet()                     # -> new WeakSet()
+"""
+
+from collections.abc import Iterable as _Iterable
+from typing import Generic as _Generic
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import register_js_module as _register_js_module
+
+T = _TypeVar("T")  # Values must be objects in JS, but we can't enforce that statically
+
+
+class WeakSet(_Generic[T]):
+	"""JavaScript WeakSet - a collection of objects with weak references.
+
+	WeakSet[T] holds weak references to values, allowing garbage collection.
+	Values must be objects (not primitives).
+	"""
+
+	def __init__(self, iterable: _Iterable[T] | None = None) -> None: ...
+
+	def add(self, value: T) -> "WeakSet[T]":
+		"""Add a value to the WeakSet. Returns the WeakSet for chaining."""
+		...
+
+	def delete(self, value: T) -> bool:
+		"""Remove a value. Returns True if the value existed."""
+		...
+
+	def has(self, value: T) -> bool:
+		"""Return True if the value exists in the WeakSet."""
+		...
+
+
+# Self-register this module as a JS builtin in global scope
+_register_js_module(name="WeakSet", global_scope=True)