smart_retry 🔄 #

Stop writing the same try/catch/for-loop boilerplate in every project.

A production-ready, pure-Dart package for intelligent async retry logic:

• ✅ Exponential / linear / constant backoff — grows delay between retries
• ✅ Full / equal / decorrelated jitter — prevents thundering herd problems
• ✅ retryIf predicate — only retry transient errors, abort on permanent ones
• ✅ onRetry callback — rich [RetryContext] before each sleep
• ✅ Lifecycle event stream — plug in any logger / crash reporter
• ✅ previewSchedule — inspect the delay table without executing
• ✅ Typed exceptions — MaxAttemptsExceededException & NonRetryableException
• ✅ Zero runtime dependencies (only meta)
• ✅ 100% Pure Dart — Flutter, Dart CLI, server-side

Table of Contents #

1. Installation
2. Quick Start
3. API Reference
   • SmartRetry.run
   • SmartRetry.runWithOptions
   • RetryOptions
   • BackoffStrategy
   • JitterStrategy
   • RetryContext
   • Event Stream
   • previewSchedule
4. Exception Handling
5. Delay Schedule Reference
6. Strategy Comparison
7. Advanced Recipes
8. Contributing
9. License

Installation #

# pubspec.yaml
dependencies:
  smart_retry: ^1.0.0

dart pub get
# or
flutter pub get

Quick Start #

import 'dart:io';
import 'package:smart_retry/smart_retry.dart';

// ── Minimal ──────────────────────────────────────────────────────────────────
final data = await SmartRetry.run(
  () => api.fetchUser(id: 42),
  maxAttempts: 5,
  retryIf: (e) => e is SocketException,
);

// ── With logging ──────────────────────────────────────────────────────────────
final data = await SmartRetry.run(
  () => api.fetchUser(id: 42),
  maxAttempts: 5,
  retryIf: (e) => e is SocketException || e is TimeoutException,
  onRetry: (ctx) => print(
    '[${ctx.attemptNumber}/${ctx.maxAttempts}] '
    'Retry in ${ctx.nextDelay.inMilliseconds}ms — ${ctx.lastException}',
  ),
);

// ── Handle errors explicitly ─────────────────────────────────────────────────
try {
  final data = await SmartRetry.run(() => api.fetchUser(id: 42));
} on MaxAttemptsExceededException catch (e) {
  print('Failed after ${e.attempts} tries: ${e.lastException}');
} on NonRetryableException catch (e) {
  print('Permanent error, not retrying: ${e.cause}');
}

API Reference #

SmartRetry.run #

The primary API. All parameters are optional with production-ready defaults.

static Future<T> run<T>(
  Future<T> Function() fn, {
  int maxAttempts = 3,
  Duration initialDelay = const Duration(milliseconds: 500),
  Duration maxDelay = const Duration(seconds: 30),
  double factor = 2.0,
  BackoffStrategy backoffStrategy = BackoffStrategy.exponential,
  JitterStrategy jitterStrategy = JitterStrategy.full,
  FutureOr<bool> Function(Exception e)? retryIf,
  void Function(RetryContext context)? onRetry,
  bool debugMode = false,
})

SmartRetry.runWithOptions #

Preferred for shared configuration across multiple call-sites.

static Future<T> runWithOptions<T>(
  Future<T> Function() fn, {
  required RetryOptions options,
})

// Define once
final _retry = RetryOptions(
  maxAttempts: 4,
  retryIf: (e) => e is SocketException,
);

// Reuse everywhere
final user  = await SmartRetry.runWithOptions(() => api.getUser(),  options: _retry);
final posts = await SmartRetry.runWithOptions(() => api.getPosts(), options: _retry);

RetryOptions #

Immutable configuration value object. Supports copyWith for derivation.

const RetryOptions({
  int maxAttempts = 3,
  Duration initialDelay = const Duration(milliseconds: 500),
  Duration maxDelay = const Duration(seconds: 30),
  double factor = 2.0,
  BackoffStrategy backoffStrategy = BackoffStrategy.exponential,
  JitterStrategy jitterStrategy = JitterStrategy.full,
  FutureOr<bool> Function(Exception e)? retryIf,
  void Function(RetryContext context)? onRetry,
  bool debugMode = false,
})

