nodedb_lite/
lib.rs

1//! # NodeDB-Lite
2//!
3//! Embedded, offline-first build of NodeDB for phones, browsers (WASM), and
4//! desktops. A single in-process library exposing the same [`NodeDb`] trait as
5//! the Origin server — document, key-value, vector, graph, full-text, spatial,
6//! columnar, timeseries, and array engines over one storage core — with CRDT
7//! sync to an Origin server over WebSocket.
8//!
9//! ## Quick start
10//!
11//! ```no_run
12//! use nodedb_lite::{NodeDbLite, PagedbStorageMem};
13//! use nodedb_client::NodeDb;
14//!
15//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
16//! let storage = PagedbStorageMem::open_in_memory().await?;
17//! let db = NodeDbLite::open(storage).await?;
18//! db.execute_sql("CREATE COLLECTION notes", &[]).await?;
19//! # Ok(())
20//! # }
21//! ```
22//!
23//! ## Durability
24//!
25//! Strict row writes commit before returning success. Native filesystem pagedb commits survive reopening without an explicit flush.
26//! Generic storage backends provide their own commit durability guarantees.
27//!
28//! Ordinary document and CRDT writes remain buffered. Unindexed `kv_put` and all `kv_delete` calls also remain buffered.
29//! Indexed KV puts and SQL KV writes commit directly. Vector rows persist during insertion.
30//! [`NodeDbLite::flush`] applies buffered document, CRDT, and KV state and persists derived engine checkpoints.
31//!
32//! Derived full-text, vector, and spatial checkpoints remain separate from strict row commits.
33//! Later maintenance errors do not roll back committed strict rows.
34//!
35//! The `open*` constructors return `Arc<NodeDbLite>` and schedule automatic flushes through [`config::LiteConfig::auto_flush_ms`].
36//! The default interval is one second. Scheduling delays and storage errors prevent a hard wall-clock durability bound.
37//! The task holds a `Weak` handle and stops when the last `Arc` disappears.
38//! Set `auto_flush_ms` to 0 for manual flushing. Call [`NodeDbLite::flush`] before dropping buffered state.
39//!
40//! For at-rest encryption see [`Encryption`].
41//!
42//! ## Cargo features
43//!
44//! - `sync` (default): the WebSocket sync client and transport. It gates `sync::client`,
45//!   `sync::transport`, `SyncClient`, `run_sync_loop`, `NodeDbLite::start_sync`, and
46//!   `NodeDbLite::stop_sync`. It pulls in `tokio-tungstenite`, `futures`, and tokio's `net` feature.
47//!
48//! A native build with `--no-default-features` contains no network code. It links no WebSocket
49//! client and enables no tokio networking. Local change capture still compiles: outbound queues,
50//! pending-entry types, and the `sync::SyncDelegate` trait. An embedder can drive its own
51//! transport through `SyncDelegate`. On wasm32 the `sync` module is absent and the feature has no
52//! effect.
53//!
54//! [`NodeDb`]: nodedb_client::NodeDb
55
56pub mod config;
57pub mod engine;
58pub mod error;
59pub mod event;
60pub mod identity;
61pub mod index;
62pub mod nodedb;
63pub mod query;
64pub mod runtime;
65pub mod sequence;
66pub mod storage;
67#[cfg(not(target_arch = "wasm32"))]
68pub mod sync;
69pub mod tasks;
70
71pub use config::LiteConfig;
72pub use error::LiteError;
73pub use nodedb::{BatchItem, GraphRagParams, HybridSearchParams, NodeDbLite, SyncGate};
74pub use nodedb_mem::{EngineId, MemoryGovernor, PressureLevel};
75pub use nodedb_query;
76pub use nodedb_types::id_gen;
77pub use storage::corruption::CorruptionPolicy;
78pub use storage::encryption::Encryption;
79pub use storage::engine::{StorageEngine, WriteOp};
80#[cfg(not(target_arch = "wasm32"))]
81pub use storage::pagedb_storage::PagedbStorageDefault;
82#[cfg(target_arch = "wasm32")]
83pub use storage::pagedb_storage::PagedbStorageOpfs;
84pub use storage::pagedb_storage::{PagedbStorage, PagedbStorageMem};
nodedb_lite/lib.rs

nodedb_lite/
lib.rs
