rs-cache-kit

Generic LRU cache with TTL, tags, and async support for Rust

Installation

[dependencies]
philiprehberger-cache-kit = "0.4.3"

Usage

use philiprehberger_cache_kit::Cache;
use std::time::Duration;

let cache = Cache::new(1000, Some(Duration::from_secs(300)));

cache.set("key".to_string(), "value".to_string());
let val = cache.get(&"key".to_string()); // Some("value")

Custom TTL and Tags

cache.set_with(
    "user:1".to_string(),
    user_data,
    Some(Duration::from_secs(60)),
    &["users", "team-a"],
);

Tag-Based Invalidation

let removed = cache.invalidate_by_tag("team-a");
println!("Removed {} entries", removed);

Thread Safety

The cache is Clone and uses Arc<RwLock<...>> internally — safe to share across threads.

let cache = Cache::new(100, None);
let cache2 = cache.clone();

std::thread::spawn(move || {
    cache2.set("key".to_string(), "from thread".to_string());
});

Other Operations

cache.has(&key)      // check existence
cache.delete(&key)   // delete entry
cache.size()         // entry count
cache.clear()        // remove all

Get or Insert

let value = cache.get_or_insert_with("key".to_string(), || {
    expensive_computation()
});

Cache Stats

Track hit/miss/eviction counters for monitoring and tuning:

let cache = Cache::new(100, None);
cache.set("a".to_string(), 1);
cache.get(&"a".to_string()); // hit
cache.get(&"z".to_string()); // miss

let stats = cache.stats();
println!("Hits: {}, Misses: {}, Evictions: {}", stats.hits, stats.misses, stats.evictions);

Batch Get

Retrieve multiple keys in one call:

cache.set("x".to_string(), 1);
cache.set("y".to_string(), 2);

let results = cache.get_many(&["x".to_string(), "y".to_string(), "z".to_string()]);
// returns HashMap with "x" => 1, "y" => 2 (missing keys omitted)

Conditional Delete

Remove entries matching a predicate:

cache.set("small".to_string(), 1);
cache.set("big".to_string(), 1000);

let removed = cache.delete_where(|_key, value| *value > 100);
// removed == 1, "big" is gone

Maintenance

cache.len()             // entry count (alias for size)
cache.is_empty()        // check if empty
cache.max_size()        // max capacity
cache.keys()            // all non-expired keys
cache.remove_expired()  // clean up expired entries

API

Function / Type	Description
`Cache::new(max_size, default_ttl)`	Create a new cache with max capacity and optional default TTL
`Cache::default()`	Create a cache with max_size=100 and no TTL
`cache.set(key, value)`	Insert a value with default TTL and no tags
`cache.set_with(key, value, ttl, tags)`	Insert a value with custom TTL and tags
`cache.get(key)`	Get a value (returns `None` if missing or expired)
`cache.get_many(keys)`	Retrieve multiple values at once
`cache.get_or_insert_with(key, f)`	Get or compute and insert a value
`cache.has(key)`	Check if a key exists and is not expired
`cache.delete(key)`	Delete an entry by key
`cache.delete_where(predicate)`	Remove entries matching a predicate
`cache.invalidate_by_tag(tag)`	Remove all entries with the given tag
`cache.clear()`	Remove all entries
`cache.size()` / `cache.len()`	Return the number of entries
`cache.is_empty()`	Check if the cache is empty
`cache.max_size()`	Return the max capacity
`cache.keys()`	Return all non-expired keys
`cache.remove_expired()`	Clean up expired entries
`cache.stats()`	Return hit/miss/eviction counters as `CacheStats`
`CacheStats`	Struct with `hits`, `misses`, `evictions` fields

Development

cargo test
cargo clippy -- -D warnings

Support

If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.

License

MIT

philiprehberger-cache-kit 0.4.3