Module: lib/core/trace/reactive

Trace hooks for the reactive system.

Two things are recorded here, and the split matters:

  • A write is a logical mutation: one property, at one path, changing from one value to another. It is recorded in the proxy traps, where the mutation actually happens, rather than in trigger() — trigger walks up the parentMap re-firing itself for every ancestor, so recording there would log one write per level of nesting for a single assignment.

  • A watcher wake is a consequence of a write. It is recorded in trigger(), inside the write's causal scope, which is what produces "cart.items.2.qty changed, and that woke CartItem#3's render".

Placing this in its own module rather than inlining it in proxyHandler.js keeps capture and recorder out of the reactive system's import graph from the reactive side, so the dependency runs one way only.

Source:

Methods

(static) traceCollectionWrite(target, key, op, sizeopt) → {number}

Opens a write node for a mutation whose before/after values are not a single pair — an array method, a Map.clear(), a Set.add().

The collection's size is recorded instead of its contents: capturing a whole array on every push would make tracing a list quadratic.

Parameters:
Name Type Attributes Description
target object

The raw collection.
key string | symbol

The method or key that changed.
op string

The operation name, e.g. push or clear.
size number <optional>

The collection's size after the mutation.
Source:
Returns:

A restore token for tracer.leave, or -1 when tracing is off.

Type
number

(static) traceWatcher(watcher) → {number}

Opens a watcher node for a watcher about to re-run because of a write.

Named watchers carry their own identity (CartItem#render, Resource#users, a computed key); anonymous ones are still worth recording, because the shape of the propagation is the answer to "why did this update".

Parameters:
Name Type Description
watcher object

The AvenxWatcher about to run.
Source:
Returns:

A restore token for tracer.leave, or -1 when tracing is off.

Type
number

(static) traceWrite(target, key, oldValue, newValue, opopt) → {number}

Opens a write node and makes it the causal parent of the reactive work the caller is about to trigger.

Callers must guard with tracer.on and must pass the returned token to tracer.leave() in a finally.

Parameters:
Name Type Attributes Description
target object

The raw object that was mutated.
key string | symbol

The mutated key.
oldValue any

The value before the mutation.
newValue any

The value after the mutation.
op string <optional>

What kind of mutation this was, when it was not a plain assignment.
Source:
Returns:

A restore token for tracer.leave, or -1 when tracing is off.

Type
number