fncache 0.1.0

A zero-boilerplate Rust library for function-level caching with pluggable backends
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# fncache

[![Crates.io](https://img.shields.io/crates/v/fncache.svg)](https://crates.io/crates/fncache)
[![Documentation](https://docs.rs/fncache/badge.svg)](https://docs.rs/fncache)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A zero-boilerplate Rust library for function-level caching with pluggable backends, inspired by `functools.lru_cache` and `request-cache`.

## Features

- **🚀 Zero Boilerplate**: Simple `#[fncache]` attribute for instant caching
- **🔌 Pluggable Backends**: Memory, File, Redis, RocksDB support
- **⚡ Async/Sync**: Seamless support for both synchronous and asynchronous functions
- **ðŸ›Ąïļ Type Safety**: Strong typing throughout the caching layer with compile-time guarantees
- **📊 Advanced Metrics**: Built-in instrumentation with latency, hit rates, and size tracking
- **🏷ïļ Cache Invalidation**: Tag-based and prefix-based cache invalidation
- **ðŸ”Ĩ Background Warming**: Proactive cache population for improved performance

## Quick Start

Add `fncache` to your `Cargo.toml` with the desired features:

```toml
[dependencies]
fncache = { version = "0.1", features = ["memory"] }
```

### Basic Usage

```rust
use fncache::{
    backends::memory::MemoryBackend,
    init_global_cache,
    fncache,
    Result,
};

#[fncache(ttl = 60)]
fn expensive_operation(x: u64) -> u64 {
    println!("Performing expensive operation for {}", x);
    std::thread::sleep(std::time::Duration::from_secs(1));
    x * x
}

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize with memory backend
    init_global_cache(MemoryBackend::new())?;
    
    // First call executes the function
    let result1 = expensive_operation(5);
    println!("Result 1: {}", result1); // Takes ~1 second
    
    // Second call returns cached result
    let result2 = expensive_operation(5);
    println!("Result 2: {}", result2); // Returns immediately
    
    Ok(())
}
```

### Async Function Example

```rust
use std::time::Duration;
use tokio::time::sleep;

#[fncache(ttl = 300)]
async fn fetch_data(id: &str) -> String {
    println!("Fetching data for {}", id);
    sleep(Duration::from_secs(1)).await;
    format!("Data for {}", id)
}
```

## Backend Examples

### Redis Backend

```rust
use fncache::backends::redis::RedisBackend;

#[tokio::main]
async fn main() -> Result<()> {
    let backend = RedisBackend::new("redis://localhost:6379")?;
    init_global_cache(backend)?;
    
    // Your cached functions work the same way
    Ok(())
}
```

### File Backend

```rust
use fncache::backends::file::FileBackend;

fn main() -> Result<()> {
    let backend = FileBackend::new("/tmp/cache")?;
    init_global_cache(backend)?;
    Ok(())
}
```

## Available Features

| Feature | Description | Default |
|---------|-------------|----------|
| `memory` | In-memory cache backend | ✅ |
| `redis-backend` | Redis backend support | ❌ |
| `file-backend` | File-based persistent cache | ❌ |
| `rocksdb-backend` | RocksDB high-performance backend | ❌ |
| `metrics` | Performance metrics collection | ✅ |
| `invalidation` | Tag-based cache invalidation | ✅ |

## Requirements

- **Rust**: 1.70 or later
- **Runtime**: `tokio` for async support
- **Dependencies**: Automatically managed via features

## Performance

- **Memory Backend**: ~1-2Ξs set latency, ~850-970Ξs get hit latency
- **Redis Backend**: ~1ms cache hit latency (network dependent)
- **File Backend**: ~100Ξs cache hit latency
- **Throughput**: Thousands of operations/second (memory backend)

See `benches/` for detailed benchmarks.

## Documentation

- **[Architecture](ARCHITECTURE.md)** - Internal design and architecture

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

## License

MIT License - see [LICENSE](LICENSE) for details.