# riverpod 0.13.1
A simple way to access state from anywhere in your application while robust and testable.
## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'riverpod:0.13.1'
```
Published: 2021-03-05T20:13:29.845912Z
Expected archive SHA-256: ca4ef57a23c113420ee9998063effab9c8b1d7142279bd16422a0f08203c79c6
Available in cache; verification: upstream_checksum
## Direct dependencies
- collection: ^1.15.0
- freezed_annotation: ^0.14.0
- meta: ^1.3.0
- state_notifier: ^0.7.0
## Package README (untrusted upstream documentation)
---
A state-management library that:
- catches programming errors at compile time rather than
at runtime
- removes nesting for listening/combining objects
- ensures that the code is testable
| riverpod | [](https://pub.dartlang.org/packages/riverpod) |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| flutter_riverpod | [](https://pub.dartlang.org/packages/flutter_riverpod) |
| hooks_riverpod | [](https://pub.dartlang.org/packages/hooks_riverpod) |
Welcome to [Riverpod]!
This project can be considered as a rewrite of [provider] to make improvements
that would be otherwise impossible.
For learning how to use [Riverpod], see its documentation: https://riverpod.dev
Long story short:
- Declare your providers as global variables:
```dart
final counterProvider = StateNotifierProvider((ref) {
return Counter();
});
class Counter extends StateNotifier {
Counter(): super(0);
void increment() => state++;
}
```
- Use them inside your widgets in a compile time safe way. No runtime exceptions!
```dart
class Example extends ConsumerWidget {
@override
Widget build(BuildContext context, ScopedReader watch) {
final count = watch(counterProvider.state);
return Text(count.toString());
}
}
```
See the [FAQ](#FAQ) if you have questions about what this means for [provider].
## Index
- [Index](#index)
- [Motivation](#motivation)
- [Contributing](#contributing)
- [FAQ](#faq)
- [Why another project when [provider] already exists?](#why-another-project-when-provider-already-exists)
- [Is it safe to use in production?](#is-it-safe-to-use-in-production)
- [Will this get merged with [provider] at some point?](#will-this-get-merged-with-provider-at-some-point)
- [Will [provider] be deprecated/stop being supported?](#will-provider-be-deprecatedstop-being-supported)
## Motivation
If [provider] is a simplification of [InheritedWidget]s, then [Riverpod] is
a reimplementation of [InheritedWidget]s from scratch.
It is very similar to [provider] in principle, but also has major differences
as an attempt to fix the common problems that [provider] face.
[Riverpod] has multiple goals. First, it inherits the goals of [provider]:
- Being able to safely create, observe and dispose states without having to worry about
losing the state on widget rebuild.
- Making our objects visible in Flutter's devtool by default.
- Testable and composable
- Improve the readability of [InheritedWidget]s when we have multiple of them
(which would naturally lead to a deeply nested widget tree).
- Make apps more scalable with a unidirectional data-flow.
From there, [Riverpod] goes a few steps beyond:
- Reading objects is now **compile-safe**. No more runtime exception.
- It makes the [provider] pattern more flexible, which allows supporting commonly
requested features like:
- Being able to have multiple providers of the same type.
- Disposing the state of a provider when it is no longer used.
- Have computed states
- Making a provider private.
- Simplifies complex object graphs. It is easier to depend on asynchronous state.
- Makes the pattern independent from Flutter
These are achieved by no longer using [InheritedWidget]s. Instead, [Riverpod]
implements its own mechanism that works in a similar fashion.
For learning how to use [Riverpod], see its documentation: https://riverpod.dev
## Contributing
Contributions are welcomed!
Here is a curated list of how you can help:
- Report bugs and scenarios that are difficult to implement
- Report parts of the documentation that are unclear
- Update the documentation / add examples
- Implement new features by making a pull-request
## FAQ
### Why another project when [provider] already exists?
While [provider] is largely used and well accepted by the community,
it is not perfect either.
People regularly file issues or ask questions about some problems they face, such as:
- Why do I have a `ProviderNotFoundException`?
- How can I make that my state automatically disposed of when not used anymore?
- How to make a provider that depends on other (potentially complex) providers?
These are legitimate problems, and I believe that something can be improved to fix
those.
The issue is, these problems are deeply rooted in how [provider] works, and
fixing those problems is likely impossible without drastic changes to the
mechanism of [provider].
In a way, if [provider] is a candle then [Riverpod] is a lightbulb. They have
very similar usages, but we cannot create a lightbulb by improving our candle.
### Is it safe to use in production?
Yes, but with caution.
[Riverpod] recently left its experimental status, but it isn't fully stable either.
The API may change slightly when more features are added, and some use-cases
may not be as simple as they could be.
But overall, you should be able to use [Riverpod] without trouble.
### Will this get merged with [provider] at some point?
No. At least not until it is proven that the community likes [Riverpod]
and that it doesn't cause more problems than it solves.
While [provider] and this project have a lot in common, they do have some
major differences. Differences big enough that it would be a large breaking
change for users of [provider] to migrate [Riverpod].
Considering that, separating both projects initially sounds like a better
compromise.
### Will [provider] be deprecated/stop being supported?
Not in the short term, no.
This project is still experimental and unpopular. While it is, in a way,
a [provider] 2.0, its worth has yet to be proven.
Until it is certain that [Riverpod] is a better way of doing things
and that the community likes it, [provider] will still be maintained.
[provider]: https://github.com/rrousselGit/provider
[riverpod]: https://github.com/rrousselGit/river_pod
[flutter_hooks]: https://github.com/rrousselGit/flutter_hooks
[inheritedwidget]: https://api.flutter.dev/flutter/widgets/InheritedWidget-class.html
[hooks_riverpod]: https://pub.dev/packages/hooks_riverpod
[flutter_riverpod]: https://pub.dev/packages/flutter_riverpod
## Changelog
# 0.13.1
- Fixed a bug where overriding a `FutureProvider` with an error value could cause tests to fail (see https://github.com/rrousselGit/river_pod/issues/355)
# 0.13.0
- stable null-safety release
- `ProviderObserver` can now have a const constructor
- Added the mechanism for state-inspection using the Flutter devtool
- loosened the version constraints of `freezed_annotation`
- deprecated `import 'riverpod/all.dart'`. Now everything is available with `riverpod/riverpod.dart`.
- Fixed a but where listening to `StreamProvider.last` could result in a `StateError` (#217)
# 0.13.0-nullsafety.3
- deprecated `import 'riverpod/all.dart'`. Now everything is available with `riverpod/riverpod.dart`.
# 0.13.0-nullsafety.1
- Fixed a but where listening to `StreamProvider.last` could result in a `StateError` (#217)
# 0.13.0-nullsafety.0
Migrated to null-safety
# 0.12.2
- Exported `AutoDisposeProviderReference`
# 0.12.1
- Fixed an remaining memory leak related to StreamProvider (see also https://github.com/rrousselGit/river_pod/issues/193)
# 0.12.0
- **Breaking** FutureProvider and StreamProvider no-longer supports `null` as a valid value.
- Fixed a memory leak with StreamProvider (see also https://github.com/rrousselGit/river_pod/issues/193)
# 0.11.2
- Fixed a bug where providers (usually ScopedProviders) did not dispose correctly
(see also https://github.com/rrousselGit/river_pod/issues/154).
# 0.11.0
- `package:riverpod/riverpod.dart` now exports `StateNotifier`
- Marked the providers with `@sealed` so that the IDE warns against
implementing/subclassing providers.
- Fix mistakes in `AsyncValue.guard`'s documentation (thanks @mono0926)
- Loosened the version constraints of `freezed_annotation` to support `0.12.0`
# 0.10.0
- Fixed a bug where the state of a provider may be disposed when it shouldn't be disposed.
- Added a way to import the implementation class of providers with modifiers,
such as `AutoDisposeProvider`.
This is useful if you want to use Riverpod with the lint `always_specify_types`:
```dart
import 'package:riverpod/all.dart';
final AutoDisposeStateProvider counter = StateProvider.autoDispose((ProviderReference ref) {
return 0;
});
```
If you do not use this lint, prefer using the default import instead, to not
pollute your auto-complete.
# 0.8.0
- Renamed `ProviderContainer.debugProviderStates` to `ProviderContainer.debugProviderElements`
- Fixed a bug where updating `ProviderScope.overrides` may cause an exception
for no reason (see https://github.com/rrousselGit/river_pod/issues/107)
# 0.7.0
- `ref.watch` on non ".autoDispose" providers can no-longer read ".autoDispose"
providers.
For more info, see http://riverpod.dev/docs/concepts/modifiers/auto_dispose#the-argument-type-autodisposeprovider-cant-be-assigned-to-the-parameter-type-alwaysaliveproviderbase
- `ScopedProvider` now accepts `null` as a function:
```dart
final example = ScopedProvider(null);
```
Which is equivalent to:
```dart
final example = ScopedProvider((watch) => throw UnimplementedError(''));
```
- Fixed a bug where `context.refresh` may not work properly if the widget tree
contains multiple `ProviderScope`.
# 0.6.1
- Fixed a bug where when disposing `ProviderContainer`, providers may be disposed
in an incorrect order.
- Improved the performances of reading providers by 25%
# 0.6.0
- Merged `Computed` and `Provider`. Now, all providers have the ability to rebuild
their state when one of the object they listen changed.
To migrate, change:
```dart
final provider = Provider(...);
final example = Computed((watch) {
final value = watch(provider);
return value;
});
```
into:
```dart
final provider = Provider(...);
final example = Provider((ref) {
final value = ref.watch(provider);
return value;
});
```
- `Computed` (now `Provider`) no-longer deeply compare collections to avoid rebuilds.
Comparing the content of lists is quite expensive and actually rarely useful.
Now, a simple `==` comparison is used.
- Renamed `ProviderStateOwner` to `ProviderContainer`
- Renamed `ProviderStateOwnerObserver` to `ProviderObserver`
- It is no-longer possible to override a provider anywhere in the widget tree.
Providers can only be overriden in the top-most `ProviderContainer`.
- Providers can now read values which may change over time using `ref.read` and `ref.watch`.
When using `ref.watch`, if the value obtained changes, this will cause the provider
to re-create its state.
- It is no-longer possible to add `ProviderObserver` anywhere in the widget tree.
They can be added only on the top-most `ProviderContainer`.
- Added `ProviderContainer.refresh(provider)`.
This method allows forcing the refresh of a provider, which can be useful
for things like "retry on error" or "pull to refresh".
* `ref.read(StreamProvider)` no-longer returns a `Stream` but an `AsyncValue`
Before:
```dart
final streamProvider = StreamProvider(...);
final example = Provider((ref) {
Stream stream = ref.read(streamProvider);
});
```
After:
```dart
final streamProvider = StreamProvider(...);
final example = Provider((ref) {
Stream stream = ref.watch(streamProvider.steam);
});
```
* `ref.read(FutureProvider)` no-longer returns a `Future` but an `AsyncValue`
Before:
```dart
final futureProvider = FutureProvider(...);
final example = Provider((ref) {
Future future = ref.read(futureProvider);
});
```
After:
```dart
final futureProvider = FutureProvider(...);
final example = Provider((ref) {
Future future = ref.watch(futureProvider.future);
});
```
* Removed `ref.dependOn`.
You can now use `ref.read`/`ref.watch` to acheive the same effect.
Before:
```dart
final streamProvider = StreamProvider(...);
final example = Provider((ref) {
Future last = ref.dependOn(streamProvider).last;
});
```
After:
```dart
final streamProvider = StreamProvider(...);
final example = Provider((ref) {
Future last = ref.watch(streamProvider.last);
});
```
* `Provider.readOwner(ProviderStateOwner)` is changed into `ProviderContainer.read(Provider)`
* `Provider.watchOwner(ProviderStateOwner, (value) {})` is changed into:
```dart
ProviderContainer container;
final provider = Provider((ref) => 0);
final subscription = container.listen(
provider,
mayHaveChanged: (sub) {},
didChange: (sub) {}.
);
subscription.close();
```
* `MyProvider.family.autoDispose` now correctly free both the arguments and the associated
providers from memory when the provider is no-longer listened.
- Added `ScopedProvider`, a new kind of provider that can be overriden anywhere
in the widget tree.
Normal providers cannot read a `ScopedProvider`.
# 0.5.1
- Fixed the documentation of `StateNotifierProvider` incorrectly showing the
documentation of `StreamProvider`.
- Improve the documentation of `StateProvider`.
# 0.5.0
- Changed `ComputedFamily` into `Computed.family`
- Added [AsyncValue.guard](https://pub.dev/documentation/riverpod/latest/riverpod/AsyncValue/guard.html to simplify transforming a Future into an AsyncValue.
- Improved the documentation of the different providers
# 0.4.0
Changed the syntax of "AutoDispose*" and "*Family" to use a syntax similar to
named constructors instead.
Before:
```dart
final myProvider = AutoDisposeStateNotifierProviderFamily((ref, id) {
return MyStateNotifier(id: id);
});
```
After:
```dart
final myProvider = StateNotifierProvider.autoDispose.family((ref, id) {
return MyStateNotifier(id: id);
});
```
The behavior is the same. Only the syntax changed.
# 0.3.0
- Added `AsyncValue.whenData`, syntax sugar for `AsyncValue.when` to handle
only the `data` case and do nothing for the error/loading cases.
- Fixed a bug that caused [Computed] to crash if it stopped being listened
then was listened again.
# 0.2.1
- `Computed` now correctly unsubscribe to a provider when their
function stops using a provider.
# 0.2.0
- `ref.read` is renamed as `ref.dependOn`
- Deprecated `ref.dependOn(streamProvider).stream` and `ref.dependOn(futureProvider).future`
in favor of a universal `ref.dependOn(provider).value`.
- added `ref.read(provider)`, syntax sugar for `ref.dependOn(provider).value`.
# 0.1.0
Initial release