vsdb/
lib.rs

1//! # vsdb
2//!
3//! `vsdb` is a high-performance, embedded database designed to feel like using
4//! Rust's standard collections. It provides persistent, disk-backed data
5//! structures — [`Mapx`] (a `HashMap`-like map), [`MapxOrd`] (a `BTreeMap`-like
6//! ordered map), [`VerMap`]
7//! (Git-model versioned storage with branching, commits, and merge),
8//! [`MptCalc`] / [`SmtCalc`] (stateless Merkle trie implementations),
9//! [`VerMapWithProof`] (versioned storage with Merkle root computation),
10//! [`SlotDex`] (skip-list-like index for paged queries),
11//! and [`VecDex`] (approximate nearest-neighbor vector index via HNSW).
12//!
13//! This crate is the primary entry point for most users.
14//!
15//! # Why core collections don't have `len()`
16//!
17//! The underlying LSM-Tree engine (mmdb) does not support atomic
18//! "write data + update count" across different keys.  A process crash
19//! between the two leaves them inconsistent — downstream code that
20//! trusts the count for index arithmetic will panic.  For this reason
21//! [`Mapx`], [`MapxOrd`], and other core primitives intentionally omit
22//! `len()`.
23//!
24//! Higher-level structures ([`VecDex`], [`SlotDex`]) **do** maintain a
25//! count because they fully control their own insert/remove paths.
26//! A dirty-flag mechanism automatically rebuilds the count from live
27//! data on recovery after an unclean shutdown.
28//!
29//! ## Application-layer counting
30//!
31//! If you need a count over a core collection, maintain it yourself:
32//!
33//! ```rust,ignore
34//! use vsdb::MapxOrd;
35//! use vsdb::{KeyEnDe, KeyEnDeOrdered, ValueEnDe};
36//!
37//! struct CountedMap<K: KeyEnDe + KeyEnDeOrdered, V: ValueEnDe> {
38//!     map: MapxOrd<K, V>,
39//!     count: usize,  // in-memory; rebuild on restart
40//! }
41//!
42//! impl<K: KeyEnDe + KeyEnDeOrdered + Ord, V: ValueEnDe> CountedMap<K, V> {
43//!     fn insert(&mut self, key: &K, value: &V) {
44//!         if !self.map.contains_key(key) {
45//!             self.count += 1;
46//!         }
47//!         self.map.insert(key, value);
48//!     }
49//!
50//!     fn remove(&mut self, key: &K) {
51//!         if self.map.contains_key(key) {
52//!             self.count -= 1;
53//!         }
54//!         self.map.remove(key);
55//!     }
56//!
57//!     fn len(&self) -> usize { self.count }
58//!
59//!     /// Rebuild from disk after an unclean shutdown.
60//!     fn rebuild_count(&mut self) {
61//!         self.count = self.map.iter().count();
62//!     }
63//! }
64//! ```
65
66#![deny(warnings)]
67#![recursion_limit = "512"]
68
69pub mod common;
70
71/// User-facing, typed data structures (e.g., `Mapx`, `MapxOrd`).
72pub mod basic;
73/// Data structures for representing directed acyclic graphs (DAGs).
74pub mod dagmap;
75/// Git-model versioned storage: branches, commits, merge, and history.
76pub mod versioned;
77
78/// Skip-list-like index for efficient, timestamp-based paged queries.
79pub mod slotdex;
80
81/// Lightweight, stateless Merkle trie implementations (MPT + SMT).
82pub mod trie;
83
84/// Approximate nearest-neighbor vector index (HNSW algorithm).
85pub mod vecdex;
86
87// --- Re-exports ---
88
89// Basic data structures
90pub use basic::{
91    mapx::Mapx, mapx_ord::MapxOrd, mapx_ord_rawkey::MapxOrdRawKey, orphan::Orphan,
92};
93
94// Common traits and types — only the three user-facing encoding traits
95// are re-exported.  `KeyEn`/`KeyDe`/`ValueEn`/`ValueDe` remain accessible
96// via `vsdb::common::ende::*` for advanced use cases.
97pub use common::ende::{KeyEnDe, KeyEnDeOrdered, ValueEnDe};
98
99// The unified, structured error type of the whole VSDB ecosystem
100// (defined in `vsdb_core`, shared by both crates).
101pub use common::error::{Result, VsdbError};
102
103// Versioned storage core types (previously not re-exported)
104pub use versioned::{
105    BranchId, Commit, CommitId, NO_COMMIT,
106    diff::DiffEntry,
107    handle::{Branch, BranchMut},
108    map::VerMap,
109};
110
111// DAG-related structures
112pub use dagmap::{DagMapId, raw::DagMapRaw, rawkey::DagMapRawKey};
113
114// Trie
115pub use trie::{MptCalc, MptProof, SmtCalc, SmtProof, TrieCalc, VerMapWithProof};
116
117// Slotdex — `SlotDex` is the generic struct (`SlotDex<S, K>`); the
118// width-specific aliases pin the slot type.
119pub use slotdex::{SlotDex, SlotDex32, SlotDex64, SlotDex128, SlotType};
120
121// VecDex — approximate nearest-neighbor vector index.
122pub use vecdex::{
123    HnswConfig, VecDex, VecDexCosine, VecDexCosineF64, VecDexL2, VecDexL2F64,
124    distance::{Cosine, DistanceMetric, InnerProduct, L2, Scalar},
125};
126
127// Re-export vsdb_core crate for advanced users, plus the user-facing
128// environment management functions.
129pub use vsdb_core::{self, vsdb_flush, vsdb_get_base_dir, vsdb_set_base_dir};
130
131// Persistent B+ tree (moved from vsdb_core).
132pub use basic::persistent_btree::PersistentBTree;
vsdb/lib.rs

vsdb/
lib.rs
