puuid

Type-safe, readable IDs. Just like Stripe.

Raw UUIDs are annoying. When you see 550e8400-e29b... in your logs, you have no idea if that’s a User ID, an Order ID, or an API Key.

Even worse, if you have a function fn process(user_id: Uuid, order_id: Uuid), it is terrifyingly easy to swap the arguments by mistake. The compiler won’t catch it.

puuid fixes this by adding Prefixes and Type Safety.

The Result

1
// ❌ Before: Mystery Strings
2
"018c6427-4f30-7f89-a1b2-c3d4e5f67890"
3

4
// ✅ After: Self-Describing IDs
5
"user_018c6427-4f30-7f89-a1b2-c3d4e5f67890"
6
"ord_018c6427-4f30-7f89-a1b2-c3d4e5f67890"

Installation

Add this to your Cargo.toml:

1
[dependencies]
2
puuid = { version = "0.1", features = ["serde", "v7"] }

Features available: v4 (random), v7 (time-sorted, recommended), serde, v1, v3, v5.

How to use it

1. The Setup

You define your prefixes once, usually in a models.rs or types.rs file.

1
use puuid::{Puuid, prefix};
2

3
// Define the prefixes
4
prefix!(User, "user");
5
prefix!(Order, "ord");
6
prefix!(ApiKey, "sk");
7

8
// Define your strong types
9
pub type UserId = Puuid<User>;
10
pub type OrderId = Puuid<Order>;
11
pub type SecretKey = Puuid<ApiKey>;

2. Generating IDs

By default, we recommend UUID v7. They are sortable by time (great for databases) and random enough to be unique.

1
fn main() {
2
    let user_id = UserId::new_v7();
3
    let order_id = OrderId::new_v7();
4

5
    println!("Created User: {}", user_id);
6
    // Output: user_018c6427-4f30-7f89-a1b2-c3d4e5f67890
7
}

3. Type Safety (The Best Part)

The compiler now protects you from mixing up IDs.

1
fn delete_order(id: OrderId) {
2
    println!("Deleting order: {}", id);
3
}
4

5
fn main() {
6
    let user_id = UserId::new_v7();
7

8
    // ❌ Compile Error: expected OrderId, found UserId
9
    // delete_order(user_id);
10
}

4. Serde Integration

If you enable the serde feature, puuid handles JSON serialization and deserialization automatically. It even validates the prefix for you!

1
#[derive(Serialize, Deserialize)]
2
struct CheckoutSession {
3
    id: OrderId,
4
    customer: UserId,
5
}
6

7
fn main() {
8
    // If the JSON string starts with "ord_", it works.
9
    // If it starts with "user_" (or is just a raw UUID), it fails deserialization.
10
    let json = r#"{
11
        "id": "ord_018...",
12
        "customer": "user_018..."
13
    }"#;
14

15
    let session: CheckoutSession = serde_json::from_str(json).unwrap();
16
}

Common Questions

Does this add overhead? Zero. Puuid<T> is a “New Type” wrapper around the standard uuid::Uuid. It compiles down to the exact same thing as a raw UUID.

Can I use standard UUID methods? Yes. Puuid implements Deref, so you can call any method from the uuid crate directly on it.

1
let id = UserId::new_v7();
2
let bytes = id.as_bytes(); // Works directly
3
let raw = id.into_inner(); // Extracts the raw uuid::Uuid

How do I store this in a Database?

Postgres/MySQL: Store it as a TEXT or VARCHAR column to keep the prefix visible.
Performance critical: You can store it as UUID (binary) by calling .into_inner() before inserting, but you lose the prefix in the DB.

License

MIT. Use it freely.

Puuid