feat(helix-lib): embeddable sdk

Cargo.toml

@@ -5,7 +5,7 @@ members = [
     "helix-macros",
     "helix-cli",
     "hql-tests",
-    "metrics",
+    "metrics", "helix-lib",
 ]
 resolver = "2"
 

helix-db/src/helixc/generator/utils.rs

@@ -415,6 +415,13 @@ impl<T: Display> Separator<T> {
 }
 pub fn write_headers() -> String {
     r#"
+// Generated by HelixDB compiler
+// This file is auto-generated. Do not edit manually.
+
+#![allow(non_snake_case)]
+#![allow(unused)]
+#![allow(dead_code)]
+
 // DEFAULT CODE
 // use helix_db::helix_engine::traversal_core::config::Config;
 
@@ -477,6 +484,7 @@ use helix_db::{
     node_matches, props, embed, embed_async,
     field_addition_from_old_field, field_type_cast, field_addition_from_value,
     protocol::{
+        request::{Request, RequestType},
         response::Response,
         value::{casting::{cast, CastType}, Value},
         format::Format,

helix-lib/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "helix-lib"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+helix-db = { path = "../helix-db" }
+helix-macros = { path = "../helix-macros" }
+sonic-rs = "0.3"
+bumpalo = "3.17"
+heed3 = "0.22"
+chrono = "0.4"
+inventory = "0.3.16"
+bytes = "1.9"
+

helix-lib/README.md

@@ -0,0 +1,160 @@
+# helix-lib
+
+Embeddable graph database SDK for HelixDB.
+
+## What It Does
+
+- Compiles `.hx` schema and queries at build time
+- Generates type-safe Rust handlers
+- Provides simple query execution API
+- Compatible with HelixDB server databases
+
+## Quick Start
+
+### 1. Add to Cargo.toml
+
+```toml
+[dependencies]
+helix-lib = "0.1.0"
+serde = { version = "1.0", features = ["derive"] }
+sonic-rs = "0.3"
+
+[build-dependencies]
+helix-lib = "0.1.0"
+```
+
+### 2. Create build.rs
+
+```rust
+fn main() {
+    helix_lib::build::compile_queries_default()
+        .expect("Failed to compile queries");
+}
+```
+
+### 3. Create Schema
+
+`queries/schema.hx`:
+
+```hql
+NODE User {
+  name: String
+  email: String
+}
+```
+
+### 4. Create Queries
+
+`queries/queries.hx`:
+
+```hql
+QUERY GetUsers() =>
+  users <- N<User>
+  RETURN users
+```
+
+### 5. Use in Code
+
+```rust
+mod queries; // Generated by build.rs
+
+use helix_lib::{HelixDB, ResponseExt};
+use serde::Deserialize;
+use sonic_rs::json;
+
+#[derive(Deserialize)]
+struct GetUsersResponse {
+    users: Vec<User>,
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let config = queries::config()?;
+    let db = HelixDB::new("./data", config)?;
+
+    let data: GetUsersResponse = db.execute("GetUsers", json!({}))?.deserialize()?;
+
+    println!("Found {} users", data.users.len());
+    Ok(())
+}
+```
+
+## API
+
+### HelixDB::new(path, config)
+
+Create a new database instance.
+
+```rust
+let db = HelixDB::new("./my_data", config)?;
+```
+
+### execute(query_name, params)
+
+Execute a query by name.
+
+```rust
+let response = db.execute("GetUsers", json!({}))?;
+```
+
+### Response Methods
+
+Chain these on the response:
+
+```rust
+// Deserialize to type
+let data: MyType = response.deserialize()?;
+
+// Get JSON value
+let json = response.json()?;
+
+// Extract field
+let users: Vec<User> = response.get_field("users")?;
+```
+
+## File Structure
+
+```
+your-project/
+├── build.rs              # Compiles .hx files
+├── queries/
+│   ├── schema.hx        # Define nodes/edges
+│   └── queries.hx       # Define queries
+└── src/
+    ├── main.rs          # Your code
+    └── queries.rs       # Generated (don't edit)
+```
+
+## Build Process
+
+1. `cargo build` runs `build.rs`
+2. Compiles `queries/*.hx` files
+3. Generates `src/queries.rs` with handlers
+4. Your code imports `mod queries`
+
+## Examples
+
+### Execute with Parameters
+
+```rust
+let response = db.execute("CreateUser", json!({
+    "name": "Alice",
+    "email": "[email protected]"
+}))?;
+```
+
+### Dynamic JSON Access
+
+```rust
+let json = db.execute("GetUsers", json!({}))?.json()?;
+println!("{}", json["users"]);
+```
+
+### Field Extraction
+
+```rust
+let users: Vec<User> = db.execute("GetUsers", json!({}))?.get_field("users")?;
+```
+
+## That's It
+
+No runtime compilation. No servers. Just embedded graph database queries.