Kind: Our Rust library that provides zero-cost, type-safe identifiers

February 13, 2024
Rust stands out for its commitment to type safety and performance. At Wingback, we harness the power of Rust code to build robust tools and APIs for B2B SaaS pricing & packaging. In this article, we want to tell you about why we created kind, a library that brings clarity and precision to managing unique identifiers, ensuring our systems are both efficient and error-free. This blog post delves into how we've used Rust's type system to our advantage.

UUIDs in Rust

Managing unique identifiers is a common challenge. Rust, with its focus on safety and performance, offers a compelling approach to handling unique identifiers, commonly known as UUIDs (Universally Unique Identifiers). UUIDs are a standardized way of identifying information across systems, and they are crucial in ensuring that each piece of data can be uniquely and reliably distinguished from all others.

A UUID is a 128-bit number, typically represented by a series of 0s and 1s, and formatted in a 8-4-4-4-12 pattern as a string. This large space of random data practically guarantees that each UUID generated will be unique, making it an ideal solution for identifying resources in a distributed system without significant risk of collision.

In Rust, working with UUIDs is made straightforward through the use of external crates like uuid, which provide the necessary tools to generate, parse, and manipulate UUID values. Here's a simple example of how a UUID might be generated and used in a Rust program:
use uuid::Uuid;

pub fn main() {
   let new_id = Uuid::new_v4();
   println!("Generated UUID: {}", new_id);
This generates a new UUID using the version 4 specification, which is based on random numbers. The simplicity of generating and working with UUIDs in Rust makes it an attractive choice for developers who need to ensure type safety and uniqueness across their systems.

However, while UUIDs are excellent for guaranteeing uniqueness, they don't inherently carry any semantic meaning or type information. This can lead to potential errors when developers must work with multiple UUIDs, as there's no compile-time guarantee that the correct UUID type is being used in the correct context.

UUIDs as unique identifiers are essentially 128 bits of random data, represented as 0s and 1s. While this system is secure and prevents synchronization issues across servers, it introduces a potential for type errors when developers interact with these identifiers. To address this, we developed kind, which uses Rust's type system to distinguish between different types of identifiers, ensuring that each has its own associated type.

Introducing kind: A Type-Safe Haven for Identifiers

This is where kind steps in, enhancing the basic UUID functionality in Rust by wrapping UUIDs in a type-safe manner. By associating each UUID with a specific type, kind ensures that a UUID representing a Customer cannot be accidentally used in place of a Plan, for instance. This brings the power of Rust's type system to bear on the problem of identifier management, combining the uniqueness of UUIDs with the safety and clarity of compile-time type checking.
So kind is more than just a type alias; it's a Rust library designed to provide a zero-cost abstraction for type safety. By utilizing Rust's associated types and trait impl, kind allows us to define unique identifiers for each entity in our system using a pub struct. Here's a glimpse of how it works:
#[derive(Debug, Clone, Serialize, Deserialize, Kind)]
#[kind(class = "Cust")]
pub struct Customer {
   pub name: String,
This pub struct ensures that each Customer has a unique identifier, prefixed with "Cust_" to make it easily distinguishable. The kind macro leverages Rust's trait system, specifically the Identifiable trait, to enforce type safety at compile time.

Ensuring Type Safety at Compile Time with kind

Type safety is a cornerstone of Rust's design, aiming to prevent errors as early as possible in the development process. Rust's powerful type system allows developers to enforce strict rules about the types of values their code can work with, catching potential bugs at compile time before they can cause harm at runtime.
The kind library introduces an id type that wraps a UUID and associates it with a specific type using Rust's generics and trait system. This association ensures that identifiers for different entities are recognized as distinct types by the compiler. For example, Id<Customer> and Id<Plan> are treated as different types, even though both are backed by a UUID.
Here's a more detailed look at how kind enforces type safety:
pub struct Id<O: Identifiable> {
   uuid: Uuid,
   phantom: PhantomData<O>,

pub trait Identifiable {
   const IDENTIFIER: &'static str;

impl Identifiable for Customer {
   const IDENTIFIER: &'static str = "Cust";

impl Identifiable for Plan {
   const IDENTIFIER: &'static str = "Plan";
In this example, Id<O> is a generic struct that holds a UUID and a marker type PhantomData<O>. The PhantomData is a zero-sized type used to tell the Rust compiler about the "phantom" association between the UUID and the type O. This association does not exist at runtime (hence the term "phantom"), but it is used during compile time to enforce type safety.
The Identifiable trait is implemented for each entity that requires a unique identifier, providing a constant that serves as a type-specific prefix for serialization and deserialization purposes. The IDENTIFIER constant ensures that each type has a unique textual representation, further enhancing the clarity and safety of our identifiers.
When you try to use an Id<Customer> where an Id<Plan> is expected, the Rust compiler will raise a type error, preventing this common source of bugs. This makes the code more robust and easier to reason about, as the type of each identifier is explicit and enforced by the compiler.

This approach not only prevents errors but also aligns with Rust's philosophy of making safety a default, allowing developers to write more reliable and maintainable code.

A Use Case in Action: kind in Our Rust Codebase

To illustrate the practical use case of kind, let's look at a simple pub fn in our Rust codebase:
pub fn get_contracts(customer_id: Id<Customer>, plan_id: Id<Plan>) {
   // Implementation here
In this function, the Rust compiler ensures that the correct id type is passed as arguments, preventing any mix-up between different types of identifiers. This level of type safety is intrinsic to Rust's type system and is what makes kind an invaluable tool in our arsenal.


kind represents our commitment to leveraging the strengths of the Rust programming language to enhance our type system and ensure type safety across our codebase. It serves as an example of how Rust's compile-time guarantees can be extended to handle unique identifiers, providing a clear use case for Rust's powerful type system. As we continue to grow and refine our tools, we invite you to explore the possibilities that Rust and kind offer, ensuring that your fn main() is as error-free and efficient as possible.

Here is the original version of this article introducing kind posted on GitHub by Lead Developer Denys Séguret.
← Blog