async property

ModifiableAsync<Cell> get async

Provides a high-level, asynchronous interface for interacting with this Cell node.

This getter returns a ModifiableAsync wrapper, which serves as the primary architectural bridge between the synchronous reactive graph and Dart's asynchronous execution model (Futures and Streams).

The Temporal Bridge

While the core of a Cell is designed for synchronous, atomic transitions within the reactive topology, real-world applications frequently require non-blocking operations. The async handle allows for Hybrid Convergence, where imperative, time-delayed logic safely interacts with the cell's protected state.

When to use

  • UI Interaction: Dispatching commands from event handlers (e.g., onPressed) without blocking the main isolate.
  • Background Orchestration: Executing business logic that involves I/O or heavy computation while maintaining reactive integrity.
  • Serialized Transitions: When multiple mutations must be queued and executed in order, ensuring no race conditions occur during asynchronous gaps.

How it works

  1. Lock Orchestration: All operations performed via async (such as apply or read) are automatically scheduled through the cell's internal Lock. This guarantees atomicity even when calls originate from different asynchronous contexts.
  2. Future Wrapping: Standard methods like apply are mirrored here but return a Future, allowing the caller to await the result of the reactive transition.
  3. Capability Preservation: The async handle respects the underlying node's modifiable manifest and TestCell rules. If called on an unmodifiable deputy, the async mutation methods will still respect the restricted capability policy.

Example: Asynchronous Command Execution

void onDepositPressed(int amount) async {
  // The async handle allows awaiting the completion of the transition
  final success = await userBalanceCell.async.apply(
    (current) => current + amount
  );

  if (success != null) {
    print('Deposit processed successfully.');
  }
}

Returns:

A ModifiableAsync wrapper specialized for this Cell, providing a suite of asynchronous tools for command execution, state observation, and signal ingestion.

Implementation

ModifiableAsync<Cell> get async;