# riverpod 2.0.0-dev.7
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:2.0.0-dev.7'
```
Published: 2022-05-12T08:56:09.335407Z
Expected archive SHA-256: 2eae8f07d013a9b9270befaf4185ea2e4b572313be40372ec0a0db0f14f5973d
Available in cache; verification: upstream_checksum
## Direct dependencies
- collection: ^1.15.0
- meta: ^1.3.0
- stack_trace: ^1.10.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, WidgetRef ref) {
final count = ref.watch(counterProvider);
return Text(count.toString());
}
}
```
See the [FAQ](#FAQ) if you have questions about what this means for [provider].
## Migration
With the release of version 1.0.0, the syntax for interacting with providers changed.
See [the migration guide](https://riverpod.dev/docs/migration/0.14.0_to_1.0.0/) for more information
## Index
- [Migration](#migration)
- [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)
- [Sponsors](#sponsors)
## 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
- Fix typos/grammar mistakes
- 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 automatically dispose my state 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.
[Riverpod] is stable and actively maintained.
### 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.
However, a migration tool is planned to help assist migration from provider
to [Riverpod].
## Sponsors
[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
# 2.0.0-dev.7
Upgrade minimum required Dart SDK version to 2.17.0
# 2.0.0-dev.6
- Added `AsyncValue.valueOrNull` to obtain the value while ignoring potential errors.
- Fixed an issue where `AsyncValue.value` did not throw if there is an error.
- Fix families not applying cacheTime/disposeDelay
- Fixed a bug where an exception may be thrown asynchronously after a
`KeepAliveLink` is cancelled.
# 2.0.0-dev.5
- Fixed a bug where emitting an `AsyncData` after an `AsyncError` leads to `AsyncValue.hasError` to be true
# 2.0.0-dev.4
- Added `ref.listenSelf`, for subscribing to changes of a provider within
that provider.
That can be useful for logging purposes or storing the state of a provider
in a DB.
- Added `disposeDelay` to all `autoDispose` providers and to `ProviderContainer`/`ProviderScope`.
This configures the amount of time before a provider is disposed when it is
not listened.
- Added `container.invalidate(provider)`/`ref.invalidate(provider)` and `ref.invalidateSelf()`.
These are similar to `ref.refresh` methods, but do not immediately rebuild the provider.
These methods are safer than `ref.refresh` as they can avoid a provider
rebuilding twice in a quick succession.
- The duration passed to `cacheTime` now represents the minimum amount of
time after the latest change of a provider, instead of the first time
a provider built.
- Fixed an issue where providers were incorrectly allowed to depend on themselves,
breaking `autoDispose` in the process.
- Fixed a memory leak when using `StateProvider.autoDispose`'s `.state`
- Fix `ProviderObserver.didDisposeProvider` not executing on provider refresh.
# 2.0.0-dev.3
When calling `ref.listen` on a provider, this provider will now properly
rebuild if one of its dependency had changed.
# 2.0.0-dev.2
- Deprecated `ref.maintainState=` in favor of a newly added `ref.keepAlive()`.
This new `ref.keepAlive()` function is similar to `maintainState` but
better handles cases where we have multiple logics that want to
keep the state of a provider alive for some period of time.
- Removed the deprecated `ProviderReference`.
- Added `ProviderContainer.cacheTime` and `MyProvider.autoDispose(..., cacheTime: duration)`.
`cacheTime` is used to keep an `autoDispose` provider alive for at least
a minimum amount of time before it gets disposed if not listened.
- Added `ref.onAddListener`, `ref.onRemoveListener`, `ref.onCancel` and
`ref.onResume`. All of which allow performing side-effects when providers
are listened or stop being listened.
# 2.0.0-dev.1
- Now requires Dart 2.16
- **Breaking** Providers no-longer throw a `ProviderException` if an exception was thrown while building their value.
Instead, they will rethrow the thrown exception and its stacktrace.
- Removed `AsyncValue`'s `isError`/`isData`
- Added new functionalities to `AsyncValue`: `hasError`, `hasData`, `copyWithPrevious`
- Added `provider.selectAsync`, which allows to both await an async value
while also filtering rebuilds.
- When a provider emits an `AsyncError` followed by an `AsyncData`,
the `AsyncData` emitted will now contain the latest error/stackTrace too.
- Fixed a cast error when overriding a provider with a more specific provider type (#1100)
- Fixed a bug where `onDispose` listeners could be executed twice under certain
conditions when using `autoDispose`.
# 2.0.0-dev.0
- **Breaking** After a provider has emitted an `AsyncValue.data` or `AsyncValue.error`,
that provider will no longer emit an `AsyncValue.loading`.
Instead, it will re-emit the latest value, but with the property
`AsyncValue.isRefreshing` to true.
This allows the UI to keep showing the previous data/error when a provider
is being refreshed.
- Adding `isLoading`, `isError`, `isData` and `asError` to `AsyncValue`.
Those getters allow interacting with `AsyncValue` without having to rely on
pattern matching.
- Fixed an issue where refreshing a `provider.future`/`provider.stream` did work properly
- Fixed false positive with `ref.watch` asserts
## 1.0.3
Removed an assert preventing from overriding the same provider/family
multiple times on a `ProviderScope`/`ProviderContainer`.
## 1.0.2
Fixed a null exception on web
## 1.0.1
Improved the performance of the assert which verifies that providers properly
respect their `dependencies` variable.
## 1.0.0
Riverpod is now stable!
### General changes
- **Breaking**: `ProviderContainer.debugProviderValues` and `ProviderContainer.debugProviderElements` are removed.
You can now instead use `ProviderContainer.getAllProviderElements`.
- Increased minimum SDK version to 2.14.0
- **Breaking** The return value when reading a `StateProvider` changed.
Before, doing `ref.read(someStateProvider)` would return the `StateController` instance.
Now, this will only return the state of the `StateController`.
This new behaviour matches `StateNotifierProvider`.
For a simple migration, the old behavior is available by writing
`ref.read(someStateProvider.state)`.
- Added `ref.listen` for triggering actions inside providers/widgets when a provider changes.
It can be used to listen to another provider without recreating the provider state:
```dart
final counterProvider = StateNotifierProvider(...);
final anotherProvider = Provider((ref) {
ref.listen(counterProvider, (previous, count) {
print('counter changed from $previous to $count');
});
});
```
Alternatively, it can be used by widgets to show modals/dialogs:
```dart
final counterProvider = StateNotifierProvider(...);
class Example extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
ref.listen(counterProvider, (previous, count) {
showDialog(...);
});
}
}
```
- It is now possible to "await" all providers that emit an `AsyncValue` (previously limited to `FutureProvider`/`StreamProvider`).
This includes cases where a `StateNotifierProvider` exposes an `AsyncValue`:
```dart
class MyAsyncStateNotifier extends StateNotifier> {
MyAsyncStateNotifier(): super(AsyncValue.loading()) {
// TODO fetch some data and update the state when it is obtained
}
}
final myAsyncStateNotifierProvider = StateNotifierProvider>((ref) {
return MyAsyncStateNotifier();
});
final someFutureProvider = FutureProvider((ref) async {
MyState myState = await ref.watch(myAsyncStateNotifierProvider.future);
});
```
- Deprecated `StreamProvider.last` in favor of `StreamProvider.future`.
- `StreamProvider.future`, `StreamProvider.stream` and `FutureProvider.future` now
expose a future/stream that is independent from how many times the associated provider "rebuilt":
- if a `StreamProvider` rebuild before its stream emitted any value,
`StreamProvider.future` will resolve with the first value of the new stream instead.
- if a `FutureProvider` rebuild before its future completes,
`FutureProvider.future` will resolve with the result of the new future instead.
- You can now override any provider with any other provider, as long as the value
that they expose matches. For example, it is possible to override a `StreamProvider`
with a `Provider>`.
- `ref.onDispose` now calls the dispose function as soon as one of the provider's
dependencies is known to have changed
- Providers can now call `ref.refresh` to refresh a provider, instead of having
to do `ref.container.refresh`.
- Providers no longer wait until their next read to recompute their state if one
of their dependencies changed and they have listeners.
- Added `ProviderContainer.pump`, a utility to easily "await" until providers
notify their listeners or are disposed.
- fixed an issue when using both `family` and `autoDispose` that could lead to an inconsistent state
### Unified the syntax for interacting with providers
- `ProviderReference` is deprecated in favor of `Ref`.
- `ref.watch` now supports `myProvider.select((value) => ...)`.
This allows filtering rebuilds:
```dart
final userProvider = StateNotifierProvider(...);
final anotherProvider = Provider((ref) {
// With this syntax, the Consumer will not rebuild if `userProvider`
// emits a new User but its "name" didn't change.
bool userName = ref.watch(userProvider.select((user) => user.name));
});
```
- **Breaking**: `ProviderObserver.didUpdateProvider` now receives both the previous and new value.
- **Breaking**: `ProviderObserver.mayHaveChanged` is removed.
- **Breaking**: `Family.overrideWithProvider` now must create a provider:
```dart
final family = Provider.family(...);
family.overrideWithProvider(
(Arg arg) => Provider((ref) => ...)
);
```
- All providers now receive a custom subclass of `ProviderRefBase` as a parameter:
```dart
Provider((ProviderRef ref) {...});
FutureProvider((FutureProviderRef ref) {...});
StateProvider((StateProviderRef ref) {...});
```
That allows providers to implement features that is not shared with other providers.
- `Provider`, `FutureProvider` and `StreamProvider`'s `ref` now have a `state` property,
which represents the currently exposed value. Modifying it will notify the listeners:
```dart
Provider((ref) {
ref.listen(onIncrementProvider, (_) {
ref.state++;
});
return 0;
});
```
- `StateProvider`'s `ref` now has a `controller` property, which allows the
provider to access the `StateController` exposed.
- **Breaking**: `ProviderReference.mounted` is removed. You can implement something similar using `onDispose`:
```dart
Provider((ref) {
var mounted = true;
ref.onDispose(() => mounted = false);
});
```
### All providers can now be scoped.
- **Breaking**: `ScopedProvider` is removed.
To migrate, change `ScopedProvider`s to `Provider`s.
- All providers now come with an extra named parameter called `dependencies`.
This parameter optionally allows defining the list of providers/families that this
new provider depends on:
```dart
final a = Provider(...);
final b = Provider((ref) => ref.watch(a), dependencies: [a]);
```
By doing so, this will tell Riverpod to automatically override `b` if `a` gets overridden.
### Updated `AsyncValue`:
- **Breaking** `AsyncValue.copyWith` is removed
- **Breaking** `AsyncValue.error(..., stacktrace)` is now a named parameter instead of postional parameter.
- Deprecated `AsyncValue.data` in favor of `AsyncValue.value`
- Allowed `AsyncData`, `AsyncError` and `AsyncLoading` to be extended
- Added `AsyncValue.whenOrNull`, similar to `whenOrElse` but instead of an
"orElse" parameter, returns `null`.
- Added `AsyncValue.value`, which allows reading the value without handling
loading/error states.
- `AsyncError` can now be instantiated with `const`.
- Added `StateController.update`, to simplify updating the state from the previous state:
```dart
final provider = StateController((ref) => 0);
...
ref.read(provider).update((state) => state + 1);
```
- It is no longer allowed to use `ref.watch` or `ref.read` inside a selector:
```dart
provider.select((value) => ref.watch(something)); // KO, cannot use ref.watch inside selectors
```
- FutureProvider now creates a `FutureOr` instead of a `Future`.
That allows bypassing the loading state in the event where a value was synchronously available.
### Bug fixes
- Fixed a bug where widgets were not rebuilding in release mode under certain conditions
- **FIX**: StreamProvider.last no longer throws a StateError when no value were emitted (#296).
- fixed an issue where when chaining providers, widgets may re-render
a frame late, potentially causing a flicker. (see #648)
## 1.0.0-dev.10
Fixed a bug where reading a provider within a consumer could throw (#796)
## 1.0.0-dev.9
Fix an issue where `*Provider.autoDispose` were not able to specify the
`dependencies` parameter.
## 1.0.0-dev.8
### Future/StreamProvider
- FutureProvider now creates a `FutureOr` instead of a `Future`
That allows bypassing the loading state in the event where a value was synchronously available.
- During loading and error states, `FutureProvider` and `StreamProvider` now expose the
latest value through `AsyncValue`.
That allows UI to show the previous data while some new data is loading,
inatead of showing a spinner:
```dart
final provider = FutureProvider((ref) async {
ref.watch(anotherProvider); // may cause `provider` to rebuild
return fetchSomething();
})
...
Widget build(context, ref) {
return ref.watch(provider).when(
error: (err, stack, _) => Text('error'),
data: (user) => Text('Hello ${user.name}'),
loading: (previous) {
if (previous is AsyncData) {
return Text('loading ... (previous: ${previous.value.name})'});
}
return CircularProgressIndicator();
}
);
}
```
### AsyncValue
- **Breaking** `AsyncValue.copyWith` is removed
- **Breaking** `AsyncValue.error(..., stacktrace)` is now a named parameter instead of postional parameter.
- **Breaking** `AsyncValue.when(loading: )` and ``AsyncValue.when(error: )` (and `when` variants)
now receive an extra "previous" parameter.
- Deprecated `AsyncValue.data` in favor of `AsyncValue.value`
- Allowed `AsyncData`, `AsyncError` and `AsyncLoading` to be extended
- Added `AsyncValue.whenOrNull`, similar to `whenOrElse` but instead of an
"orElse" parameter, returns `null`.
- Added `AsyncValue.value`, which allows reading the value without handling
loading/error states.
- `AsyncError` can now be instantiated with `const`.
- `AsyncLoading` and `AsyncError` now optionally includes the previous state.
### General
- **Breaking** All `overrideWithProvider` methods are removed.
To migrate, instead use `overrideWithValue`.
- All providers now come with an extra named parameter called `dependencies`.
This parameter optionally allows defining the list of providers/families that this
new provider depends on:
```dart
final a = Provider(...);
final b = Provider((ref) => ref.watch(a), dependencies: [a]);
```
By doing so, this will tell Riverpod to automatically override `b` if `a` gets overridden.
- Added `StateController.update`, to simplify updating the state from the previous state:
```dart
final provider = StateController((ref) => 0);
...
ref.read(provider).update((state) => state + 1);
```
- It is no longer allowed to use `ref.watch` or `ref.read` inside a selector:
```dart
provider.select((value) => ref.watch(something)); // KO, cannot user ref.watch inside selectors
```
### Bug-fixes
- fixed a bug where providers were rebuilding even when not being listened to
- fixed `ref.listen` now working when downcasting the value of a provider.
- fixed a bug where disposing a scoped `ProviderContainer` could cause other
`ProviderContainer`s to stop working.
- fixed an issue where conditionally depending on an "autoDispose" provider
may not properly dispose of it (see #712)
- fixed an issue where when chaining providers, widgets may re-render
a frame late, potentially causing a flicker. (see #648)
## 1.0.0-dev.7
- Fixed `ProviderObserver` not working when modifying a `StateProvider`.
- Fixed a bug where scoped provider were potentially not disposed
- Fixed a bug where widgets were not rebuilding in release mode under certain conditions
## 1.0.0-dev.6
- **FIX**: StreamProvider.last no longer throws a StateError when no value were emitted (#296).
- Re-enabled debug assertions that were temporarily disabled by previous dev versions.
- Allows families to be scoped/overridden
- Fixed bugs with `ref.refresh` not working on some providers
- renamed `ProviderBase.recreateShouldNotify` to `updateShouldNotify`
## 1.0.0-dev.5
Fixed an issue where provider listeners could not be called properly.
## 1.0.0-dev.3
Fixed various issues related to scoped providers.
## 1.0.0-dev.2
- All providers can now be scoped.
- **breaking**: `ScopedProvider` is removed. To migrate, change `ScopedProvider`s to `Provider`s.
## 1.0.0-dev.1
- Add missing exports (see #532)
## 1.0.0-dev.0
- `ref.watch` now support `myProvider.select((value) => ...)`.
This allows filtering rebuilds:
```dart
final userProvider = StateNotifierProvider(...);
final anotherProvider = Provider((ref) {
// With this syntax, the Consumer will not rebuild if `userProvider`
// emits a new User but its "name" didn't change.
bool userName = ref.watch(userProvider.select((user) => user.name));
});
```
- **Breaking**: `Family.overrideWithProvider` now must create a provider:
```dart
final family = Provider.family(...);
family.overrideWithProvider(
(Arg arg) => Provider((ref) => ...)
);
```
- **Breaking**: `ProviderObserver.didUpdateProvider` now receives both the previous and new value.
- **Breaking**: `ProviderObserver.mayHaveChanged` is removed.
- Added `ref.listen`, used to listen to another provider without recreating the provider state:
```dart
final counter = StateNotifierProvider(...);
final anotherProvider = Provider((ref) {
ref.listen(counter, (count) {
print('counter change: $count');
});
});
```
- `ProviderReference` is deprecated in favor of `ProviderRefBase`.
- All providers now receive a custom subclass of `ProviderRefBase` as a parameter:
```dart
Provider((ProviderRef ref) {...});
FutureProvider((FutureProviderRef ref) {...});
StateProvider((StateProviderRef ref) {...});
```
That allows providers to implement features that is not shared with other providers.
- `Provider`, `FutureProvider` and `StreamProvider`'s `ref` now have a `state` property,
which represents the currently exposed value. Modifying it will notify the listeners:
```dart
Provider((ref) {
ref.listen(onIncrementProvider, (_) {
ref.state++;
});
return 0;
});
```
- `StateProvider`'s `ref` now has a `controller` property, which allows the
provider to access the `StateController` exposed.
- **Breaking**: `ProviderReference.mounted` is removed. You can implement something similar using `onDispose`:
```dart
Provider((ref) {
var mounted = true;
ref.onDispose(() => mounted = false);
});
```
- **Breaking**: `ProviderContainer.debugProviderValues` and `ProviderContainer.debugProviderElements` are removed.
You can now instead use `ProviderContainer.getAllProviderElements`.
- `StreamProvider.last`, `StreamProvider.stream` and `FutureProvider.future` now
expose a future/stream that is independent from how many times the associated provider "rebuilt":
- if a `StreamProvider` rebuild before its stream emitted any value,
`StreamProvider.last` will resolve with the first value of the new stream instead.
- if a `FutureProvider` rebuild before its future completes,
`FutureProvider.future` will resolve with the result of the new future instead.
- You can now override any provider with any other provider, as long as the value
that they expose matches. For example, it is possible to override a `StreamProvider`
with a `Provider>`.
- `ref.onDispose` now calls the dispose function as soon as one of the provider's
dependency is known to have changed
- Providers can now call `ref.refresh` to refresh a provider, instead of having
to do `ref.container.refresh`.
- Providers no longer wait until their next read to recompute their state if one
of their dependencies changed and they have listeners.
- Added `ProviderContainer.pump`, a utility to easily "await" until providers
notify their listeners or are disposed.
- fixed an issue when using both `family` and `autoDispose` that could lead to an inconsistent state
## 0.14.0+3
Removed an assert that could cause issues when an application is partially migrated to null safety.
## 0.14.0+1
- Re-added `StateProvider.overrideWithValue`/`StateProvider.overrideWithProvider` that were unvoluntarily removed.
## 0.14.0
- **BREAKING CHANGE** The `Listener`/`LocatorMixin` typedefs are removed as the former could cause a name
conflict with the widget named `Listener` and the latter is not supported when using Riverpod.
- **BREAKING CHANGE** The syntax for using `StateNotifierProvider` was updated.
Before:
```dart
class MyStateNotifier extends StateNotifier {...}
final provider = StateNotifierProvider((ref) => MyStateNotifier());
...
Widget build(context, watch) {
MyStateNotifier notifier = watch(provider);
MyModel model = watch(provider.state);
}
```
After:
```dart
class MyStateNotifier extends StateNotifier {...}
final provider = StateNotifierProvider>((ref) => MyStateNotifier());
...
Widget build(context, watch) {
MyStateNotifier notifier = watch(provider.notifier);
MyModel model = watch(provider);
}
```
See also https://github.com/rrousselGit/river_pod/issues/341 for more information.
- **BREAKING CHANGE** It is no longer possible to override `StreamProvider.stream/last` and `FutureProvider.future`.
- feat: Calling `ProviderContainer.dispose` multiple time no longer throws.
This simplifies the tear-off logic of tests.
- feat: Added `ChangeNotifierProvider.notifier` and `StateProvider.notifier`
They allow obtaining the notifier associated with the provider, without causing widgets/providers to rebuild when the state updates.
- fix: overriding a `StateNotifierProvider`/`ChangeNotifierProvider` with `overrideWithValue` now correctly listens to the notifier.
## 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 `AutoDisposeProviderRefBase`
## 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((ProviderRefBase 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 overridden 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 achieve 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 to.
- Added `ScopedProvider`, a new kind of provider that can be overridden 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 to
then was listened to 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