feat: HydratedBloc migration API

[erickzanardo]

Description

Right now, if the developer wants to migrate the data schema of a hydrated bloc, they need to implement it manually themselves in the fromJson method, hydrated blocs does not offer any "out of the box" or opinionated approach for such thing.

Desired Solution

It would be great if HydratedBloc/Cubit had an out of the box approach for such thing, that would ensure a standard across projects and would also make it easier for developers to implement migrations.

This is the API I have thought of:

Version

In the bloc cubit, the developer could override a getter method that would return a version number of the current implementation of the fromJson/toJson methods on the bloc:

class MyHydratedBloc extends HydratedBloc<Events, State> {
  // omitted

  @override
  int get version => 1;
}

By default this method would return 0;

Migrations getter

The developer would be able to override another getter called migrations, which would return a map for version numbers and migration, something like:

class MyHydratedBloc extends HydratedBloc<Events, State> {
  // omitted

  @override
  int get version => 1;

  @override
  Map<int, HydrationMigration> get migrations => {
    1: HydrationMigration(
       migrate: (data) {
         return { 'new_filed': data['old_field'] };
       },
     ),
  }
}

Alternatives Considered

An alternative in case such API would not be something that would be wanted to be included in the package, could be writing some docs with an "official suggestion" on how people could achieve that.

Additional Context

I would be happy to work on a PR for this if agreed on moving forward

[mrverdant13]

As a more flexible option, it would be great to have a migrate method to be overridden and that can access the old and new version.

class MyHydratedBloc extends HydratedBloc<Events, State> {
  // Other members...

  @override
  int get version => 1;

  @override
  Map<String, dynamic> migrate({
    required Map<String, dynamic> data,
    required int newVersion,
    int? previousVersion, // `null` on first run
  }) {
    // Perform migration logic and return resolved JSON representation of the state
  }
}