txApply static method
An Atomic Evolution Sequencer that executes multiple state mutations within a single coordinated transaction.
When to use:
- Multi-Cell Consistency: Updating multiple cells (e.g., a
balanceandledger) where partial updates would break graph integrity. - Performance Optimization: Batching high-frequency updates to prevent redundant downstream "churn" or multiple UI repaints.
- Cyclic Dependency Guards: Coordinating updates that might otherwise trigger race conditions if executed in isolation.
How it works:
txApply opens a "Transaction Frame." All updates performed within the
scope are staged. Only when the scope completes successfully are the
changes committed and propagated through the reactive graph. If an error
occurs, the staged pulses are discarded (rolled back).
Parameters:
options: Configuration including theactionclosure, securitycontext, conflictpolicy, and whether towaitfor stabilization.
Returns:
An ApplyTransactionScope result indicating success, timing, and forensic metadata for the committed batch.
See Also:
- Cell.state: The primary target for transactional updates.
- TransactionOptions: For advanced isolation and locking controls.
- Example: See
example/atomic_multi_update.dartfor a walkthrough of bank transfer logic and multi-node consistency.
AI Agent Guide
Layer: Cell — this is a graph node. Not an operator (Flow), not a book (Tissue).
When to use: The BRD says two retained facts move together or not at all, or an external act can fail after a local write — participants are Tissue books, with apply + compensate.
When NOT to use: one book with no undo (an ordinary Tissue write from Cell.observe); never wrap riskOf (policy is pure).
Live signature: Cell.txApply([TxApplyOptions options = const TxApplyOptions()]) → ApplyTransactionScope — pinned at cell: 1.1.0
Do NOT confuse with: Cell.transaction (coordinates ValueCell, not Tissue).
Guide: HowTo-Mitose-Cell.md §3.4 "Cell.txApply — the only atomic commit, on Tissue" (#cell-txapply)
Example: example/atomic_multi_update.dart
Cross-layer: the books written inside the commands are cell_tissue collections.
Minimal compilable example
final counter = Cell.state<int>(initial: 0);
final tx = Cell.txApply();
await tx.execute(participants: [counter.cell], body: (scope) {
counter.update(5); // staged — committed when execute completes
});
print(counter.cell.value);
Implementation
static ApplyTransactionScope txApply([
TxApplyOptions options = const TxApplyOptions(),
]) =>
_txApply(options);