AbstractOptionaloptions: IRetreeNodeOptionsRuntime options for this Retree node.
AbstractdependenciesDependencies to listen for changes to.
When any IReactiveDependency criteria is met, a change will be emitted for this ReactiveNode instance.
Keep this getter deterministic. Do not start subscriptions, perform network work, or mutate state here. Use ReactiveNode.onObserved, ReactiveNode.onUnobserved, and ReactiveNode.onChanged for lifecycle work.
The returned array may change length or ordering while the node is
observed. Retree treats added, removed, or reordered entries as
invalidation and refreshes subscriptions. Use null when you want an
inactive slot to keep its position, but it is not required for
correctness.
Creates a new IReactiveDependency instance.
the node to listen to "nodeChanged" events for.
Optionalcomparisons: any[]Optional. Values to compare between updates to node.
dependency object.
Use this inside the ReactiveNode.dependencies getter or an
@select dependency selector when one slot needs explicit comparison
cells. If node is a Retree-managed object, it is observed with
nodeChanged. If node is a primitive or unproxied value, Retree
treats it as a comparison-only dependency.
Comparison cells should be deterministic. If their length/order changes,
Retree treats that as invalidation and emits for this node. If no
comparisons are provided, every nodeChanged event from the dependency
emits for this node.
Creates a new IReactiveDependency instance.
dependency object.
Use this inside the ReactiveNode.dependencies getter or an
@select dependency selector when one slot needs explicit comparison
cells. If node is a Retree-managed object, it is observed with
nodeChanged. If node is a primitive or unproxied value, Retree
treats it as a comparison-only dependency.
Comparison cells should be deterministic. If their length/order changes,
Retree treats that as invalidation and emits for this node. If no
comparisons are provided, every nodeChanged event from the dependency
emits for this node.
Create a reactive pointer to an existing Retree-managed node.
Existing Retree-managed node to point at.
A Retree-managed RetreeLink whose current points at node.
This is a convenience wrapper around Retree.link. Use it when a
ReactiveNode method needs to return or store a pointer to a node owned
elsewhere without reparenting that node.
Do not use link when ownership should move; use Retree.move or
ReactiveNode.moveTo. Do not use it when two locations need
independent state; use Retree.clone.
ProtectedmemoMemoize the result of fn, scoped to this ReactiveNode instance.
Optionalcomparisons: unknown[]Two forms:
this.memo(fn, deps?) — derives the cache key
from the active getter's property name. Throws if called outside a getter or
more than once in the same getter.this.memo(key, fn, deps?) — works anywhere; required when
stacking multiple memo cells in one getter, or memoizing inside a method.Cache semantics for comparisons:
undefined: run fn under automatic dependency trapping and
recompute when one of the trapped reads changes.[]: compute once and cache forever for this instance.[a, b, ...]: recompute when any cell shallow-changes using Object.is.
Tree-node cells are compared by their latest reproxy identity, so passing
this.list correctly invalidates when list mutates.memo is a cache, not a subscription. It does not emit
nodeChanged or trigger React renders by itself. Pair it with
dependencies, Retree.select, or useSelect when you also need
notification behavior.
class ListFilter extends ReactiveNode {
list: Card[] = [];
searchText = "";
// Keyless form
get filteredList() {
return this.memo(
() => this.list.filter((c) => c.text === this.searchText),
[this.list, this.searchText]
);
}
// Explicit-key form (e.g. when stacking two memos in one getter)
get pair() {
const a = this.memo("a", () => expensiveA(), [this.list]);
const b = this.memo("b", () => expensiveB(), [this.searchText]);
return { a, b };
}
get dependencies() { return [this.dependency(this.list)]; }
}
Memoize the result of fn, scoped to this ReactiveNode instance.
Optionalcomparisons: unknown[]Two forms:
this.memo(fn, deps?) — derives the cache key
from the active getter's property name. Throws if called outside a getter or
more than once in the same getter.this.memo(key, fn, deps?) — works anywhere; required when
stacking multiple memo cells in one getter, or memoizing inside a method.Cache semantics for comparisons:
undefined: run fn under automatic dependency trapping and
recompute when one of the trapped reads changes.[]: compute once and cache forever for this instance.[a, b, ...]: recompute when any cell shallow-changes using Object.is.
Tree-node cells are compared by their latest reproxy identity, so passing
this.list correctly invalidates when list mutates.memo is a cache, not a subscription. It does not emit
nodeChanged or trigger React renders by itself. Pair it with
dependencies, Retree.select, or useSelect when you also need
notification behavior.
class ListFilter extends ReactiveNode {
list: Card[] = [];
searchText = "";
// Keyless form
get filteredList() {
return this.memo(
() => this.list.filter((c) => c.text === this.searchText),
[this.list, this.searchText]
);
}
// Explicit-key form (e.g. when stacking two memos in one getter)
get pair() {
const a = this.memo("a", () => expensiveA(), [this.list]);
const b = this.memo("b", () => expensiveB(), [this.searchText]);
return { a, b };
}
get dependencies() { return [this.dependency(this.list)]; }
}
Move this node to a new structural parent.
Retree-managed destination collection or object.
Optionalkey: numberOptional array insertion index, map key, or object property key.
The latest reproxy for this node after it moves.
This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.
Do not call moveTo on a root node; roots have no parent to remove from.
Do not manually remove the node from its current parent before moving.
Move this node to a new structural parent.
Retree-managed destination collection or object.
Optional array insertion index, map key, or object property key.
The latest reproxy for this node after it moves.
This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.
Do not call moveTo on a root node; roots have no parent to remove from.
Do not manually remove the node from its current parent before moving.
Move this node to a new structural parent.
Retree-managed destination collection or object.
The latest reproxy for this node after it moves.
This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.
Do not call moveTo on a root node; roots have no parent to remove from.
Do not manually remove the node from its current parent before moving.
Move this node to a new structural parent.
Retree-managed destination collection or object.
Optional array insertion index, map key, or object property key.
The latest reproxy for this node after it moves.
This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.
Do not call moveTo on a root node; roots have no parent to remove from.
Do not manually remove the node from its current parent before moving.
ProtectedonRuns after this ReactiveNode receives a fresh reproxy.
Override this when a node needs to synchronize derived state only after a
real Retree change. Retree runs this before nodeChanged /
treeChanged listeners flush. If no transaction is already active,
Retree starts one so state updates made here are batched with the reproxy
that triggered the effect.
Use this for small synchronization writes that should happen only after Retree has confirmed a real change. Avoid writing unconditionally here; guard against loops by checking whether the derived value actually changed.
ProtectedonRuns when this ReactiveNode gets its first active
nodeChanged or treeChanged observer.
Override this for work that requires the proxied instance, such as starting external subscriptions that write back into Retree state.
Keep setup idempotent. Retree calls this when the first active
nodeChanged or treeChanged listener starts observing the node, not
when the node is constructed.
ProtectedonRuns when this ReactiveNode loses its last active
nodeChanged or treeChanged observer.
Use this to clean up resources created in ReactiveNode.onObserved. Do not rely on it as a destructor for unobserved nodes; it only runs after observation had started.
Prepare lazy Retree child proxies below this ReactiveNode.
Optional depth limit. Omit to prepare all reachable non-ignored child objects.
Retree lazily proxies plain object and array fields on ReactiveNodes. Call
this when an app wants to pay that first-touch cost during a controlled
phase, such as while showing a loading spinner. This walks only own data
properties, so computed getters like dependencies are not evaluated or
cached as child nodes. Fields marked with @ignore are skipped.
Do not call this for every render. Call it once during setup, loading, or before a known interaction that will traverse a large subtree.
Declare dependencies for other nodes in the tree to conditionally emit changes for the node.
Remarks
Return Retree-managed nodes directly when any change to that node should emit. Return primitive values directly when they should be compared only. Use ReactiveNode.dependency when a reactive dependency needs explicit comparison cells. Dependency arrays should be deterministic, but may change length or order at runtime. Retree treats shape changes as invalidation and refreshes subscriptions.
Example