Crate vsdb 

vsdb

vsdb is a high-performance, embedded database designed to feel like using Rust’s standard collections. It provides persistent, disk-backed data structures — Mapx (a HashMap-like map), MapxOrd (a BTreeMap-like ordered map), VerMap (Git-model versioned storage with branching, commits, and merge), MptCalc / SmtCalc (stateless Merkle trie implementations), VerMapWithProof (versioned storage with Merkle root computation), SlotDex (skip-list-like index for paged queries), and VecDex (approximate nearest-neighbor vector index via HNSW).

This crate is the primary entry point for most users.

Why core collections don’t have len()

The underlying LSM-Tree engine (mmdb) does not support atomic “write data + update count” across different keys. A process crash between the two leaves them inconsistent — downstream code that trusts the count for index arithmetic will panic. For this reason Mapx, MapxOrd, and other core primitives intentionally omit len().

Higher-level structures (VecDex, SlotDex) do maintain a count because they fully control their own insert/remove paths. A dirty-flag mechanism automatically rebuilds the count from live data on recovery after an unclean shutdown.

Application-layer counting

If you need a count over a core collection, maintain it yourself:

use vsdb::MapxOrd;
use vsdb::{KeyEnDe, KeyEnDeOrdered, ValueEnDe};

struct CountedMap<K: KeyEnDe + KeyEnDeOrdered, V: ValueEnDe> {
    map: MapxOrd<K, V>,
    count: usize,  // in-memory; rebuild on restart
}

impl<K: KeyEnDe + KeyEnDeOrdered + Ord, V: ValueEnDe> CountedMap<K, V> {
    fn insert(&mut self, key: &K, value: &V) {
        if !self.map.contains_key(key) {
            self.count += 1;
        }
        self.map.insert(key, value);
    }

    fn remove(&mut self, key: &K) {
        if self.map.contains_key(key) {
            self.count -= 1;
        }
        self.map.remove(key);
    }

    fn len(&self) -> usize { self.count }

    /// Rebuild from disk after an unclean shutdown.
    fn rebuild_count(&mut self) {
        self.count = self.map.iter().count();
    }
}

Re-exports

pub use basic::mapx::Mapx;

pub use basic::mapx_ord::MapxOrd;

pub use basic::mapx_ord_rawkey::MapxOrdRawKey;

pub use basic::orphan::Orphan;

pub use common::ende::KeyEnDe;

pub use common::ende::KeyEnDeOrdered;

pub use common::ende::ValueEnDe;

pub use common::error::Result as VsdbResult;

pub use common::error::VsdbError;

pub use versioned::diff::DiffEntry;

pub use versioned::handle::Branch;

pub use versioned::handle::BranchMut;

pub use versioned::map::VerMap;

pub use versioned::BranchId;

pub use versioned::Commit;

pub use versioned::CommitId;

pub use versioned::NO_COMMIT;

pub use dagmap::DagMapId;

pub use dagmap::raw::DagMapRaw;

pub use dagmap::rawkey::DagMapRawKey;

pub use trie::MptCalc;

pub use trie::MptProof;

pub use trie::SmtCalc;

pub use trie::SmtProof;

pub use trie::TrieCalc;

pub use trie::VerMapWithProof;

pub use slotdex::SlotDex32;

pub use slotdex::SlotDex64 as SlotDex;

pub use slotdex::SlotDex64;

pub use slotdex::SlotDex128;

pub use slotdex::SlotType;

pub use vecdex::distance::Cosine;

pub use vecdex::distance::DistanceMetric;

pub use vecdex::distance::InnerProduct;

pub use vecdex::distance::L2;

pub use vecdex::distance::Scalar;

pub use vecdex::HnswConfig;

pub use vecdex::VecDex;

pub use vecdex::VecDexCosine;

pub use vecdex::VecDexCosineF64;

pub use vecdex::VecDexL2;

pub use vecdex::VecDexL2F64;

pub use basic::persistent_btree::PersistentBTree;

pub use vsdb_core;

Modules

basic

User-facing, typed data structures (e.g., Mapx, MapxOrd).

common

Common Components

dagmap

Data structures for representing directed acyclic graphs (DAGs).

slotdex

Skip-list-like index for efficient, timestamp-based paged queries. Slot-based index for efficient, timestamp-based paged queries.

trie

Lightweight, stateless Merkle trie implementations (MPT + SMT). Lightweight, stateless Merkle trie implementations.

vecdex

Approximate nearest-neighbor vector index (HNSW algorithm). Approximate nearest-neighbor vector index backed by the HNSW algorithm.

versioned

Git-model versioned storage: branches, commits, merge, and history.

Macros

cow_bytes_bounds

define_map_wrapper

entry_or_insert_via_mock

Constants

NULL

A constant representing a null or empty byte slice.

Functions

vsdb_flush

Flushes all data to disk.

vsdb_get_base_dir

Returns the base directory path for VSDB.

vsdb_set_base_dir

Sets the base directory path for VSDB manually.