fix: don't notify signals tracking AsyncSignal.future when transitioning to loading state

Author: Yegair

packages/signals_core/lib/src/async/computed.dart

@@ -14,6 +14,21 @@ import 'future.dart';
 /// ```
 ///
 /// Since all dependencies are passed in as arguments there is no need to worry about calling the signals before any async gaps with await.
+///
+/// If async signals need to be tracked across an async gap and they are being awaited via their `.future`,
+/// then use their `.completion` for the dependencies rather than the async signal itself.
+/// This way the `computedFrom` will be reset when the tracked signal completes, effectively ignoring their transition into a loading state.
+///
+/// ```dart
+/// final count = asyncSignal(AsyncData(0));
+///
+/// final s = computedFrom([count.completion], (_) async => await count.future);
+///
+/// await s.future; // 0
+/// count.value = AsyncLoading(); // ignored by the computedFrom
+/// count.value = AsyncData(1);
+/// await s.future; // 1
+/// ```
 FutureSignal<T> computedFrom<T, A>(
   List<ReadonlySignal<A>> signals,
   Future<T> Function(List<A> args) fn, {

packages/signals_core/lib/src/async/future.dart

@@ -170,6 +170,24 @@ class FutureSignal<T> extends StreamSignal<T> {
   /// count.value = 1; // resets the future
   /// s.value; // state with count 1
   /// ```
+  ///
+  /// If other async signals need to be tracked across an async gap and they are being awaited via their `.future`,
+  /// then use their `.completion` for the dependencies rather than the async signal itself.
+  /// This way the `futureSignal` will be reset when the tracked signal completes, effectively ignoring their transition into a loading state.
+  ///
+  /// ```dart
+  /// final count = asyncSignal(AsyncData(0));
+  ///
+  /// final s = futureSignal(
+  ///     () async => await count.future,
+  ///     dependencies: [count.completion],
+  /// );
+  ///
+  /// await s.future; // 0
+  /// count.value = AsyncLoading(); // ignored by the future signal
+  /// count.value = AsyncData(1);
+  /// await s.future; // 1
+  /// ```
   /// @link https://dartsignals.dev/async/future
   /// {@endtemplate}
   FutureSignal(

packages/signals_core/lib/src/async/signal.dart

@@ -1,7 +1,5 @@
 import 'dart:async';
 
-import 'package:meta/meta.dart';
-
 import '../core/signals.dart';
 import '../mixins/event_sink.dart';
 import 'state.dart';
@@ -173,60 +171,77 @@ class AsyncSignal<T> extends Signal<AsyncState<T>>
     super.value, {
     super.debugLabel,
     super.autoDispose,
-  }) : _initialValue = value;
+  })  : _initialValue = value,
+        _completion = _AsyncCompletionSignal<T>(
+          initialValue: value,
+          debugLabel: debugLabel != null ? '${debugLabel}_completion' : null,
+        );
+
+  @override
+  void dispose() {
+    _completion.dispose();
+    super.dispose();
+  }
 
   final AsyncState<T> _initialValue;
   bool _initialized = false;
 
-  /// Internal Completer for values
-  @internal
-  Completer<bool> completer = Completer<bool>();
+  final _AsyncCompletionSignal<T> _completion;
+
+  /// Tracks the async completion of this signal.
+  ///
+  /// Notifies if the value of this signal changes to [AsyncData] or [AsyncError],
+  /// but not if it changes to [AsyncLoading].
+  ///
+  /// Intended to be used for tracking dependencies across async gaps,
+  /// when awaiting the [future] of this signal.
+  ///
+  /// ```dart
+  /// computedFrom([someAsyncSignal.completion], (_) async {
+  ///   await Future.delayed(const Duration(seconds: 1));
+  ///   return await someAsyncSignal.future;
+  /// });
+  /// ```
+  ReadonlySignal<Future<T>> get completion => _completion;
 
   /// The future of the signal completer
-  Future<T> get future async {
-    value;
-    await completer.future;
-    return value.requireValue;
-  }
+  Future<T> get future => completion.value;
 
   /// Returns true if the signal is completed an error or data
   bool get isCompleted {
-    value;
-    return completer.isCompleted;
+    future;
+    return _completion.isCompleted;
+  }
+
+  @override
+  bool set(AsyncState<T> val, {bool force = false}) {
+    return batch(() {
+      _completion.setValue(val);
+      return super.set(val, force: force);
+    });
   }
 
   /// Set the error with optional stackTrace to [AsyncError]
   void setError(Object error, [StackTrace? stackTrace]) {
-    batch(() {
-      value = AsyncState.error(error, stackTrace);
-      if (completer.isCompleted) completer = Completer<bool>();
-      completer.complete(true);
-    });
+    set(AsyncState.error(error, stackTrace));
   }
 
   /// Set the value to [AsyncData]
   void setValue(T value) {
-    batch(() {
-      this.value = AsyncState.data(value);
-      if (completer.isCompleted) completer = Completer<bool>();
-      completer.complete(true);
-    });
+    set(AsyncState.data(value));
   }
 
   /// Set the loading state to [AsyncLoading]
   void setLoading([AsyncState<T>? state]) {
-    batch(() {
-      value = state ?? AsyncState.loading();
-      completer = Completer<bool>();
-    });
+    set(state ?? AsyncState.loading());
   }
 
   /// Reset the signal to the initial value
   void reset([AsyncState<T>? value]) {
     batch(() {
-      this.value = value ?? _initialValue;
+      super.value = value ?? _initialValue;
       _initialized = false;
-      if (completer.isCompleted) completer = Completer<bool>();
+      _completion.setValue(const AsyncLoading());
     });
   }
 
@@ -435,3 +450,69 @@ AsyncSignal<T> asyncSignal<T>(
     autoDispose: autoDispose,
   );
 }
