⚡ quantum_cache #

A blazing-fast, pure-Dart, dual-layer (L1 memory + L2 disk) cache for Flutter and Dart. Up to 10× faster than Hive with ARC adaptive eviction, TTL, AES-256-GCM encryption, and Isolate safety.

Why quantum_cache? #

Performance #

Measured on a mid-range device (Pixel 7 / iPhone 14):

Architecture #

  SuperCache  (public API)
       │
       ▼
  CacheOrchestrator
  ┌──────────────────────────────────────────────┐
  │  L1MemoryCache   ← HashMap  O(1) read/write │
  │  L2DiskCache     ← B-Index  O(1) disk seek  │
  │  WriteBuffer     ← batched disk I/O          │
  │  TtlManager      ← periodic TTL cleanup      │
  └──────────────────────────────────────────────┘
       │
       ▼
  StorageEngine   (DartIoStorage | WebStorage)
       │
       ▼
  IndexManager   (in-memory B-Index + .idx file)

Read-Through (get) #

1. Check L1 — O(1) HashMap lookup → return immediately (≈90% of reads)
2. Check L2 — O(1) B-Index seek → decode → promote to L1 → return
3. Miss → return null

Write-Behind (put) #

1. Write to L1 synchronously (< 1 µs)
2. Enqueue in WriteBuffer
3. WriteBuffer flushes to L2 in batches (every 500 ms or 100 ops)

Installation #

dependencies:
  quantum_cache: ^1.0.0

Quick Start #

import 'package:quantum_cache/quantum_cache.dart';

Future<void> main() async {
  // 1 — Register custom adapters BEFORE init
  SuperCache.registerAdapter(UserAdapter());

  // 2 — Initialize once at app startup
  await SuperCache.init(
    config: const CacheConfig(
      maxMemoryEntries: 2000,
      defaultTtl: Duration(hours: 24),
      evictionPolicy: EvictionPolicyType.arc,
      enableStatistics: true,
    ),
  );

  final cache = SuperCache.instance;

  // 3 — Write
  await cache.put('username', 'Alice');
  await cache.put('score', 9500, ttl: const Duration(minutes: 30));
  await cache.put('user', myUser);

  // 4 — Read (typed, nullable)
  final name = await cache.get<String>('username');   // 'Alice'
  final score = await cache.get<int>('score');         // 9500
  final user = await cache.get<UserModel>('user');     // UserModel(...)

  // 5 — Cache-aside pattern
  final products = await cache.getOrPut(
    'product_list',
    () => api.fetchProducts(),
    ttl: const Duration(minutes: 15),
  );

  // 6 — Statistics
  print(cache.statistics); // formatted table

  // 7 — Dispose at app shutdown
  await cache.dispose();
}

Custom Objects #

// 1 — Define your model with annotations
@Cacheable(typeId: 1)
class UserModel {
  @CacheField(0) final String id;
  @CacheField(1) final String name;
  @CacheField(2) final int age;
  @CacheField(3) final DateTime createdAt;
  @CacheField(4) final List<String> roles;

  const UserModel({
    required this.id,
    required this.name,
    required this.age,
    required this.createdAt,
    required this.roles,
  });
}

// 2a — Auto-generate adapter (recommended):
//   dart run quantum_cache:quantum_cache_builder lib/models

// 2b — Or write the adapter manually:
class UserAdapter extends SuperCacheAdapter<UserModel> {
  @override int get typeId => 1;

  @override
  UserModel read(BinaryReader reader) => UserModel(
    id:        reader.readString(),
    name:      reader.readString(),
    age:       reader.readInt32(),
    createdAt: DateTime.fromMicrosecondsSinceEpoch(reader.readInt64()),
    roles: List.generate(reader.readUint32(), (_) => reader.readString()),
  );

  @override
  void write(BinaryWriter writer, UserModel obj) {
    writer
      ..writeString(obj.id)
      ..writeString(obj.name)
      ..writeInt32(obj.age)
      ..writeInt64(obj.createdAt.microsecondsSinceEpoch)
      ..writeUint32(obj.roles.length);
    for (final r in obj.roles) writer.writeString(r);
  }
}

