ApplyCommand typedef

ApplyCommand = ({ApplyArguments arguments, ApplyCompensation? compensation, Function function})

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:

  1. Permission Check: The framework verifies if the function is allowed to run (checking Cell.modifiable).
  2. Safety Gate: The "Integrity Gate" (TestCell.action) inspects the command to ensure it won't break any business rules.
  3. Execution: The function is run, or staged if a transaction is active.
  4. 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:

Implementation

typedef ApplyCommand = ({
  Function function,
  ApplyArguments arguments,
  ApplyCompensation? compensation
});