tinykv 0.3.0

A simple, file-backed, human-readable key-value store with TTL support
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

# tinykv
[![Crates.io](https://img.shields.io/crates/v/tinykv.svg)](https://crates.io/crates/tinykv)
[![Downloads](https://img.shields.io/crates/d/tinykv.svg)](https://crates.io/crates/tinykv)

A minimal file-backed key-value store for Rust with no_std support.

## Why I built this

I was working on **Tazı** (named after the Turkish sighthound), a JS/TS test runner and Jest alternative, when I needed simple persistent storage for test configurations and app settings. 

I tried existing solutions:
- sled felt like overkill for storing simple config
- pickledb looked good but seemed unmaintained  
- Rolling my own JSON persistence was getting repetitive

So I built tinykv - the simple KV store I wish existed. Turns out other Rust developers had the same problem.

## Features

- JSON file storage (human-readable, git-friendly)
- Optional TTL (expiration) per key
- Auto-save and backup options
- Atomic writes (no corruption)
- Simple serde integration
- no_std support for embedded systems
- Works in WASM environments

## Feature Flags

- **default**: Uses `serde` for maximum compatibility
- **std**: Enables standard library features (file I/O, TTL)
- **nanoserde**: Uses `nanoserde` for smaller binaries and faster compilation

## Usage

```toml
# Default (std + serde)
tinykv = "0.3"

# Embedded systems (no_std + nanoserde)
tinykv = { version = "0.3", default-features = false, features = ["nanoserde"] }

# Ultra-minimal (pure no_std)
tinykv = { version = "0.3", default-features = false }
```

### Standard usage (with file I/O)

```rust
use tinykv::TinyKV;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut kv = TinyKV::open("settings.json")?
        .with_auto_save();

    kv.set("theme", "dark")?;
    kv.set_with_ttl("session", "abc123", 3600)?; // 1 hour

    let theme: String = kv.get("theme")?.unwrap_or("light".to_string());
    println!("Using {} theme", theme);
    
    Ok(())
}
```

The file looks like this:
```json
{
  "theme": {
    "value": "dark",
    "expires_at": null
  },
  "session": {
    "value": "abc123", 
    "expires_at": 1721234567
  }
}
```

### Embedded/WASM usage (no_std)

```rust
#![no_std]
extern crate alloc;
use tinykv::TinyKV;

fn embedded_main() -> Result<(), tinykv::TinyKVError> {
    let mut kv = TinyKV::new(); // In-memory store
    
    kv.set("device_id", "ESP32_001")?;
    kv.set("sample_rate", "1000")?;
    
    // Serialize to string for flash storage
    let data = kv.to_data()?;
    // flash_write(&data)?;
    
    // Load from serialized data
    let mut kv2 = TinyKV::from_data(&data)?;
    let device_id = kv2.get("device_id");
    
    Ok(())
}
```

## When to use tinykv

**Good for:**
- CLI tool configuration
- Game save files  
- Application settings
- Test data that needs persistence
- Prototyping without database setup
- Embedded systems and IoT devices
- WASM applications

**Not for:**
- High-performance applications
- Complex queries or relationships
- Multi-user concurrent access
- Large datasets

## Platform Support
tinykv works across different environments:

- Desktop applications: Full features with file I/O, TTL, backups
- Embedded systems: Memory-efficient with nanoserde serialization
- WASM projects: Browser-compatible with minimal footprint
- IoT devices: Ultra-minimal string-based storage


## API Documentation

https://docs.rs/tinykv

## License

MIT License - see the full text in the repository.