How Signals.dart Achieves Automatic Dependency Tracking in Flutter

Overview

Signals.dart is a Dart implementation of the Preact Signals model. It provides fine‑grained reactive primitives— signal, computed, and effect —that automatically track dependencies and update only the parts of the UI that depend on changed data.

Core Primitives

signal

: creates a mutable Signal object whose .value getter registers a dependency and whose setter increments a version number and notifies dependents. computed: a lazily evaluated signal that derives its value from one or more source signals. The value is recomputed only when any source version has changed. effect: registers a side‑effect function that runs immediately and re‑runs whenever any signal read during its execution changes.

Node Graph

All primitives are built on a double‑linked Node structure. Each Node stores:

A reference to its source ReadonlySignal ( _source).

Links to previous/next source nodes ( _prevSource, _nextSource).

A target consumer ( _target) and links to previous/next target nodes ( _prevTarget, _nextTarget).

A version number ( _version) used to decide whether a consumer needs to recompute.

When a computed or effect reads a signal’s .value, the current global evalContext (the running computed/effect) is added as a dependent node to that signal. When a signal’s setter runs, it increments its version and notifies all target nodes, which then decide whether to re‑run based on version changes.

Effect Implementation

On first run the effect’s callback is invoked immediately.

The effect’s execution sets evalContext = this (via an internal start function) so that any signal read registers the effect as a dependent.

When a signal changes, the effect is placed into a global batchedEffect list. After the batch finishes, endBatch iterates the list and runs each effect’s callback.

Computed Implementation

The computed getter calls internalRefresh, which:

Invokes needsToRecompute to compare stored source versions with current ones.

If any source version changed, recomputes the value, updates its own version, and returns the new value.

Because the computation runs only on .value access, computed provides automatic memoisation and avoids unnecessary work.

Flutter Integration

Signals.dart offers three main ways to use signals in Flutter:

SignalsMixin : a mixin for State classes that creates signals via createSignal and automatically registers an effect that calls setState when the signal changes.

class _CounterState extends State<Counter> with SignalsMixin {
  late final Signal<int> counter = createSignal(0);
  void _inc() => counter.value++;
  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('Counter')),
    body: Center(child: Text('$counter')),
    floatingActionButton: FloatingActionButton(
      onPressed: _inc,
      child: const Icon(Icons.add),
    ),
  );
}

Watch widget : a declarative widget that rebuilds when any accessed signal changes. Internally it creates a computed that returns the builder’s result, so the builder runs only when its dependencies update.

final counter = signal(0);
Watch.builder(builder: (context) => Text('$counter'));

SignalProvider : an InheritedWidget that can expose a signal down the widget tree. Because signals are context‑agnostic, this is optional for most use‑cases.

Lifecycle Management & Utilities

When using the low‑level effect(() { … }) API you must manually dispose the effect to avoid leaks. The mixin‑based createEffect registers the effect with the widget’s lifecycle, handling disposal automatically.

Two utility functions are provided: peek(): temporarily clears evalContext so a read does not create a dependency. batch(() { … }): temporarily disables the global batchedEffect list, allowing multiple signal updates to be processed as a single batch.

Performance Characteristics

Signals.dart achieves high‑granularity updates by:

Using a version number ( _version) on each node instead of storing full values, making change detection cheap.

Lazy evaluation of computed values, so expensive calculations run only when needed.

Batching effect executions to avoid redundant UI rebuilds.

Summary

Signals.dart implements a lightweight reactive system based on a double‑linked Node graph. Effect and Computed register themselves as the current evalContext, allowing signal getters to automatically add dependency edges. Signal setters increment a version number and notify dependent nodes, which recompute only when necessary. In Flutter, SignalsMixin, Watch, and SignalProvider expose these capabilities with minimal boilerplate, enabling automatic UI updates while keeping state management decoupled from the widget tree.