An extension to the bloc state management library which automatically persists and restores bloc states.

Usage #

1. Use HydratedBlocDelegate

void main() async {
  BlocSupervisor.delegate = await HydratedBlocDelegate.build();
  runApp(App());
}

2. Extend HydratedBloc and override initialState, fromJson and toJson methods

class CounterBloc extends HydratedBloc<CounterEvent, CounterState> {
  // Use previously cached initialState if it's available
  @override
  CounterState get initialState {
    return super.initialState ?? CounterState(0);
  }

  // Called when trying to read cached state from storage.
  // Be sure to handle any exceptions that can occur and return null
  // to indicate that there is no cached data.
  @override
  CounterState fromJson(Map<String, dynamic> source) {
    try {
      return CounterState(source['value'] as int);
    } catch (_) {
      return null;
    }
  }

  // Called on each state change (transition)
  // If it returns null, then no cache updates will occur.
  // Otherwise, the returned value will be cached.
  @override
  Map<String, int> toJson(CounterState state) {
    try {
      return { 'value': state.value };
    } catch (_) {
      return null;
    }
  }

  @override
  Stream<CounterState> mapEventToState(CounterEvent event) async* {
    switch (event) {
      case CounterEvent.decrement:
        yield CounterState(currentState.value - 1);
        break;
      case CounterEvent.increment:
        yield CounterState(currentState.value + 1);
        break;
    }
  }
}

enum CounterEvent { increment, decrement }

class CounterState {
  int value;

  CounterState(this.value);
}

Now our CounterBloc is a HydratedBloc and will automatically persist its state. We can increment the counter value, hot restart, kill the app, etc... and our CounterBloc will always retain its state.

How it works #

Overview #

hydrated_bloc exports a HydratedStorage interface which means it can work with any storage provider. Out of the box, it comes with its own implementation: HydratedBlocStorage.

HydratedBlocStorage is built on top of path_provider for a platform-agnostic storage layer. The out-of-the-box storage implementation reads/writes to file using the toJson/fromJson methods on HydratedBloc and should perform very well for most use-cases (performance reports coming soon).

Considerations #

All data is written to temporary storage which means it can be wiped by the operating system at any point in time. As a result, hydrated_bloc is not intended to be used as a persistent database and should be viewed as a cache instead.

In addition, while the HydratedBlocStorage client doesn't automatically encrypt/decrypt the data, it is fairly straightforward to implement a custom HydratedStorage client which does support encryption.