riverpod

• Update devtool extension

• Deprecated SyncProviderTransformerMixin. It is replaced by the newly added APIs
• Devtool-only: Better support for scoped providers with multiple overrides.
• Upgraded analyzer to <15.0.0
• Added CustomProviderListenable, a slightly simplified way of making custom provider extensions
• Added the ability to do ValueListenable<int> listenable = ref.watch(counterProvider.listenable). This uses the new pkg:listen.
• Fix invalidate/refresh not finding providers and families when called from a scoped ProviderContainer/ProviderScope with overrides, if the provider was never read through that scope. (thanks to @itsUndefined)
• Fix markNeedsBuild exception when flushing a provider inside Widget lifecycle
• Fix invalidate/refresh not finding providers and families when called from a scoped ProviderScope with overrides, if the provider was never read through that scope. (thanks to @itsUndefined)
• Fixed a listener leak if ConsumerState.dispose threw.

• Fixes assertion error when providers are unpaused.
• Fix AsyncNotifierProvider/StreamNotifierProvider disposing dependencies watched after an asynchronous gap during rebuild. (thanks to @a1573595)
• Devtool-only: Fixed a TapGestureRecognizer leak in the state inspector, where the recognizer was recreated on every rebuild and never disposed. (thanks to @Gyeony95)
• Fix Mutation.run throwing a StateError ("subscription was closed") when the ProviderContainer was disposed while the mutation was still running. (thanks to @Gyeony95)
• Fix Mutation.reset not cancelling an in-flight run. The pending run could previously write its result back over the reset state once it completed. (thanks to @Gyeony95)

• Fixed Riverpod devtool not starting.

• Devtool-only: Added debugTrackProviderCreation, which can be set to true to enable the Riverpod devtool to jump to the source of a provider.

• Added Ref.onManualInvalidation() lifecycle method to listen for manual provider invalidations. This allows distinguishing between manual invalidations (via refresh/invalidate/invalidateSelf) and automatic invalidations caused by dependency changes. Additionally, providers can now forward invalidations to other providers within onManualInvalidation callbacks, enabling patterns like:

  final sourceProvider = Provider<String>(...);
  final derivedProvider = Provider((ref) {
    final thing = ref.watch(sourceProvider);
    ref.onManualInvalidation(() {
      ref.invalidate(sourceProvider);
    });
    return '$thing is derived!';
  });
  
  ref.invalidate(derivedProvider); // also invalidates sourceProvider!
  

  Which allows for users to invalidate only the providers they care about, while implementation details can be handled privately. (thanks to @TekExplorer)

• Added ProviderContainer.allProviders(), to obtain all providers accessible from said container. You can optionally specify allProviders(family: myFamily) to only include providers from said family.

• Refactored internal scheduling mechanism to solve some markNeedsBuild error.

• Removed @internal for ProviderFamily.new

• Added various life-cycles to ProviderObserver

• Fix .future incorrectly notifying listeners even when AsyncValue doesn't change.

• Fixed a bug where resuming a paused provider could cause it to never notify its listener ever again.

• Added missing weak flags to WidgetRef.listen/listenManual
• Added Ref.isPaused to check if there are any active/non-paused listeners.
• Deprecated family.overrideWith in favour of family.overrideWith2 The behaviour is the same, but the callback now takes the argument as a parameter. In 4.0.0, overrideWith2 will be renamed to overrideWith.
• Fix a regression that caused Notifiers to lose their state when one of their dependencies changed. (thanks to @yegair)
• Fixed ref.mounted returning true for stale refs after provider rebuild, causing race conditions in async providers.
• Fixed a bug where providers with only weak listeners (ref.listen(..., weak: true)) would incorrectly initialize during hot reload (thanks to @tguerin)
• Fixes selectAsync sometimes throwing an exception when unsubscribed to.

• Added an alternative way to combine asynchronous providers. This can be done by using AsyncValue.requireValue inside FutureProvider/AsyncNotifier like so:

  final sumProvider = FutureProvider((ref) { // Not async
    AsyncValue<int> a = ref.watch(aProvider);
    AsyncValue<int> b = ref.watch(bProvider);
  
    // The following is safe if used inside the init function of providers.
    return a.requireValue + b.requireValue;
  })
  

  This enables synchronously combining asynchronous providers.

  See AsyncValue.requireValue

