PropagationStrategy enum

Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.

The PropagationStrategy governs the temporal and behavioral characteristics of how a stimulus (a Pulse) travels from a source Cell through its Synapses to downstream observers. By selecting a strategy, developers can optimise for latency, throughput, or stability, essentially defining the "metabolic rate" of specific branches in the reactive graph.

When to use

  • You typically set a strategy via a PropagationPolicy when creating synapses:
    final synapses = Synapses(
      policy: PropagationPolicy(
        strategy: PropagationStrategy.debounced,
        debounceTime: Duration(milliseconds: 300),
      ),
    );
    
    Choose the strategy that matches your use case – most common are immediate (default), debounced (for user input), and throttled (for rate‑limiting).
  • immediate: For critical state updates that must be synchronous.
  • async: To break deep recursion or offload to the event loop.
  • debounced: For search‑as‑you‑type, where only the final value matters.
  • throttled: For rate‑limiting high‑frequency events (e.g., scroll).
  • batched: For aggregating multiple updates into one (e.g., logging).
  • audit: To get the latest value at a fixed interval.
  • debounceLeading: To respond immediately to the first event, then wait.
  • persistent: To replay the last state to new observers.

How it works

  • The strategy is applied at the egress point – when a pulse is about to be broadcast to observers.
  • The policy holds the strategy and any timing parameters.
  • The synapses implementation switches on the strategy to determine how to buffer, delay, or batch outgoing pulses.
  • Each strategy has a specific behaviour; see the individual enum values for details.
final searchSynapses = Synapses<String, Cell>(
  policy: PropagationPolicy(
    strategy: PropagationStrategy.debounced,
    debounceTime: Duration(milliseconds: 300),
  ),
);

See also:

Inheritance
Available extensions

Values

immediate → const PropagationStrategy

The Default Synchronous strategy. Pulses are delivered immediately and recursively within the current execution pulse.

  • Behavior: When a cell is triggered, it immediately invokes the receptors of all linked cells on the same stack frame.
  • Use Case: Ideal for critical state logic, validation rules, and scenarios where "Tearing" (inconsistent state between related nodes) must be strictly avoided.
  • Trade-off: High-frequency updates can lead to UI jank or temporary blocking of the event loop if the downstream graph is deep.
async → const PropagationStrategy

The Microtask Deferral strategy. Pulses are scheduled to be broadcast on the next turn of the event loop.

  • Behavior: Uses Future or scheduleMicrotask to decouple the source trigger from the observer execution.
  • Use Case: Beneficial for breaking up long execution chains and ensuring the current function returns before downstream side effects begin.
  • Trade-off: Introduces a small amount of latency and breaks immediate synchronous execution flow.
batched → const PropagationStrategy

The Accumulative Processing strategy. Multiple signals are collected into a buffer and delivered as a single unit.

  • Behavior: Pulses are held in a buffer until a specific batchSize is reached or a time window expires. They are then delivered as a single Pulse containing a collection of payloads.
  • Use Case: High-throughput scenarios like logging, bulk database writes, or multi-item UI updates where processing individuals would be inefficient.
  • Trade-off: Increased memory overhead for the buffer and delayed delivery for the first items in the batch.
buffered → const PropagationStrategy

The Temporal Aggregation strategy for lossless signal delivery.

  • Behavior: Pulses are accumulated in an internal queue during a deterministic time window. Unlike throttled or debounced, no intermediate signals are discarded. Once the throttleTime expires, all captured pulses are broadcast as a single composite event.
  • Use Case: Ideal for high-density telemetry, audit trails, and I/O-heavy operations (like database persistence or network logging) where preserving every event is critical, but processing them individually is inefficient.
  • Trade-off: Introduces a delivery delay for all signals in the buffer equal to the remaining duration of the current temporal cycle, and increases memory pressure proportional to the burst volume.
  • Memory: Requires temporary heap storage for the accumulated pulses until the flush occurs.
debounced → const PropagationStrategy

The Trailing Edge strategy. Delivery is delayed until a specified period of "silence" has passed.

  • Behavior: Each new pulse resets a debounced timer. The pulse is only broadcast if no new signals are received within that window.
  • Use Case: Search-as-you-type inputs, window resizing, or any scenario where only the final state after a burst of activity is relevant.
  • Trade-off: Pulses that arrive during the burst are discarded; only the last one survives.
throttled → const PropagationStrategy

The Fixed Frequency strategy. Ensures signals are delivered at a controlled, maximum rate.

  • Behavior: The first pulse is delivered immediately, and a throttled timer starts. Subsequent signals during this window are ignored until the timer expires.
  • Use Case: Limiting expensive operations like scroll event listeners, API rate-limiting, or physical hardware sensors that emit more data than the consumer needs.
  • Trade-off: Intermediate data points between throttle ticks are lost, providing a "sampled" view of the state.
audit → const PropagationStrategy

The Trailing-Edge Sampling strategy. Ensures the latest state within a periodic window is delivered.

  • Behavior: Similar to throttled, but instead of delivering the first pulse of a window, it delivers the most recent pulse received when the throttleTime expires.
  • Use Case: Real-time dashboards or telemetry where you need the freshest data point at a fixed frequency, without the "silence" requirement of debounced.
  • Trade-off: Introduces a constant latency equal to the throttleTime.
debounceLeading → const PropagationStrategy

The Leading-Edge Debounce strategy. Delivers the first signal and silences subsequent signals during the window.

  • Behavior: High-responsiveness. Delivers the first pulse immediately, then ignores all others until the throttleTime silence window is met.
  • Use Case: Button debouncing where the user expects immediate UI feedback, but the backend must be protected from double-clicks.
persistent → const PropagationStrategy

The State-Preserving Relink strategy. Ensures newly linked observers receive the last known state.

  • Behavior: When a new Cell is linked, it automatically receives the most recent Pulse emitted by the source.
  • Use Case: Late-binding UI components or dynamic observers that need to "catch up" to the current system state.

Properties

hashCode → int
The hash code for this object.
no setterinherited
index → int
A numeric identifier for the enumerated value.
no setterinherited
name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

values → const List<PropagationStrategy>
A constant List of the values in this enum, in order of their declaration.