124 lines
3.3 KiB
Markdown
124 lines
3.3 KiB
Markdown
# 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.*
|