• Fixed a bug with scoping when specifying dependencies: [...]

• Added Override.origin. This enables knowing which provider is associated with an override.

• Fix a regression with AsyncLoading.isRefreshing/isReloading

• Fixed a false positive incorrectly causing Providers are not allowed to modify other providers during their initialization.

• Improve the error message when a circular dependency error is thrown

• Now supports Dart 3.7.0
• Support async 2.12.0

Finally, a stable release for Riverpod 3.0!

For the full changelog, check out https://riverpod.dev/docs/whats_new

• A provider that is currently being retried is now flagged as "loading" while the retry attempts complete. Meaning that ref.watch(provider.future) skips the intermediate error states.
• Fix an issue with the internals of AsyncValue
• ProviderObserver is now marked with base
• Fix provider rebuild order issue.
• Fix "Tried to refresh x multiple times in the same frame" incorrectly triggering.
• Removed FamilyNotifier and variants, in favour of Notifier.
• Preserve persisted state if a provider throws.
• provider.future will now skip offline-persisted state by default. This avoids awkward unexpected provider rebuild when chaining persisted providers.
• Made Mutation.call generic. This allows for better compatibility with generic-returning functions (thanks to @TekExplorer)

• Added MutationState.isPending/isIdle/hasError/isSuccess
• fixes various "pause" issues
• Bump minimum meta version
• Added AsyncValue.retrying, to check when a retry is scheduled or pending
• Exposed the default retry implementation (ProviderContainer.defaultRetry)
• Offline's Storage now is base and requires overriding deleteOutOfDate
• Make AsyncValue.copyWithPrevious @internal. This API was not meant to be public.

• Added Async/SyncProviderTransformerMixin. Those enable making custom ProviderListenables using a reasonably simple syntax. For instance, you could implement your own provider.select
• Reworked mutations to work without code-generation
• Added AsyncResult. This is an interface shared between AsyncData and AsyncError, but not AsyncLoading.
• Revert Notifier life-cycle change. They are once again preserved across rebuilds.
• Provider errors are now reported to the ProviderContainer's Zone instead of whatever last used the provider.
• Breaking: When a ref.watch/ref.read rethrows an error, the error is now wrapped in a ProviderException.
• Use TickerMode instead of Visibility for pausing out-of-view widgets
• Reworked offline to simplify its usage
• Added widget test helper to find a ProviderContainer in the widget tree: tester.container() (thanks to @Luckey-Elijah)

• Docs update
• Fix an AsyncValue bug

Some docs/internal changes

• Attempt to fix a runtime error in Javascript builds

Say hello to Riverpod 3.0.0! This major version is a transition version, to unblock the development of the project. It is quite possible that a 4.0.0 will be released relatively soon in the future, so keep that in mind when migrating.

Here are some highlights about this version:

• Offline and mutation support, as experimental features
• Automatic retry support
• Pause/resume support
• Simplification of various aspects of the API (such as fusing AutoDisposeNotifier/Notifier)
• Added a Ref.mounted to simplify dealing with provider disposal
• Improved testing with the new ProviderContainer.test() and the ability to mock a Notifier's build method without mocking the whole object using provider.overrideWithBuild(...)

Note about experimental features: Anything imported with package:riverpod/experimental/....dart are not stable features. They may be modified in breaking ways without a major version. Use with care!

Full change list

