Path Listener (path-listener)

path-listener implements the tosijs observer model. Although these events are exported from tosijs they shouldn't need to be used very often. Mostly they're used to manage state.

touch(path: string) and .touch()

This is used to say that a value at a path has changed. Remember that the observer proxy simply wraps an object, and if you change the object directly, the proxy won't know about it.

The two most common uses for touch() are:

1. You want to make lots of changes to a large data structure, possibly over a period of time (e.g. update hundreds of thousands of values in a table that involve service calls or heavy computation) and don't want to thrash the UI so you just change the object directly.
2. You want to change the content of an object but need a something that is bound to the "outer" object to be refreshed.

Every BoxedProxy also has a .touch() method, so you can call it directly on any proxied value:

app.user.name.touch()   // force update for this scalar
app.user.touch()        // force update for the whole object
app.items[2].touch()    // force update for a list item

Id-path synthesis

When you touch a path that contains an array index (e.g. items[2] or items[2].name), touch() automatically synthesizes the equivalent id-path touches (e.g. items[id=abc] or items[id=abc].name). This means that .touch() on list items correctly updates DOM elements bound via idPath, even when you've mutated the underlying data behind the proxy's back.

observe() and unobserve()

const listener = observe(
  path: string | RegExp | (path: string) => boolean,
  (changedPath: string) => {
    ...
  }
)

// and later, when you're done
unobserve(listener);

observe(…) lets you call a function whenever a specified path changes. You'll be passed the path that changed and you can do whatever you like. It returns a reference to the listener to allow you to dispose of it later.

unobserve(listener) removes the listener.

If the callback updates the DOM, you almost certainly want bind instead

This is the single commonest way to write more code than you need in tosijs, and the cost is not the extra lines — it is that the element becomes invisible to the agent surface.

Two divs, both driven by state:

// hand-rolled: observe, then write the DOM yourself
const rolled = div({})
observe('app.name', () => { rolled.textContent = app.name.value })

// bound
const bound = div({ bindText: app.name })

Both update correctly. But describe() returns one record, not two — the agent map is built from bound elements, and an element becomes wired by being bound and by nothing else. The hand-rolled div is absent from the map, so an agent cannot see what it shows or what drives it.

bind also brings what you would otherwise write yourself: the initial value applied on setup, surgical list updates via idPath, the async-batched touch, and bindings that accumulate on one element rather than clobbering each other.

observe is right when the reaction is not a DOM update — persisting to storage, sending an analytics event, kicking off a fetch, driving a canvas or a WebGL scene. Reach for it there, and for anything the DOM is not the output of.

If you are calling touch() often, that is usually the same signal from the other end: bindings would be doing that work.

Which path does the callback receive?

The path that was TOUCHED — as specific as the write was — not the path you observed. An observer on a root therefore sees different spellings depending on what happened, and that is the rule rather than an inconsistency:

observe('app', cb)

app.rows[id=a].f.k = 2   // cb('app.rows[id=a].f.k')  — a leaf write
app.value = nextDoc      // cb('app')                 — the root replaced
touch('app')             // cb('app')                 — an explicit touch

So a callback that parses the path must handle the root case explicitly. Rounding "the field this path names" silently does nothing when the path IS the root, and code that then falls through to a full re-render will destroy the widget under the user's pointer — reported that way in tosijs#35. If you only care that something under a path changed, ignore the argument and re-read what you need.

Note also that tosi() schedules a touch on the root as it registers, so an observer installed immediately afterwards sees that root touch first. await updates() between registering state and observing it drains that, and is usually what you want in tests.

This is how binding works. When you bind a path to an interface element, an observer is created that knows when to update the interface element. (If the binding is "two-way" (i.e. provides a fromDOM callback) then an input or change event that hits that element will update the value at the bound path.

async updates()

You can await updates() or use updates().then(…) to execute code after any changes have been rendered to the DOM. Typically, you shouldn't have to mess with this, but sometimes—for example—you might need to know how large a rendered UI element is to adjust something else.

It's also used a lot in unit tests. After you perform some logic, does it appear correctly in the UI?

⚠️ Drain after tosi() before you observe

Registering state queues a touch on the root path, and touch() is async-batched — so if you observe immediately after tosi(), that pending notification is still in flight and lands on your callback:

tosi({ app: { a: 0, b: 0 } })
observe('app.a', (path) => console.log(path))   // registration touch pending
app.a.value = 1
await updates()                                 // logs 'app', not 'app.a'

Because a root touch notifies every descendant, an observer on app.b fires too — so it reads convincingly as "writing a woke every sibling". It isn't. Add await updates() after tosi() and before installing observers:

tosi({ app: { a: 0, b: 0 } })
await updates()                                 // <- drain the registration
observe('app.a', (path) => console.log(path))
app.a.value = 1
await updates()                                 // logs 'app.a', and only that

Writes are surgical: every form (app.a.value = 1, app.a = 1, and the string-path form boxed['app.a'] = 1) touches exactly app.a. If a probe suggests otherwise, check for an undrained registration first — the symptom is specific and stable enough to look like a real finding.