Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/liamwh/surreal-id
Create custom ID types that are guaranteed to be valid RecordIDs in SurrealDB
https://github.com/liamwh/surreal-id
rust surrealdb typesafety
Last synced: about 1 month ago
JSON representation
Create custom ID types that are guaranteed to be valid RecordIDs in SurrealDB
- Host: GitHub
- URL: https://github.com/liamwh/surreal-id
- Owner: liamwh
- License: apache-2.0
- Created: 2023-09-22T07:47:46.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-21T14:34:15.000Z (2 months ago)
- Last Synced: 2024-10-31T11:57:09.126Z (about 2 months ago)
- Topics: rust, surrealdb, typesafety
- Language: Rust
- Homepage:
- Size: 185 KB
- Stars: 16
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE.md
Awesome Lists containing this project
- awesome-surreal - surreal-id - (Rust) - Create custom ID types that are guaranteed to be valid RecordIds in SurrealDB, add them to your structs, and serialize and deserialize from SurrealDB with ease. (Libraries)
README
[](https://crates.io/crates/surreal_id)
[](https://docs.rs/surreal-id/)
[](https://codecov.io/gh/liamwh/surreal-id)
[](https://deps.rs/repo/github/liamwh/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
```rust
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>(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:
```rust
#[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::(()).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:
```rust
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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
([LICENSE-MIT](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.