// Base config
const base = RetryOptions(maxAttempts: 4, retryIf: _isTransient);

// Derived config — inherits base, overrides specific fields
final upload = base.copyWith(maxAttempts: 8, maxDelay: Duration(minutes: 2));

BackoffStrategy #

Controls how the base delay grows between attempts.

JitterStrategy #

Controls randomisation applied on top of the base delay.

RetryContext #

Passed to onRetry before every retry sleep.

Event Stream #

SmartRetry.events is a broadcast stream of [RetryEvent] instances.

SmartRetry.events.listen((event) {
  switch (event) {
    case AttemptStarted(:final attemptNumber, :final maxAttempts):
      print('▶ $attemptNumber/$maxAttempts');

    case AttemptFailed(:final attemptNumber, :final exception, :final nextDelay):
      logger.warn('Attempt $attemptNumber failed (${nextDelay.inMilliseconds}ms): $exception');

    case AttemptSucceeded(:final attemptNumber, :final totalElapsed):
      metrics.increment('retry.success', tags: {'attempt': '$attemptNumber'});

    case AllAttemptsFailed(:final totalAttempts, :final lastException):
      Sentry.captureException(lastException);

    case RetryAborted(:final exception):
      logger.error('Non-retryable: $exception');
  }
});

Available event types: AttemptStarted, AttemptFailed, AttemptSucceeded, AllAttemptsFailed, RetryAborted.

previewSchedule #

Inspect the full delay table without executing any code.

final schedule = SmartRetry.previewSchedule(
  options: RetryOptions(
    maxAttempts: 5,
    initialDelay: Duration(milliseconds: 500),
    factor: 2.0,
    backoffStrategy: BackoffStrategy.exponential,
    jitterStrategy: JitterStrategy.none,
  ),
);

for (final row in schedule) {
  print('Retry #${row.attempt}: ${row.actualDelay.inMilliseconds}ms');
}
// Retry #1: 500ms
// Retry #2: 1000ms
// Retry #3: 2000ms
// Retry #4: 4000ms

Exception Handling #

try {
  final result = await SmartRetry.run(() => api.getData());
} on MaxAttemptsExceededException catch (e) {
  // All attempts failed — transient problem persisted too long
  print('Gave up after ${e.attempts} attempts in ${e.totalElapsed.inSeconds}s');
  print('Last error: ${e.lastException}');
} on NonRetryableException catch (e) {
  // retryIf returned false — permanent error, no point retrying
  print('Permanent failure: ${e.cause}');
  print('Reason: ${e.message}');
}

Delay Schedule Reference #

Default configuration (maxAttempts: 5, initialDelay: 500ms, factor: 2.0, jitter: full):

Strategy Comparison #

Advanced Recipes #

Async retryIf predicate #

await SmartRetry.run(
  () => api.upload(file),
  retryIf: (e) async {
    // Check connectivity before deciding to retry
    final connected = await connectivity.checkConnectivity();
    return connected && e is SocketException;
  },
);

Shared config across a service class #

class ApiService {
  static final _opts = RetryOptions(
    maxAttempts: 4,
    initialDelay: const Duration(milliseconds: 300),
    retryIf: (e) => e is SocketException || e is TimeoutException,
    onRetry: (ctx) => log.warn('[API] retry ${ctx.attemptNumber}'),
  );

  Future<User> getUser(int id) =>
      SmartRetry.runWithOptions(() => _http.get('/users/$id'), options: _opts);

  Future<List<Post>> getPosts() =>
      SmartRetry.runWithOptions(() => _http.get('/posts'), options: _opts);
}

Plug in Sentry / Firebase Crashlytics #

void setupRetryMonitoring() {
  SmartRetry.events.listen((event) {
    if (event is AllAttemptsFailed) {
      Sentry.captureException(event.lastException, hint: Hint.withMap({
        'attempts': '${event.totalAttempts}',
      }));
    }
  });
}

Contributing #

Pull requests and issues are welcome at github.com/Brah-Timo/smart_retry.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Run tests: dart test
4. Run the linter: dart analyze
5. Submit a PR

License #

MIT © 2026