dawidpereira Type System Design
Core Question
What invariants should the type system enforce?
Every time you reach for a String where an enum would work,
a u64 where a UserId would be clearer, or a runtime check
where a compile-time guarantee is possible — ask whether the
type system can do the work for you.
The Rust type system is powerful enough to catch entire categories of bugs at compile time. The question is always: is the added type complexity worth the guarantee?
Error → Design Question
| Error | Don't Just Say | Ask Instead |
|---|---|---|
| E0277 (trait not satisfied) | "Add the bound" | Is the trait design right for this use case? |
| E0308 (type mismatch) | "Cast it" | Are the types modeling the domain correctly? |
| E0599 (method not found) | "Wrong type" | Should this method exist on this type? |
| E0038 (not object-safe) | "Box it" | Should this use static dispatch instead? |
Quick Decisions
| Situation | Reach For | Why |
|---|---|---|
| Prevent mixing IDs (user_id vs order_id) | Newtype wrapper | Compile-time distinction, zero cost |
| Value must be validated (email, port) | Parse-don't-validate newtype | Validity guaranteed by construction |
| Mutually exclusive states | Enum | Invalid states unrepresentable |
| Optional value | Option<T> |
Absence is explicit |
| Fallible operation | Result<T, E> |
Failure is explicit |
| State machine transitions | Typestate pattern | Invalid transitions won't compile |
| Prevent external trait implementations | Sealed trait | Evolution without breaking changes |
| Add methods to foreign types | Extension trait | Works around orphan rules |
| Type-level marker, no runtime data | PhantomData<T> |
Zero-size, expresses type relationship |
| Fixed set of valid values (not strings) | Enum, not &str |
Typos caught at compile time |
| Heterogeneous collection | Box<dyn Trait> |
Different concrete types, same interface |
| Monomorphized hot path | impl Trait / generics |
Zero-cost, no vtable dispatch |
| Callback parameter | impl Fn() bound |
Most flexible for callers, zero-cost |
| Mutable callback | impl FnMut() bound |
When the callback needs to mutate captured state |
| One-shot callback (ownership) | impl FnOnce() bound |
Callback consumes captured values |
| Closures that cross threads | move + Send + 'static |
Forces value capture for thread safety |
| Storing mixed closures | Box<dyn Fn()> |
Type erasure when closure types vary |
| Custom collection iteration | implement Iterator + IntoIterator |
Enables for loops and adapter chains |
| Lazy transformation pipeline | iterator adapters (map, filter, flat_map) | Zero-allocation chains until collect |
Static vs Dynamic Dispatch
Need different concrete types in the same collection?
├── Yes → dyn Trait (dynamic dispatch)
│ └── Box<dyn Trait> for owned, &dyn Trait for borrowed
└── No → impl Trait or generics (static dispatch)
└── Monomorphized: zero overhead, larger binary
Static (impl Trait / generics) |
Dynamic (dyn Trait) |
|
|---|---|---|
| Performance | Inlined, zero overhead | Vtable lookup per call |
| Binary size | Larger (monomorphized copies) | Smaller (single implementation) |
| Heterogeneous collections | No | Yes |
| Compile time | Slower | Faster |
| Object safety required | No | Yes |
Object safety requires: no Self: Sized bound, no
generic methods, no Self in return position
(without -> Box<dyn Trait>).
Newtype Pattern
Zero-cost wrapper that adds type safety:
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct UserId(u64);
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct OrderId(u64);
// These are now distinct types — can't mix them
fn get_order(user: UserId, order: OrderId) -> Order { ... }
Parse-Don't-Validate
Validate at construction, trust the type afterward:
pub struct Email(String);
impl Email {
pub fn new(s: &str) -> Result<Self, EmailError> {
if s.contains('@') && s.len() > 3 {
Ok(Email(s.to_string()))
} else {
Err(EmailError::Invalid(s.to_string()))
}
}
pub fn as_str(&self) -> &str { &self.0 }
}
// Once you have an Email, it's valid — no re-checking needed
fn send(to: &Email, body: &str) { ... }
Usage Scenarios
Scenario 1: "I have a function taking two u64 parameters
and callers keep swapping them"
→ Wrap each in a newtype: UserId(u64) and OrderId(u64).
Zero runtime cost, compiler catches swaps.
Scenario 2: "Should I use Box<dyn Handler> or generics
for my plugin system?"
→ If you need a Vec<Box<dyn Handler>> with different
concrete types, use dynamic dispatch. If each call site uses
one known type, use impl Handler for zero-cost dispatch.
Scenario 3: "I'm getting E0277 'the trait bound is not satisfied' everywhere" → Don't just add bounds. Check: is the bound on the right level (impl block vs struct)? Are you constraining too early? Bounds on the struct definition propagate everywhere — prefer bounds on impl blocks.
Reference Files
| File | Read When |
|---|---|
| references/generics.md | Working with generic bounds, Into/AsRef/From patterns, avoiding over-abstraction |
| references/type-driven.md | Designing newtypes, enums for states, PhantomData, parse-don't-validate, typestate |
| references/trait-design.md | Sealed traits, extension traits, object safety, common trait implementations |
| references/closures-and-iterators.md | Fn/FnMut/FnOnce traits, capture semantics, move closures, returning closures, custom Iterator/IntoIterator, FromIterator |
Cross-References
| When | Check |
|---|---|
| Ownership issues with generic types | rust-ownership → Quick Decisions |
| Error types and Result patterns | rust-errors → Quick Decisions |
| API design beyond type system (builders, naming) | rust-api → Quick Decisions |
| FFI newtypes with #[repr(transparent)] | rust-unsafe → Quick Decisions |
| Move closures for spawn, Send bounds | rust-async → Quick Decisions |
| Iterator chains, lazy evaluation | rust-perf → Quick Decisions |