+
+class _AsyncCompletionSignal<T> extends Signal<Future<T>> {
+  _AsyncCompletionSignal._(
+    Completer<T> completer, {
+    required super.debugLabel,
+  })  : _completer = completer,
+        super(_ignoreUncaughtErrors(completer.future));
+
+  factory _AsyncCompletionSignal({
+    required AsyncState<T> initialValue,
+    required String? debugLabel,
+  }) {
+    final completer = Completer<T>();
+
+    switch (initialValue) {
+      case AsyncLoading():
+        break;
+
+      case AsyncData(:final value):
+        completer.complete(value);
+        break;
+
+      case AsyncError(:final error, :final stackTrace):
+        completer.completeError(error, stackTrace);
+        break;
+    }
+
+    return _AsyncCompletionSignal._(completer, debugLabel: debugLabel);
+  }
+
+  Completer<T> _completer;
+
+  bool _initialized = false;
+  bool get isCompleted => _initialized && _completer.isCompleted;
+
+  void setValue(AsyncState<T> value) {
+    if (_completer.isCompleted) {
+      _completer = Completer<T>();
+      this.value = _ignoreUncaughtErrors(_completer.future);
+    }
+
+    switch (value) {
+      case AsyncLoading():
+        return;
+
+      case AsyncData(:final value):
+        _initialized = true;
+        _completer.complete(value);
+        return;
+
+      case AsyncError(:final error, :final stackTrace):
+        _initialized = true;
+        _completer.completeError(error, stackTrace);
+        return;
+    }
+  }
+
+  static Future<T> _ignoreUncaughtErrors<T>(Future<T> future) {
+    // Makes sure the future never reports an uncaught error to
+    // the current zone. Seems to be necessary to avoid uncaught
+    // errors to be reported when async signals are being used
+    // synchronously, i.e. when their .future is not used.
+    future.ignore();
+    return future;
+  }
+}

packages/signals_core/lib/src/async/stream.dart

@@ -356,6 +356,17 @@ class StreamSignal<T> extends AsyncSignal<T> {
     return super.value;
   }
 
+  @override
+  Future<T> get future {
+    untracked(() {
+      // make sure the stream is exectuted,
+      // so the returned future will be completed eventually
+      value;
+    });
+
+    return super.future;
+  }
+
   @override
   void setError(Object error, [StackTrace? stackTrace]) {
     super.setError(error, stackTrace);

packages/signals_core/test/async/computed_test.dart

@@ -27,6 +27,29 @@ void main() {
       expect(result, 10);
     });
 
+    test('computedAsync with .future dependencies', () async {
+      var calls = 0;
+      final count = asyncSignal(AsyncData(0));
+
+      final s = computedAsync(() async {
+        calls++;
+        final future = count.future;
+        await Future.delayed(const Duration(milliseconds: 5));
+        return await future;
+      });
+
+      await expectLater(s.future, completion(0));
+      expect(calls, 1);
+
+      count.value = AsyncLoading();
+      final loadingExpectation = expectLater(s.future, completion(1));
+
+      count.value = AsyncData(1);
+      await expectLater(s.future, completion(1));
+      expect(calls, 2);
+      await loadingExpectation;
+    });
+
     test('computedFrom', () async {
       Future<int> future(List<int> ids) async {
         await Future.delayed(const Duration(milliseconds: 5));
@@ -49,6 +72,28 @@ void main() {
       expect(result, 10);
     });
 
+    test('computedFrom with .completion dependencies', () async {
+      var calls = 0;
+      final count = asyncSignal(AsyncData(0));
+
+      final s = computedFrom([count.completion], (_) async {
+        calls++;
+        await Future.delayed(const Duration(milliseconds: 5));
+        return await count.future;
+      });
+
+      await expectLater(s.future, completion(0));
+      expect(calls, 1);
+
+      count.value = AsyncLoading();
+      final loadingExpectation = expectLater(s.future, completion(1));
+
+      count.value = AsyncData(1);
+      await expectLater(s.future, completion(1));
+      expect(calls, 2);
+      await loadingExpectation;
+    });
+
     test('check repeated calls', () async {
       int calls = 0;