Merge branch 'main' into refactor/log

.github/workflows/doc.yml

@@ -0,0 +1,31 @@
+name: Doc CI
+
+on:
+  push:
+    branches: main
+  pull_request:
+    branches: main
+    paths:
+      - "guide/**"
+jobs:
+  build:
+    name: Build, Test and Deploy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch
+      pull-requests: write  # To create a PR from that branch
+    steps:
+      - name: Checkout️
+        uses: actions/checkout@v4
+
+      - name: Install and Build
+        run: |
+          cd guide
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.28/mdbook-v0.4.28-x86_64-unknown-linux-gnu.tar.gz | tar xzf -
+          echo $PWD >> $GITHUB_PATH
+          ./mdbook build
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: guide/book # The folder the action should deploy.

.gitignore

@@ -3,3 +3,4 @@
 Cargo.lock
 db_path
 bindings/python/target
+guide/book

guide/book.toml

@@ -0,0 +1,11 @@
+[book]
+authors = ["crwen"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Tonbo Guide"
+
+[output.html]
+git-repository-url = "https://github.com/tonbo-io/tonbo"
+[output.html.playground]
+runnable = false

guide/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+- [Getting started](./start.md)
+- [Examples](./examples/index.md)
+  - [Using Tonbo](./examples/declare.md)
+  - [Integrate with Datafusio](./examples/datafusion.md)
+  - [Using under Wasm](./examples/wasm.md)
+- [Contribution](./contribution/index.md)
+  - [Building](./contribution/build.md)

guide/src/contribution/build.md

@@ -0,0 +1,3 @@
+# Building Tonbo
+
+TODO

guide/src/examples/datafusion.md

@@ -0,0 +1,3 @@
+# Integrate with Datafusio
+
+TODO

guide/src/examples/declare.md

@@ -0,0 +1,102 @@
+# Using Tonbo
+
+define your schema
+
+```rust
+use tonbo::Record;
+
+/// Use macro to define schema of column family just like ORM
+/// It provides type-safe read & write API
+#[derive(Record, Debug)]
+pub struct User {
+    #[record(primary_key)]
+    name: String,
+    email: Option<String>,
+    age: u8,
+    bytes: Bytes,
+}
+```
+
+```rust
+use std::ops::Bound;
+
+use bytes::Bytes;
+use fusio::path::Path;
+use futures_util::stream::StreamExt;
+use tokio::fs;
+use tonbo::{executor::tokio::TokioExecutor, DbOption, Projection, Record, DB};
+
+
+#[tokio::main]
+async fn main() {
+    // make sure the path exists
+    let _ = fs::create_dir_all("./db_path/users").await;
+
+    let options = DbOption::new(
+        Path::from_filesystem_path("./db_path/users").unwrap(),
+        &UserSchema,
+    );
+    // pluggable async runtime and I/O
+    let db = DB::new(options, TokioExecutor::current(), UserSchema)
+        .await
+        .unwrap();
+
+    // insert with owned value
+    db.insert(User {
+        name: "Alice".into(),
+        email: Some("[email protected]".into()),
+        age: 22,
+        bytes: Bytes::from(vec![0, 1, 2]),
+    })
+    .await
+    .unwrap();
+
+    {
+        // tonbo supports transaction
+        let txn = db.transaction().await;
+
+        // get from primary key
+        let name = "Alice".into();
+
+        // get the zero-copy reference of record without any allocations.
+        let user = txn
+            .get(
+                &name,
+                // tonbo supports pushing down projection
+                Projection::All,
+            )
+            .await
+            .unwrap();
+        assert!(user.is_some());
+        assert_eq!(user.unwrap().get().age, Some(22));
+
+        {
+            let upper = "Blob".into();
+            // range scan of user
+            let mut scan = txn
+                .scan((Bound::Included(&name), Bound::Excluded(&upper)))
+                // tonbo supports pushing down projection
+                .projection(vec![1, 3])
+                // push down limitation
+                .limit(1)
+                .take()
+                .await
+                .unwrap();
+            while let Some(entry) = scan.next().await.transpose().unwrap() {
+                assert_eq!(
+                    entry.value(),
+                    Some(UserRef {
+                        name: "Alice",
+                        email: Some("[email protected]"),
+                        age: None,
+                        bytes: Some(&[0, 1, 2]),
+                    })
+                );
+            }
+        }
+
+        // commit transaction
+        txn.commit().await.unwrap();
+    }
+}
+```

guide/src/examples/index.md

@@ -0,0 +1 @@
+# Examples of using Tonbo

guide/src/examples/wasm.md

@@ -0,0 +1,72 @@
+
+# Using under Wasm
+
+This is the Wasm example of tonbo showing how to use tonbo under Wasm.
+
+## `Cargo.toml`
+
+Since only limited features of tokio can be used in wasm, we need to disable tokio and use `wasm` feature in tonbo.
+
+```toml
+fusio = { git = "https://github.com/tonbo-io/fusio.git", rev = "216eb446fb0a0c6e5e85bfac51a6f6ed8e5ed606", package = "fusio", version = "0.3.3", features = [
+  "dyn",
+  "fs",
+] }
+tonbo = { git = "https://github.com/tonbo-io/tonbo", default-features = false, features = ["wasm"] }
+```
+
+## Create DB
+
+Tonbo provide [OPFS(origin private file system)](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) as storage backend, but the path is a little different. You should use `Path::from_opfs_path` or `Path::parse` rather than `Path::from_filesystem_path` and it is not permitted to use paths that temporarily step outside the sandbox with something like `../foo` or `./bar`.
+
+```rust
+use fusio::path::Path;
+use tonbo::{executor::opfs::OpfsExecutor, DbOption, DB};
+
+async fn main() {
+
+    let options = DbOption::new(
+        Path::from_opfs_path("db_path/users").unwrap(),
+        &UserSchema,
+    );
+    let db = DB::<User, OpfsExecutor>::new(options, OpfsExecutor::new(), UserSchema)
+        .await
+        .unwrap();
+}
+```
+
+## Operations on DB
+
+After create `DB` instance, you can operate it as usual
+
+```rust
+let txn = db.transaction().await;
+
+// get from primary key
+let name = "Alice".into();
+
+let user = txn.get(&name, Projection::All).await.unwrap();
+
+let upper = "Blob".into();
+// range scan of user
+let mut scan = txn
+    .scan((Bound::Included(&name), Bound::Excluded(&upper)))
+    // tonbo supports pushing down projection
+    .projection(vec![1])
+    // push down limitation
+    .limit(1)
+    .take()
+    .await
+    .unwrap();
+
+while let Some(entry) = scan.next().await.transpose().unwrap() {
+    assert_eq!(
+        entry.value(),
+        Some(UserRef {
+            name: "Alice",
+            email: Some("[email protected]"),
+            age: None,
+        })
+    );
+}
+```

guide/src/introduction.md

@@ -0,0 +1,11 @@
+# The Tonbo user guide
+Welcome to the tonbo user guide! This book is about [tonbo](https://github.com/tonbo-io/tonbo). Tonbo is an embedded, persistent database offering fast KV-like methods for conveniently writing and scanning type-safe structured data. Tonbo can be used to build data-intensive applications, including other types of databases.
+
+
+The rough order of material in this user guide is as follows:
+1. Getting started
+2. Examples on using tonbo
+3. How to make contributions to Tonbo
+
+
+If you want to learn the design of tonbo, you can see this [blog](https://tonbo.io/blog/introducing-tonbo).