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

  1. Zero Tracking Stack Overhead: Dependency registration happens purely via explicit function calls without maintaining or unwinding global thread-local or zone-scoped context stacks.
  2. 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.
  3. 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-await and post-yield via(...) calls remain tracked for the latest active turn while superseded turns and deactivated scopes are isolated automatically.
  4. 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 bloom as an upstream dependency and returns its underlying valid data payload of type T.
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 bloom as 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 tether to this tracking scope's lifecycle.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited