orElse callback when retries are exhausted

retry/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v3.2.0
+ * `orElse` callback to calculate a value when the attempts where exhausted.
+
 ## v3.1.0
  * Stable null-safety release.
 

retry/lib/retry.dart

@@ -118,10 +118,15 @@ class RetryOptions {
   /// If no [retryIf] function is given this will retry any for any [Exception]
   /// thrown. To retry on an [Error], the error must be caught and _rethrown_
   /// as an [Exception].
+  ///
+  /// If [orElse] is given and the [attemps] are exhausted by retryable
+  /// exceptions (either by default or via [retryIf]), the function will
+  /// return the result of [orElse].
   Future<T> retry<T>(
     FutureOr<T> Function() fn, {
     FutureOr<bool> Function(Exception)? retryIf,
     FutureOr<void> Function(Exception)? onRetry,
+    FutureOr<T> Function(Exception)? orElse,
   }) async {
     var attempt = 0;
     // ignore: literal_only_boolean_expressions
@@ -132,6 +137,10 @@ class RetryOptions {
       } on Exception catch (e) {
         if (attempt >= maxAttempts ||
             (retryIf != null && !(await retryIf(e)))) {
+          if (orElse != null) {
+            return await orElse(e);
+          }
+
           rethrow;
         }
         if (onRetry != null) {
@@ -171,6 +180,10 @@ class RetryOptions {
 /// If no [retryIf] function is given this will retry any for any [Exception]
 /// thrown. To retry on an [Error], the error must be caught and _rethrown_
 /// as an [Exception].
+///
+/// If [orElse] is given and the [attemps] are exhausted by retryable
+/// exceptions (either by default or via [retryIf]), the function will
+/// return the result of [orElse].
 Future<T> retry<T>(
   FutureOr<T> Function() fn, {
   Duration delayFactor = const Duration(milliseconds: 200),
@@ -179,10 +192,16 @@ Future<T> retry<T>(
   int maxAttempts = 8,
   FutureOr<bool> Function(Exception)? retryIf,
   FutureOr<void> Function(Exception)? onRetry,
+  FutureOr<T> Function(Exception)? orElse,
 }) =>
     RetryOptions(
       delayFactor: delayFactor,
       randomizationFactor: randomizationFactor,
       maxDelay: maxDelay,
       maxAttempts: maxAttempts,
-    ).retry(fn, retryIf: retryIf, onRetry: onRetry);
+    ).retry(
+      fn,
+      retryIf: retryIf,
+      onRetry: onRetry,
+      orElse: orElse,
+    );

retry/pubspec.yaml

@@ -1,5 +1,5 @@
 name: retry
-version: 3.1.0
+version: 3.2.0
 description: |
   Utility for wrapping an asynchronous function in automatic retry logic with
   exponential back-off, useful when making requests over network.

retry/test/retry_test.dart

@@ -131,5 +131,35 @@ void main() {
       await expectLater(f, throwsA(isException));
       expect(count, equals(2));
     });
+
+    test('retry + orElse', () async {
+      var count = 0;
+      final v = await retry(
+        () async {
+          count++;
+          throw Exception();
+        },
+        orElse: (_) => 1,
+        maxAttempts: 3,
+      );
+      expect(count, 3);
+      expect(v, 1);
+    });
+
+    test('retry + orElse throws', () async {
+      var count = 0;
+      await expectLater(
+        () => retry(
+          () async {
+            count++;
+            throw Exception('fn');
+          },
+          orElse: (_) => throw FormatException('orElse'),
+          maxAttempts: 3,
+        ),
+        throwsA(isA<FormatException>()),
+      );
+      expect(count, 3);
+    });
   });
 }