flowdb 0.8.0

A high-performance embedded time-series + JSON document storage engine (LSM-tree), with built-in IndexedDB-compatible API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! JsonDB – A JSON document database interface built on top of FlowDB.
//!
//! Provides an IndexedDB-like API with ACID transactions, secondary indexes,
//! and auto-increment support.

pub(crate) mod cursor;
pub(crate) mod db;
pub(crate) mod helpers;
pub(crate) mod keyrange;
pub(crate) mod query;
#[cfg(test)]
mod tests;
pub(crate) mod transaction;

mod encoding;
mod schema;

use serde_json::Value;

pub use cursor::{Cursor, CursorDirection, IndexCursor};
pub use db::JsonDB;
pub use keyrange::KeyRange;
pub use query::{QueryBuilder, SortDir};
pub use schema::{IndexDef as IndexSchema, StoreDef as StoreSchema};
pub use transaction::Transaction;

/// Trait implemented by the [`ObjectStore`](derive@ObjectStore) derive macro.
///
/// Provides a [`StoreDef`] that can be applied via [`JsonDB::apply_store`].
///
/// # Example
///
/// ```ignore
/// use flowdb::jsondb::ObjectStore;
///
/// #[derive(ObjectStore)]
/// #[store(key_path = "id")]
/// struct User {
///     #[index(unique)]
///     email: String,
///     #[index]
///     age: u32,
/// }
/// ```
pub trait ObjectStore {
    /// Returns the [`StoreDef`] for this struct, including all annotated indexes.
    fn store_def() -> StoreSchema;
}

/// Trait for types that can be used as a primary key argument.
///
/// Implemented for `&str`, `String`, `i64`, `i32`, `u64`, `u32`, `Value`, and `&Value`.
///
/// Used by the serde-typed methods [`JsonDB::get_doc`] and [`JsonDB::delete_doc`]
/// to accept both string and numeric keys without the caller needing to wrap them in `json!()`.
pub trait KeyArg {
    /// Convert `self` into a `serde_json::Value` suitable for use as a document key.
    fn into_value(self) -> Value;
}

impl KeyArg for &str {
    fn into_value(self) -> Value {
        Value::String(self.to_string())
    }
}
impl KeyArg for String {
    fn into_value(self) -> Value {
        Value::String(self)
    }
}
impl KeyArg for i64 {
    fn into_value(self) -> Value {
        Value::Number(self.into())
    }
}
impl KeyArg for i32 {
    fn into_value(self) -> Value {
        Value::Number((self as i64).into())
    }
}
impl KeyArg for u64 {
    fn into_value(self) -> Value {
        Value::Number(self.into())
    }
}
impl KeyArg for u32 {
    fn into_value(self) -> Value {
        Value::Number((self as u64).into())
    }
}
impl KeyArg for Value {
    fn into_value(self) -> Value {
        self
    }
}
impl KeyArg for &Value {
    fn into_value(self) -> Value {
        self.clone()
    }
}

/// Transaction mode (read-only vs read-write).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransactionMode {
    /// Read-only — queries only.
    ReadOnly,
    /// Read-write — queries, puts, deletes, and index updates.
    ReadWrite,
}