super_cache library
super_cache — Production-grade mobile-first caching engine for Flutter.
Core package: zero external dependencies.
Basic usage
final cache = MemoryCache<String, User>(
maxEntries: 200,
defaultTTL: Duration(minutes: 5),
);
await cache.put('user_1', user);
final user = await cache.get('user_1');
await cache.dispose();
With Clean Architecture
class UserRepository with CacheRepositoryMixin<String, User> {
@override
Cache<String, User> get cache => _cache;
final _cache = MemoryCache<String, User>(maxEntries: 200);
Future<User?> getUser(String id) => fetchWithCache(
id,
onMiss: () => _api.fetchUser(id),
);
}
Classes
-
Cache<
K, V> -
The common interface implemented by every super_cache layer:
MemoryCache,SecureCache,DiskCache, andCacheOrchestrator. - CacheAside
- Cache-aside (lazy loading): check cache first; on miss, load from source and populate the cache. This is the most common pattern.
-
CacheCodec<
V> -
Defines how a value of type
Vis serialized to and fromUint8List. -
CacheHit<
V> - The key was found and the value has not expired.
- CacheMetrics
- A snapshot of cache statistics at a point in time.
-
CacheMiss<
V> - The key was not found, or the entry was hard-expired and removed.
-
CacheOrchestrator<
K, V> - A sequential layered cache: L1 (memory) → L2 (optional) → L3 (optional).
- CachePolicy
- Defines how the cache interacts with the underlying data source.
-
CacheResult<
V> -
The result of a
Cache.getResultcall. -
CacheStale<
V> -
The key was found but the TTL has elapsed.
Only returned when
ExpirationBehavior.softis configured. The stale value is returned so the UI can display something while a background refresh is triggered. -
MemoryCache<
K, V> - An in-memory LRU cache with optional TTL expiration.
- RefreshAhead
- Refresh-ahead: once refreshAfter has elapsed since the value was last fetched from the source, the next read triggers a background refresh while still returning the current (potentially stale) value. Reads within refreshAfter are served from the cache without touching the source.
- WriteThrough
- Write-through: every write goes to both the cache and the source simultaneously. Reads always hit the cache.
Enums
- ExpirationBehavior
-
Controls what
Cache.getreturns for an expired entry. - TTLMode
- Controls how a TTL is measured for cached entries.
Mixins
-
CacheRepositoryMixin<
K, V> - Adds caching behaviour to a repository with one method.
Typedefs
-
SizeEstimator<
V> = int Function(V value) - A function that estimates the in-memory size of a cached value in bytes.
Exceptions / Errors
- CacheDecodeException
- Thrown by CacheCodec.decode when the bytes cannot be decoded.