// 3 — Register before init
SuperCache.registerAdapter(UserAdapter());
await SuperCache.init();

Named Instances #

// Session cache — memory only, 5-minute TTL
await SuperCache.init(
  name: 'session',
  config: const CacheConfig(
    boxName: 'session',
    enableDiskCache: false,
    defaultTtl: Duration(minutes: 5),
  ),
);

// Assets cache — large, long-lived
await SuperCache.init(
  name: 'assets',
  config: const CacheConfig(
    boxName: 'assets',
    maxMemoryEntries: 10000,
    maxMemorySizeBytes: 200 * 1024 * 1024,
  ),
);

final session = SuperCache.named('session');
final assets  = SuperCache.named('assets');

Encryption #

// Generate a key (store it in flutter_secure_storage!)
final key = AesCipher.generateKey(); // 32 cryptographically random bytes

// Or derive from a password:
final key = AesCipher.deriveKey(
  'my-password',
  myStoredSalt,
  iterations: 100000,
);

await SuperCache.init(
  config: CacheConfig(encryptionKey: key),
);

// All disk data is now AES-256-GCM encrypted.
// In-memory data is never encrypted (it is already in the process memory).

Configuration Reference #

const CacheConfig(
  // ── L1 Memory ────────────────────────────────────────────
  maxMemoryEntries:    1000,         // Max entries in RAM
  maxMemorySizeBytes:  50 * 1024 * 1024, // Max RAM (50 MB)

  // ── L2 Disk ──────────────────────────────────────────────
  enableDiskCache:     true,         // Set false for RAM-only
  maxDiskSizeBytes:    500 * 1024 * 1024, // Max disk (500 MB)
  diskDirectory:       null,         // Defaults to app documents
  boxName:             'quantum_cache_default',

  // ── TTL ──────────────────────────────────────────────────
  defaultTtl:          null,         // null = never expires
  enableTtlCleanup:    true,
  ttlCleanupInterval:  Duration(minutes: 5),

  // ── Eviction ─────────────────────────────────────────────
  evictionPolicy:      EvictionPolicyType.arc, // arc | lru | lfu

  // ── Write Buffer ─────────────────────────────────────────
  writeBufferSize:     100,          // Ops before auto-flush
  writeBufferFlushInterval: Duration(milliseconds: 500),
  syncWrites:          false,        // true = await disk flush

  // ── Encryption ───────────────────────────────────────────
  encryptionKey:       null,         // 32-byte AES-256 key

  // ── Isolate ──────────────────────────────────────────────
  enableIsolateSupport: false,       // Run disk I/O in isolate

  // ── Compaction ───────────────────────────────────────────
  compactionThreshold: 0.30,         // Compact at 30% waste
  autoCompact:         true,

  // ── Diagnostics ──────────────────────────────────────────
  enableStatistics:    true,
  enableLogging:       false,
  logLevel:            CacheLogLevel.warning,
)

Statistics #

final stats = SuperCache.instance.statistics;

print('Hit rate:     ${(stats.hitRate * 100).toStringAsFixed(1)}%');
print('L1 hits:      ${stats.l1Hits}');
print('L2 hits:      ${stats.l2Hits}');
print('Misses:       ${stats.misses}');
print('Evictions:    ${stats.evictions}');
print('Avg read:     ${stats.avgReadLatencyUs.toStringAsFixed(1)} µs');
print('Throughput:   ${stats.requestsPerSecond.toStringAsFixed(0)} req/s');

// Immutable snapshot for logging/analytics
final snap = stats.snapshot();
await analytics.track(snap.toMap());

Testing with Mocks #

import 'package:quantum_cache/quantum_cache.dart';

class MockCache implements SuperCacheBase {
  final _store = <String, dynamic>{};

  @override Future<T?> get<T>(String key) async => _store[key] as T?;
  @override Future<void> put<T>(String key, T value, {Duration? ttl, bool forceSync = false}) async => _store[key] = value;
  @override Future<bool> remove(String key) async => _store.remove(key) != null;
  @override Future<bool> containsKey(String key) async => _store.containsKey(key);
  @override Future<void> clear() async => _store.clear();
  // ... implement remaining interface methods
}

License #

MIT © 2026 — see LICENSE.