PersistedSignal

A Signal whose value is persistently stored in a key-value database.

PersistedSignal allows application state (such as user preferences, theme options, authentication tokens, and drafts) to automatically survive application restarts without writing tedious boilerplate for manual loading and saving.

Concrete Subclasses#

For common primitive types, use the provided concrete classes:

• PersistedBoolSignal / PersistedNullableBoolSignal
• PersistedIntSignal / PersistedNullableIntSignal
• PersistedDoubleSignal / PersistedNullableDoubleSignal
• PersistedNumSignal / PersistedNullableNumSignal
• PersistedStringSignal / PersistedNullableStringSignal
• PersistedEnumSignal / PersistedNullableEnumSignal

Simple Usage Example#

// 1. Create or obtain a key-value store adapter (like standard in-memory)
final localStore = SignalsInMemoryKeyValueStore();

// 2. Create the persisted signal with a unique key
final darkModeSignal = PersistedBoolSignal(
  false, // Fallback initial value
  key: 'settings.dark_mode',
  store: localStore,
);

// 3. The value is automatically loaded asynchronously on instantiation.
// Mutating the value synchronously schedules an async save under the hood:
darkModeSignal.value = true; // Automatically persisted to store

Custom Serialization / Complex Objects#

To persist complex objects (e.g. custom classes), subclass PersistedSignal and override the decode and encode methods, or mixin PersistedSignalMixin on a custom Signal class.

class User {
  final String name;
  final int age;
  User(this.name, this.age);

  Map<String, dynamic> toJson() => {'name': name, 'age': age};
  factory User.fromJson(Map<String, dynamic> json) => User(json['name'], json['age']);
}

class PersistedUserSignal extends PersistedSignal<User> {
  PersistedUserSignal(
    super.internalValue, {
    required super.key,
    required super.store,
  });

  @override
  User decode(String value) => User.fromJson(jsonDecode(value));

  @override
  String encode(User value) => jsonEncode(value.toJson());
}

Constructors#

Properties#

SignalsKeyValueStore#

An abstract class defining the persistence adapter contract for PersistedSignal.

Implement this interface to bind PersistedSignal to your storage engine of choice, such as local files, SQLite, SharedPreferences, Hive, or indexedDB.

Example: Custom Shared Preferences Store (Flutter)#

import 'package:shared_preferences/shared_preferences.dart';
import 'package:signals/signals.dart';

class SharedPreferencesStore implements SignalsKeyValueStore {
  final SharedPreferences prefs;
  SharedPreferencesStore(this.prefs);

  @override
  Future<String?> getItem(String key) async {
    return prefs.getString(key);
  }

  @override
  Future<void> setItem(String key, String value) async {
    await prefs.setString(key, value);
  }

  @override
  Future<void> removeItem(String key) async {
    await prefs.remove(key);
  }
}

Properties#

Methods#

PersistedSignalMixin#

A mixin that adds local persistence capabilities to a standard Signal.

By mixing in PersistedSignalMixin on a Signal subclass, the signal will automatically retrieve its stored state on boot and save its state whenever .value is mutated.

Classes mixing in PersistedSignalMixin must implement:

• key: A unique identifier string for the key-value database.
• store: An implementation of SignalsKeyValueStore.

Serialization Customization#

By default, the mixin uses standard JSON parsing (jsonDecode / jsonEncode). If your data type T is not natively supported by JSON, override:

• decode to convert the raw string value back into type T.
• encode to serialize type T into a string.

Properties#

Methods#

SignalsInMemoryKeyValueStore#

An in-memory, volatile implementation of SignalsKeyValueStore.

This serves as a fallback engine and does not persist across restarts/reload.

Properties#

Methods#

PersistedNullableStringSignal#

A PersistedSignal that stores a nullable string value.

[!warning] An empty value is considered null

Constructors#

Methods#

PersistedNullableIntSignal#

A PersistedSignal that stores a nullable integer value.

Constructors#

Methods#

PersistedNullableNumSignal#

A PersistedSignal that stores a nullable numeric value.

Constructors#

Methods#

PersistedNullableBoolSignal#

A PersistedSignal that stores a nullable string value.

Constructors#

Methods#

PersistedNullableDoubleSignal#

A PersistedSignal that stores a nullable double value.

Constructors#

Methods#

PersistedNullableEnumSignal#

A PersistedSignal that stores a nullable enum value.

Constructors#

Properties#

Methods#

PersistedIntSignal#

A PersistedSignal that stores an integer value.

Constructors#

Methods#

PersistedBoolSignal#

A PersistedSignal that stores a boolean value.

Constructors#

Methods#

PersistedDoubleSignal#

A PersistedSignal that stores an double value.

Constructors#

Methods#

PersistedNumSignal#

A PersistedSignal that stores a numeric value.

Constructors#

Methods#

PersistedStringSignal#

A PersistedSignal that stores a string value.

Constructors#

Methods#

PersistedEnumSignal#

A PersistedSignal that stores an enum value.

Constructors#

Properties#

Methods#

PersistedSignalOptions#

Configuration options for a PersistedSignal.

Constructors#

Methods#