Flutter Cache Vault #

A developer-friendly, user-transparent cache manager for Flutter apps — inspired by Telegram's Storage Usage screen.

✨ Features #

• Named Buckets — Isolated cache zones per feature (images, API, user data)
• Multiple Backends — Memory, SharedPrefs, SQLite, File System, Hybrid (L1+L2)
• Eviction Strategies — LRU, LFU, FIFO, Priority-based
• TTL & Expiry — Per-item or per-bucket time-to-live with lazy + proactive purge
• Cache Patterns — cacheOrFetch, staleWhileRevalidate out of the box
• Tagging — Tag items at write time, bulk-invalidate by tag across all buckets
• Encryption — AES-256 encrypted buckets with transparent read/write
• Diagnostics — Hit/miss rates, size tracking, event streams, debug overlay
• Ready-Made UI — Telegram-style storage manager screen, donut chart, bucket tiles
• Zero Config UI — Widgets read from CacheVault directly, just drop in and go

📦 Installation #

dependencies:
  flutter_cache_vault: ^1.0.0

flutter pub get

🚀 Quick Start (10 lines) #

import 'package:flutter_cache_vault/flutter_cache_vault.dart';
import 'package:flutter_cache_vault/ui.dart';

// 1. Initialize
await CacheVault.init(CacheConfig(
  globalMaxSize: 500 * 1024 * 1024,
  defaultTTL: Duration(days: 7),
  defaultBackend: BackendType.memory,
));

// 2. Create a bucket
final images = CacheVault.bucket('images', BucketOptions(
  maxSize: 100 * 1024 * 1024,
  ttl: Duration(days: 30),
  evictionStrategy: EvictionStrategy.lru,
  displayName: 'Images',
));

// 3. Read & Write
await images.set('avatar_123', imageBytes);
final data = await images.get<Uint8List>('avatar_123');

// 4. Show the storage manager UI
Navigator.push(context, MaterialPageRoute(
  builder: (_) => CacheManagerScreen(),
));

📖 API Reference #

Core #

CRUD Operations #

Cache Patterns #

Invalidation #

Eviction Strategies #

Storage Backends #

UI Widgets #

🎨 UI Widgets #

CacheManagerScreen #

Full-screen storage manager with donut chart, bucket list, clear button, auto-remove policies, and max size slider.

Navigator.push(context, MaterialPageRoute(
  builder: (_) => CacheManagerScreen(
    title: 'Storage',
    footerNote: 'Files are stored in the cloud and can be re-downloaded.',
    theme: CacheManagerTheme(primaryColor: Colors.blue),
    onClearComplete: (freedBytes) => print('Freed $freedBytes bytes'),
  ),
));

CacheDebugOverlay #

Wrap your app during development:

CacheDebugOverlay(
  enabled: kDebugMode,
  child: MyApp(),
)

🔒 Encryption #

await CacheVault.init(CacheConfig(
  encryptionKey: 'my-32-character-encryption-key!!',
));

final secrets = CacheVault.bucket('secrets', BucketOptions(
  encrypted: true,
));

await secrets.set('token', sensitiveData);

🏷️ Tagging #

// Tag at write time
await apiCache.set('post_45', data, tags: ['user:123', 'posts']);

// Invalidate across ALL buckets
await CacheVault.invalidateTag('user:123');

📊 Diagnostics #

final report = await CacheVault.report();
print('Total: ${ByteFormatter.format(report.totalSizeBytes)}');
for (final b in report.perBucket) {
  print('${b.displayName}: ${b.hitRate * 100}% hit rate');
}

// Or pretty-print to console
await CacheVault.debugPrint();

🔄 Event Stream #

CacheVault.events.listen((event) {
  print('${event.type} in ${event.bucketName}: ${event.key}');
});

imageCache.onEvict.listen((event) => print('Evicted: ${event.key}'));

📁 Package Structure #

lib/
├── flutter_cache_vault.dart      ← Pure Dart core (main export)
├── ui.dart                       ← Flutter UI widgets (optional import)
└── src/
    ├── core/                     ← CacheVault, CacheBucket, models
    ├── eviction/                 ← LRU, LFU, FIFO, Priority strategies
    ├── backends/                 ← Memory, SharedPrefs, SQLite, File, Hybrid
    ├── serialization/            ← JSON, Bytes, custom serializer interface
    ├── encryption/               ← AES encrypted backend wrapper
    ├── migration/                ← Version-based data migration
    └── ui/                       ← All Flutter widgets

🧪 Running Tests #

flutter test

📄 License #

MIT License — see LICENSE for details. # CacheVault # CacheVault