async_guard

Prevent duplicate async calls, handle loading & errors in one line.
No more boilerplate. No more bugs. Just guard it.

What is this? #

async_guard is a lightweight utility that wraps any async call with production-ready protections — in a single line:

• 🛡️ Duplicate prevention — block concurrent calls with the same ID
• ⏳ Loading state — one callback, automatic start/stop
• 🚨 Error handling — built-in try-catch, no boilerplate
• ⏱️ Timeout support — auto-cancel long-running tasks
• 🧬 Lifecycle safe — guards against setState after dispose
• 🔘 GuardedButton — drop-in widget with double-tap protection & loading indicator
• 🪄 Extension syntax — chain .guard() on any Future

Every Flutter developer writes the same 15 lines of loading/error/duplicate boilerplate. async_guard replaces all of it with one function call.

Getting Started #

Installation #

dependencies:
  async_guard: ^0.0.1

flutter pub get

Minimal Example #

import 'package:async_guard/async_guard.dart';

// That's it. Errors caught, duplicates blocked.
final result = await guard(() => api.login());

Usage #

Basic #

final result = await guard(() => api.login());

If login() throws, the error is caught. If the same call is already running, the duplicate is ignored.

With loading state #

await guard(
  () => api.login(),
  onLoading: (isLoading) => setState(() => loading = isLoading),
);

onLoading(true) fires before execution, onLoading(false) fires after — regardless of success or failure.

With error handling #

await guard(
  () => api.login(),
  onError: (e) => showSnackBar('Failed: $e'),
);

Full example #

final user = await guard<User>(
  () => api.login(email, password),
  id: 'login',
  onLoading: (v) => setState(() => isLoading = v),
  onSuccess: (user) => navigateTo('/home'),
  onError: (e) => showSnackBar('Error: $e'),
  timeout: Duration(seconds: 10),
);

GuardedButton #

A drop-in widget that handles everything automatically:

GuardedButton(
  onTap: () => api.submit(data),
  child: Text('Submit'),
)

• ✅ Disables itself while running
• ✅ Shows a loading indicator
• ✅ Prevents double-tap
• ✅ Zero configuration needed

Customize the loading indicator:

GuardedButton(
  onTap: () => api.submit(data),
  loadingIndicator: CircularProgressIndicator(color: Colors.white),
  style: ElevatedButton.styleFrom(backgroundColor: Colors.blue),
  child: Text('Submit'),
)

Extension Syntax #

Chain .guard() on any Future:

final token = await api.login(email, password).guard(id: 'login');

With callbacks:

await api.login(email, password).guard(
  id: 'login',
  onLoading: (v) => setState(() => loading = v),
  onError: (e) => showError(e),
);

Lifecycle-Safe Async #

Prevent setState after dispose crashes:

@override
void initState() {
  super.initState();
  safeAsync(this, () async {
    final data = await api.fetchData();
    setState(() => _data = data);
  });
}

Or use the extension on State:

this.runSafe(() async {
  final data = await api.fetchData();
  setState(() => _data = data);
});

API Reference #

guard<T>() #

safeAsync() #

GuardedButton #

Extensions #

Why This Package? #

Flutter async code is repetitive and error-prone:

// ❌ What you write today — every single time
bool _isLoading = false;

Future<void> _submit() async {
  if (_isLoading) return;           // prevent double tap
  setState(() => _isLoading = true);
  try {
    await api.submit();
  } catch (e) {
    showError(e);
  } finally {
    if (mounted) {
      setState(() => _isLoading = false);
    }
  }
}

// ✅ With async_guard
await guard(
  () => api.submit(),
  id: 'submit',
  onLoading: (v) => setState(() => _isLoading = v),
  onError: (e) => showError(e),
);

15 lines → 5 lines. No bugs, no forgetting mounted, no duplicate calls.

Architecture #

lib/
 ├── async_guard.dart          ← Barrel export
 └── src/
      ├── guard.dart           ← Core guard() function
      ├── guard_manager.dart   ← Singleton task tracker
      ├── safe_async.dart      ← Lifecycle-safe async helpers
      ├── guarded_button.dart  ← Double-tap-proof button widget
      └── extensions.dart      ← Future<T>.guard() extension

Zero dependencies beyond Flutter SDK. Lightweight, tree-shakeable, and fully tested.

Requirements #

💖 Support #

If this package helps you build better Flutter apps, consider supporting the development:

Your support helps keep this package maintained and up-to-date. Every contribution is greatly appreciated! 🙏

License #

MIT — see LICENSE for details.