feat(bloc)!: BlocOverrides API

[felangel]

Status

READY

Breaking Changes

YES

Description

The current API used to override the default BlocObserver and EventTransformer is:

void main() {
  Bloc.observer = CustomBlocObserver();
  Bloc.transformer = customEventTransformer();
  
  // ...
}

This approach relies on a global singleton for both the BlocObserver and EventTransformer. As a result, it's not possible to:

• Have multiple BlocObserver or EventTransformer implementations scoped to different parts of the application
• Have BlocObserver or EventTransformer overrides be scoped to a package
  • Suppose a package that depends on package:bloc registers its own BlocObserver, any consumer of the package will either have to overwrite the package's BlocObserver or report to the package's BlocObserver.

It's also more difficult to test because of the shared, global state across tests.

This pull request introduces a BlocOverrides class which allows developers to override BlocObserver and/or EventTransformer for a specific Zone rather than relying on a global, mutable singleton.

void main() {
  BlocOverrides.runZoned(
    () {
      // ...
    },
    blocObserver: CustomBlocObserver(),
    eventTransformer: customEventTransformer(),
  );
}

Bloc instances will use the BlocObserver and/or EventTransformer for the current Zone via BlocOverrides.current. If there are no BlocOverrides for the zone, they will use the existing internal defaults (base BlocObserver and concurrent EventTransformer -- no change in terms of behavior/functionality).

As previously mentioned, this would allow each zone to function independently with its own BlocOverrides and BlocOverrides are immutable meaning the BlocOverrides specified when the zone is created cannot be modified.

BlocOverrides.runZoned(
  () {
    // BlocObserverA and eventTransformerA
    final overrides = BlocOverrides.current;
      
    // Blocs in this zone report to BlocObserverA
    // and use eventTransformerA as the default transformer.
    // ...

    // Later...
    BlocOverrides.runZoned(
      () {
        // BlocObserverB and eventTransformerB
        final overrides = BlocOverrides.current;
    
        // Blocs in this zone report to BlocObserverB
        // and use eventTransformerB as the default transformer.
        // ...
      },
      blocObserver: BlocObserverB(),
      eventTransformer: eventTransformerB(),
    );
  },
  blocObserver: BlocObserverA(),
  eventTransformer: eventTransformerA(),
);

This pull request removes the static, mutable Bloc.observer and Bloc.transformer APIs which is a breaking change. BlocObserver and EventTransformer overrides will need to be specified via BlocOverrides.runZoned instead as described above.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🛠️ Bug fix (non-breaking change which fixes an issue)
• ❌ Breaking change (fix or feature that would cause existing functionality to change)
• 🧹 Code refactor
• ✅ Build configuration change
• 📝 Documentation
• 🗑️ Chore

[codecov]

Codecov Report

Merging #2932 (eef7b60) into feat/v8.0.0 (a08e238) will not change coverage.
The diff coverage is 100.00%.

@@              Coverage Diff              @@
##           feat/v8.0.0     #2932   +/-   ##
=============================================
  Coverage       100.00%   100.00%           
=============================================
  Files               25        25           
  Lines              671       691   +20     
=============================================
+ Hits               671       691   +20     

Impacted Files	Coverage Δ
packages/bloc/lib/src/bloc_observer.dart	100.00% <ø> (ø)
packages/bloc/lib/src/bloc.dart	100.00% <100.00%> (ø)
packages/bloc_test/lib/src/bloc_test.dart	100.00% <100.00%> (ø)
packages/replay_bloc/lib/src/replay_bloc.dart	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a08e238...eef7b60. Read the comment docs.

[lhmzhou]

LGTM