Add manual invalidation support to provider invalidation logic

Author: TekExplorer

packages/riverpod/lib/src/core/element.dart

@@ -514,7 +514,7 @@ depending on itself.
     _debugCurrentCreateHash = provider.debugGetCreateSourceHash();
 
     if (previousHash != _debugCurrentCreateHash) {
-      invalidateSelf(asReload: false);
+      invalidateSelf(asReload: false, manual: false);
     }
   }
 
@@ -714,7 +714,7 @@ depending on itself.
         _pendingRetryTimer = Timer(duration, () {
           _pendingRetryTimer = null;
           _retryCount++;
-          invalidateSelf(asReload: false);
+          invalidateSelf(asReload: false, manual: false);
         });
       });
     }
@@ -746,13 +746,22 @@ The provider ${_debugCurrentlyBuildingElement!.origin} modified $origin while bu
     debugCanModifyProviders?.call();
   }
 
-  void invalidateSelf({required bool asReload}) {
+  void invalidateSelf({required bool asReload, required bool manual}) {
     if (!_didMount) return;
 
     if (asReload) _didChangeDependency = true;
     if (_mustRecomputeState) return;
 
     _mustRecomputeState = true;
+
+    // Call manual invalidation listeners before runOnDispose clears them
+    if (manual) {
+      final onManualInvalidationListeners = ref?._onManualInvalidationListeners;
+      if (onManualInvalidationListeners != null) {
+        _runCallbacks(container, onManualInvalidationListeners);
+      }
+    }
+
     runOnDispose();
     mayNeedDispose();
     container.scheduler.scheduleProviderRefresh(this);
@@ -1193,6 +1202,7 @@ $this''',
     ref._onRemoveListeners = null;
     ref._onChangeSelfListeners = null;
     ref._onErrorSelfListeners = null;
+    ref._onManualInvalidationListeners = null;
     _didCancelOnce = false;
 
     assert(

packages/riverpod/lib/src/core/provider_container.dart

@@ -977,10 +977,10 @@ final class ProviderContainer implements Node, MutationTarget {
       case ProviderBase<Object?>():
         _pointerManager
             .readElement(provider)
-            ?.invalidateSelf(asReload: asReload);
+            ?.invalidateSelf(asReload: asReload, manual: !asReload);
       case Family():
         for (final element in _pointerManager.listFamily(provider)) {
-          element.invalidateSelf(asReload: asReload);
+          element.invalidateSelf(asReload: asReload, manual: !asReload);
         }
     }
   }

packages/riverpod/lib/src/core/ref.dart

@@ -50,6 +50,7 @@ sealed class Ref implements MutationTarget {
   List<void Function()>? _onCancelListeners;
   List<void Function()>? _onAddListeners;
   List<void Function()>? _onRemoveListeners;
+  List<void Function()>? _onManualInvalidationListeners;
 
   /// Whether we're initializing this provider for the first time.
   ///
@@ -332,7 +333,36 @@ final <yourProvider> = Provider(dependencies: [<dependency>]);
   void invalidateSelf({bool asReload = false}) {
     _throwIfInvalidUsage();
 
-    _element.invalidateSelf(asReload: asReload);
+    _element.invalidateSelf(asReload: asReload, manual: !asReload);
+  }
+
+  /// {@template riverpod.onManualInvalidation}
+  /// A life-cycle for whenever this provider is manually invalidated, as opposed
+  /// to automatic invalidation caused by dependency changes.
+  ///
+  /// This callback is triggered when:
+  /// - [invalidateSelf] with `asReload: false` (the default)
+  /// - [invalidate] with `asReload: false` (the default) on this provider
+  /// - [refresh] on this provider
+  ///
+  /// This callback is NOT triggered when:
+  /// - A dependency watched with [watch] changes
+  /// - [invalidateSelf] or [invalidate] with `asReload: true`
+  ///
+  /// Returns a function which can be called to remove the listener.
+  ///
+  /// See also:
+  /// - [invalidateSelf], to invalidate this provider
+  /// - [refresh], to forcefully re-evaluate a provider
+  /// {@endtemplate}
+  @experimental
+  RemoveListener onManualInvalidation(void Function() cb) {
+    _throwIfInvalidUsage();
+
+    final list = _onManualInvalidationListeners ??= [];
+    list.add(cb);
+
+    return () => list.remove(cb);
   }
 
   /// Notify dependents that this provider has changed.