sled_extensions/
lib.rs

1#![deny(missing_docs)]
2
3//! # Sled Extensions
4//! _Wrappers around the [Sled embedded database](https://docs.rs/sled/0.28.0/sled) to permit
5//! storing structured data_
6//! - [Join the discussion on Matrix](https://matrix.to/#/!skqvSdiKcFwIdaQoLD:asonix.dog?via=asonix.dog)
7//!
8//! Using Sled Extensions is much like using Sled. The Tree API mirrors Sled's directly, and the
9//! [`Db`] type is extended through traits.
10//!
11//! ```rust
12//! use sled_extensions::{Config, Db, DbExt};
13//!
14//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
15//! let db = Config::default().temporary(true).open()?;
16//! let tree = db.open_json_tree::<usize>("json-tree")?;
17//!
18//! tree.insert(b"hey", 32)?;
19//!
20//! if let Some(num) = tree.get(b"hey")? {
21//!     assert_eq!(num, 32);
22//! } else {
23//!     unreachable!("Shouldn't be empty");
24//! }
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! Available features
30//! - `bincode` - Enable storing bincode-encoded data
31//! - `cbor` - Enable storing cbor-encoded data
32//! - `json` - Enable storing json-encoded data
33
34mod db;
35mod encoding;
36mod error;
37mod expiring_tree;
38mod structured_tree;
39
40pub use sled::{abort, Config, Db, IVec, TransactionError};
41
42pub use self::{
43    db::DbExt,
44    encoding::Encoding,
45    error::{Error, Result},
46    structured_tree::CompareAndSwapError,
47};
48
49/// Basic structured trees
50///
51/// This module contains the base types that other trees are built on. In fact, most trees are
52/// just type aliases for the basic trees here with pre-defined encodings.
53pub mod structured {
54    pub use crate::structured_tree::{
55        StructuredBatch as Batch, StructuredIter as Iter,
56        StructuredTransactionalTree as TransactionalTree, StructuredTree as Tree,
57    };
58
59    /// This module names types for more easily interacting with Expiring Trees
60    ///
61    /// The number of type parameters are reduced by asserting that the encoder used for the
62    /// expiring tree's metadata is the same encoder used for values stored in the tree.
63    pub mod expiring {
64        use crate::expiring;
65
66        /// A basic expiring strutured tree
67        ///
68        /// This tree is an alias for a generic expiring tree, but asserts that the metadata
69        /// encoding is the same as the value encoding.
70        pub type Tree<V, E> = expiring::Tree<V, E, E>;
71
72        /// The builder associated with the Tree
73        pub type TreeBuilder<V, E> = expiring::TreeBuilder<V, E, E>;
74
75        /// The Iterator associated with the Tree
76        pub type Iter<'a, V, E> = expiring::Iter<'a, V, E, E>;
77
78        /// The Batch associated with the Tree
79        pub type Batch<V, E> = expiring::Batch<V, E>;
80
81        /// The TransactionalTree associated with the Tree
82        pub type TransactionalTree<'a, V, E> = expiring::TransactionalTree<'a, V, E, E>;
83    }
84}
85
86/// Basic expiring trees
87///
88/// The trees defined here are generic over Encoder types for the metadata and values stored in
89/// the tree.
90pub mod expiring {
91    pub use crate::expiring_tree::{
92        ExpiringBatch as Batch, ExpiringIter as Iter,
93        ExpiringTransactionalTree as TransactionalTree, ExpiringTree as Tree,
94        ExpiringTreeBuilder as TreeBuilder,
95    };
96
97    /// "Plain" expiring trees
98    ///
99    /// This module is generic over the metadata encoding, but assumes values stored in the tree
100    /// are IVecs. This allows for binary types to be stored without impacting performance
101    pub mod plain {
102        use sled::IVec;
103
104        pub use crate::encoding::PlainEncoding;
105
106        /// The "Plain" Tree
107        pub type Tree<E> = super::Tree<IVec, E, PlainEncoding>;
108
109        /// The "Plain" Tree's Builder
110        pub type TreeBuilder<E> = super::TreeBuilder<IVec, E, PlainEncoding>;
111
112        /// The "Plain" Tree's Batch
113        pub type Batch = super::Batch<IVec, PlainEncoding>;
114
115        /// The "Plain" Tree's Iterator
116        pub type Iter<'a, E> = super::Iter<'a, IVec, E, PlainEncoding>;
117
118        /// The "Plain" Tree's TransactionalTree
119        pub type TransactionalTree<'a, E> = super::TransactionalTree<'a, IVec, E, PlainEncoding>;
120    }
121}
122
123#[cfg(feature = "bincode")]
124/// A module containing trees that are pre-configured to store Bincode-encoded data
125pub mod bincode {
126    use crate::structured;
127
128    pub use crate::encoding::BincodeEncoding;
129
130    /// A tree that stores data of type V encoded as Bincode
131    pub type Tree<V> = structured::Tree<V, BincodeEncoding>;
132
133    /// The bincode tree's iterator
134    pub type Iter<V> = structured::Iter<V, BincodeEncoding>;
135
136    /// The bincode tree's batch
137    pub type Batch<V> = structured::Batch<V, BincodeEncoding>;
138
139    /// The bincode tree's transaction
140    pub type TransactionalTree<'a, V> = structured::TransactionalTree<'a, V, BincodeEncoding>;
141
142    /// A module containing expiring trees that store Bincode-encoded data
143    pub mod expiring {
144        use crate::expiring;
145
146        use super::BincodeEncoding;
147
148        /// An expiring tree that stores data of type V encoded as Bincode
149        pub type Tree<V> = expiring::Tree<V, BincodeEncoding, BincodeEncoding>;
150
151        /// The expiring bincode tree's builder
152        pub type TreeBuilder<V> = expiring::TreeBuilder<V, BincodeEncoding, BincodeEncoding>;
153
154        /// The expiring bincode tree's iterator
155        pub type Iter<'a, V> = expiring::Iter<'a, V, BincodeEncoding, BincodeEncoding>;
156
157        /// The expiring bincode tree's batch
158        pub type Batch<V> = expiring::Batch<V, BincodeEncoding>;
159
160        /// The expiring bincode tree's transaction
161        pub type TransactionalTree<'a, V> =
162            expiring::TransactionalTree<'a, V, BincodeEncoding, BincodeEncoding>;
163    }
164}
165
166#[cfg(feature = "cbor")]
167/// A module containing trees that are pre-configured to store Cbor-encoded data
168pub mod cbor {
169    use crate::structured_tree::{
170        StructuredBatch, StructuredIter, StructuredTransactionalTree, StructuredTree,
171    };
172
173    pub use crate::encoding::CborEncoding;
174
175    /// A tree that stores data of type V encoded as Cbor
176    pub type Tree<V> = StructuredTree<V, CborEncoding>;
177
178    /// The cbor tree's iterator
179    pub type Iter<V> = StructuredIter<V, CborEncoding>;
180
181    /// The cbor tree's batch
182    pub type Batch<V> = StructuredBatch<V, CborEncoding>;
183
184    /// The cbor tree's transaction
185    pub type TransactionalTree<'a, V> = StructuredTransactionalTree<'a, V, CborEncoding>;
186
187    /// A module containing expiring trees that store Cbor-encoded data
188    pub mod expiring {
189        use crate::expiring;
190
191        use super::CborEncoding;
192
193        /// An expiring tree that stores data of type V encoded as Cbor
194        pub type Tree<V> = expiring::Tree<V, CborEncoding, CborEncoding>;
195
196        /// The expiring cbor tree's builder
197        pub type TreeBuilder<V> = expiring::TreeBuilder<V, CborEncoding, CborEncoding>;
198
199        /// The expiring cbor tree's iterator
200        pub type Iter<'a, V> = expiring::Iter<'a, V, CborEncoding, CborEncoding>;
201
202        /// The expiring cbor tree's batch
203        pub type Batch<V> = expiring::Batch<V, CborEncoding>;
204
205        /// The expiring cbor tree's transaction
206        pub type TransactionalTree<'a, V> =
207            expiring::TransactionalTree<'a, V, CborEncoding, CborEncoding>;
208    }
209}
210
211#[cfg(feature = "json")]
212/// A module containing trees that are pre-configured to store Json-encoded data
213pub mod json {
214    use crate::structured_tree::{
215        StructuredBatch, StructuredIter, StructuredTransactionalTree, StructuredTree,
216    };
217
218    pub use crate::encoding::JsonEncoding;
219
220    /// A tree that stores data of type V encoded as Json
221    pub type Tree<V> = StructuredTree<V, JsonEncoding>;
222
223    /// The json tree's iterator
224    pub type Iter<V> = StructuredIter<V, JsonEncoding>;
225
226    /// The json tree's batch
227    pub type Batch<V> = StructuredBatch<V, JsonEncoding>;
228
229    /// The json tree's transaction
230    pub type TransactionalTree<'a, V> = StructuredTransactionalTree<'a, V, JsonEncoding>;
231
232    /// A module containing expiring trees that store Json-encoded data
233    pub mod expiring {
234        use crate::expiring;
235
236        use super::JsonEncoding;
237
238        /// An expiring tree that stores data of type V encoded as Json
239        pub type Tree<V> = expiring::Tree<V, JsonEncoding, JsonEncoding>;
240
241        /// The expiring json tree's builder
242        pub type TreeBuilder<V> = expiring::TreeBuilder<V, JsonEncoding, JsonEncoding>;
243
244        /// The expiring json tree's iterator
245        pub type Iter<'a, V> = expiring::Iter<'a, V, JsonEncoding, JsonEncoding>;
246
247        /// The expiring json tree's batch
248        pub type Batch<V> = expiring::Batch<V, JsonEncoding>;
249
250        /// The expiring json tree's transaction
251        pub type TransactionalTree<'a, V> =
252            expiring::TransactionalTree<'a, V, JsonEncoding, JsonEncoding>;
253    }
254}
sled_extensions/lib.rs

sled_extensions/
lib.rs
