riverpod

When calling ref.listen on a provider, this provider will now properly rebuild if one of its dependency had changed.

• 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.

• 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.

• 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

Removed an assert preventing from overriding the same provider/family multiple times on a ProviderScope/ProviderContainer.

Fixed a null exception on web

Improved the performance of the assert which verifies that providers properly respect their dependencies variable.

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 behavior 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:

  final counterProvider = StateNotifierProvider<Counter, int>(...);
  
  final anotherProvider = Provider<T>((ref) {
    ref.listen<int>(counterProvider, (previous, count) {
      print('counter changed from $previous to $count');
    });
  });
  

  Alternatively, it can be used by widgets to show modals/dialogs:

  final counterProvider = StateNotifierProvider<Counter, int>(...);
  
  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      ref.listen<int>(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:

  class MyAsyncStateNotifier extends StateNotifier<AsyncValue<MyState>> {
    MyAsyncStateNotifier(): super(AsyncValue.loading()) {
      // TODO fetch some data and update the state when it is obtained
    }
  }
  
  final myAsyncStateNotifierProvider = StateNotifierProvider<MyAsyncStateNotifier, AsyncValue<MyState>>((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<Model> with a Provider<AsyncValue<Model>>.

• 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:

  final userProvider = StateNotifierProvider<UserController, User>(...);
  
  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:

  final family = Provider.family<State, Arg>(...);
  
  family.overrideWithProvider(
    (Arg arg) => Provider<State>((ref) => ...)
  );
  

• All providers now receive a custom subclass of ProviderRefBase as a parameter:

  Provider<T>((ProviderRef<T> ref) {...});
  FutureProvider<T>((FutureProviderRef<T> ref) {...});
  StateProvider<T>((StateProviderRef<T> 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:

    Provider<int>((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:

  Provider<T>((ref) {
    var mounted = true;
    ref.onDispose(() => mounted = false);
  });
  

All providers can now be scoped.

• Breaking: ScopedProvider is removed. To migrate, change ScopedProviders to Providers.

• 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:

  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 positional 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:

  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:

  provider.select((value) => ref.watch(something)); // KO, cannot use ref.watch inside selectors
  

• FutureProvider now creates a FutureOr<T> instead of a Future<T>. 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)

Fixed a bug where reading a provider within a consumer could throw (#796)

Fix an issue where *Provider.autoDispose were not able to specify the dependencies parameter.

Future/StreamProvider

• FutureProvider now creates a FutureOr<T> instead of a Future<T> 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, instead of showing a spinner:

  final provider = FutureProvider<User>((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<User>) {
          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 positional 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:

  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:

  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:

  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 downcasing the value of a provider.
• fixed a bug where disposing a scoped ProviderContainer could cause other ProviderContainers 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)

• 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

• 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

Fixed an issue where provider listeners could not be called properly.

Fixed various issues related to scoped providers.

• All providers can now be scoped.
• breaking: ScopedProvider is removed. To migrate, change ScopedProviders to Providers.

• Add missing exports (see #532)

• ref.watch now support myProvider.select((value) => ...). This allows filtering rebuilds:

  final userProvider = StateNotifierProvider<UserController, User>(...);
  
  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:

  final family = Provider.family<State, Arg>(...);
  
  family.overrideWithProvider(
    (Arg arg) => Provider<State>((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:

  final counter = StateNotifierProvider<Counter, int>(...);
  
  final anotherProvider = Provider<T>((ref) {
    ref.listen<int>(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:

  Provider<T>((ProviderRef<T> ref) {...});
  FutureProvider<T>((FutureProviderRef<T> ref) {...});
  StateProvider<T>((StateProviderRef<T> 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:

    Provider<int>((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:

  Provider<T>((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<Model> with a Provider<AsyncValue<Model>>.

• 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

• 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:

  class MyStateNotifier extends StateNotifier<MyModel> {...}
  
  final provider = StateNotifierProvider<MyStateNotifier>((ref) => MyStateNotifier());
  
  ...
  Widget build(context, watch) {
    MyStateNotifier notifier = watch(provider);
    MyModel model = watch(provider.state);
  }
  

  After:

  class MyStateNotifier extends StateNotifier<MyModel> {...}
  
  final provider = StateNotifierProvider<MyStateNotifier, MyModel>>((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.

• Re-added StateProvider.overrideWithValue/StateProvider.overrideWithProvider that were involuntarily removed.

Removed an assert that could cause issues when an application is partially migrated to null safety.

• Fixed a bug where overriding a FutureProvider with an error value could cause tests to fail (see https://github.com/rrousselGit/riverpod/issues/355)

• 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)

• 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)

Migrated to null-safety

• Exported AutoDisposeProviderRefBase

• Fixed an remaining memory leak related to StreamProvider (see also https://github.com/rrousselGit/riverpod/issues/193)

• 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)

• Fixed a bug where providers (usually ScopedProviders) did not dispose correctly (see also https://github.com/rrousselGit/riverpod/issues/154).

• 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

• 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:

  import 'package:riverpod/all.dart';
  
  final AutoDisposeStateProvider<int> counter = StateProvider.autoDispose<int>((ProviderRefBase ref) {
    return 0;
  });
  

  If you do not use this lint, prefer using the default import instead, to not pollute your auto-complete.

• 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)

• 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:

  final example = ScopedProvider<int>(null);
  

  Which is equivalent to:

  final example = ScopedProvider<int>((watch) => throw UnimplementedError(''));
  

• Fixed a bug where context.refresh may not work properly if the widget tree contains multiple ProviderScope.

• Fixed a bug where when disposing ProviderContainer, providers may be disposed in an incorrect order.
• Improved the performances of reading providers by 25%

• 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:

  final provider = Provider(...);
  final example = Computed((watch) {
    final value = watch(provider);
    return value;
  });
  

  into:

  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<T>) no longer returns a Stream<T> but an AsyncValue<T> Before:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Stream<T> stream = ref.read(streamProvider);
  });
  

  After:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Stream<T> stream = ref.watch(streamProvider.steam);
  });
  

• ref.read(FutureProvider<T>) no longer returns a Future<T> but an AsyncValue<T>

  Before:

  final futureProvider = FutureProvider<T>(...);
  final example = Provider((ref) {
    Future<T> future = ref.read(futureProvider);
  });
  

  After:

  final futureProvider = FutureProvider<T>(...);
  final example = Provider((ref) {
    Future<T> future = ref.watch(futureProvider.future);
  });
  

• Removed ref.dependOn. You can now use ref.read/ref.watch to achieve the same effect.

  Before:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Future<T> last = ref.dependOn(streamProvider).last;
  });
  

  After:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Future<T> last = ref.watch(streamProvider.last);
  });
  

• Provider.readOwner(ProviderStateOwner) is changed into ProviderContainer.read(Provider)

• Provider.watchOwner(ProviderStateOwner, (value) {}) is changed into:

  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.

• Fixed the documentation of StateNotifierProvider incorrectly showing the documentation of StreamProvider.
• Improve the documentation of StateProvider.

• 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

Changed the syntax of "AutoDispose*" and "*Family" to use a syntax similar to named constructors instead.

Before:

final myProvider = AutoDisposeStateNotifierProviderFamily<MyStateNotifier, int>((ref, id) {
  return MyStateNotifier(id: id);
});

After:

final myProvider = StateNotifierProvider.autoDispose.family<MyStateNotifier, int>((ref, id) {
  return MyStateNotifier(id: id);
});

The behavior is the same. Only the syntax changed.

• 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.

• Computed now correctly unsubscribe to a provider when their function stops using a provider.

• 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.

Initial release

<!-- cSpell:ignoreRegExp @\w+ -->