m05-type-driven

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?

---

| Pattern | Don't Just Say | Ask Instead |

|---------|----------------|-------------|

| Primitive obsession | "It's just a string" | What does this value represent? |

| Boolean flags | "Add an is_valid flag" | Can states be types? |

| Optional everywhere | "Check for None" | Is absence really possible? |

| Validation at runtime | "Return Err if invalid" | Can we validate at construction? |

---

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

1. When is validation possible?

- At construction → validated newtype

- At state transition → type state

- Only at runtime → Result with clear error

1. Who needs to know the invariant?

- Compiler → type-level encoding

- API users → clear type signatures

- Runtime only → documentation

---

When type design is unclear:

```

"Need to validate email format"

↑ Ask: Is this a domain value object?

↑ Check: m09-domain (Email as Value Object)

↑ Check: domain-* (validation requirements)

```

| Situation | Trace To | Question |

|-----------|----------|----------|

| What types to create | m09-domain | What's the domain model? |

| State machine design | m09-domain | What are valid transitions? |

| Marker trait usage | m04-zero-cost | Static or dynamic dispatch? |

---

From design to implementation:

```

"Need type-safe wrapper for primitives"

↓ Newtype: struct UserId(u64);

"Need compile-time state validation"

↓ Type State: Connection

"Need to track phantom type parameters"

↓ PhantomData: PhantomData

"Need capability markers"

↓ Marker Trait: trait Validated {}

"Need gradual construction"

↓ Builder: Builder::new().field(x).build()

```

---

| Pattern | Purpose | Example |

|---------|---------|---------|

| Newtype | Type safety | struct UserId(u64); |

| Type State | State machine | Connection |

| 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 {} } |

Newtype

```rust

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

impl Email {

pub fn new(s: &str) -> Result {

// Validate once, trust forever

validate_email(s)?;

Ok(Self(s.to_string()))

}

}

```

Type State

```rust

struct Connection(TcpStream, PhantomData);

struct Disconnected;

struct Connected;

struct Authenticated;

impl Connection {

fn connect(self) -> Connection { ... }

}

impl Connection {

fn authenticate(self) -> Connection { ... }

}

```

---

| Need | Pattern |

|------|---------|

| Type safety for primitives | Newtype |

| Compile-time state validation | Type State |

| Lifetime/variance markers | PhantomData |

| Capability flags | Marker Trait |

| Gradual construction | Builder |

| Closed set of impls | Sealed Trait |

| Zero-sized type marker | ZST struct |

---

| Anti-Pattern | Why Bad | Better |

|--------------|---------|--------|

| Boolean flags for states | Runtime errors | Type state |

| String for semantic types | No type safety | Newtype |

| Option for uninitialized | Unclear invariant | Builder |

| Public fields with invariants | Invariant violation | Private + validated new() |

---

| When | See |

|------|-----|

| Domain modeling | m09-domain |

| Trait design | m04-zero-cost |

| Error handling in constructors | m06-error-handling |

| Anti-patterns | m15-anti-pattern |