fastcache 1.2.0

A fast and efficient caching library for Dart applications.

FastCache

A fast and efficient caching library for Dart applications, featuring LRU (Least Recently Used) eviction policy, TTL (Time-To-Live) expiration, and automatic update cycles.

Features

• LRU Cache: Implements Least Recently Used eviction policy with configurable capacity
• TTL Support: Time-To-Live expiration for cache items with customizable periods
• Auto-Update: Automatic background updates for cache items
• Synchronous & Asynchronous APIs: Support for both sync and async operations
• Callback Functions: Hooks for expire, evict, and update events
• Thread-Safe: Built with synchronized operations for concurrent access

Getting Started

Installation

Add fastcache to your pubspec.yaml:

dependencies:
  fastcache: ^1.0.0

Then run:

dart pub get

Import

import 'package:fastcache/fastcache.dart';

Usage

Basic Operations

// Create cache with capacity of 3
final cache = FastCache<String, int>(3);

// Add items
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
print(await cache.get(Future.value('a'))); // Output: 1

// Use subscript operator
cache['d'] = 4; // Exceeds capacity, 'a' (oldest) will be evicted

TTL Expiration

final cache = FastCache<String, String>();

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

Auto-Update Cycle

int counter = 0;
final cache = FastCache<String, int>();

// Auto-update every 1 second
await cache.set(
  Future.value('auto-update'),
  Future.value(counter),
  updateCycle: Future.value(Duration(seconds: 1)),
  onUpdate: Future.value((key, oldValue) {
    counter++;
    return counter;
  }),
);

Synchronous Operations

final cache = FastCache<int, String>();

cache.setSync(1, 'one');
print(cache.getSync(1)); // Output: one
cache.removeSync(1);

Batch Operations

final cache = FastCache<String, int>();

wait cache.set(Future.value('a'), Future.value(1));
await cache.set(Future.value('b'), Future.value(2));

print(await cache.keys);      // Output: (a, b)
print(await cache.values);    // Output: (1, 2)
print(await cache.length);    // Output: 2

await cache.clear();

API Reference

FastCache Class

Method	Description
set(key, value)	Add or update a cache item
get(key)	Retrieve a cache item
remove(key)	Remove a cache item
clear()	Clear all items
keys	Get all keys
values	Get all values
length	Get cache size
contains(key)	Check if key exists

Configuration Options

• capacity: Maximum number of items (default: unlimited)
• period: TTL duration for automatic expiration
• updateCycle: Auto-update interval
• onExpire: Callback when item expires
• onEvict: Callback when item is evicted
• onUpdate: Callback for auto-update

Additional Information

• Documentation: See the API documentation for detailed information
• Examples: Check the example folder for more usage examples
• Tests: Run tests with dart test

License

MIT License