batch top-level constant

BatchFunctor const batch

Top-level transactional batch functor.

Executes the given action callback within a transactional batch scope, coalescing downstream terminal notifications until the outermost batch scope completes.

Mutations occurring inside the batch propagate dirty signals eagerly to preserve Read-Your-Own-Writes (RYOW) integrity for derived computations, while terminal invalidations (effects, listeners, UI rebuilds) are deferred and flushed atomically as a single batch when the outermost batch scope completes.

System Architectural Flow

                    batch(() {
                      sourceA.data = 10; ──► Push-Dirty Phase 1 (Eager)
                      sourceB.data = 20; ──► Push-Dirty Phase 1 (Eager)
                    })
                            │
                            ▼ (Outer batch scope exits)
             [Coalesced Phase 2 Notification Wave]
                            │
         ┌──────────────────┴──────────────────┐
         ▼                                     ▼
  Terminal Listener A                   Terminal Listener B
  (Flushed once)                        (Flushed once)

Architectural Benefits

1. Glitch-Free Atomicity: Intermediate inconsistent states are never dispatched to terminals.
2. Notification Coalescing: Reduces redundant microtask scheduling and UI layout passes.
3. Read-Your-Own-Writes (RYOW): In-scope evaluations immediately reflect local mutations.

See BatchFunctor.call for complete parameter specifications, execution contracts, and anti-pattern prevention.

Examples

final counter = blooming(0);
final text = blooming('hello');

batch(() {
  counter.data++;
  text.data = 'world';
}); // All downstream terminal listeners fire once here.

Implementation

const batch = BatchFunctor._();