sal-modular/docs/kvstore.md

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
• Main Components
• Supported Environments
• Quickstart & Usage Examples
• API Reference
• 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

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

// In a browser/WASM environment:
use kvstore::{KVStore, WasmStore};

// Must be called from an async context (e.g., JS Promise)
let store = WasmStore::open("mydb").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

#[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

pub struct NativeStore { /* ... */ }

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

WasmStore

pub struct WasmStore { /* ... */ }

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

Error Handling

#[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
• For integration examples, see build_instructions.md

---

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