Hyperbee

A peer-to-peer append-only B-tree built on Hypercore. Compatible with the JavaScript version.

$ cargo add hyperbee

Usage

From the examples:

use hyperbee::Hyperbee;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hb = Hyperbee::from_ram().await?;
    // Insert "world" with key "hello"
    hb.put(b"hello", Some(b"world")).await?;

    // Get the value for key "hello"
    let Some((_seq, Some(val))) = hb.get(b"hello").await? else {
        panic!("could not get value");
    };
    assert_eq!(val, b"world");

    // Trying to get a non-exsitant key returns `None`
    let res = hb.get(b"no key here").await?;
    assert_eq!(res, None);

    // Deleting a key returns `true` if it was present
    let res = hb.del(b"hello").await?;
    assert!(res.is_some());

    // Getting deleted key returns `None`
    let res = hb.get(b"hello").await?;
    assert_eq!(res, None);

    Ok(())
}

Foreign Language Bindings

We use UniFFI to generate libraries for other languages. To build the library for python run:

cargo build -F ffi && cargo run -F ffi --bin uniffi-bindgen generate --library target/debug/libhyperbee.so --language python --out-dir out

This generates a file out/hyperbee.py, which an be used. This file requires that libhyperbee.so be present alongside the .py file. Distributable python packages are still a work-in-progress. Currently only Python is tested. See the tests for example usage.

Parity with JS Hyperbee

• full functional interoperability with JS Hyperbee files
• read, write, and delete operations
• in-order key streaming like JS's createReadStream
• support gt, lt, etc bounds for key streaming
• accept compare-and-swap for put and del.
• support prefixed key operations like JS's sub
• one-to-one binary output #23

Future work

• Build FFI wrappers
• improved wire format
• configurable tree parameters

Development

Run the tests with $ cargo test.

Each significant pull request should include an update the CHANGELOG.md

Release

Releases are mostly handled with cargo release. After each Rust release. We manually release a new python package. Building the python package is done with maturin and it is released with twine.

# create a virtualenv with the tools we need
python -m venv venv && . venv/bin/activate
pip install --upgrade twine maturin

# build the wheels
python -m maturin build --release

# Upload the wheels to pypi. This uses my api token from ~/.pypirc
python -m twine upload target/wheels/hyperbeepy-<target>.whl