rust-type-driven-design

Type-Driven Design

Layer 1: Language Mechanics

Core Question

How can the type system prevent invalid states?

Before reaching for runtime checks:

• Can the compiler catch this error?
• Can invalid states be unrepresentable?
• Can the type encode the invariant?

---

Thinking Prompt

Before adding runtime validation:

1. Can the type encode the constraint?

   • Numeric range → bounded types or newtypes
   • Valid states → type state pattern
   • Semantic meaning → newtype

2. When is validation possible?

   • At construction → validated newtype
   • At state transition → type state
   • Only at runtime → Result with clear error

3. Who needs to know the invariant?

   • Compiler → type-level encoding
   • API users → clear type signatures
   • Runtime only → documentation

---

Pattern Quick Reference

Pattern	Purpose	Example
Newtype	Type safety	struct UserId(u64);
Type State	State machine	Connection<Connected>
PhantomData	Variance/lifetime	PhantomData<&'a T>
Marker Trait	Capability flag	trait Validated {}
Builder	Gradual construction	Builder::new().name("x").build()
Sealed Trait	Prevent external impl	mod private { pub trait Sealed {} }

---

Pattern Examples

Newtype — validated domain value

struct Email(String);  // Not just any string

impl Email {
    pub fn new(s: &str) -> Result<Self, ValidationError> {
        // Validate once, trust forever
        validate_email(s)?;
        Ok(Self(s.to_string()))
    }
}

Type State — compile-time state machine

struct Connection<State>(TcpStream, PhantomData<State>);

struct Disconnected;
struct Connected;
struct Authenticated;

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { todo!() }
}

impl Connection<Connected> {
    fn authenticate(self) -> Connection<Authenticated> { todo!() }
}
// compile error if you call authenticate() on Disconnected