ChangeStackSignal

A reactive Signal that records its history of values, allowing undo and redo operations.

ChangeStackSignal stores successive values of the signal in a double-ended queue. This allows you to revert back to previous values using undo and re-apply undone values using redo. You can also specify an optional limit parameter to cap the history queue size.

If you only need access to the initial and immediate previous values of a signal (without a full history stack or undo/redo mechanisms), use the lightweight TrackedSignalMixin instead.

Example Usage#

import 'package:signals/signals.dart';

void main() {
  final counter = ChangeStackSignal<int>(0, limit: 5);

  effect(() {
    print('Counter: ${counter.value}');
  }); // Prints: "Counter: 0"

  counter.value = 1; // Prints: "Counter: 1"
  counter.value = 2; // Prints: "Counter: 2"

  print('Can Undo: ${counter.canUndo}'); // Prints: "Can Undo: true"

  // Perform undo operation (automatically triggers reactive updates)
  counter.undo(); // Prints: "Counter: 1"
  counter.undo(); // Prints: "Counter: 0"

  // Perform redo operation
  counter.redo(); // Prints: "Counter: 1"
}

This class works best with values that are immutable or copied when updated. If you mutate an object in-place directly without assigning a new value using the .value setter or set(...), the history queue will store references to the same mutated object, and undo/redo operations will not reflect changes correctly.

Constructors#

View Constructors

`ChangeStackSignal(super.value, {int? limit, ChangeSignalOptions? options, @Deprecated('Use options: ChangeSignalOptions(autoDispose: ...) instead') bool? autoDispose, @Deprecated('Use options: ChangeSignalOptions(name: ...) instead') String? debugLabel})`

Creates a ChangeStackSignal initialized with the provided value.

changeStack#

Creates a ChangeStackSignal initialized with the provided value.

This is a convenience helper function for creating reactive undo/redo history signals. You can pass a limit to restrict the maximum history stack size.

import 'package:signals/signals.dart';

final s = changeStack(0, limit: 10);
s.value = 1;
s.undo(); // Returns to 0