Implement trigger_ref to force-notify watchers of a proxy (closes #123)

Modeled after Vue's triggerRef: after making deep mutations to a value
nested inside a shallow proxy (which bypass the proxy and are therefore
invisible to observ), trigger_ref(proxy) notifies the proxy's dep and
all live keydeps, as if its first level was written to. Works on any
proxy; all views of the same target share their deps, so triggering
one view notifies watchers on all of them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BAdkw8VAYycyoPWjFf2WD7

Author: claude

docs/guide/readonly-shallow.md

@@ -50,6 +50,25 @@ This is an escape hatch for performance-sensitive cases: when a value is a large
 
 `shallow_readonly()` combines both behaviors: a read-only view where only first-level reads are tracked.
 
+## Force-triggering with `trigger_ref`
+
+Sometimes you *do* mutate a value nested inside a shallow proxy in place — for example when the structure is too large to replace wholesale. Since those mutations bypass the proxy, observ cannot see them. `trigger_ref()` (named after [Vue's `triggerRef`](https://vuejs.org/api/reactivity-advanced.html#triggerref)) force-notifies the watchers that depend on a proxy, as if its first level was written to:
+
+```python
+from observ import shallow_reactive, trigger_ref, watch_effect
+
+state = shallow_reactive({"big": {"huge": [...]}})
+
+watcher = watch_effect(lambda: render(state["big"]))
+
+state["big"]["huge"].append(item)  # NOT tracked: deep mutation
+trigger_ref(state)                 # force: re-runs the effect
+```
+
+Watchers re-evaluate their watched function; whether a `watch()` *callback* then fires follows the normal rules: watchers on a container value (or with `deep=True`) always fire, while a watcher on a plain value only fires when that value actually differs from the previous evaluation.
+
+`trigger_ref` accepts any proxy (it works on the result of `ref()` and `reactive()` too). All proxies for the same target share their bookkeeping, so triggering one view notifies the watchers on all of them.
+
 ## Overview
 
 | Function             | Writable | Deep |

docs/reference/api.md

@@ -4,7 +4,7 @@ Everything documented on this page is available from the top-level `observ` pack
 
 ```python
 from observ import (
-    reactive, readonly, shallow_reactive, shallow_readonly, ref, to_raw,
+    reactive, readonly, shallow_reactive, shallow_readonly, ref, to_raw, trigger_ref,
     computed, watch, watch_effect, Watcher,
     init, loop_factory, scheduler,
 )
@@ -46,6 +46,8 @@ Combination of `shallow_reactive` and `readonly`.
 
 ::: observ.proxy.ref
 
+::: observ.proxy.trigger_ref
+
 ::: observ.proxy.to_raw
 
 ## Watching state

observ/__init__.py

@@ -13,6 +13,7 @@
     shallow_reactive,
     shallow_readonly,
     to_raw,
+    trigger_ref,
 )
 from .scheduler import scheduler
 from .watcher import Watcher, computed, watch, watch_effect

observ/proxy.py

@@ -164,6 +164,29 @@ def shallow_readonly(target: T) -> T:
     return proxy(target, readonly=True, shallow=True)
 
 
+def trigger_ref(target: Any) -> None:
+    """
+    Force-notify the watchers that depend on the given proxy, as if
+    its first level was written to. This is typically used together
+    with a shallow proxy (`shallow_reactive`, `shallow_readonly`),
+    after making deep mutations to a value nested inside it — those
+    mutations bypass the proxy, so observ cannot see them by itself.
+    """
+    if not isinstance(target, Proxy):
+        raise TypeError(
+            "trigger_ref() expects a proxy "
+            "(e.g. the result of ref, reactive or shallow_reactive)"
+        )
+    dep = target.__dep__
+    keydeps = dep.keydeps
+    if keydeps is not None:
+        # Notifying may run sync watchers, which can release keydeps
+        # and thereby mutate the (weak) mapping, so iterate a snapshot
+        for keydep in list(keydeps.values()):
+            keydep.notify()
+    dep.notify()
+
+
 def to_raw(target: Proxy[T] | T) -> T:
     """
     Returns a raw object from which any trace of proxy has been replaced

tests/test_trigger_ref.py

@@ -0,0 +1,126 @@
+from unittest.mock import Mock
+
+import pytest
+
+from observ import (
+    computed,
+    readonly,
+    shallow_reactive,
+    trigger_ref,
+    watch,
+    watch_effect,
+)
+
+
+def test_trigger_ref_shallow_key_watcher():
+    state = shallow_reactive({"value": {"count": 0}})
+    watcher = watch(lambda: state["value"], Mock(), sync=True)
+
+    # Deep mutations bypass a shallow proxy, so no watcher fires
+    state["value"]["count"] = 1
+    watcher.callback.assert_not_called()
+
+    trigger_ref(state)
+    watcher.callback.assert_called_once()
+
+
+def test_trigger_ref_notifies_dep_and_keydeps():
+    state = shallow_reactive({"items": [1]})
+    keyed = watch(lambda: state["items"], Mock(), sync=True)
+    container = watch(lambda: dict(state.items()), Mock(), sync=True)
+
+    trigger_ref(state)
+
+    keyed.callback.assert_called_once()
+    container.callback.assert_called_once()
+
+
+def test_trigger_ref_watch_effect():
+    state = shallow_reactive({"value": [1, 2]})
+    lengths = []
+    watcher = watch_effect(lambda: lengths.append(len(state["value"])), sync=True)
+
+    assert lengths == [2]
+
+    state["value"].append(3)
+    assert lengths == [2]
+
+    trigger_ref(state)
+    assert lengths == [2, 3]
+
+    assert watcher.active
+
+
+def test_trigger_ref_computed():
+    state = shallow_reactive({"data": {"count": 1}})
+
+    @computed
+    def doubled():
+        return state["data"]["count"] * 2
+
+    assert doubled() == 2
+
+    state["data"]["count"] = 3
+    # The computed doesn't know its (shallow) dependency changed
+    assert doubled() == 2
+
+    trigger_ref(state)
+    assert doubled() == 6
+
+
+def test_trigger_ref_shallow_list():
+    items = shallow_reactive([{"a": 0}])
+    watcher = watch(lambda: items[0], Mock(), sync=True)
+
+    items[0]["a"] = 1
+    watcher.callback.assert_not_called()
+
+    trigger_ref(items)
+    watcher.callback.assert_called_once()
+
+
+def test_trigger_ref_through_readonly_view():
+    state = shallow_reactive({"data": {"x": 0}})
+    view = readonly(state)
+    watcher = watch(lambda: view["data"], Mock(), sync=True)
+
+    state["data"]["x"] = 1
+    watcher.callback.assert_not_called()
+
+    # All proxies for the same target share their deps, so triggering
+    # any view notifies watchers on all of them
+    trigger_ref(view)
+    watcher.callback.assert_called_once()
+
+
+def test_trigger_ref_plain_value_unchanged():
+    # Callbacks that watch a plain (non-container) value only fire
+    # when that value actually differs from the previous evaluation
+    state = shallow_reactive({"value": 0})
+    watcher = watch(lambda: state["value"], Mock(), sync=True)
+
+    trigger_ref(state)
+    watcher.callback.assert_not_called()
+
+    # But the watched function is re-evaluated, so effects do re-run
+    reads = []
+    effect = watch_effect(lambda: reads.append(state["value"]), sync=True)
+    assert reads == [0]
+    trigger_ref(state)
+    assert reads == [0, 0]
+
+    assert effect.active
+
+
+def test_trigger_ref_requires_proxy():
+    with pytest.raises(TypeError):
+        trigger_ref({"value": 1})
+
+    with pytest.raises(TypeError):
+        trigger_ref(None)
+
+
+def test_trigger_ref_no_watchers():
+    # Triggering a proxy nobody watches is a no-op
+    state = shallow_reactive({"value": 1})
+    trigger_ref(state)