• Breaking: ChangeNotifierProvider, StateProvider and StateNotifierProvider are moved out of package:hooks_riverpod/hooks_riverpod.dart to package:hooks_riverpod/legacy.dart.
• Failing providers are now automatically retried after a delay. The delay can be optionally configured.
• Allow using Ref synchronously after a provider has been invalidated. This avoids mounted exceptions when doing multiple operations in a quick succession.
• Breaking: All providers now use == to compare previous/new values and filter updates. If you want to revert to the old behavior, you can override updateShouldNotify inside Notifiers.
• Instead of Provider.autoDispose() and Provider.autoDispose.family(), it is now possible to write Provider(isAutoDispose: true) and Provider.family(isAutoDispose: true).
• Breaking: ProviderListenable.addListener is deleted and now internal-only. A simpler alternative will be added in the future.
• Breaking: ProviderObserver methods have been updated to take a ProviderObserverContext parameter. This replaces the old provider+container parameters, and contains extra information.
• Breaking: Removed all Ref subclasses (such FutureProviderRef). Use Ref directly instead. For FutureProviderRef.future, migrate to using an AsyncNotifier.
• Breaking All ref and notifier methods besides "mounted" now throw if used after getting disposed.
• Breaking: StateProvider and StateNotifierProvider are moved out of package:flutter_riverpod/flutter_riverpod.dart to package:flutter_riverpod/legacy.dart.
• Breaking Some internal utils are no-longer exported.
• Breaking AsyncValue.value now returns null during errors.
• Breaking removed AsyncValue.valueOrNull (use .value instead).
• Stream/FutureProvider.overrideWithValue was added back.
• Breaking: Notifier and variants are now recreated whenever the provider rebuilds. This enables using Ref.mounted to check dispose.
• Breaking: StreamProvider now pauses its StreamSubscription when the provider is not actively listened.
• Breaking: Calling ref.watch multiple times calls ref.onListen every-times.
• Breaking: A provider is now considered "paused" if all of its listeners are also paused. So if a provider A is watched only by a provider B, and B is currently unused, then A will be paused.
• Breaking: When an asynchronous provider rebuilds, it doesn't immediately stops listening to its previous providers. Instead, those subscriptions are removed when the rebuild completes. This impacts how "auto-dispose" behaves. See https://github.com/rrousselGit/riverpod/issues/1253
• Fix StreamProvider not cancelling the StreamSubscription if the stream is never emitted any value.
• All Ref life-cycles (such as Ref.onDispose) and Notifier.listenSelf now return a function to remove the listener.
• Added methods to ProviderObserver for listening to "mutations". Mutations are a new code-generation-only feature. See riverpod_generator's changelog for more information.
• Added Ref.listen(..., weak: true). When specifying weak: true, the listener will not cause the provider to be initialized. This is useful when wanting to react to changes to a provider, but not trigger a network request if not necessary.
• AsyncValue now has an optional progress field. This can be set by providers to allow the UI to show a custom progress logic.
• An error is now thrown when trying to override a provider twice in the same ProviderContainer.
• Disposing a ProviderContainer now disposes of all of its sub ProviderContainers too.
• Added ProviderSubscription.pause()/.resume(). This enables temporarily stopping the subscription to a provider, without it possibly loosing its state when using autoDispose.
• Added ProviderContainer.test(). This is a custom constructor for testing purpose. It is meant to replace the createContainer utility.
• Added NotifierProvider.overrideWithBuild, to override Notifier.build without overriding methods of the notifier.
• Ref.mounted has been added. It can now be used to check if a provider was disposed.
• When a provider is rebuilt, a new Ref is now created. This avoids issues where an old build of a provider is still performing work.
• Updated AsyncValue documentations to use pattern matching.
• Added support for Ref/ProviderContainer.invalidate(provider, asReload: true)
• Failing providers are now automatically retried after a delay. The delay can be optionally configured.
• Fixed a bug when overriding a specific provider of a family, combined with dependencies: [family]

• Added AsyncNotifier.listenSelf. It was mistakenly absent from the 2.6.0 release

• Deprecated all Ref subclasses. Instead, use Ref itself.
• Deprecated Ref's type argument. Use Ref without its generic parameter instead.
• Deprecated any Ref member that used Ref's generic (such as Ref.state or Ref.listenSelf). Instead, use a Notifier.
• Added Notifier.listenSelf, as a replacement to Ref.listenSelf.
• Ref.watch and other methods now accept auto-dispose providers too.

• Fixed a typo in the documentation (thanks to @ljbkusters)

