super_cache_disk

Persistent file-based cache for Flutter and Dart, built on top of super_cache.

Each entry is stored as a pair of files in a directory you provide — a .dat file for the encoded value and a .meta file for TTL and SHA-256 checksum metadata. SHA-256 integrity is verified on every get(); corrupted entries are treated as a cache miss and deleted automatically.

---

Features

• File-per-entry persistence — survives app restarts.
• SHA-256 integrity check on every read.
• Non-blocking writes via a sequential write queue; dispose() flushes all pending writes.
• Write-back buffer: get() immediately after put() returns the correct value even before the disk write completes.
• Optional gzip compression (compress: true).
• FIFO eviction when maxEntries (default 500) is exceeded.
• Background TTL sweep (configurable sweepInterval).
• Pure Dart — no Flutter dependency required. Compatible with dart test.

---

Installation

dependencies:
  super_cache: ^1.0.0
  super_cache_disk: ^1.0.0

---

Quick start

import 'package:super_cache_disk/super_cache_disk.dart';

// In tests — use a temp directory:
final dir = await Directory.systemTemp.createTemp('my_cache_');

// In Flutter — use path_provider:
// final appDir = await getApplicationCacheDirectory();
// final dir = Directory('${appDir.path}/my_cache')..createSync(recursive: true);

final cache = DiskCache<String, User>(
  directory: dir,
  codec: JsonCacheCodec(
    fromJson: User.fromJson,
    toJson: (u) => u.toJson(),
  ),
  maxEntries: 500,
  defaultTTL: const Duration(hours: 24),
);

await cache.initialize(); // scans dir and rebuilds index; required before use

await cache.put('user_1', user);
final user = await cache.get('user_1');
await cache.dispose(); // flushes write queue

---

Codecs

Codec	Value type	Notes
JsonCacheCodec<V>	Any V	Requires fromJson / toJson functions
StringCacheCodec	String	UTF-8 encode/decode

Implement CacheCodec<V> from super_cache for custom binary formats.

---

Configuration

DiskCache<String, Uint8List>(
  directory: dir,
  codec: RawBytesCodec(),
  maxEntries: 1000,                          // FIFO cap (default: 500)
  defaultTTL: const Duration(hours: 1),      // applied when no per-entry TTL
  compress: true,                            // gzip compress before writing
  sweepInterval: const Duration(minutes: 5), // background expiry check
)

---

removeWhere limitation

removeWhere can only remove entries stored during the current session (i.e., via put since the last initialize()). Entries loaded from a previous session are identified only by their key hash and cannot be matched by value. Use remove(key) or clear() for those.

---

Persistence across restarts

// Session 1
final cache = DiskCache<String, String>(directory: dir, codec: const StringCacheCodec());
await cache.initialize();
await cache.put('greeting', 'hello');
await cache.dispose(); // flushes write queue

// Session 2 — same directory
final cache2 = DiskCache<String, String>(directory: dir, codec: const StringCacheCodec());
await cache2.initialize();
print(await cache2.get('greeting')); // 'hello'

---

As L3 in a layered cache

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

final disk = DiskCache<String, User>(
  directory: cacheDir,
  codec: JsonCacheCodec(fromJson: User.fromJson, toJson: (u) => u.toJson()),
);
await disk.initialize();

final cache = CacheOrchestrator<String, User>(
  l1: MemoryCache(maxEntries: 100),
  l3: disk,
);