cache_guard

Simple async caching for Flutter. Run once, reuse forever.
No more boilerplate. No more duplicate calls. Just cache it.

---

What is this?

cache_guard is a lightweight utility that caches any async result with production-ready protections — in a single line:

• 🚀 Cache async results — execute once, reuse on every subsequent call
• 🔒 Prevent duplicate calls — concurrent requests for the same key share a single execution
• ⏱️ TTL support — set expiration durations for automatic cache invalidation
• 🔄 Force refresh — bypass cache when you need fresh data
• 🧩 Fluent extension — chain .cache("key") directly on any Future
• 🪶 Lightweight — zero external dependencies, pure Dart
• 🎯 Minimal API — 4 functions, 1 extension, that's it

Every Flutter developer writes the same caching boilerplate. cache_guard replaces all of it with one function call.

---

Getting Started

Installation

dependencies:
  cache_guard: ^0.0.1

flutter pub get

Minimal Example

import 'package:cache_guard/cache_guard.dart';

// That's it. Cached, deduplicated, zero config.
final user = await cacheGuard('user', () => api.getUser());

---

Usage

Basic

final user = await cacheGuard('user', () => api.getUser());

First call executes the API and caches the result. Second call returns the cached value instantly.

With TTL

final user = await cacheGuard(
  'user',
  () => api.getUser(),
  ttl: Duration(minutes: 5),
);

Cache expires after 5 minutes. Next call after expiration re-executes the task.

Force Refresh

final user = await cacheGuard(
  'user',
  () => api.getUser(),
  forceRefresh: true,
);

Ignores cache and always fetches fresh data.

Extension Syntax

final user = await api.getUser().cache('user');

// With TTL
final user = await api.getUser().cache('user', ttl: Duration(minutes: 5));

Cache Utilities

// Check if a key is cached
if (hasCache('user')) {
  print('User is cached!');
}

// Get cached value synchronously
final user = getCache<User>('user');

// Clear a specific key
clearCache('user');

// Clear all cache
clearCache();

---

API Reference

cacheGuard<T>()

Parameter	Type	Default	Description
key	String	—	Unique cache key
task	Future<T> Function()	—	The async function to execute and cache
ttl	Duration?	null	Time-to-live before cache expires
forceRefresh	bool	false	Bypass cache and re-execute the task

clearCache()

Parameter	Type	Default	Description
key	String?	null	Specific key to clear, or all if null

hasCache()

Parameter	Type	Description
key	String	Key to check

getCache<T>()

Parameter	Type	Description
key	String	Key to retrieve

Extensions

Extension	On	Method	Description
CacheGuardExtension<T>	Future<T>	.cache()	Fluent syntax for cacheGuard()

---

Why This Package?

Flutter async code often leads to repetitive caching patterns:

// ❌ What you write today — every single time
Map<String, dynamic> _cache = {};

Future<User> getUser() async {
  if (_cache.containsKey('user')) {
    return _cache['user'];
  }
  final user = await api.getUser();
  _cache['user'] = user;
  return user;
}

// ✅ With cache_guard
final user = await cacheGuard('user', () => api.getUser());

10 lines → 1 line. No bugs, no race conditions, no duplicate calls.

---

Architecture

lib/
 ├── cache_guard.dart          ← Barrel export
 └── src/
      ├── cache_guard_impl.dart ← Core cacheGuard() + utilities
      ├── cache_store.dart      ← In-memory storage & TTL logic
      └── extensions.dart       ← Future<T>.cache() extension

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

---

Requirements

Requirement	Version
Dart SDK	>=3.0.0 <4.0.0
Flutter	>=3.10.0
Null safety	✅
Dependencies	None (Flutter SDK only)

---

💖 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.