When the compiler catches bugs before you run the code
You are building a configuration system. You need a DatabaseConnection that requires a host, a port, and a password. In Python or JavaScript, you write a constructor that takes these arguments, and you hope the caller provides them. If they forget the password, you get a runtime error. Maybe a panic. Maybe a silent failure that crashes the server an hour later.
Rust lets you do better. You can design the types so that a DatabaseConnection cannot exist without a password. The compiler rejects any code that tries to create one. You move the validation from runtime to compile time. This is type-level programming. You encode logic in the type system, and the compiler executes that logic while checking your code.
Types as data, traits as functions
Type-level programming means writing programs that run at compile time. The "data" in these programs are types. The "functions" are traits and generics. The "output" is either valid machine code or a compiler error.
Rust does not have dependent types like Idris or Agda. You cannot pass a value N and have the type be Array<N> where N varies at runtime. Rust's type system is Turing-complete through const generics, trait resolution, and associated types, but the values you manipulate are known at compile time. You use types to represent states, constraints, or metadata. You use traits to define how those types interact.
Think of it like a puzzle. The types are the shapes of the pieces. The compiler is the table. You can only snap pieces together if the shapes match. Type-level programming is designing the shapes so that invalid combinations physically cannot connect. If you try to force a square peg into a round hole, the compiler stops you.
Minimal example: a state machine with phantom types
The most common entry point is the phantom type. A phantom type is a type parameter that appears in the signature but not in the fields. It carries no runtime data. It exists only to tell the compiler about a property of the value.
Here is a door that tracks whether it is open or closed.
use std::marker::PhantomData;
// The door carries a state type S, but stores no data for S.
struct Door<S> {
_state: PhantomData<S>,
}
// Empty structs represent the possible states.
struct Closed;
struct Open;
// Only a closed door can be opened.
impl Door<Closed> {
/// Transitions the door from closed to open.
/// Consumes self to prevent using the old state.
fn open(self) -> Door<Open> {
Door { _state: PhantomData }
}
}
// Only an open door can be closed.
impl Door<Open> {
/// Transitions the door from open to closed.
fn close(self) -> Door<Closed> {
Door { _state: PhantomData }
}
}
fn main() {
// Create a door in the closed state.
let door = Door::<Closed> { _state: PhantomData };
// Open it. The type changes to Door<Open>.
let open_door = door.open();
// Close it. The type changes back to Door<Closed>.
let closed_door = open_door.close();
// This would fail to compile:
// closed_door.close();
// Error: Door<Closed> does not implement close.
}
The PhantomData marker tells the compiler that Door logically contains an S, even though the memory layout doesn't include it. This affects drop checks and variance. The convention is to name the field _state or _marker to signal that it is unused at runtime.
Walkthrough: how the compiler tracks state
When you write Door::<Closed>, you are instantiating the generic struct with S = Closed. The compiler generates a concrete type Door<Closed>. The impl Door<Closed> block provides methods for that specific type. The open method returns Door<Open>.
If you try to call open on a Door<Open>, the compiler looks for an impl Door<Open> that defines open. It finds none. It emits E0599 (no function named open found for struct Door<Open>). The error message tells you exactly which state is wrong. You cannot accidentally open an open door. The code simply does not exist.
This pattern scales. You can add Locked, Broken, or UnderMaintenance states. Each state gets its own impl block. Methods are only available when the state permits them. The compiler enforces the state machine transitions.
Make the impossible states unrepresentable. If a state cannot exist, don't write code that allows it.
Realistic example: a builder that forces required fields
Phantom types shine in builder patterns. A builder constructs a complex object step by step. You can use type-level programming to ensure the user sets all required fields before calling build().
use std::marker::PhantomData;
// The builder tracks progress through the State type parameter.
struct UserBuilder<State> {
name: Option<String>,
age: Option<u32>,
_state: PhantomData<State>,
}
// State types represent the progress.
struct Empty;
struct NameSet;
struct AgeSet;
struct Ready;
// Start with an empty builder.
impl UserBuilder<Empty> {
/// Creates a new builder with no fields set.
fn new() -> Self {
UserBuilder {
name: None,
age: None,
_state: PhantomData,
}
}
/// Sets the name and transitions to NameSet state.
fn name(self, name: &str) -> UserBuilder<NameSet> {
UserBuilder {
name: Some(name.into()),
age: None,
_state: PhantomData,
}
}
}
// After name is set, you can set the age.
impl UserBuilder<NameSet> {
/// Sets the age and transitions to Ready state.
fn age(self, age: u32) -> UserBuilder<Ready> {
UserBuilder {
name: self.name,
age: Some(age),
_state: PhantomData,
}
}
}
// Only a Ready builder can be built.
impl UserBuilder<Ready> {
/// Consumes the builder and returns the final user data.
/// Unwraps are safe because the type guarantees fields are set.
fn build(self) -> (String, u32) {
(self.name.unwrap(), self.age.unwrap())
}
}
fn main() {
// This compiles: name then age, then build.
let user = UserBuilder::new()
.name("Alice")
.age(30)
.build();
// This fails to compile:
// UserBuilder::new().build();
// Error: UserBuilder<Empty> does not implement build.
// This also fails:
// UserBuilder::new().name("Bob").build();
// Error: UserBuilder<NameSet> does not implement build.
}
The build method only exists on UserBuilder<Ready>. You cannot call it until you have set both name and age. The order is enforced by the state transitions. You must call name before age in this design. If you want to allow any order, you need more states or a different approach. The type system forces you to think about the workflow.
The unwrap calls inside build are safe. The type system guarantees that name and age are Some. You never hit a panic here. The compiler proved the invariants.
Trust the type system. If it compiles, the invariant holds.
Pitfalls and compiler errors
Type-level programming has costs. Error messages can be cryptic. When the compiler rejects code, it often says E0308 (mismatched types) or E0277 (trait bound not satisfied). It might not tell you which state is wrong. You have to read the type signatures to understand the failure.
Monomorphization bloat is another concern. Every combination of type parameters generates a separate copy of the code. If you have a complex state machine with many states, the binary size can grow. Profile your binary if size matters. The compiler optimizes some duplication, but not all.
Over-engineering is the biggest risk. Not every validation needs to be type-level. If the data comes from user input or a file, you must validate at runtime. Type-level checks only work for data known at compile time. Don't use phantom types to validate a string from a text box. Use runtime checks for dynamic data.
Keep the state machine small. Bloat grows exponentially with states.
Decision: when to use type-level programming
Use type-level programming when the invariant is critical and known at compile time. Use it for state machines where invalid transitions indicate a logic error. Use it for builders that enforce required fields. Use it for unit systems where you want to prevent adding meters to seconds.
Use runtime validation when data comes from users, networks, or files. Use runtime checks when the cost of compile-time complexity outweighs the benefit. Use runtime checks for performance-critical paths where type resolution adds overhead.
Use enums for simple state machines where transitions are frequent and dynamic. Enums are lighter weight and easier to read. Use enums when you need to inspect the state at runtime. Use enums when the state space is small and fixed.
Use trait bounds for polymorphism, not just type-level logic. Traits allow you to write generic code that works with many types. Use trait bounds when you want to abstract over behavior. Use trait bounds when you need to dispatch based on type at compile time.
Make the compiler your QA team. Feed it the right constraints.