1# Chapter 7 - Type State Pattern
2 
3Models state at compile time, preventing bugs by making illegal states unrepresentable. It takes advantage of the Rust generics and type system to create sub-types that can only be reached if a certain condition is achieved, making some operations illegal at compile time. 
4 
5> Recently it became the standard design pattern of Rust programming. However, it is not exclusive to Rust, as it is achievable and has inspired other languages to do the same [swift](https://swiftology.io/articles/typestate/) and [typescript](https://catchts.com/type-state).
6 
7## 7.1 What is Type State Pattern?
8 
9**Type State Pattern** is a design pattern where you encode different **states** of the system as **types**, not as runtime flags or enums. This allows the compiler to enforce state transitions and prevent illegal actions at compile time. It also improves the developer experience, as developers only have access to certain functions based on the state of the type.
10 
11> Invalid states become compile errors instead of runtime bugs.
12 
13## 7.2 Why use it?
14 
15* Avoids runtime checks for state validity. If you reach certain states, you can make certain assumptions of the data you have.
16* Models state transitions as type transitions. This is similar to a state machine, but in compile time.
17* Prevents data misuse, e.g. using uninitialized objects.
18* Improves API safety and correctness.
19* The phantom data field is removed after compilation so no extra memory is allocated.
20 
21## 7.3 Simple Example: File State
22 
23[Github Example](https://github.com/apollographql/rust-best-practices/tree/main/examples/simple-type-state)
24```rust
25use std::{io, path::{Path, PathBuf}};
26 
27struct FileNotOpened;
28struct FileOpened;
29 
30#[derive(Debug)]
31struct File<State> {
32    /// Path to the opened file
33    path: PathBuf,
34    /// Open `File` handler
35    handle: Option<std::fs::File>,
36    /// Type state manager
37    _state: std::marker::PhantomData<State>
38}
39 
40impl File<FileNotOpened> {
41    /// `open` is the only entry point for this struct.
42    /// * When called with a valid path, it will return a `File<FileOpened>` with a valid `handler` and `path`
43    /// * `open` serves as an alternative to `new` and `defaults` methods (usable when your struct needs valid data to exist).
44    fn open(path: &Path) -> io::Result<File<FileOpened>> {
45        // If file is invalid, it will return `std::io::Error`
46        let file = std::fs::File::open(path)?;
47        Ok(
48            File {
49                path: path.to_path_buf(),
50                // Always valid
51                handle: Some(file),
52                _state: std::marker::PhantomData::<FileOpened>
53            }
54        )
55    }
56}
57 
58impl File<FileOpened> {
59    /// Reads the content of the `File` as a `String`.
60    /// `read` can only be called by state `File<FileOpened>`
61    fn read(&mut self) -> io::Result<String> {
62        use io::Read;
63 
64        let mut content = String::new();
65        let Some(handle)= self.handle.as_mut() else {
66            unreachable!("Safe to unwrap as state can only be reached when file is open");
67        };
68        handle.read_to_string(&mut content)?;
69        Ok(content)
70    }
71 
72    /// Returns the valid path buffer.
73    fn path(&self) -> &PathBuf {
74        &self.path
75    }
76}
77```
78 
79## 7.4 Real-World Examples
80 
81### Builder Pattern with Compile-Time Guarantees
82 
83> Forces the user to **set required fields** before calling `.build()`.
84 
85[Github Example](https://github.com/apollographql/rust-best-practices/tree/main/examples/type-state-builder)
86 
87A type-state pattern can have more than one associated states:
88 
89```rust
90use std::marker::PhantomData;
91 
92struct MissingName;
93struct NameSet;
94struct MissingAge;
95struct AgeSet;
96 
97#[derive(Debug)]
98struct Person {
99    name: String,
100    age: u8,
101    email: Option<String>,
102}
103 
104struct Builder<NameState, AgeState> {
105    name: Option<String>,
106    age: u8,
107    email: Option<String>,
108    _name_marker: PhantomData<NameState>,
109    _age_marker: PhantomData<AgeState>,
110}
111 
112impl Builder<MissingName, MissingAge> {
113    fn new() -> Self {
114        Builder { name: None, age: 0, _name_marker: PhantomData, _age_marker: PhantomData, email: None }
115    }
116 
117    fn name(self, name: String) -> Builder<NameSet, MissingAge> {
118        Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData, email: None }
119    }
120 
121    fn age(self, age: u8) -> Builder<MissingName, AgeSet> {
122        Builder { age, _age_marker: PhantomData::<AgeSet>, name: None, _name_marker: PhantomData, email: None }
123    }
124}
125 
126impl Builder<NameSet, MissingAge> {
127    fn age(self, age: u8) -> Builder<NameSet, AgeSet> {
128        Builder { age, _age_marker: PhantomData::<AgeSet>, name: self.name, _name_marker: PhantomData::<NameSet>, email: None }
129    }
130}
131 
132impl Builder<MissingName, AgeSet> {
133    fn email(self, email: String) -> Self {
134        Self { name: self.name , age: self.age , email: Some(email) , _name_marker: self._name_marker , _age_marker: self._age_marker }
135    }
136 
137    fn name(self, name: String) -> Builder<NameSet, AgeSet> {
138        Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData::<AgeSet>, email: self.email }
139    }
140}
141 
142impl Builder<NameSet, AgeSet> {
143    fn build(self) -> Person {
144        Person { 
145            name: self.name.unwrap_or_else(|| unreachable!("Name is guarantee to be set")), 
146            age: self.age,
147            email: self.email,
148        }
149    }
150}
151```
152 
153Although a bit more verbose than a usual builder, this guarantees that all necessary fields are present (note that e-mail is optional field only present in the final builder).
154 
155#### Usage:
156```rust
157// ✅ Valid cases
158let person: Person = Builder::new().name("name".to_string()).age(30).build();
159let person: Person = Builder::new().age(30).name("name".to_string()).build();
160let person: Person = Builder::new().age(30).name("name".to_string()).email("[email protected]".to_string()).build();
161 
162// ❌ Invalid cases
163let person: Person = Builder::new().name("name".to_string()).build(); // ❌ Compile error: Age required to `build`
164let person: Person = Builder::new().age(30).build(); // ❌ Compile error: Name required to `build`
165let person: Person = Builder::new().age(30).email("[email protected]".to_string()).build(); // ❌ Compile error: Name required to `build`
166let person: Person = Builder::new().build();// ❌ Compile error: Name and Age required to `build`
167```
168 
169### Network Protocol State Machine
170 
171Illegal transitions like sending a message before connecting **simply don't compile**:
172 
173```rust
174// Mock example
175struct Disconnected;
176struct Connected;
177 
178struct Client<State> {
179    stream: Option<std::net::TcpStream>,
180    _state: std::marker::PhantomData<State>
181}
182 
183impl Client<Disconnected> {
184    fn connect(addr: &str) -> std::io::Result<Client<Connected>> {
185        let stream = std::net::TcpStream::connect(addr)?;
186        Ok(Client {
187            stream: Some(stream),
188            _state: std::marker::PhantomData::<Connected>
189        })
190    }
191}
192 
193impl Client<Connected> {
194    fn send(&mut self, msg: &str) {
195        use std::io::Write;
196        let Some(stream) = self.stream.as_mut() else {
197            unreachable!("Stream is guarantee to be set");
198        };
199        stream.write_all(msg.as_bytes())
200    }
201}
202```
203 
204## 7.5 Pros and Cons
205 
206### ✅ Use Type-State Pattern When:
207* Your want **compile-time state safety**.
208* You need to enforce **API constraints**.
209* You are writing a library/crate that is heavy dependent on variants.
210* Your want to replace runtime booleans or enums with **type-safe code paths**.
211* You need compile time correctness.
212 
213### ❌ Avoid it when:
214* Writing trivial states like enums.
215* Don't need type-safety.
216* When it leads to overcomplicated generics.
217* When runtime flexibility is required.
218 
219### 🚨 Downsides and Cautions
220* Can lead to more **verbose solutions**.
221* Can lead to **complex type signatures**.
222* May require **unsafe** to return **variant outputs** based on different states.
223* May required a bunch of duplication (e.g. same struct field reused).
224* PhantomData is not intuitive for beginners and can feel a bit hacky.
225 
226> Use this pattern when it **saves bugs, increases safety or simplifies logic**, not just for cleverness.
227