super_cache #

A production-grade, mobile-first LRU caching engine for Flutter and Dart.

Zero external dependencies. Batteries-included observability, TTL, memory pressure handling, and Clean Architecture integration out of the box.

Features #

Installation #

dependencies:
  super_cache: ^1.0.0

For Flutter-specific features (memory pressure, debug overlay):

import 'package:super_cache/super_cache_flutter.dart';

For pure-Dart environments (tests, CLI):

import 'package:super_cache/super_cache.dart';

Quick start #

In-memory LRU cache #

import 'package:super_cache/super_cache.dart';

final cache = MemoryCache<String, User>(
  maxEntries: 200,
  defaultTTL: const Duration(minutes: 5),
);

cache.put('user_1', user);
final user = cache.get('user_1'); // null if expired or evicted
cache.dispose();

Layered cache (L1 memory + L3 disk) #

import 'package:super_cache/super_cache.dart';
import 'package:super_cache_disk/super_cache_disk.dart';

final cache = CacheOrchestrator<String, Product>(
  l1: MemoryCache(maxEntries: 100),
  l3: DiskCache(
    directory: cacheDir,
    codec: JsonCacheCodec(
      fromJson: Product.fromJson,
      toJson: (p) => p.toJson(),
    ),
  ),
);

await (cache.l3 as DiskCache).initialize();
await cache.put('p_1', product);
final p = await cache.get('p_1'); // L1 hit on second access

Repository mixin #

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,
    policy: const CacheAside(ttl: Duration(minutes: 5)),
    onMiss: () => _api.fetchUser(id),
  );
}

Concurrent calls for the same key while the cache is cold trigger only one onMiss invocation — the second caller awaits the same Future.

Cache policies #

TTL modes #

// Absolute TTL (default): entry expires X seconds after put()
final cache = MemoryCache<String, String>(
  defaultTTL: const Duration(minutes: 10),
);

// Sliding TTL: TTL resets on every successful get()
final sliding = MemoryCache<String, String>(
  defaultTTL: const Duration(minutes: 10),
  ttlMode: TTLMode.sliding,
);

Observability #

// One-shot snapshot
final m = cache.metrics;
print('Hit rate: ${(m.hitRate * 100).toStringAsFixed(1)}%');
print('Entries: ${m.currentEntries} / ${m.hits + m.misses} requests');

// Live stream (emits on every sweep interval)
cache.metricsStream.listen((m) {
  debugPrint('$m');
});

Memory pressure (Flutter) #

import 'package:super_cache/super_cache_flutter.dart';

final cache = MemoryCache<String, Uint8List>(maxEntries: 500);
final watcher = MemoryCachePressureWatcher(cache: cache);
// WidgetsBinding registers automatically — no extra setup needed.
// Dispose when done:
watcher.dispose();

On moderate memory pressure: evicts the least-recently-used 20% of entries. On critical pressure: evicts 50%.

Packages in this family #