LogoSignals.dart
Copy Markdown
rodydavis/signals.dart ★9999⑂99

Type: ReadonlySignal

API reference and details for ReadonlySignal from signals.dart.

ReadonlySignal#

Kind: class  |  Package: package:preact_signals

Class: ReadonlySignal#

An interface for read-only signals.

A ReadonlySignal is a reactive container whose value can be read but not directly mutated. Under the hood, any Signal implements or can be cast/exposed as a ReadonlySignal. This is a core architectural pattern for encapsulating state: classes can modify state internally using a private mutable Signal, while exposing a public ReadonlySignal to consumers to enforce unidirectional data flow.

Whenever the underlying value changes, any active effect or computed signal that reads this signal's value will automatically be re-evaluated.

Example Usage#

import 'package:preact_signals/preact_signals.dart';

class CounterController {
  // Keep the mutable state private to the controller
  final _counter = signal(0);

  // Expose a public read-only signal to external consumers
  ReadonlySignal<int> get counter => _counter;

  void increment() {
    _counter.value++;
  }

  void decrement() {
    _counter.value--;
  }
}

void main() {
  final controller = CounterController();

  // React to updates from the read-only signal
  final dispose = effect(() {
    print("The current count is: ${controller.counter.value}");
  });

  // controller.counter.value = 10; // Error: Cannot mutate a ReadonlySignal!

  controller.increment(); // Prints: "The current count is: 1"
  controller.increment(); // Prints: "The current count is: 2"

  dispose();
}
Use [ReadonlySignal] to prevent consumers of your stores or controllers from modifying state bypassing the controller's methods. This ensures consistent, predictable, and traceable mutations throughout your application.

Members of ReadonlySignal#

Member Type Signature Description
globalId method dart int globalId Global ID of the signal
value method dart T value Compute the current value
name method dart String? name The name of the signal for debugging purposes.
watched method dart void Function()? watched Callback called when the signal goes from 0 to >=1 listeners.
unwatched method dart void Function()? unwatched Callback called when the signal goes from >=1 to 0 listeners.
toString method dart String toString()
toJson method dart dynamic toJson() Convert value to JSON
call method dart T call() Return the value when invoked
get method dart T get() Helper method to get the current value
peek method dart T peek() In the rare instance that you have an effect that should write to another signal based on the previous value, but you don't want the effect to be subscribed to that signal, you can read a signals's previous value via signal.peek() .
subscribe method dart void Function() subscribe(void Function(T value) fn) Subscribe to value changes with a dispose function

References#

The ReadonlySignal type is referenced and used in the following pages: