BloomVia class final
The scoped dependency tracker injected into computed, RawViaTerminal, and reactive widget build callbacks.
Unlike implicit global stack tracking, BloomVia requires explicit
observation calls (via(node)) during the evaluation pass. This creates an
explicit, deterministic, and AI-friendly dependency manifest while preserving
dynamic runtime branching, 1-pass epoch-based pruning, and on-demand
asynchronous turn isolation.
Data Propagation Flow
[Evaluation Scope / RawViaTerminal]
│
├─► via(nodeA) ──► Registers DAG edge & returns valid data payload A
├─► via(nodeB) ──► Registers DAG edge & returns valid data payload B
│
└─► Returns computed result & sweeps obsolete edges (1-Pass Epoch Sweeping)
Key Invariants & Architectural Benefits
- Zero Tracking Stack Overhead: Dependency registration happens purely via explicit function calls without maintaining or unwinding global thread-local or zone-scoped context stacks.
- 1-Pass Dynamic Epoch Sweeping: Unused dependency edges from inactive conditional branches are swept immediately in a single pass at the end of the synchronous evaluation turn.
- On-Demand Asynchronous Turn Isolation: Synchronous evaluations reuse a single BloomVia
instance with zero heap allocations. When an evaluation returns a Future or Stream
(e.g.,
computed.future,computed.stream,switched), post-awaitand post-yieldvia(...)calls remain tracked for the latest active turn while superseded turns and deactivated scopes are isolated automatically. - AI Coding Agent Ground Truth: Explicit manifests prevent AI agents and static analysis tools from missing reactive edges or generating rogue, untracked property reads.
Warning (Anti-Pattern Prevention):
- Do NOT read reactive nodes untracked inside a derivation closure without
wrapping them in
via(...). - Do NOT escape or store the BloomVia instance in external fields, timers, or UI event callbacks outside the evaluation closure. While dependency tracking registrations (BloomVia.call, state, tether) are silently ignored after a synchronous evaluation completes or from a superseded asynchronous turn, control-flow methods (exit and exitIfStale when stale) and evaluating empty or error nodes throw an internal short-circuit sentinel. If invoked outside the framework's evaluation scope, no resolver is present to trap this sentinel, causing an uncaught Error.
BAD:
final price = blooming(100);
final quantity = blooming(2);
// [Anti-Pattern] Reading untracked directly without via() leaves node untracked
final badTotal = computed((via) {
return untracked(price.bloom) * untracked(quantity.bloom); // Untracked! Misses graph invalidations!
});
GOOD:
final price = blooming(100);
final quantity = blooming(2);
// [Recommended] Explicitly register dependencies through via()
final goodTotal = computed((via) {
return via(price.bloom) * via(quantity.bloom); // Dynamically tracked in LPDAG
});
Examples
final firstName = blooming('Jane');
final lastName = blooming('Doe');
final fullName = computed((via) {
return '${via(firstName.bloom)} ${via(lastName.bloom)}';
});
// Pattern matching on upstream node state without short-circuiting:
final status = computed((via) {
final state = via.state(firstName.bloom);
return switch (state.phase) {
BloomPhase.valid => 'User: ${state.data}',
BloomPhase.empty => 'No user',
BloomPhase.error => 'Error: ${state.error}',
};
});
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
call<
T> (Bloom< T> bloom) → T -
Scoped watch function that tracks
bloomas an upstream dependency and returns its underlying valid data payload of typeT. -
exit(
{Object? emptyReason}) → Never -
Short-circuits the current evaluation epoch and immediately transitions
this reactive derivation into an empty state with an optional
emptyReason. -
exitIfInactive(
{Object? emptyReason}) → void - Deprecated alias for exitIfStale.
-
exitIfStale(
{Object? emptyReason}) → void - Short-circuits the current asynchronous evaluation into an empty state if this turn has become stale (superseded by a subsequent mutation, deactivated mid-flight, or closed).
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
state<
T> (Bloom< T> bloom) → BloomState<T> -
Registers
bloomas an active dependency in the current evaluation epoch and returns its 3-phase BloomState container without short-circuiting. -
tether<
T extends Tether> (T tether) → T -
Tethers declarative
tetherto this tracking scope's lifecycle. -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited