statepatch 0.1.0__tar.gz → 0.2.0__tar.gz

{statepatch-0.1.0 → statepatch-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: statepatch
-Version: 0.1.0
+Version: 0.2.0
 Summary: Immer-style ops over a plain JSON tree: observables that emit every mutation as an op
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT

{statepatch-0.1.0 → statepatch-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statepatch"
-version = "0.1.0"
+version = "0.2.0"
 description = "Immer-style ops over a plain JSON tree: observables that emit every mutation as an op"
 readme = "README.md"
 license = "MIT"

statepatch-0.2.0/src/statepatch/__init__.py

@@ -0,0 +1,22 @@
+"""Immer-style ops over a plain JSON tree.
+
+An ``Observable`` wraps one value: ``.value`` reads a plain snapshot, every
+mutation applies to the tree and emits the matching ``Op`` to subscribers.
+Observables compose: an observable stored inside another mounts its op
+stream at that path; removing it detaches it, live and reusable.
+"""
+
+from ._core import Observable, Proxy, append, observable
+from ._wire import Listener, Op, Path, Segment, plain
+
+__all__ = [
+    "observable",
+    "Observable",
+    "Proxy",
+    "plain",
+    "append",
+    "Op",
+    "Path",
+    "Segment",
+    "Listener",
+]

statepatch-0.1.0/src/statepatch/__init__.py → statepatch-0.2.0/src/statepatch/_core.py

@@ -1,96 +1,6 @@
-"""Immer-style ops over a plain JSON tree.
+from typing import Any, Callable, Iterator
 
-An ``Observable`` wraps one value: ``.value`` reads a plain snapshot, every
-mutation applies to the tree and emits the matching ``Op`` to subscribers.
-Observables compose: an observable stored inside another mounts its op
-stream at that path; removing it detaches it, live and reusable.
-"""
-
-import math
-from datetime import datetime
-from typing import Any, Callable, Iterator, NamedTuple
-
-Segment = str | int
-Path = tuple[Segment, ...]
-
-
-class Op(NamedTuple):
-    kind: str  # "replace" | "add" | "remove"
-    path: Path
-    value: Any = None
-
-
-Listener = Callable[[Op], None]
-
-_MAX_SAFE_INT = 2**53 - 1
-_MISSING: Any = object()
-
-
-def _snapshot(node: Any) -> Any:
-    if isinstance(node, Observable):
-        return _snapshot(node._state)
-    if isinstance(node, dict):
-        return {key: _snapshot(item) for key, item in node.items()}
-    if isinstance(node, list):
-        return [_snapshot(item) for item in node]
-    return node
-
-
-def plain(value: Any) -> Any:
-    """Resolve a proxy or observable to a plain snapshot; pass anything else through."""
-    if isinstance(value, Proxy):
-        _owner, _rel, node = value._target()
-        return _snapshot(node)
-    if isinstance(value, Observable):
-        return _snapshot(value._state)
-    return value
-
-
-def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:
-    """Validated deep copy keeping ``Observable`` nodes in place; returns the
-    stored tree and the mount points found inside it (paths rooted at ``base``)."""
-    mounts: list[tuple[Path, Observable]] = []
-
-    def walk(value: Any, path: Path) -> Any:
-        if isinstance(value, Observable):
-            mounts.append((path, value))
-            return value
-        if isinstance(value, Proxy):
-            value = plain(value)
-        if isinstance(value, bool) or value is None or isinstance(value, str):
-            return value
-        if isinstance(value, float):
-            if math.isnan(value) or math.isinf(value):
-                raise ValueError(f"{value!r} is not wire-encodable; floats must be finite")
-            return value
-        if isinstance(value, int):
-            if abs(value) > _MAX_SAFE_INT:
-                raise ValueError(
-                    f"integer {value} exceeds the JS safe range (|n| <= 2**53-1); send it as a string"
-                )
-            return value
-        if isinstance(value, datetime):
-            if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
-                raise ValueError("naive datetime is not wire-encodable; attach a timezone")
-            return value
-        if isinstance(value, (list, tuple)):
-            return [walk(item, path + (i,)) for i, item in enumerate(value)]
-        if isinstance(value, dict):
-            out: dict[str, Any] = {}
-            for key, item in value.items():
-                if not isinstance(key, str):
-                    raise TypeError(f"object keys must be strings, got {type(key).__name__}")
-                out[key] = walk(item, path + (key,))
-            return out
-        raise TypeError(f"{type(value).__name__} is not wire-encodable")
-
-    return walk(value, base), mounts
-
-
-def _index(container: Any, key: Any) -> Any:
-    if isinstance(container, list) and isinstance(key, int) and key < 0:
-        return key + len(container)
-    return key
+from ._wire import _MISSING, Listener, Op, Path, Segment, _adopt, _index, _snapshot, plain
 
 
 class Observable:
@@ -220,6 +130,8 @@ class Observable:
             return node._target(())
         return self, path, node
 
+    # container delegators
+
     def __getitem__(self, key: Any) -> Any:
         return Proxy(self, ())[key]
 
@@ -320,11 +232,7 @@ class Proxy:
             else container[key]
         )
         path = rel + (key,)
-        if isinstance(old, str) and isinstance(value, str) and value.startswith(old):
-            if value == old:
-                return
-            container[key] = value
-            owner._emit(Op("add", path + (len(old),), value[len(old) :]))
+        if isinstance(old, str) and value == old:
             return
         stored, mounts = _adopt(value, path)
         owner._admit(mounts, path)
@@ -522,3 +430,22 @@ class Proxy:
     def __repr__(self) -> str:
         _owner, _rel, node = self._target()
         return repr(_snapshot(node))
+
+
+def append(parent: Any, key: Segment, suffix: str) -> None:
+    """Append ``suffix`` to the string at ``parent[key]``, recording an end-offset text-insert ``add`` op."""
+    if isinstance(parent, Observable):
+        parent = Proxy(parent, ())
+    if not isinstance(parent, Proxy):
+        raise TypeError(f"append expects a proxy or observable, got {type(parent).__name__}")
+    if not isinstance(suffix, str):
+        raise TypeError(f"append suffix must be a string, got {type(suffix).__name__}")
+    owner, rel, container = parent._target()
+    key = _index(container, key)
+    old = container[key]
+    if not isinstance(old, str):
+        raise TypeError(f"cannot append to a non-string at path {list(rel + (key,))!r}")
+    if suffix == "":
+        return
+    container[key] = old + suffix
+    owner._emit(Op("add", rel + (key, len(old)), suffix))

statepatch-0.2.0/src/statepatch/_wire.py

@@ -0,0 +1,94 @@
+import math
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple
+
+if TYPE_CHECKING:
+    from ._core import Observable
+
+Segment = str | int
+Path = tuple[Segment, ...]
+
+
+class Op(NamedTuple):
+    kind: str  # "replace" | "add" | "remove"
+    path: Path
+    value: Any = None
+
+
+Listener = Callable[[Op], None]
+
+_MAX_SAFE_INT = 2**53 - 1
+_MISSING: Any = object()
+
+
+def _snapshot(node: Any) -> Any:
+    from ._core import Observable
+
+    if isinstance(node, Observable):
+        return _snapshot(node._state)
+    if isinstance(node, dict):
+        return {key: _snapshot(item) for key, item in node.items()}
+    if isinstance(node, list):
+        return [_snapshot(item) for item in node]
+    return node
+
+
+def plain(value: Any) -> Any:
+    """Resolve a proxy or observable to a plain snapshot; pass anything else through."""
+    from ._core import Observable, Proxy
+
+    if isinstance(value, Proxy):
+        _owner, _rel, node = value._target()
+        return _snapshot(node)
+    if isinstance(value, Observable):
+        return _snapshot(value._state)
+    return value
+
+
+def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:
+    """Validated deep copy keeping ``Observable`` nodes in place; returns the
+    stored tree and the mount points found inside it (paths rooted at ``base``)."""
+    from ._core import Observable, Proxy
+
+    mounts: list[tuple[Path, Observable]] = []
+
+    def walk(value: Any, path: Path) -> Any:
+        if isinstance(value, Observable):
+            mounts.append((path, value))
+            return value
+        if isinstance(value, Proxy):
+            value = plain(value)
+        if isinstance(value, bool) or value is None or isinstance(value, str):
+            return value
+        if isinstance(value, float):
+            if math.isnan(value) or math.isinf(value):
+                raise ValueError(f"{value!r} is not wire-encodable; floats must be finite")
+            return value
+        if isinstance(value, int):
+            if abs(value) > _MAX_SAFE_INT:
+                raise ValueError(
+                    f"integer {value} exceeds the JS safe range (|n| <= 2**53-1); send it as a string"
+                )
+            return value
+        if isinstance(value, datetime):
+            if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+                raise ValueError("naive datetime is not wire-encodable; attach a timezone")
+            return value
+        if isinstance(value, (list, tuple)):
+            return [walk(item, path + (i,)) for i, item in enumerate(value)]
+        if isinstance(value, dict):
+            out: dict[str, Any] = {}
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+                out[key] = walk(item, path + (key,))
+            return out
+        raise TypeError(f"{type(value).__name__} is not wire-encodable")
+
+    return walk(value, base), mounts
+
+
+def _index(container: Any, key: Any) -> Any:
+    if isinstance(container, list) and isinstance(key, int) and key < 0:
+        return key + len(container)
+    return key

{statepatch-0.1.0 → statepatch-0.2.0}/tests/test_observable.py

@@ -4,7 +4,7 @@ mounted observables forward their op streams at the mount path."""
 from datetime import datetime, timezone
 
 import pytest
-from statepatch import Op, observable
+from statepatch import Op, append, observable
 
 
 def collect(obs):
@@ -27,18 +27,46 @@ def test_dict_and_list_mutations_emit_wire_shaped_ops():
     state["status"] = "streaming"
     state["messages"].append({"id": "m1", "content": ""})
     state["messages"][0]["content"] = "hel"
-    state["messages"][0]["content"] = "hello"  # suffix diff -> string add
+    state["messages"][0]["content"] = "hello"  # assign is always a replace
     state["messages"].pop(0)
     assert ops == [
         Op("replace", ("status",), "streaming"),
         Op("add", ("messages", 0), {"id": "m1", "content": ""}),
-        Op("add", ("messages", 0, "content", 0), "hel"),
-        Op("add", ("messages", 0, "content", 3), "lo"),
+        Op("replace", ("messages", 0, "content"), "hel"),
+        Op("replace", ("messages", 0, "content"), "hello"),
         Op("remove", ("messages", 0)),
     ]
     assert state.value == {"status": "streaming", "messages": []}
 
 
+def test_append_emits_an_end_offset_string_add():
+    state = observable({"text": "he", "parts": ["ab"]})
+    ops = collect(state)
+    append(state, "text", "llo")
+    append(state["parts"], 0, "c")
+    append(state, "text", "")  # empty suffix is a no-op
+    assert state.value == {"text": "hello", "parts": ["abc"]}
+    assert ops == [
+        Op("add", ("text", 2), "llo"),
+        Op("add", ("parts", 0, 2), "c"),
+    ]
+
+
+def test_append_fails_fast_on_bad_targets():
+    state = observable({"n": 1, "text": "hi"})
+    ops = collect(state)
+    with pytest.raises(TypeError, match="non-string"):
+        append(state, "n", "x")
+    with pytest.raises(TypeError, match="suffix must be a string"):
+        append(state, "text", 1)
+    with pytest.raises(KeyError):
+        append(state, "missing", "x")
+    with pytest.raises(TypeError, match="proxy or observable"):
+        append({"text": "hi"}, "text", "x")
+    assert state.value == {"n": 1, "text": "hi"}
+    assert ops == []
+
+
 def test_values_are_dealised_on_write():
     state = observable({})
     held = {"a": [1]}