# state_notifier 0.7.2+1 ValueNotifier, but outside Flutter and with some extra perks ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir flutter pub add 'state_notifier:0.7.2+1' ``` Published: 2022-01-16T00:36:15.252312Z Expected archive SHA-256: 8fe42610f179b843b12371e40db58c9444f8757f8b69d181c97e50787caed289 Available in cache; verification: upstream_checksum ## Direct dependencies - meta: ^1.1.8 ## Package README (untrusted upstream documentation) [![pub package](https://img.shields.io/pub/v/state_notifier.svg)](https://pub.dartlang.org/packages/state_notifier) Welcome to **state_notifier**~ This package is a recommended solution for managing state when using [Provider] or [Riverpod]. Long story short, instead of extending [ChangeNotifier], extend [StateNotifier]: ```dart class City { City({required this.name, required this.population}); final String name; final int population; } class CityNotifier extends StateNotifier> { CityNotifier() : super(const []); void addCity(City newCity) { state = [ ...state, newCity, ]; } } ``` ## Motivation The purpose of [StateNotifier] is to be a simple solution to control state in an immutable manner. While [ChangeNotifier] is simple, through its mutable nature, it can be harder to maintain as it grows larger. By using immutable state, it becomes a lot simpler to: - compare previous and new state - implement undo-redo mechanism - debug the application state ## Good practices ### **DON'T** update the state of a StateNotifier outside the notifier While you could technically write: ```dart class Counter extends StateNotifier { Counter(): super(0); } final notifier = Counter(); notifier.state++; ``` That is considered anti-pattern (and your IDE should show a warning). Only the [StateNotifier] should modify its state. Instead, prefer using a method: ```dart class Counter extends StateNotifier { Counter(): super(0); void increment() => state++: } final notifier = Counter(); notifier.increment(); ``` The goal is to centralize all the logic that modifies a [StateNotifier] within the [StateNotifier] itself. ## FAQ ### Why are listeners called when the new state is == to the previous state? You may realize that a [StateNotifier] does not use `==` to verify that the state has changed before notifying for changes . This behavior is voluntary, for performance reasons. The reasoning is that `StateNotifier` is typically used with complex objects, which often override `==` to perform a deep comparison. But performing a deep comparison can be a costly operation, especially since it is common for the state to contain lists/maps. Similarly, for complex states, it is rare that when calling `notifier.state = newState`, the new and previous states are the same. As such, instead of using `==`, [StateNotifier] relies on `identical` to compare objects. This way, when using [StateNotifier] with simple states like `int`/enums, it will correctly filter identical states. At the same time, this preserves performance on complex states, at `identical` will not perform a deep object comparison. ### Using a custom notification filter logic You can override the method `updateShouldNotify(T old,T current)` of a `StateNotifier` to change the default behaviour, such as for: - using `==` instead of `identical` to filter updates, for deep state comparison - always return `true` to revert to older behaviors of `StateNotifier` ```dart @override bool updateShouldNotify(User old, User current) { /// only update the User content changes, even if using a different instance return old.name != current.name && old.age != current.age; } ``` ## Usage ### Integration with Freezed While entirely optional, it is recommended to use [StateNotifier] in combination with [Freezed]. [Freezed] is a code-generation package for data-classes in Dart, which automatically generates methods like `copyWith` and add support for union-types. A typical example would be using [Freezed] to handle data vs error vs loading states. With its union-types, it can lead to a significant improvement in maintainability as, it: - ensures that your application will not enter illogical states (such as both having a "data" and being in "loading" state) - ensures that logic handles all possible cases. Such as forcing to check loading/error cases before trying to access the data. The idea is that, rather than defining the data, error and loading state in a single object like: ```dart class MyState { MyState(...); final Data data; final Object? error; final bool loading; } ``` We can use Freezed to define it as: ```dart @freezed class MyState { factory MyState.data(Data data) = MyStateData; factory MyState.error(Object? error) = MyStateError; factory MyState.loading() = MyStateLoading; } ``` That voluntarily prevents us from doing: ```dart void main() { MyState state; print(state.data); } ``` Instead, we can use the generated `map` method to handle the various cases: ```dart void main() { MyState state; state.when( data: (state) => print(state.data), loading: (state) => print('loading'), error: (state) => print('Error: ${state.error}'), ); } ``` ### Integration with [provider]/service locators [StateNotifier] is easily compatible with [provider] through an extra mixin: `LocatorMixin`. Consider a typical [StateNotifier]: ```dart class Count { Count(this.count); final int count; } class Counter extends StateNotifier { Counter(): super(Count(0)); void increment() { state = Count(state.count + 1); } } ``` In this example, we may want to use `Provider.of`/`context.read` to connect our `Counter` with external services. To do so, simply mix-in `LocatorMixin` as such: ```dart class Counter extends StateNotifier with LocatorMixin { // unchanged } ``` That then gives you access to: - `read`, a function to obtain services - `update`, a new life-cycle that can be used to listen to changes on a service We could use them to change our `Counter` incrementation to save the counter in a DB when incrementing the value: ```dart class Counter extends StateNotifier with LocatorMixin { Counter(): super(Count(0)) void increment() { state = Count(state.count + 1); read().writeInt('count', state.count); } } ``` Where `Counter` and `LocalStorage` are defined using `provider` this way: ```dart void main() { runApp( MultiProvider( providers: [ Provider(create: (_) => LocalStorage()), StateNotifierProvider(create: (_) => Counter()), ], child: MyApp(), ), ); } ``` Then, `Counter`/`Count` are consumed using your typical `context.watch`/`Consumer`/`context.select`/...: ```dart @override Widget build(BuildContext context) { int count = context.watch().count; return Scaffold( body: Text('$count'), floatingActionButton: FloatingActionButton( onPressed: () => context.read().increment(), child: Icon(Icons.add), ), ); } ``` **Testing** When using `LocatorMixin`, you may want to mock a dependency for your tests.\ Of course, we still don't want to depend on Flutter/provider to do such a thing. Similarly, since `state` is protected, tests need a simple way to read the state. As such, `LocatorMixin` also adds extra utilities to help you with this scenario: ```dart myStateNotifier.debugMockDependency(myDependency); print(myStateNotifier.debugState); myStateNotifier.debugUpdate(); ``` As such, if we want to test our previous `Counter`, we could mock `LocalStorage` this way: ```dart test('increment and saves to local storage', () { final mockLocalStorage = MockLocalStorage(); final counter = Counter() ..debugMockDependency(mockLocalStorage); expect(counter.debugState, 0); counter.increment(); // works fine since we mocked the LocalStorage expect(counter.debugState, 1); // mockito stuff verify(mockLocalStorage.writeInt('int', 1)); }); ``` **Note:** `LocatorMixin` only works on `StateNotifier`, if you try to use it on other classes by `with LocatorMixin` then it will not work. [provider]: https://pub.dev/packages/provider [freezed]: https://pub.dev/packages/freezed [riverpod]: https://pub.dev/packages/riverpod [changenotifierprovider]: https://pub.dev/documentation/provider/latest/provider/ChangeNotifierProvider-class.html [statenotifier]: https://pub.dev/documentation/state_notifier/latest/state_notifier/StateNotifier-class.html [locatormixin]: https://pub.dev/documentation/state_notifier/latest/state_notifier/LocatorMixin-class.html [valuenotifier]: https://api.flutter.dev/flutter/foundation/ValueNotifier-class.html [changenotifier]: https://api.flutter.dev/flutter/foundation/ChangeNotifier-class.html ## Changelog ## 0.7.2+1 - Fixed an issue with `updateShouldNotify` naturally always returning `false`. ## 0.7.2 - Added `StateNotifier.updateShouldNotify` for customizing notification filtering (thanks to @maxzod) ## 0.7.1 - Improved the error when a listener of a `StateNotifier` throws to include the thrown error/stacktrace - `StateNotifier.state =` now filters updates using `identical`. ## 0.7.0 Stable release of null-safe `StateNotifier` ## 0.7.0-nullsafety.0 Migrated to non-nullable types ## [0.6.0] - 28/07/2020 Added `StateNotifier.stream`, to listen to a `StateNotifier` using the `Stream` API. ## [0.5.0] - 4/06/2020 If no `onError` is specified, errors are now reported to the current `Zone`. ## [0.4.0] - 13/03/2020 Added a flag on `addListener` to disable the first immediate call of the listener thanks to @smiLLe ## [0.3.0] - 08/03/2020 Add an `initState` life-cycle to be able to init the `StateNotifier` using `read`. ## [0.1.0+1] - 06/03/2020 Add example ## [0.1.0] - 06/03/2020 Initial release.