ApplyCommand typedef
A complete request to perform an action or change state within a cell.
ApplyCommand is a lightweight container (a record) that holds everything needed to execute a task: the function to run, the data to pass to it, and an optional plan to undo the change if needed.
In this framework, you don't just "call a method." Instead, you create a command and submit it. This allows the framework to check permissions, validate data, and keep a perfect log of every change.
Why it is used
- Predictable Changes: By grouping the function and its arguments into one object, the framework can inspect the request before it happens.
- Audit Trail: Every command generates a "receipt," allowing you to see exactly who did what and when.
- Reversibility: Because the command can carry "compensation" logic, it provides a built-in way to roll back changes if an error occurs.
The Command Journey
When a command is submitted via Cell.apply, it follows a strict path:
- Permission Check: The framework verifies if the function is allowed to run (checking Cell.modifiable).
- Safety Gate: The "Integrity Gate" (TestCell.action) inspects the command to ensure it won't break any business rules.
- Execution: The function is run, or staged if a transaction is active.
- Receipt: An ApplyOutcome is returned, containing a detailed history of the event.
Technical Details
- Lightweight: As a Dart record, it is very memory-efficient, which is important when processing thousands of signals in a complex graph.
- Atomic: It ensures the function and its "undo" logic stay together, preventing situations where you change state but forget how to revert it.
See also:
- Cell.apply — The gateway used to submit these commands.
- ApplyArguments — The data payload carried by this command.
- ApplyCompensation — The instructions for undoing this command.
Implementation
typedef ApplyCommand = ({
Function function,
ApplyArguments arguments,
ApplyCompensation? compensation
});