fastcache 1.2.0

A fast and efficient caching library for Dart applications.

example/fastcache_example.dart

import 'dart:async';
import 'package:fastcache/fastcache.dart';

void main() async {
  // ------------------------------
  // 1. Basic Cache Operations
  // ------------------------------
  print('=== Basic Cache Operations ===');
  final cache = FastCache<String, int>(3); // Create cache with capacity of 3

  // Add items using set method
  await cache.set(Future.value('a'), Future.value(1));
  await cache.set(Future.value('b'), Future.value(2));
  await cache.set(Future.value('c'), Future.value(3));

  // Get items using get method
  print('a: ${await cache.get(Future.value('a'))}'); // Output: a: 1
  print('b: ${await cache.get(Future.value('b'))}'); // Output: b: 2
  print('c: ${await cache.get(Future.value('c'))}'); // Output: c: 3

  // Use subscript operator
  cache['d'] = 4; // Exceeds capacity, 'a' (oldest) will be evicted
  print('d: ${cache['d']}'); // Output: d: 4
  print(
    'a evicted (oldest): ${await cache.get(Future.value('a'))}',
  ); // Output: a evicted (oldest): null
  print(
    'b still exists: ${await cache.get(Future.value('b'))}',
  ); // Output: b still exists: 2

  // ------------------------------
  // 2. LRU Policy Demonstration
  // ------------------------------
  print('\n=== LRU Policy Demonstration ===');
  // Current order: b (most recent), c, d (oldest after b,c were accessed)
  // Access b to make it most recent
  await cache.get(Future.value('b'));
  await cache.get(Future.value('c'));
  await cache.get(Future.value('d'));

  await cache.set(
    Future.value('e'),
    Future.value(5),
  ); // Exceeds capacity, b is oldest now
  print(
    'b evicted (oldest): ${await cache.get(Future.value('b'))}',
  ); // Output: b evicted (oldest): null
  print('e added: ${await cache.get(Future.value('e'))}'); // Output: e added: 5
  print(
    'c still exists: ${await cache.get(Future.value('c'))}',
  ); // Output: c still exists: 3

  // ------------------------------
  // 3. TTL Expiration Feature
  // ------------------------------
  print('\n=== TTL Expiration Feature ===');
  final ttlCache = FastCache<String, String>();

  // Set item with TTL (expires after 2 seconds)
  await ttlCache.set(
    Future.value('temp'),
    Future.value('temporary value'),
    period: Future.value(Duration(seconds: 2)),
    onExpire: Future.value((key, value) {
      print('$key expired with value: $value');
    }),
  );

  print(
    'temp: ${await ttlCache.get(Future.value('temp'))}',
  ); // Output: temp: temporary value
  print('Waiting 3 seconds...');
  await Future.delayed(Duration(seconds: 3));
  print(
    'After expiration: ${await ttlCache.get(Future.value('temp'))}',
  ); // Output: After expiration: null

  // ------------------------------
  // 4. Auto-update Feature (Update Cycle)
  // ------------------------------
  print('\n=== Auto-update Feature ===');
  int counter = 0;
  final updateCache = FastCache<String, int>();

  // Set item with auto-update every 1 second
  await updateCache.set(
    Future.value('auto-update'),
    Future.value(counter),
    updateCycle: Future.value(Duration(seconds: 1)),
    onUpdate: Future.value((key, oldValue) {
      counter++;
      print('Auto-updating $key: $oldValue -> $counter');
      return counter;
    }),
  );

  // First get triggers initial update since value is marked as stale
  print(
    'After initial get: ${await updateCache.get(Future.value('auto-update'))}',
  ); // Output: After initial get: 1
  print('Waiting 1.5 seconds for auto-update...');
  await Future.delayed(Duration(milliseconds: 1500));
  print(
    'After auto-update cycle: ${await updateCache.get(Future.value('auto-update'))}',
  ); // Output: After auto-update cycle: 2

  // ------------------------------
  // 5. Callback Functions
  // ------------------------------
  print('\n=== Callback Functions ===');
  final callbackCache = FastCache<String, String>(2);

  // Set default callbacks
  callbackCache.onDefaultExpireSync = (key, value) {
    print('Expire callback: $key -> $value');
  };

  callbackCache.onDefaultEvictSync = (key, value) {
    print('Evict callback: $key -> $value');
  };

  await callbackCache.set(Future.value('x'), Future.value('value1'));
  await callbackCache.set(Future.value('y'), Future.value('value2'));
  await callbackCache.set(
    Future.value('z'),
    Future.value('value3'),
  ); // x (oldest) gets evicted

  // Now set item with TTL to demonstrate expire callback
  await callbackCache.set(
    Future.value('temp'),
    Future.value('temp-value'),
    period: Future.value(Duration(seconds: 1)),
  );
  print('Waiting 1.5 seconds for expiration...');
  await Future.delayed(Duration(milliseconds: 1500));
  print('After temp expires: ${await callbackCache.get(Future.value('temp'))}');

  // ------------------------------
  // 6. Synchronous Operations
  // ------------------------------
  print('\n=== Synchronous Operations ===');
  final syncCache = FastCache<int, String>();

  syncCache.setSync(1, 'one');
  syncCache.setSync(2, 'two');

  print('Sync get 1: ${syncCache.getSync(1)}'); // Output: one
  print('Sync get 2: ${syncCache.getSync(2)}'); // Output: two

  syncCache.removeSync(1);
  print('After remove 1: ${syncCache.getSync(1)}'); // Output: null

  // ------------------------------
  // 7. Batch Operations
  // ------------------------------
  print('\n=== Batch Operations ===');
  final batchCache = FastCache<String, int>();

  await batchCache.set(Future.value('a'), Future.value(1));
  await batchCache.set(Future.value('b'), Future.value(2));
  await batchCache.set(Future.value('c'), Future.value(3));

  print('All keys: ${await batchCache.keys}'); // Output: (a, b, c)
  print('All values: ${await batchCache.values}'); // Output: (1, 2, 3)
  print('Cache size: ${await batchCache.length}'); // Output: 3

  await batchCache.clear();
  print('After clear size: ${await batchCache.length}'); // Output: 0

  print('\n=== Demo Complete ===');
}