mytheclipse_cache/lib.rs
1//! # mytheclipse-cache
2//!
3//! A unified multi-layer cache abstraction that keeps your application from
4//! being locked to any single cache provider.
5//!
6//! - **L1 (in-process) caches**: [`memory::MemoryCache`] (zero-dependency,
7//! default) or [`moka_cache::MokaL1`] (high-performance, TTL/max-capacity).
8//! - **L2 (distributed) caches**: [`redis::RedisCache`] backed by Redis/Valkey.
9//! - **Multi-layer composition**: [`multilayer::MultiLayerCache`] layers an L1
10//! over an L2 behind one [`Cache`] face; reads fall through to L2 and
11//! backfill L1.
12//! - **Cache-aside / auto-refresh**: [`cache_aside::CacheAside`] reads through
13//! to a data source on a miss and caches the result.
14//!
15//! The core [`Cache`] trait is byte-oriented; typed convenience (JSON) is
16//! layered on top via [`memory::typed::TypedCache`].
17//!
18//! ## Example
19//!
20//! Multi-layer + cache-aside composition (default features):
21//!
22//! ```no_run
23//! # #[cfg(all(feature = "l1-memory", feature = "cache-aside"))]
24//! # async fn run() {
25//! use mytheclipse_cache::{Cache, MemoryCache, MultiLayerCache, CacheAside};
26//! let l1 = MemoryCache::new();
27//! let l2 = MemoryCache::new(); // in a real app: a RedisCache
28//! let cache = MultiLayerCache::new(l1, l2);
29//!
30//! cache.set("user:1", b"payload".to_vec(), None).await.unwrap();
31//! assert_eq!(cache.get("user:1").await.unwrap(), Some(b"payload".to_vec()));
32//!
33//! // Cache-aside: fill misses from a source of truth.
34//! let aside = CacheAside::new(
35//! MemoryCache::new(),
36//! |key| async move { Some(format!("data-for-{key}").into_bytes()) },
37//! );
38//! let _v = aside.get("orders:42").await.unwrap();
39//! # }
40//! # #[cfg(not(all(feature = "l1-memory", feature = "cache-aside")))]
41//! # fn run() {}
42//! ```
43
44#![forbid(unsafe_code)]
45
46pub mod traits;
47
48#[cfg(feature = "l1-memory")]
49pub mod memory;
50
51#[cfg(feature = "l1-moka")]
52pub mod moka_cache;
53
54#[cfg(feature = "l2-redis")]
55pub mod redis;
56
57#[cfg(feature = "cache-aside")]
58pub mod cache_aside;
59
60#[cfg(feature = "cache-aside")]
61pub mod multilayer;
62
63#[cfg(feature = "cache-aside")]
64pub mod auto_refresh;
65
66#[cfg(feature = "cache-aside")]
67pub mod metrics;
68
69pub use traits::{Cache, CacheError};
70
71#[cfg(feature = "l1-memory")]
72pub use memory::MemoryCache;
73
74#[cfg(feature = "l1-moka")]
75pub use moka_cache::MokaL1;
76
77#[cfg(feature = "l2-redis")]
78pub use redis::RedisCache;
79
80#[cfg(feature = "cache-aside")]
81pub use cache_aside::CacheAside;
82
83#[cfg(feature = "cache-aside")]
84pub use multilayer::MultiLayerCache;