Skip to content

Create custom ID types that are guaranteed to be valid RecordIDs in SurrealDB

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE.md
MIT
LICENSE-MIT.md
Notifications You must be signed in to change notification settings

liamwh/surreal-id

Repository files navigation

Crates.io Documentation Codecov Dependency status

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

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.

About

Create custom ID types that are guaranteed to be valid RecordIDs in SurrealDB

Topics

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE.md
MIT
LICENSE-MIT.md

Stars

Watchers

Forks

Packages

No packages published