super_cache 1.0.0

A production-grade, mobile-first LRU caching engine for Flutter. Zero external dependencies. Includes TTL, observability, memory pressure awareness, layered orchestration, and Clean Architecture integration.

Changelog

All notable changes to super_cache are documented here. Releases follow Semantic Versioning.

---

1.0.0 — 2024-01-01

Stable public release. API is frozen — no breaking changes will be made without a major version bump.

Added

• CacheOrchestrator<K,V> — sequential L1 → L2 → L3 cache with automatic promotion on hit.
• CacheRepositoryMixin<K,V> — adds fetchWithCache to any repository class; supports CacheAside, WriteThrough, and RefreshAhead policies with built-in stampede protection.
• MemoryCachePressureWatcher<K,V> — WidgetsBindingObserver integration that evicts 20% (moderate) or 50% (critical) of LRU entries on iOS/Android memory pressure events. Exported from super_cache_flutter.dart.
• CacheDebugOverlay<K,V> — Flutter widget showing live hit-rate, entry count, and estimated bytes. Exported from super_cache_flutter.dart.
• Barrel split: super_cache.dart (pure Dart) and super_cache_flutter.dart (Flutter-specific exports). Use the plain barrel in Dart-only code.

Changed

• MemoryCache sliding TTL now correctly resets lastAccessedAt on every non-expired get().
• Bytes-based eviction triggers as soon as estimatedBytes > maxBytes.

---

0.2.0

Added

• Sliding TTL mode (TTLMode.sliding).
• Bytes-based capacity limit (maxBytes + SizeEstimator<V>).
• metricsStream — broadcast stream that emits CacheMetrics on every sweep interval.
• CacheMetrics.hitRate, missRate, copyWith, toString.
• CacheOrchestrator, CacheRepositoryMixin, CacheDebugOverlay, MemoryCachePressureWatcher.

---

0.1.0

Initial internal release.

Added

• Cache<K,V> abstract interface with FutureOr<V?> returns (memory and disk implementations share one interface).
• MemoryCache<K,V> — O(1) LRU using HashMap + manual doubly-linked list.
• Count-based eviction (maxEntries).
• Absolute TTL with lazy expiration on get().
• Background sweep timer (configurable interval, cancelled in dispose()).
• CacheResult<V> sealed class: CacheHit, CacheStale, CacheMiss.
• CachePolicy sealed class: CacheAside, WriteThrough, RefreshAhead.
• CacheCodec<V> interface (used by disk and secure layers).
• CacheMetrics snapshot (hits, misses, evictions, currentEntries, estimatedBytes, hitRate, since).
• putAll, removeWhere, containsKey, getResult.