# kvstore Crate Overview

`kvstore` is a runtime-agnostic, async key-value storage crate designed for both native (using `sled`) and WASM/browser (using IndexedDB via the `idb` crate) environments. It provides a unified API for all platforms, enabling seamless storage abstraction for Rust applications.

---

## Table of Contents
- [Summary](#summary)
- [Main Components](#main-components)
- [Supported Environments](#supported-environments)
- [Quickstart & Usage Examples](#quickstart--usage-examples)
- [API Reference](#api-reference)
- [More Information](#more-information)

---

## Summary
The `kvstore` crate defines an async trait for key-value storage, with robust implementations for native and browser environments. It is the storage backend for higher-level crates such as `vault`.

---

## Main Components
- **KVStore Trait**: Async interface for key-value operations (`get`, `set`, `remove`, `contains_key`, `keys`, `clear`).
- **NativeStore**: Native backend using `sled` (requires Tokio runtime).
- **WasmStore**: WASM/browser backend using IndexedDB via the `idb` crate.
- **KVError**: Error type covering I/O, serialization, encryption, and backend-specific issues.

---

## Supported Environments
- **Native:** Uses `sled` for fast, embedded storage. Blocking I/O is offloaded to background threads using Tokio.
- **Browser (WASM):** Uses IndexedDB via the `idb` crate. Fully async and Promise-based.

---

## Quickstart & Usage Examples

### Native Example
```rust
use kvstore::{KVStore, NativeStore};

#[tokio::main]
async fn main() {
    let store = NativeStore::open("/tmp/mydb").unwrap();
    store.set("foo", b"bar").await.unwrap();
    let val = store.get("foo").await.unwrap();
    println!("Got: {:?}", val);
}
```

### WASM/Browser Example
```rust
// In a browser/WASM environment:
use kvstore::{KVStore, WasmStore};

// Must be called from an async context (e.g., JS Promise)
let store = WasmStore::open("vault").await.unwrap();
store.set("foo", b"bar").await.unwrap();
let val = store.get("foo").await.unwrap();
// Use the value as needed
```

---

## API Reference

### KVStore Trait
```rust
#[async_trait]
pub trait KVStore {
    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>>;
    async fn set(&self, key: &str, value: &[u8]) -> Result<()>;
    async fn remove(&self, key: &str) -> Result<()>;
    async fn contains_key(&self, key: &str) -> Result<bool>;
    async fn keys(&self) -> Result<Vec<String>>;
    async fn clear(&self) -> Result<()>;
}
```

### NativeStore
```rust
pub struct NativeStore { /* ... */ }

impl NativeStore {
    pub fn open(path: &str) -> Result<Self>;
    // Implements KVStore trait
}
```

### WasmStore
```rust
pub struct WasmStore { /* ... */ }

impl WasmStore {
    pub async fn open(name: &str) -> Result<Self>;
    // Implements KVStore trait
}
```

### Error Handling
```rust
#[derive(Debug, Error)]
pub enum KVError {
    Io(std::io::Error),
    KeyNotFound(String),
    StoreNotFound(String),
    Serialization(String),
    Deserialization(String),
    Encryption(String),
    Decryption(String),
    Other(String),
}
```

---

## More Information
- For architecture and design, see [`architecture.md`](architecture.md)
- For integration examples, see [`build_instructions.md`](build_instructions.md)

---

*For advanced usage, backend customization, and WASM integration, see the linked documents above.*