8 stable releases
new 2.2.0 | Jan 11, 2025 |
---|---|
1.0.18 |
|
1.0.17 | Jul 28, 2024 |
1.0.11 |
|
1.0.7 |
|
#168 in Procedural macros
498 downloads per month
33KB
449 lines
Surreal Derive
Description
- Generates query statements
- Provides easy access to query results via paths
- Supports serialization to
surrealdb::sql::Value
and deserialization fromsurrealdb::sql::Value
instead of using serde - Support enum
- Easy to add custom type
- Supports IDs and nested structs
- Supports relations
Installation
1. Install surreal-devl: https://crates.io/crates/surreal_devl
cargo add surreal_devl
2. Install surreal-derive:
cargo add surreal_derive_plus
Usage:
Generate query statement
use surreal_derive_plus::{SurrealDerive, surreal_quote};
use surrealdb::sql::Value;
// Example 1: Generate query statement
#[derive(SurrealDerive)]
struct User {
name: String,
age: i32,
}
let user = User { name: "john".to_string(), age: 30 };
// Generates: CREATE user:john CONTENT { name: 'john', age: 30 }
let query = surreal_quote!("CREATE #record(&user)");
Easy access to query result from path
let result: SurrealQR = db.query("SELECT * FROM user").await?.take(RPath::from(0));
// Access nested fields
let name: Option<String> = result.get(RPath::from("user").get("name"))?.deserialize()?;
Serialize and Deserialize
#[derive(SurrealDerive)]
struct User {
name: String,
age: i32,
}
// Serialize
let user = User { name: "alice", age: 25 };
let value: Value = user.serialize();
// Deserialize
let user: User = SurrealDeserializer::deserialize(&value)?;
Support id and nested struct
#[derive(SurrealDerive)]
struct Address {
street: String,
city: String,
}
#[derive(SurrealDerive)]
struct User {
name: String,
address: Address, // Nested struct
}
impl SurrealId for User {
fn id(&self) -> Thing {
Thing::from(("user", self.name.as_str()))
}
}
#[derive(SurrealDerive)]
struct Company {
user: Link<User>,
address: Address, // Nested struct
}
let address = Address {
street: String::from("123 Main St"),
city: String::from("New York")
};
let user_address = Address {
street: String::from("122 Main St"),
city: String::from("New York")
};
let user = User {
name: String::from("john"),
address: user_address
};
let company = Company {
user: Link::from(user),
address: address
};
// Create user with nested struct address
let query = db.query(surreal_quote!("CREATE #record(&user)")).await?;
// Create company with link to user eg: user = user:john
let query = surreal_quote!("CREATE #record(&company)");
let result: Option<Company> = db.query("SELECT * FROM company").await?.take(RPath::from(0));
Support relation
#[derive(SurrealDerive)]
struct Employment {
role: String,
salary: f64,
}
let edge = Employment {
role: "Developer",
salary: 100000.0
}.relate(employee, company);
// Creates relation: RELATE employee:john->employment:developer->company:acme
db.query(surreal_quote!("#relate(&edge)")).await?;
Foreign key
struct User {
name: String,
// Link to user by using id, eg: `friend = user:<john>`
friend: Box<Link<User>>
}
impl SurrealId for User {
fn id(&self) -> Thing {
Thing::from(("user", self.name.as_str()))
}
}
Support enum
Basic enum serialization
#[derive(SurrealDerive)]
enum UserRole {
Admin,
User { level: i32 },
Moderator(String),
}
// Serialization format:
// Admin -> "Admin"
// User { level: 5 } -> { "user": { "level": 5 } }
// Moderator("forums") -> { "moderator": "forums" }
// Example usage with struct
#[derive(SurrealDerive)]
struct User {
name: String,
role: UserRole,
}
let admin = User {
name: "alice".to_string(),
role: UserRole::Admin,
};
// Creates a record with structure:
// {
// "name": "alice",
// "role": "Admin"
// }
let query = surreal_quote!("CREATE #record(&admin)");
Tagged enum serialization
#[derive(SurrealDerive)]
#[surreal(tag = "type")]
enum Message {
Text { content: String },
Image { url: String, caption: String },
Audio { url: String, duration: i32 },
}
// Serialization format:
// Text { content: "Hello" } ->
// { "type": "Text", "value": { "content": "Hello" } }
// Image { url: "pic.jpg", caption: "My photo" } ->
// { "type": "Image", "value": { "url": "pic.jpg", "caption": "My photo" } }
// Audio { url: "song.mp3", duration: 180 } ->
// { "type": "Audio", "value": { "url": "song.mp3", "duration": 180 } }
// Example usage:
let text_msg = Message::Text { content: "Hello".to_string() };
// Create message
let query = surreal_quote!("CREATE #record(&text_msg)");
// Query by type
let query = surreal_quote!("SELECT * FROM message WHERE type = 'text'");
// Deserialize
let result: Message = db.query("SELECT * FROM message WHERE type = 'text'").await?.take(0)?;
assert!(matches!(result, Message::Text { .. }));
Support custom type
To support custom types, implement both SurrealSerializer
and SurrealDeserializer
traits:
use chrono::{DateTime, Utc};
use surrealdb::sql::Value;
// Example: Custom DateTime wrapper
struct CustomDateTime(DateTime<Utc>);
impl SurrealSerializer for CustomDateTime {
fn serialize(&self) -> Value {
// Convert to SurrealDB datetime value
Value::from(self.0)
}
}
impl SurrealDeserializer for CustomDateTime {
fn deserialize(value: &Value) -> Result<Self, Box<dyn std::error::Error>> {
match value {
Value::DateTime(dt) => Ok(CustomDateTime(*dt)),
_ => Err("Expected DateTime value".into())
}
}
}
// Use in structs
#[derive(SurrealDerive)]
struct Event {
name: String,
timestamp: CustomDateTime
}
// Example usage:
let event = Event {
name: "Meeting".to_string(),
timestamp: CustomDateTime(Utc::now())
};
// Serialize to SurrealDB
let query = surreal_quote!("CREATE #record(&event)");
// Deserialize from query results
let result: Event = db.query("SELECT * FROM event").await?.take(0)?;
Variables
Normal variable
let age = 2;
let query_statement = surreal_derive_plus::surreal_quote!("CREATE user SET age = #age");
Array
let arr = vec![1,2,3,1];
let query_statement = surreal_derive_plus::surreal_quote!("CREATE user SET arr = #val(&arr)");
Struct Array
let friends = vec![
User {
name: "Ethan".to_string(),
full_name: "Ethan Sullivan".to_string(),
password: "123123".to_string(),
},
User {
name: "Olivia".to_string(),
full_name: "Olivia Anderson".to_string(),
password: "123123".to_string(),
}
];
let query_statement = surreal_derive_plus::surreal_quote!("CREATE user SET friends = #val(&friends)");
DateTime
let birthday: DateTime<Utc> = Utc.with_ymd_and_hms(2020, 1, 1, 0, 0, 0).unwrap();
let query_statement = surreal_derive_plus::surreal_quote!("CREATE user SET birthday = #val(&birthday)");
Duration
let party_duration = Duration::from_millis(2 * 60 * 60 * 1000);
let party_started_at: DateTime<Utc> = Utc.with_ymd_and_hms(2023, 1, 1, 14, 0, 0).unwrap();
let query_statement = surreal_derive_plus::surreal_quote!("CREATE party SET duration = #val(&party_duration), #val(&party_started_at)");
Surreal ID
Convert a struct into it's id if it has implement SurrealId
trait
impl SurrealId for User {
fn id(&self) -> Thing {
Thing::from(("user", self.name.as_str()))
}
}
let user = User {
name: "clay".to_string(),
full_name: "clay".to_string(),
password: "123123".to_string(),
};
let query_statement = surreal_derive_plus::surreal_quote!("UPDATE #id(&user) SET age = 10");
Custom Settings
You can customize settings inside Cargo.toml
You might need to call cargo clean
for changes to take effect
[package.metadata]
# Will log the query command at runtime
surreal_enable_log = false
# Will log the generated code at build time
surreal_enable_compile_log = false
# Change the naming convention of generated statement into camel case
surreal_use_camel_case = false
# The log namespace, apply for both build time log and runtime log
surreal_namespace = "surrealql-derive"
# The macro name that use for info log, for example
surreal_info_log_macro = "println"
# The macro name that use for warning log, for example
surreal_warn_log_macro = "println"
License
This project is licensed under the MIT License - see below for details:
MIT License
Copyright (c) 2024 surreal-derive contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Dependencies
~69MB
~1.5M SLoC