mirror of
https://github.com/fluencelabs/rust-libp2p
synced 2025-06-01 12:11:20 +00:00
Merge pull request #67 from tomaka/datastore-docs
Add documentation and README for datastore
This commit is contained in:
tomaka
GitHub
commit
d56d0e59a4
76
datastore/README.md
Normal file
76
datastore/README.md
Normal file
@ -0,0 +1,76 @@
|
||||
General-purpose key-value storage.
|
||||
The keys are strings, and the values are of any type you want.
|
||||
|
||||
> **Note**: This crate is meant to be a utility for the implementation of other crates ; it
|
||||
> does not directly participate in the stack of libp2p.
|
||||
|
||||
This crate provides the `Datastore` trait, whose template parameter is the type of the value.
|
||||
It is implemented on types that represent a key-value storage.
|
||||
The only available implementation for now is `JsonFileDatastore`.
|
||||
|
||||
# JSON file datastore
|
||||
|
||||
The `JsonFileDatastore` can provide a key-value storage that loads and stores data in a single
|
||||
JSON file. It is only available if the value implements the `Serialize`, `DeserializeOwned`
|
||||
and `Clone` traits.
|
||||
|
||||
The `JsonFileDatastore::new` method will attempt to load existing data from the path you pass
|
||||
as parameter. This path is also where the data will be stored. The content of the store is
|
||||
flushed on drop or if you call `flush()`.
|
||||
|
||||
```rust
|
||||
use datastore::Datastore;
|
||||
use datastore::JsonFileDatastore;
|
||||
|
||||
let datastore = JsonFileDatastore::<Vec<u8>>::new("/tmp/test.json").unwrap();
|
||||
datastore.put("foo".into(), vec![1, 2, 3]);
|
||||
datastore.put("bar".into(), vec![0, 255, 127]);
|
||||
assert_eq!(datastore.get("foo").unwrap(), &[1, 2, 3]);
|
||||
datastore.flush().unwrap(); // optional
|
||||
```
|
||||
|
||||
# Query
|
||||
|
||||
In addition to simple operations such as `get` or `put`, the `Datastore` trait also provides
|
||||
a way to perform queries on the key-value storage, using the `query` method.
|
||||
|
||||
The struct returned by the `query` method implements the `Stream` trait from `futures`,
|
||||
meaning that the result is asynchronous.
|
||||
|
||||
> **Note**: For now the API of the `get` and `has` methods makes them potentially blocking
|
||||
> operations, though the only available implementation doesn't block. The API of these
|
||||
> methods may become asynchronous in the future if deemed necessary.
|
||||
|
||||
```rust
|
||||
extern crate datastore;
|
||||
extern crate futures;
|
||||
|
||||
use datastore::{Query, Order, Filter, FilterTy, FilterOp};
|
||||
use datastore::Datastore;
|
||||
use datastore::JsonFileDatastore;
|
||||
use futures::{Future, Stream};
|
||||
|
||||
let datastore = JsonFileDatastore::<Vec<u8>>::new("/tmp/test.json").unwrap();
|
||||
let query = datastore.query(Query {
|
||||
// Only return the keys that start with this prefix.
|
||||
prefix: "fo".into(),
|
||||
// List of filters for the keys and/or values.
|
||||
filters: vec![
|
||||
Filter {
|
||||
ty: FilterTy::ValueCompare(&vec![6, 7, 8].into()),
|
||||
operation: FilterOp::NotEqual,
|
||||
},
|
||||
],
|
||||
// Order in which to sort the results.
|
||||
orders: vec![Order::ByKeyDesc],
|
||||
// Number of entries to skip at the beginning of the results (after sorting).
|
||||
skip: 1,
|
||||
// Limit to the number of entries to return (use `u64::max_value()` for no limit).
|
||||
limit: 12,
|
||||
// If true, don't load the values. For optimization purposes.
|
||||
keys_only: false,
|
||||
});
|
||||
|
||||
let results = query.collect().wait().unwrap();
|
||||
println!("{:?}", results);
|
||||
```
|
||||
@ -18,6 +18,88 @@
|
||||
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
// DEALINGS IN THE SOFTWARE.
|
||||
|
||||
// TODO: use this once stable ; for now we just copy-paste the content of the README.md
|
||||
//#![doc(include = "../README.md")]
|
||||
|
||||
//! General-purpose key-value storage.
|
||||
//! The keys are strings, and the values are of any type you want.
|
||||
//!
|
||||
//! > **Note**: This crate is meant to be a utility for the implementation of other crates ; it
|
||||
//! > does not directly participate in the stack of libp2p.
|
||||
//!
|
||||
//! This crate provides the `Datastore` trait, whose template parameter is the type of the value.
|
||||
//! It is implemented on types that represent a key-value storage.
|
||||
//! The only available implementation for now is `JsonFileDatastore`.
|
||||
//!
|
||||
//! # JSON file datastore
|
||||
//!
|
||||
//! The `JsonFileDatastore` can provide a key-value storage that loads and stores data in a single
|
||||
//! JSON file. It is only available if the value implements the `Serialize`, `DeserializeOwned`
|
||||
//! and `Clone` traits.
|
||||
//!
|
||||
//! The `JsonFileDatastore::new` method will attempt to load existing data from the path you pass
|
||||
//! as parameter. This path is also where the data will be stored. The content of the store is
|
||||
//! flushed on drop or if you call `flush()`.
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use datastore::Datastore;
|
||||
//! use datastore::JsonFileDatastore;
|
||||
//!
|
||||
//! let datastore = JsonFileDatastore::<Vec<u8>>::new("/tmp/test.json").unwrap();
|
||||
//! datastore.put("foo".into(), vec![1, 2, 3]);
|
||||
//! datastore.put("bar".into(), vec![0, 255, 127]);
|
||||
//! assert_eq!(datastore.get("foo").unwrap(), &[1, 2, 3]);
|
||||
//! datastore.flush().unwrap(); // optional
|
||||
//! ```
|
||||
//!
|
||||
//! # Query
|
||||
//!
|
||||
//! In addition to simple operations such as `get` or `put`, the `Datastore` trait also provides
|
||||
//! a way to perform queries on the key-value storage, using the `query` method.
|
||||
//!
|
||||
//! The struct returned by the `query` method implements the `Stream` trait from `futures`,
|
||||
//! meaning that the result is asynchronous.
|
||||
//!
|
||||
//! > **Note**: For now the API of the `get` and `has` methods makes them potentially blocking
|
||||
//! > operations, though the only available implementation doesn't block. The API of these
|
||||
//! > methods may become asynchronous in the future if deemed necessary.
|
||||
//!
|
||||
//! ```no_run
|
||||
//! extern crate datastore;
|
||||
//! extern crate futures;
|
||||
//!
|
||||
//! # fn main() {
|
||||
//! use datastore::{Query, Order, Filter, FilterTy, FilterOp};
|
||||
//! use datastore::Datastore;
|
||||
//! use datastore::JsonFileDatastore;
|
||||
//! use futures::{Future, Stream};
|
||||
//!
|
||||
//! let datastore = JsonFileDatastore::<Vec<u8>>::new("/tmp/test.json").unwrap();
|
||||
//! let query = datastore.query(Query {
|
||||
//! // Only return the keys that start with this prefix.
|
||||
//! prefix: "fo".into(),
|
||||
//! // List of filters for the keys and/or values.
|
||||
//! filters: vec![
|
||||
//! Filter {
|
||||
//! ty: FilterTy::ValueCompare(&vec![6, 7, 8].into()),
|
||||
//! operation: FilterOp::NotEqual,
|
||||
//! },
|
||||
//! ],
|
||||
//! // Order in which to sort the results.
|
||||
//! orders: vec![Order::ByKeyDesc],
|
||||
//! // Number of entries to skip at the beginning of the results (after sorting).
|
||||
//! skip: 1,
|
||||
//! // Limit to the number of entries to return (use `u64::max_value()` for no limit).
|
||||
//! limit: 12,
|
||||
//! // If true, don't load the values. For optimization purposes.
|
||||
//! keys_only: false,
|
||||
//! });
|
||||
//!
|
||||
//! let results = query.collect().wait().unwrap();
|
||||
//! println!("{:?}", results);
|
||||
//! # }
|
||||
//! ```
|
||||
|
||||
extern crate base64;
|
||||
extern crate chashmap;
|
||||
#[macro_use]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user