deprecate: BlocOverrides API

[felangel]

Overview

The BlocOverrides API was introduced in v8.0.0 in an attempt to support scoping bloc-specific configurations such as BlocObserver, EventTransformer, and HydratedStorage. In pure Dart applications, the changes worked well; however, in Flutter applications the new API caused more problems than it solved.

The BlocOverrides API was inspired by similar APIs in Flutter/Dart:

• HttpOverrides
• IOOverrides

Problems

While it wasn't the primary reason for these changes, the BlocOverrides API introduced additional complexity for developers. In addition to increasing the amount of nesting and lines of code needed to achieve the same effect, the BlocOverrides API required developers to have a solid understanding of Zones in Dart. Zones are not a beginner-friendly concept and failure to understand how Zones work could lead to the introduction of bugs (such as uninitialized observers, transformers, storage instances).

For example, many developers would have something like:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  BlocOverrides.runZoned(...);
}

The above code, while appearing harmless, can actually lead to many difficult to track bugs. Whatever zone WidgetsFlutterBinding.ensureInitialized is initially called from will be the zone in which gesture events are handled (e.g. onTap, onPressed callbacks) due to GestureBinding.initInstances. This is just one of many issues caused by using zoneValues.

In addition, Flutter does many things behind the scenes which involve forking/manipulating Zones (especially when running tests) which can lead to unexpected behaviors (and in many cases behaviors that are outside the developer's control -- see issues below).

Due to the use of the runZoned, the transition to the BlocOverrides API led to the discovery of several bugs/limitations in Flutter (specifically around Widget and Integration Tests):

• runZoned with zoneValues unavailable during integration_test flutter/flutter#96939
• Flutter framework does not warn when ensureInitialized is called in a different zone than runApp flutter/flutter#94123
• runZoned with zoneValues lost after hot reload flutter/flutter#93676

which affected many developers using the bloc library:

• feat: BlocOverrides add support for runZonedGuarded #3394
• test: Missing example integration_test that works for HydratedBloc #3350
• docs: zone overrides documentation could mention how to deal with nested runZoned #3319

Decision

After many discussions with various members of the community (including folks from the Dart/Flutter teams), we've decided to deprecate the BlocOverrides API and reintroduce the previous APIs in order to provide a safe, beginner friendly API, eliminate the need to worry about the above issues. When using Zones, technically there's nothing stopping another package from overriding the Zone values provided or even creating a brand new Zone which does not inherit the previous zone specifications. By moving back to the previous API, we eliminate these potential pit-falls and end up with a safer, simpler API.

Next Steps

The BlocOverrides and HydratedBlocOverrides APIs will be deprecated, the previous Bloc.observer, Bloc.transformer, and HydratedBloc.storage APIs will be restored, and the deprecated APIs will be removed in the next major release.

Migration

Currently, in order to specify a custom BlocObserver or EventTransformer we use the BlocOverrides.runZoned API:

Before

void main() {
  BlocOverrides.runZoned(
    () {
      // Application code...
    },
    blocObserver: MyBlocObserver(),
    eventTransformer: myEventTransformer(),
  );
}

After these changes, you will be able to use the previous APIs (from v7.x.x) to specify a custom BlocObserver, EventTransformer, or HydratedStorage instance.

After

void main() {
  Bloc.observer = MyBlocObserver();
  Bloc.transformer = myEventTransformer(),
  // Application code...
}

[purplenoodlesoop]

Hi @felangel!

That's a good call, BlocOverrides did raise a lot of questions. I maintain an ecosystem-compatible BLoC alternative that uses the old API, and I have encountered similar complaints from users of my package.

To avoid breaking changes, I've implemented a system that can use both Zone injection and plain static variables – maybe you could use it as a reference to do something similar.

• Observer
• Injection config
• Injection location

[felangel]

The BlocOverrides API has been deprecated in bloc v8.1.0.

[bartekpacia]

Thank you very much @felangel!