streaming_shared_preferences 1.0.0-dev-8

A reactive key-value store for Flutter projects, built on top of shared_preferences.

streaming_shared_preferences

(collecting feedback to get this to a 1.0 release)

A reactive key-value store for Flutter projects.

It wraps shared_preferences with a reactive Stream based layer, allowing you to listen and react to changes in the underlying values.

Getting started

To get a hold of StreamingSharedPreferences, await on instance:

import 'package:streaming_shared_preferences/streaming_shared_preferences.dart';

...
final preferences = await StreamingSharedPreferences.instance;

The public API follows the same naming convention as shared_preferences does, but with a little twist - every getter returns a Preference object, which is a special type of Stream.

Quick overview of the API surface

Here's plain Dart example on how you would print a value to console every time a counter integer changes:

// Get a reference to the counter Preference, and provide a default value 
// of 0 in case it is null.
Preference<int> counter = preferences.getInt('counter', defaultValue: 0);

// "counter" is a Stream<int> - it can do anything a Stream<int> can.
// We're just going to listen to it and print the value to console.
counter.listen((value) {
  print(value);
});

// Somewhere else in your code, update the value.
counter.setValue(1);

We could also call preferences.setInt('counter', 1), but this is more convenient. Since a Preference knows how to set its own value, there's no need to provide a key.

Assuming that there's no previously stored value for counter, the above example will print 0, 1, 2 and 3 to the console.

Connecting it to Flutter widgets

The recommended way is to use the PreferenceBuilder widget. If you have only one Preference in your app, it might make sense to create and listen to a Preference inline:

class MyCounterWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    /// PreferenceBuilder is like StreamBuilder, but with less boilerplate.
    /// We don't have to provide `initialData` as it can be fetched synchronously
    /// from the provided Preference. There's also no initial flicker or needless rebuilds.
    ///
    /// If you want, you could use a StreamBuilder too.
    return PreferenceBuilder<int>(
      preferences.getInt('counter', defaultValue: 0),
      builder: (BuildContext context, int counter) {
        return Text('Button pressed $counter times!');
      }
    );
  }
}

Use a wrapper class when having multiple preferences

If you have multiple preferences, the recommended approach is to create a class that holds all your Preference objects in a single place:

/// A class that holds [Preference] objects for the common values that you want
/// to store in your app. This is *not* necessarily needed, but it makes your
/// code more neat and fool-proof.
class MyAppSettings {
  MyAppSettings(StreamingSharedPreferences preferences)
      : counter = preferences.getInt('counter', defaultValue: 0),
        nickname = preferences.getString('nickname', defaultValue: '');

  final Preference<int> counter;
  final Preference<String> nickname;
}

In our app entrypoint, we obtain an instance to StreamingSharedPreferences once and pass that to our settings class. Now we can pass MyAppSettings down to the widgets that use it:

Future<void> main() async {
  /// Obtain instance to streaming shared preferences, create MyAppSettings, and
  /// once that's done, run the app.
  final preferences = await StreamingSharedPreferences.instance;
  final settings = MyAppSettings(preferences);
  
  runApp(MyApp(settings));
}

This makes the calling code become quite neat:

class MyCounterWidget extends StatelessWidget {
  MyCounterWidget(this.settings);
  final MyAppSettings settings;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        PreferenceBuilder<String>(
          settings.nickname,
          builder: (context, nickname) => Text('Hey $nickname!'),
        ),
        PreferenceBuilder<int>(
          settings.counter,
          builder: (context, counter) => Text('You have pushed the button $counter times!'),
        ),
        FloatingActionButton(
          onPressed: () {
            /// To obtain the current value synchronously, we can call ".getValue()".
            final currentValue = settings.counter.getValue();

            /// To update the value, we can call ".setValue()" - no need to provide a key!
            /// Alternatively, we could just call "preferences.setInt('counter', currentValue + 1)".
            settings.counter.setValue(currentValue + 1);
          },
          child: Icon(Icons.add),
        ),
      ],
    );
  }
}

You can see a full working example of this in the example project.

When your widget hierarchy becomes deep enough, you would want to pass MyAppSettings around with an InheritedWidget instead.

Storing custom types with JsonAdapter

The entire library is built to support storing custom data types easily with a PreferenceAdapter. In fact, every built-in type has its own PreferenceAdapter - so technically, every type is actually a custom value!

For most cases, there's a convenience adapter that handles common pitfalls when storing and retrieving custom values called JsonAdapter. It helps you to store your values in JSON and it also saves you from duplicating if (value == null) return null for your custom adapters.

For example, if we have a class called SampleObject:

class SampleObject {
  SampleObject(this.isAwesome);
  final bool isAwesome;

  SampleObject.fromJson(Map<String, dynamic> json) :
    isAwesome = json['isAwesome'];

  Map<String, dynamic> toJson() => { 'isAwesome': isAwesome };
}

As seen from the above example, SampleObject implements both fromJson and toJson.

When the toJson method is present, JsonAdapter will call toJson automatically. For reviving, you need to provide a deserializer that calls fromJson manually:

final sampleObject = preferences.getCustomValue<SampleObject>(
  'my-key',
  defaultValue: SampleObject.empty(),
  adapter: JsonAdapter(
    deserializer: (value) => SampleObject.fromJson(value),
  ),
);

Depending on your use case, you need to provided a non-null SampleObject.empty() that represents a sane default for your custom type when it's not there just yet.

Using JsonAdapter with built_value

You can do custom serialization logic before JSON encoding the object by providing a serializer. Similarly, you can use deserializer to map the decoded JSON map into any object you want.

For example, if the previous SampleObject didn't have toJson and fromJson methods, but was a built_value model instead:

final sampleObject = preferences.getCustomValue<SampleObject>(
  'my-key',
  defaultValue: SampleObject.empty(),
  adapter: JsonAdapter(
    serializer: (value) => serializers.serialize(value),
    deserializer: (value) => serializers.deserialize(value),
  ),
);

"But what about muh abstraction!"

If you're all about the clean architecture and don't want to pollute your domain layer with Preference objects from a third-party library by some random internet stranger, all the power to you.

Here's one way to make Uncle Bob proud.

/// The contract for persistent values in your app that can be shared
/// to your pure business logic classes
abstract class MyAppSettings {
  Stream<int> getCounter();
  void setCounter(int value);
}

class MyHomePageBloc {
  MyHomePageBloc(this.settings);
  final MyAppSettings settings;

  // Do something with "getCounter()" and "setCounter()" along with 
  // whatever your business use case needs
}

No StreamingSharedPreferences specifics went in there. If for some reason you want to switch into some other library (or get rid of this library altogether), you can do so without modifying your business logic.

Here's how the implementation based on StreamingSharedPreferences would look like:

/// One implementation of MyAppSettings backed by StreamingSharedPreferences
class MyStreamingSharedPreferencesSettings implements MyAppSettings {
  MyStreamingSharedPreferences(StreamingSharedPreferences preferences)
      : counter = preferences.getInt('counter', defaultValue: 0);

  final Preference<int> _counter;

  // Preference<int> is a Stream<int>, so we can just return it
  @override
  Stream<int> getCounter() => _counter;

  // Preference exposes a handy "setValue()" method to update the value
  @override
  void setCounter(int value) => _counter.setValue(value);
}

Not too bad, is it? It's a good thing Preference<int> is also a Stream<int> and that there's a handy setter function for every preference.