• Improved Provider(dependencies: [...]) documentation.
• Fix out of date pub.dev description
• ref.invalidate now correctly clear all resources associated with the provider if the provider is no-longer used.
• Fix selectAsync sometimes never resolving.
• Fix ProviderSubscription.read returned by ref.listen(provider.future) not throwing if used after the subscription has been closed.
• Fix ref.onAddListener and other life-cycles not being triggered when listening to provider.future/provider.notifier.
• Fix a bug that caused Assertion failed: _lastFuture == null

• Add test argument to AsyncValue.guard method. (thanks to @utamori)

• Fix "pending timer" issue inside tests when using ref.keepAlive().
• Fix Ref.invalidate/Ref.refresh not throwing on circular dependency.
• Fix an infinite loop caused by ref.keepAlive if the KeepAliveLink is immediately closed.
• Fix container.exists(provider) on nested containers not checking their parent containers.

Fix exceptions when using multiple root ProviderContainers/ProviderScopes.

• Fix ProviderObserver.didUpdateProvider being called with an incorrect "provider" parameter when the provider is overridden.

• Exceptions in asynchronous providers are now correctly received by ProviderObserver.providerDidFail.
• Fix exception when a ProviderScope is rebuilt with a different key.

• Update the documentation of provider.argument to match the behavior of generated providers.

• Fixed incorrect @visibleForTesting warning.

• Fix invalid Dart docs (thanks to @srawlins)

• Added Notifier.stateOrNull. This will return null if used when the notifier has yet to be initialized or is in error state.

Riverpod now requires package:meta >=1.9.0

• Added support for state_notifier 1.0.0
• Notifier.state is now accessible inside tests

• Improved error message for missing dependencies (thanks to @ValentinVignal)
• Fixed various typos in the documentation (thanks to @ValentinVignal)
• Fix not disposing autoDispose family providers

• fix AsyncValue.isReloading docs

• Fixes an issue with nested ProviderScope (thanks to @jeiea)

• The debugger no-longer pauses on uncaught exceptions inside providers. This was voluntary, but too many people have complained that it often is a false positive.
• Removed unused dependency (thanks to @passsy)

• Deprecated the generic parameter of Family. This will enable implementing generic providers in riverpod_generator once it is removed.
• Updated documentation

• Updated AsyncValue.value/valueOrNull docs to cover the "previous value" cases (thanks to @AhmedLSayed9)

• Added StreamNotifier + StreamNotifierProvider. This is for building a StreamProvider while exposing ways to modify the stream.

  It is primarily meant to be used using code-generation via riverpod_generator, by writing:

  @riverpod
  class Example extends _$Example {
    @override
    Stream<Model> build() {
      // TODO return some stream
    }
  }
  

• Deprecated StreamProvider.stream Instead of:

  ref.watch(provider.stream).listen(...)
  

  do:

  ref.listen(provider, (_, value) {...});
  

  Instead of:

  final a = StreamProvider((ref) {
    return ref.watch(b.stream).map((e) => Model(e));
  })
  

  Do:

  final a = FutureProvider((ref) async {
    final e = await ref.watch(b.future);
    return Model(e);
  })
  

• Some restrictions on the dependencies parameter of providers have been lifted. It is no-longer necessary to include providers which do not themselves specify dependencies. All providers should specify dependencies if they are scoped at any point.

• Annotated Notifier.state setter as protected.

• Improve type-inference when using AsyncValue.whenOrNull (thanks to @AhmedLSayed9)
• Fixed AsyncValue.asError incorrectly not preserving the generic type
• Internal refactoring for riverpod_generator

Fixes an issue with FutureProvider<void> (#2028)

• Update dependencies.
• fixes an exception on newer Dart versions
• fixes an edge-case where FutureProvider/AsyncNotifier did not emit the new state when the created Future completed (#1997)
• fixes errors inside FutureProvider/AsyncNotifier/StreamProvider not preserving the previous state (if any).

Fix typos

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(..., isRefresh: 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)

• FIX: Fixed an assert error if a family depends on itself while specifying dependencies. (#1721).

Updated changelog (see 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

Fix Timer leak when using cacheTime/disposeDelay and disposing a ProviderContainer

fix: a bug where unmounting a nested ProviderScope could cause an exception (#1400)

Upgrade minimum required Dart SDK version to 2.17.0