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, and CacheOrchestrator.
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 V is serialized to and from Uint8List.
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.getResult call.
CacheStale<V>
The key was found but the TTL has elapsed. Only returned when ExpirationBehavior.soft is 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.get returns 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.