feat(bloc)!: v8.0.0

.github/workflows/hydrated_bloc.yaml

@@ -33,7 +33,7 @@ jobs:
         run: flutter analyze lib test example
 
       - name: Run tests
-        run: flutter test -j 1 --no-pub --coverage --test-randomize-ordering-seed random
+        run: flutter test --no-pub --coverage --test-randomize-ordering-seed random
 
       - name: Check Code Coverage
         uses: VeryGoodOpenSource/[email protected]

README.md

@@ -43,7 +43,10 @@ Our top sponsors are shown below! [[Become a Sponsor](https://github.com/sponsor
             </td>
             <td align="center">
                 <a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank"><img width="250px" src="https://stream-blog.s3.amazonaws.com/blog/wp-content/uploads/fc148f0fc75d02841d017bb36e14e388/Stream-logo-with-background-.png"/></a><br/><span><a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank">Try the Flutter Chat Tutorial &nbsp💬</a></span>
-            </td>            
+            </td>
+            <td align="center">
+                <a href="https://www.miquido.com/flutter-development-company/?utm_source=github&utm_medium=sponsorship&utm_campaign=bloc-silver-tier&utm_term=flutter-development-company&utm_content=miquido-logo"><img src="https://raw.githubusercontent.com/felangel/bloc/master/docs/assets/miquido_logo.png" width="225"/></a>
+            </td>
         </tr>
     </tbody>
 </table>

docs/_coverpage.md

@@ -22,17 +22,16 @@
     <a href="#/gettingstarted">Get Started</a>    
 </p>
 
-<p align="center" style="margin-top: 2em; margin-bottom: 0"><b>Sponsored with 💖 by</b></p>
+<p align="center" style="margin-top: 2em; margin-bottom: 1em"><b>Sponsored with 💖 by</b></p>
 
-<table align="center">
-    <tbody>
-        <tr>
-            <td align="center" style="padding-right: 0.5em">
-                <a href="https://verygood.ventures"><img src="https://raw.githubusercontent.com/felangel/bloc/master/docs/assets/vgv_logo_transparent.png" width="80"/></a>
-            </td>
-            <td align="center" style="padding-left: 0.5em">
-                <a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank"><img width="120" src="https://stream-blog-v2.imgix.net/blog/wp-content/uploads/bae8c920a484d1c49dbd148306aa1335/stream-bloc-flutter.png?auto=compress&fit=clip&w=120"/></a><br/><span><a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank">Try the Flutter Chat Tutorial &nbsp💬</a></span>
-            </td>
-        </tr>
-    </tbody>
-</table>
+<div id="cover-sponsors-grid">
+    <div>
+        <a href="https://verygood.ventures"><img src="https://raw.githubusercontent.com/felangel/bloc/master/docs/assets/vgv_logo_transparent.png" width="65"/></a>
+    </div>
+    <div>
+        <a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank"><img width="120" src="https://stream-blog-v2.imgix.net/blog/wp-content/uploads/bae8c920a484d1c49dbd148306aa1335/stream-bloc-flutter.png?auto=compress&fit=clip&w=120"/></a><br/><span><a href="https://getstream.io/chat/flutter/tutorial/?utm_source=https://github.com/felangel/bloc&utm_medium=github&utm_content=developer&utm_term=flutter" target="_blank">Try the Flutter Chat Tutorial &nbsp💬</a></span>
+    </div>
+    <div>
+        <a href="https://www.miquido.com/flutter-development-company/?utm_source=github&utm_medium=sponsorship&utm_campaign=bloc-silver-tier&utm_term=flutter-development-company&utm_content=miquido-logo"><img src="https://raw.githubusercontent.com/felangel/bloc/master/docs/assets/miquido_logo_transparent.png" width="225"/></a>
+    </div>
+</div>

docs/_snippets/core_concepts/simple_bloc_observer_on_change_usage.dart.md

@@ -1,8 +1,12 @@
 ```dart
 void main() {
-  Bloc.observer = SimpleBlocObserver();
-  CounterCubit()
-    ..increment()
-    ..close();
+  BlocOverrides.runZoned(
+    () {
+      CounterCubit()
+        ..increment()
+        ..close();
+    },
+    blocObserver: SimpleBlocObserver(),
+  );
 }
-```
+```

docs/_snippets/core_concepts/simple_bloc_observer_on_transition_usage.dart.md

@@ -1,8 +1,12 @@
 ```dart
 void main() {
-  Bloc.observer = SimpleBlocObserver();
-  CounterBloc()
-    ..add(Increment())
-    ..close();
+  BlocOverrides.runZoned(
+    () {
+      CounterBloc()
+        ..add(Increment())
+        ..close();
+    },
+    blocObserver: SimpleBlocObserver(),
+  );
 }
-```
+```

docs/assets/style.css

@@ -54,3 +54,15 @@ section.cover blockquote > .buttons > a:hover {
 #TOPBANNER p {
   padding: 1.25rem 0;
 }
+
+#cover-sponsors-grid {
+  display: grid;
+  grid-auto-rows: 1fr;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 0px 1em;
+  max-width: 600px;
+  justify-content: center;
+  align-items: center;
+  margin: 0 auto;
+  font-size: 0.8em;
+}

docs/migration.md

@@ -2,6 +2,243 @@
 
 ?> 💡 **Tip**: Please refer to the [release log](https://github.com/felangel/bloc/releases) for more information regarding what changed in each release.
 
+## v8.0.0
+
+### package:bloc
+
+#### ❗✨ Introduce new `BlocOverrides` API
+
+!> In bloc v8.0.0, `Bloc.observer` and `Bloc.transformer` were removed in favor of the `BlocOverrides` API.
+
+##### Rationale
+
+The previous API used to override the default `BlocObserver` and `EventTransformer` relied on a global singleton for both the `BlocObserver` and `EventTransformer`.
+
+As a result, it was 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
+  - If a package were to depend on `package:bloc` and registered its own `BlocObserver`, any consumer of the package would either have to overwrite the package's `BlocObserver` or report to the package's `BlocObserver`.
+
+It was also more difficult to test because of the shared global state across tests.
+
+Bloc v8.0.0 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.
+
+**v7.x.x**
+
+```dart
+void main() {
+  Bloc.observer = CustomBlocObserver();
+  Bloc.transformer = customEventTransformer();
+
+  // ...
+}
+```
+
+**v8.0.0**
+
+```dart
+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 (no change in behavior/functionality).
+
+This allows allow each `Zone` to function independently with its own `BlocOverrides`.
+
+```dart
+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(),
+);
+```
+
+#### ❗✨ Improve Error Handling and Reporting
+
+!> In bloc v8.0.0, `BlocUnhandledErrorException` is removed. In addition, any uncaught exceptions are always reported to `onError` and rethrown (regardless of debug or release mode). The `addError` API reports errors to `onError`, but does not treat reported errors as uncaught exceptions.
+
+##### Rationale
+
+The goal of these changes is:
+
+- make internal unhandled exceptions extremely obvious while still preserving bloc functionality
+- support `addError` without disrupting control flow
+
+Previously, error handling and reporting varied depending on whether the application was running in debug or release mode. In addition, errors reported via `addError` were treated as uncaught exceptions in debug mode which led to a poor developer experience when using the `addError` API (specifically when writing unit tests).
+
+In v8.0.0, `addError` can be safely used to report errors and `blocTest` can be used to verify that errors are reported. All errors are still reported to `onError`, however, only uncaught exceptions are rethrown (regardless of debug or release mode).
+
+#### ❗🧹 Make `BlocObserver` abstract
+
+!> In bloc v8.0.0, `BlocObserver` was converted into an `abstract` class which means an instance of `BlocObserver` cannot be instantiated.
+
+##### Rationale
+
+`BlocObserver` was intended to be an interface. Since the default API implementation are no-ops, `BlocObserver` is now an `abstract` class to clearly communicate that the class is meant to be extended and not directly instantiated.
+
+**v7.x.x**
+
+```dart
+void main() {
+  // It was possible to create an instance of the base class.
+  final observer = BlocObserver();
+}
+```
+
+**v8.0.0**
+
+```dart
+class MyBlocObserver extends BlocObserver {...}
+
+void main() {
+  // Cannot instantiate the base class.
+  final observer = BlocObserver(); // ERROR
+
+  // Extend `BlocObserver` instead.
+  final observer = MyBlocObserver(); // OK
+}
+```
+
+#### ❗✨ `add` throws `StateError` if Bloc is closed
+
+!> In bloc v8.0.0, calling `add` on a closed bloc will result in a `StateError`.
+
+##### Rationale
+
+Previously, it was possible to call `add` on a closed bloc and the internal error would get swallowed, making it difficult to debug why the added event was not being processed. In order to make this scenario more visible, in v8.0.0, calling `add` on a closed bloc will throw a `StateError` which will be reported as an uncaught exception and propagated to `onError`.
+
+#### ❗✨ `emit` throws `StateError` if Bloc is closed
+
+!> In bloc v8.0.0, calling `emit` within a closed bloc will result in a `StateError`.
+
+##### Rationale
+
+Previously, it was possible to call `emit` within a closed bloc and no state change would occur but there would also be no indication of what went wrong, making it difficult to debug. In order to make this scenario more visible, in v8.0.0, calling `emit` within a closed bloc will throw a `StateError` which will be reported as an uncaught exception and propagated to `onError`.
+
+#### ❗🧹 Remove Deprecated APIs
+
+!> In bloc v8.0.0, all previously deprecated APIs were removed.
+
+##### Summary
+
+- `mapEventToState` removed in favor of `on<Event>`
+- `transformEvents` removed in favor of `EventTransformer` API
+- `TransitionFunction` typedef removed in favor of `EventTransformer` API
+- `listen` removed in favor of `stream.listen`
+
+### package:bloc_test
+
+#### ✨ `MockBloc` and `MockCubit` no longer require `registerFallbackValue`
+
+!> In bloc_test v9.0.0, developers no longer need to explicitly call `registerFallbackValue` when using `MockBloc` or `MockCubit`.
+
+##### Summary
+
+`registerFallbackValue` is only needed when using the `any()` matcher from `package:mocktail` for a custom type. Previously, `registerFallbackValue` was needed for every `Event` and `State` when using `MockBloc` or `MockCubit`.
+
+**v8.x.x**
+
+```dart
+class FakeMyEvent extends Fake implements MyEvent {}
+class FakeMyState extends Fake implements MyState {}
+class MyMockBloc extends MockBloc<MyEvent, MyState> implements MyBloc {}
+
+void main() {
+  setUpAll(() {
+    registerFallbackValue(FakeMyEvent());
+    registerFallbackValue(FakeMyState());
+  });
+
+  // Tests...
+}
+```
+
+**v9.0.0**
+
+```dart
+class MyMockBloc extends MockBloc<MyEvent, MyState> implements MyBloc {}
+
+void main() {
+  // Tests...
+}
+```
+
+### package:hydrated_bloc
+
+#### ❗✨ Introduce new `HydratedBlocOverrides` API
+
+!> In hydrated_bloc v8.0.0, `HydratedBloc.storage` was removed in favor of the `HydratedBlocOverrides` API.
+
+##### Rationale
+
+Previously, a global singleton was used to override the `Storage` implementation.
+
+As a result, it was not possible to have multiple `Storage` implementations scoped to different parts of the application. It was also more difficult to test because of the shared global state across tests.
+
+`HydratedBloc` v8.0.0 introduces a `HydratedBlocOverrides` class which allows developers to override `Storage` for a specific `Zone` rather than relying on a global mutable singleton.
+
+**v7.x.x**
+
+```dart
+void main() async {
+  HydratedBloc.storage = await HydratedStorage.build(
+    storageDirectory: await getApplicationSupportDirectory(),
+  );
+
+  // ...
+}
+```
+
+**v8.0.0**
+
+```dart
+void main() {
+  final storage = await HydratedStorage.build(
+    storageDirectory: await getApplicationSupportDirectory(),
+  );
+
+  HydratedBlocOverrides.runZoned(
+    () {
+      // ...
+    },
+    storage: storage,
+  );
+}
+```
+
+`HydratedBloc` instances will use the `Storage` for the current `Zone` via `HydratedBlocOverrides.current`.
+
+This allows allow each `Zone` to function independently with its own `BlocOverrides`.
+
 ## v7.2.0
 
 ### package:bloc

examples/angular_counter/web/main.dart

@@ -23,6 +23,8 @@ class SimpleBlocObserver extends BlocObserver {
 }
 
 void main() {
-  Bloc.observer = SimpleBlocObserver();
-  runApp(ng.AppComponentNgFactory);
+  BlocOverrides.runZoned(
+    () => runApp(ng.AppComponentNgFactory),
+    blocObserver: SimpleBlocObserver(),
+  );
 }

examples/flutter_bloc_with_stream/test/ticker_page_test.dart

@@ -11,10 +11,6 @@ import 'package:mocktail/mocktail.dart';
 class MockTickerBloc extends MockBloc<TickerEvent, TickerState>
     implements TickerBloc {}
 
-class FakeTickerEvent extends Fake implements TickerEvent {}
-
-class FakeTickerState extends Fake implements TickerState {}
-
 extension on WidgetTester {
   Future<void> pumpTickerPage(TickerBloc tickerBloc) {
     return pumpWidget(
@@ -28,11 +24,6 @@ extension on WidgetTester {
 void main() {
   late TickerBloc tickerBloc;
 
-  setUpAll(() {
-    registerFallbackValue(FakeTickerEvent());
-    registerFallbackValue(FakeTickerState());
-  });
-
   setUp(() {
     tickerBloc = MockTickerBloc();
   });

examples/flutter_complex_list/lib/main.dart

@@ -1,11 +1,13 @@
 import 'package:bloc/bloc.dart';
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:flutter_complex_list/app.dart';
 import 'package:flutter_complex_list/repository.dart';
 import 'package:flutter_complex_list/simple_bloc_observer.dart';
 
 void main() {
-  Bloc.observer = SimpleBlocObserver();
-  runApp(App(repository: Repository()));
+  BlocOverrides.runZoned(
+    () => runApp(App(repository: Repository())),
+    blocObserver: SimpleBlocObserver(),
+  );
 }