surreal-id

surreal-id

The surreal-id crate offers a standardized way to create and validate IDs in your application for usage with SurrealDB. Using the [NewId] trait, the crate streamlines the ID type defining process with a blanket implementation of new that handles errors like malformed or empty IDs, and ensures consistency with associated table names and functionality with SurrealDB. This also enables developers to create custom IDs in their application layer and serialize and deserialize those types safely from SurrealDB, ensuring type safety and consistency throughout the app.

Example

use serde::{Deserialize, Serialize};
use surreal_id::NewId;
use surrealdb::{opt::RecordId, sql::Id};

pub const USERS_TABLE: &str = "users";

#[derive(Serialize, Deserialize)]
pub struct UserId(RecordId);

impl NewId for UserId {
    const TABLE: &'static str = USERS_TABLE;

    fn from_inner_id<T: Into<Id>>(inner_id: T) -> Self {
        UserId(RecordId {
            tb: Self::TABLE.to_string(),
            id: inner_id.into(),
        })
    }

    fn get_inner_string(&self) -> String {
        self.0.id.to_string()
    }
}

Now you can instantiate the UserId type using new, and use it in your struct with SurrealDB like so:

#[derive(Serialize, Deserialize)]
pub struct User {
    id: UserId,
    name: String,
}

// The new function is automatically created for us
// by the blanket implementation from the NewId trait
let typesafe_custom_id = UserId::new("fa77edc3-56ed-4208-9e0b-c0b1c32e2d34").unwrap();

let user_to_be_created = User {
    id: typesafe_custom_id,
    name: "John Doe".to_string(),
};

let db = Surreal::new::<Mem>(()).await.unwrap();
db.use_ns("test").use_db("test").await.unwrap();

let create_result = db.create(USERS_TABLE).content(&user_to_be_created).await;
let retrieved_user: User = create_result.unwrap().remove(0);

assert_eq!(user_to_be_created, retrieved_user)

You also get the following methods on your custom ID type for free:

typesafe_custom_id.table() // returns "users"
typesafe_custom_id.id_with_brackets() // returns "⟨fa77edc3-56ed-4208-9e0b-c0b1c32e2d34⟩"
typesafe_custom_id.id_without_brackets() // returns "fa77edc3-56ed-4208-9e0b-c0b1c32e2d34"

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.