# riverpod 2.1.0
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.1.0'
```
Published: 2022-10-31T19:09:35.707429Z
Expected archive SHA-256: ce7f4a288da62b53446ede246e75786e83b7dce6f7e40250b9148efba5866156
Available in cache; verification: upstream_checksum
## Direct dependencies
- collection: ^1.15.0
- meta: ^1.4.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?
It is possible. Some experiments are being made that could make this
doable. But their outcome isn't clear yet.
(no link to an issue to avoid putting unnecessary pressure on the people
involved)
If those experiments are successful (although unlikely), then Provider
and Riverpod could be fused.
### Will provider be deprecated/stop being supported?
Maybe.
Provider has numerous flaws that can't quite be fixed. At the same time,
Riverpod has proven to fix many of those.
As such, deprecating Provider is being considered.
The only inconvenience of Riverpod is the need for a "Consumer",
which Provider doesn't need.
But some alternatives are being investigated to maybe remove this constraint.
Whatever the decision is, a migration tool is planned to help assist
migration from provider to [Riverpod]. Along with whatever other tool necessary to help.
## Sponsors
[provider]: https://github.com/rrousselGit/provider
[riverpod]: https://github.com/rrousselGit/riverpod
[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.1.0
A small release adding missing utilities and fixing some web related issues.
- Added `provider.overrideWith((ref) => state`)
- Added `FutureProviderRef.future`.
- Deprecated `StateProvider.state`
Instead, use either `ref.watch(stateProvider)` or `ref.read(stateProvider.notifier).state =`
- Deprecated `provider.overrideWithProvider`. Instead use `provider.overrideWith`
- Added `Ref.notifyListeners()` to forcibly notify dependents.
This can be useful for mutable state.
- Added `@useResult` to `Ref.refresh`/`WidgetRef.refresh`
- Added `Ref.exists` to check whether a provider is initialized or not.
- `FutureProvider`, `StreamProvider` and `AsyncNotifierProvider` now preserve the
previous data/error when going back to loading.
This is done by allowing `AsyncLoading` to optionally contain a value/error.
- Added `AsyncValue.when(skipLoadingOnReload: bool, skipLoadingOnRefresh: bool, skipError: bool)`
flags to give fine control over whether the UI should show `loading`
or `data/error` cases.
- Add `AsyncValue.requireValue`, to forcibly obtain the `value` and throw if in
loading/error state
- Doing `ref.watch(futureProvider.future)` can no-longer return a `SynchronousFuture`.
That behavior could break various `Future` utilities, such as `Future.wait`
- Add `AsyncValue.copyWithPrevious(..., isRefres: false)` to differentiate
rebuilds from `ref.watch` vs rebuilds from `ref.refresh`.
- ProviderContainer no-longer throws when disposed if it has an undisposed child ProviderContainer.
- Fixes a stackoverflow on Web caused by Dart (thanks to @leehack)
- Fixes a bug when the root ProviderContainer is not associated with a ProviderScope.
- Fixes a case where a circular dependency between providers was incorrectly allowed (#1766)
## 2.0.2
- **FIX**: Fixed an assert error if a `family` depends on itself while specifying `dependencies`. (#1721).
## 2.0.2
Fixed an assert error if a `family` depends on itself while specifying `dependencies`.
## 2.0.1
Updated changelog (see 2.0.0)
## 2.0.0
Here is the changelog for all the changes in the 2.0 version.
An article is in progress and will be linked here once available.
**Breaking changes**:
- `FutureProvider.stream` is removed.
- Using `overrideWithProvider`, it is no-longer possible to override a provider
with a different type of provider (such as overriding `FutureProvider` with a `StreamProvider`).
- `AsyncError.stackTrace` is now a required positional parameter and non-nullable
- All `overrideWithValue` methods are removed, besides `Provider.overrideWithValue`.
This change is temporary, and these methods will be reintroduced in a later version.
In the meantime, you can use `overrideWithProvider`.
- Modifiers (`provider.future`, `provider.state`, ...) no-longer are providers, and therefore no-longer
appear inside `ProviderObserver`.
- The `Reader` typedef is removed. Use `Ref` instead.
- `ProviderListener` is removed. Used `ref.listen` instead.
- Removed the deprecated `ProviderReference`.
- 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.
- It is no longer possible to pass `provider.future/.notifier/...` to the parameter `dependencies` of provider.
Passing the provider directly is enough.
- The `Family` type now has a single generic parameter instead of 3.
Non-breaking changes:
- Upgrade minimum required Dart SDK version to 2.17.0
- Added `provider.selectAsync`, which allows to both await an async value
while also filtering rebuilds.
- 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 `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.
- 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.
- A new `AutoDisposeRef.keepAlive()` function is added. It is meant to replace
`AutoDisposeRef.maintainState` to make logic for preventing the disposal of a provider more reusable.
- feat; `AutoDisposeRef.maintainState` is deprecated. Use the new `AutoDisposeRef.keepAlive()` instead.
- Add support for `ref.invalidate(family)` to recompute an entire family (#1517)
- Added `AsyncValue.valueOrNull` to obtain the value while ignoring potential errors.
- Added new functionalities to `AsyncValue`: `hasError`, `hasData`, `asError`, `isLoading`
, `copyWithPrevious` and `unwrapPrevious`.
Fixes:
- fixed a bug where `AsyncValue.whenData` did not preserve `AsyncValue.isLoading/isRefreshing`
- `StateProvider` and `StateNotifierProvider` no longer notify their listeners
on `ref.refresh` if the new result is identical to the old one.
- fixed potential null exception when using `autoDispose`
- fixed a bug where unmounting a nested ProviderScope could cause an exception (#1400)
- 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.
- Fixed an issue where `AsyncValue.value` did not throw if there is an error.
- 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`.
- Fixed an issue where refreshing a `provider.future`/`provider.stream` did work properly
- Fixed false positive with `ref.watch` asserts
## 2.0.0-dev.9
Fix Timer leak when using `cacheTime`/`disposeDelay` and disposing a `ProviderContainer`
## 2.0.0-dev.8
fix: a bug where unmounting a nested ProviderScope could cause an exception (#1400)
## 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/riverpod/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/riverpod/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/riverpod/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/riverpod/issues/193)
## 0.11.2
- Fixed a bug where providers (usually ScopedProviders) did not dispose correctly
(see also https://github.com/rrousselGit/riverpod/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/riverpod/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