The Type-State Pattern

19 min read

The type-state pattern moves an object’s state out of its runtime data and into its type, so the compiler can reject illegal operations before the program ever runs. Methods only exist on the states where they make sense, turning “this method isn’t valid right now” runtime bugs into compile errors.

Quick Overview

In TypeScript you usually track state with a field (status: "draft" | "published") and then check that field at runtime before doing anything. The type-state pattern flips this around: each state becomes a distinct type (Post<Draft> vs Post<Published>), and a method like .send() simply does not exist on the wrong state. Misusing the object becomes a type error, not a runtime panic — and because the state markers are zero-sized, you pay nothing for the safety at runtime.

This is the same idea behind the cargo new defaults: the latest stable toolchain (Rust 1.96.0 on the 2024 edition) encourages encoding invariants in types, and type-state is the purest expression of that philosophy.

TypeScript/JavaScript Example

Here is a typical blog-post workflow in TypeScript. The state lives in a field, and every method that cares about state has to guard against the wrong one:

1
// A post can be a draft or published. State is a runtime field.
2
class Post {
3
  private content = "";
4
  private state: "draft" | "published" = "draft";
5

6
  addText(text: string): void {
7
    if (this.state !== "draft") {
8
      throw new Error("cannot edit a published post");
9
    }
10
    this.content += text;
11
  }
12

13
  publish(): void {
14
    if (this.state !== "draft") {
15
      throw new Error("post is already published");
16
    }
17
    this.state = "published";
18
  }
19

20
  views(): number {
21
    if (this.state !== "published") {
22
      throw new Error("a draft has no views");
23
    }
24
    return 42;
25
  }
26
}
27

28
const post = new Post();
29
post.addText("Hello, type states!");
30
post.publish();
31
console.log(post.views()); // 42
32

33
// Nothing stops this from compiling — it throws at RUNTIME:
34
const draft = new Post();
35
console.log(draft.views()); // Error: a draft has no views

Key points:

The state is data (this.state), so the type system cannot see it.
Every method re-checks the state and throws — boilerplate that is easy to forget.
draft.views() type-checks happily; the bug only appears when that line actually runs.
A reviewer cannot tell from the type Post whether a given value is safe to publish.

Note: TypeScript can do better than this with discriminated unions and “branded” types, and we will compare those at the end. But the field-plus-guard style above is what most production TypeScript actually looks like.

Rust Equivalent

In Rust, the state becomes a generic type parameter. Post<Draft> and Post<Published> are different types, and each one only has the methods that are valid for it:

1
use std::marker::PhantomData;
2

3
// State marker types. They hold no data and are never instantiated.
4
struct Draft;
5
struct Published;
6

7
// The post carries its state as the generic parameter `S`.
8
// `PhantomData<S>` records the state in the type without storing any bytes.
9
struct Post<S> {
10
    content: String,
11
    _state: PhantomData<S>,
12
}
13

14
// Methods available in *any* state.
15
impl<S> Post<S> {
16
    fn content(&self) -> &str {
17
        &self.content
18
    }
19
}
20

21
// Methods available ONLY on a Draft post.
22
impl Post<Draft> {
23
    fn new() -> Post<Draft> {
24
        Post { content: String::new(), _state: PhantomData }
25
    }
26

27
    fn add_text(&mut self, text: &str) {
28
        self.content.push_str(text);
29
    }
30

31
    // Consumes the Draft and returns a Published — a *type transition*.
32
    fn publish(self) -> Post<Published> {
33
        Post { content: self.content, _state: PhantomData }
34
    }
35
}
36

37
// Methods available ONLY on a Published post.
38
impl Post<Published> {
39
    fn views(&self) -> u32 {
40
        42
41
    }
42
}
43

44
fn main() {
45
    let mut draft = Post::<Draft>::new();
46
    draft.add_text("Hello, type states!");
47
    println!("draft content: {}", draft.content());
48

49
    let published = draft.publish(); // draft is consumed here
50
    println!("published content: {}", published.content());
51
    println!("views: {}", published.views());
52
}

Real output:

1
draft content: Hello, type states!
2
published content: Hello, type states!
3
views: 42

The interesting line is the one we cannot write. Calling views() on a draft is not a runtime error — it does not compile:

1
// does not compile (error[E0599]: no method named `views`)
2
let draft = Post::<Draft>::new();
3
let _ = draft.views();

The real compiler error:

1
error[E0599]: no method named `views` found for struct `Post<Draft>` in the current scope
2
  --> src/main.rs:27:19
3
   |
4
 6 | struct Post<S> {
5
   | -------------- method `views` not found for this struct
6
...
7
27 |     let _ = draft.views();
8
   |                   ^^^^^ method not found in `Post<Draft>`
9
   |
10
   = note: the method was found for
11
           - `Post<Published>`

Detailed Explanation

Let’s walk through the pieces, contrasting each with the TypeScript version.

struct Draft; and struct Published; are zero-sized marker types. They have no fields and you never create a value of them. Their only job is to be distinct types the compiler can tell apart. This is closest to TypeScript’s unique symbol or a branded type — except in Rust the brand participates in method resolution, not just assignability.

Post<S> makes the state a type parameter. Where TypeScript wrote state: "draft" | "published" as a field, Rust writes <S> as part of the type. Post<Draft> and Post<Published> are now as different to the compiler as Vec<String> and Vec<i32>.

PhantomData<S> is the bridge. A struct must “use” each of its type parameters, but S here is only a label — there is no actual Draft value to store. std::marker::PhantomData<S> is a zero-sized standard-library type that tells the compiler “pretend this struct contains an S” without occupying any memory. Without it, struct Post<S> { content: String } would fail to compile because S is unused. (We confirm the zero-size claim below.)

impl<S> Post<S> defines shared methods. Anything in this block — like content() — is available no matter what state you are in. This is the equivalent of a method with no state guard.

impl Post<Draft> and impl Post<Published> define state-specific methods. This is the heart of the pattern. add_text and publish live on Post<Draft>; views lives on Post<Published>. Because Rust resolves methods against the concrete type, views is simply absent from a draft. There is no guard, no throw, no runtime cost — the method just is not there.

fn publish(self) -> Post<Published> is the transition. Note self by value (not &self or &mut self). Taking self consumes the draft: the old Post<Draft> is moved into publish and a brand-new Post<Published> comes out. This guarantees you cannot keep using the draft after publishing it — the compiler enforces a strict, linear lifecycle. Compare this to the TypeScript publish(), which mutates a field in place and leaves the now-stale Post object lying around for someone to misuse.

This consume-and-return shape is why type-state pairs so naturally with Rust’s ownership and move semantics: a state transition is literally a value moving from one type to another.

Key Differences

Aspect	TypeScript (field + guard)	Rust (type-state)
Where state lives	A runtime field (`this.state`)	A type parameter (`Post<Draft>`)
When misuse is caught	At runtime, when the line executes	At compile time, before running
Wrong-state method call	Type-checks, then throws	Does not compile (no such method)
Cost of a state check	An `if` on every call	Zero — the check is the type system
Stale-object reuse	Possible (object still exists)	Prevented (transition consumes `self`)
Runtime memory overhead	A discriminant field (string/number)	None — markers are zero-sized
Visible in the signature?	No — `Post` hides its state	Yes — `Post<Published>` is self-documenting

Why Rust leans on this. Rust has no exceptions and discourages “this should never happen” panics. The compiler is the cheapest, earliest place to catch a mistake, so idiomatic Rust pushes invariants into types whenever the set of states is small and known. The payoff is “make illegal states unrepresentable”: if your function takes a Post<Published>, you know it was published — you do not have to defensively check.

Zero cost is real, not a slogan. The marker types and PhantomData compile to nothing. We can prove it with std::mem::size_of:

1
use std::marker::PhantomData;
2

3
struct Draft;
4
struct Published;
5

6
struct Post<S> {
7
    content: String,
8
    _state: PhantomData<S>,
9
}
10

11
fn main() {
12
    println!("size_of String          = {}", std::mem::size_of::<String>());
13
    println!("size_of Post<Draft>      = {}", std::mem::size_of::<Post<Draft>>());
14
    println!("size_of Post<Published>  = {}", std::mem::size_of::<Post<Published>>());
15
    println!("size_of Draft marker     = {}", std::mem::size_of::<Draft>());
16
    println!("size_of PhantomData      = {}", std::mem::size_of::<PhantomData<Draft>>());
17
}

Real output:

1
size_of String          = 24
2
size_of Post<Draft>      = 24
3
size_of Post<Published>  = 24
4
size_of Draft marker     = 0
5
size_of PhantomData      = 0

Post<Draft> is exactly the size of its real data (the String); the state label costs nothing. Contrast this with the TypeScript version, where every object carries a state string for its entire lifetime.

Common Pitfalls

1. Forgetting `PhantomData` (unused type parameter)

If you write the struct without PhantomData, the compiler rejects it because S is never used:

1
// does not compile (error[E0392]: type parameter `S` is never used)
2
struct Post<S> {
3
    content: String,
4
}

The real error tells you exactly what to do:

1
error[E0392]: type parameter `S` is never used
2
 --> src/main.rs:1:13
3
  |
4
1 | struct Post<S> {
5
  |             ^ unused type parameter
6
  |
7
  = help: consider removing `S`, referring to it in a field, or using a marker such as `PhantomData`
8
  = help: if you intended `S` to be a const parameter, use `const S: /* Type */` instead

The fix is the _state: PhantomData<S> field shown earlier. The leading underscore in the field name silences the “field never read” lint, since you never read a PhantomData.

2. Expecting the transition method to leave the old value usable

Because publish(self) takes self by value, the original draft is moved. Trying to use it again is a borrow-checker error, not a logic bug:

1
// does not compile (error[E0382]: use of moved value)
2
let draft = Post::<Draft>::new();
3
let _published = draft.publish();
4
let _again = draft.publish(); // draft was already consumed

The real error:

1
error[E0382]: use of moved value: `draft`
2
  --> src/main.rs:24:18
3
   |
4
21 |     let draft = Post::<Draft>::new();
5
   |         ----- move occurs because `draft` has type `Post<Draft>`, which does not implement the `Copy` trait
6
22 |     let _published = draft.publish(); // moves `draft`
7
   |                            --------- `draft` moved due to this method call
8
...
9
24 |     let _again = draft.publish();
10
   |                  ^^^^^ value used here after move

This is the pattern working as intended — but it surprises TypeScript developers, who are used to objects living on after a mutating call. Reassign the result (let post = post.transition();, often shadowing the same name) instead of reusing the old binding.

3. Reaching for `dyn`/trait objects to “store either state”

You cannot put Post<Draft> and Post<Published> in the same Vec without erasing their distinguishing types — which defeats the pattern. If you genuinely need a runtime-variable state (for example, a value whose state is decided by user input at runtime), type-state is the wrong tool; use a plain enum instead. Type-state shines when the transitions are known statically in the code path. See the strategy and command patterns (strategy-pattern.md, command-pattern.md) for the runtime-dispatch alternatives.

4. Over-applying it

Three states with a clear linear flow? Great fit. A dozen states with arbitrary transitions, or states chosen at runtime? The type explosion and impl duplication will hurt more than the safety helps. Reach for an enum state machine there.

Best Practices

Use unit structs as markers (struct Draft;), not enums or empty modules. They are the lightest possible label and are conventional.
Make transitions consume self so stale states cannot linger. Return the new typed value.
Put shared methods in impl<S> Post<S> and state-specific methods in impl Post<ConcreteState>. Keep the split obvious.
Name the marker field _state (leading underscore) to document intent and silence dead-code lints.

Seal your states with a private trait when you want to guarantee no downstream crate invents a new state. Bound the type parameter on a State trait whose supertrait lives in a private module:

1
use std::marker::PhantomData;
2

3
mod sealed {
4
    pub trait Sealed {}
5
}
6

7
// Public marker trait, but only types that impl the private `Sealed`
8
// (all of which live in this crate) can satisfy it.
9
trait State: sealed::Sealed {}
10

11
struct Locked;
12
struct Unlocked;
13

14
impl sealed::Sealed for Locked {}
15
impl sealed::Sealed for Unlocked {}
16
impl State for Locked {}
17
impl State for Unlocked {}
18

19
struct Door<S: State> {
20
    _state: PhantomData<S>,
21
}
22

23
impl Door<Locked> {
24
    fn new() -> Self {
25
        Door { _state: PhantomData }
26
    }
27
    fn unlock(self) -> Door<Unlocked> {
28
        println!("click — unlocked");
29
        Door { _state: PhantomData }
30
    }
31
}
32

33
impl Door<Unlocked> {
34
    fn lock(self) -> Door<Locked> {
35
        println!("clunk — locked");
36
        Door { _state: PhantomData }
37
    }
38
    fn open(&self) {
39
        println!("the door swings open");
40
    }
41
}
42

43
fn main() {
44
    let door = Door::<Locked>::new();
45
    let door = door.unlock();
46
    door.open();
47
    let _door = door.lock();
48
}

Real output:

1
click — unlocked
2
the door swings open
3
clunk — locked

An outside attempt to add its own state by writing struct Rogue; and impl State for Rogue {} is rejected, because Rogue cannot implement the private Sealed supertrait:

1
error[E0277]: the trait bound `Rogue: Sealed` is not satisfied
2
  --> src/main.rs:42:16
3
   |
4
42 | impl State for Rogue {}
5
   |                ^^^^^ the trait `Sealed` is not implemented for `Rogue`
6
   |
7
   = help: the following other types implement trait `Sealed`:
8
             Locked
9
             Unlocked
10
note: required by a bound in `State`
11
  --> src/main.rs:7:14
12
   |
13
 7 | trait State: sealed::Sealed {}
14
   |              ^^^^^^^^^^^^^^ required by this bound in `State`

This sealed-trait technique is the same one the standard library uses to keep traits like std::error::Error’s relatives closed; it pairs naturally with type-state.

Real-World Example

A very common real use is a typed request builder that refuses to send() until both the HTTP method and the URL are set — caught at compile time, with the call order left flexible. Here we track two independent bits of state with two type parameters:

1
use std::marker::PhantomData;
2

3
// Two markers, reused for both "slots".
4
struct Unset;
5
struct Set;
6

7
struct RequestBuilder<M, U> {
8
    method: Option<String>,
9
    url: Option<String>,
10
    headers: Vec<(String, String)>,
11
    _method: PhantomData<M>,
12
    _url: PhantomData<U>,
13
}
14

15
impl RequestBuilder<Unset, Unset> {
16
    fn new() -> Self {
17
        RequestBuilder {
18
            method: None,
19
            url: None,
20
            headers: Vec::new(),
21
            _method: PhantomData,
22
            _url: PhantomData,
23
        }
24
    }
25
}
26

27
// Setting the method flips only `M` to `Set`, preserving whatever `U` was.
28
impl<U> RequestBuilder<Unset, U> {
29
    fn method(self, m: &str) -> RequestBuilder<Set, U> {
30
        RequestBuilder {
31
            method: Some(m.to_string()),
32
            url: self.url,
33
            headers: self.headers,
34
            _method: PhantomData,
35
            _url: PhantomData,
36
        }
37
    }
38
}
39

40
// Setting the url flips only `U` to `Set`, preserving whatever `M` was.
41
impl<M> RequestBuilder<M, Unset> {
42
    fn url(self, u: &str) -> RequestBuilder<M, Set> {
43
        RequestBuilder {
44
            method: self.method,
45
            url: Some(u.to_string()),
46
            headers: self.headers,
47
            _method: PhantomData,
48
            _url: PhantomData,
49
        }
50
    }
51
}
52

53
// `header` works in any state and leaves the state markers unchanged.
54
impl<M, U> RequestBuilder<M, U> {
55
    fn header(mut self, k: &str, v: &str) -> Self {
56
        self.headers.push((k.to_string(), v.to_string()));
57
        self
58
    }
59
}
60

61
// `send` exists ONLY when both markers are `Set`.
62
impl RequestBuilder<Set, Set> {
63
    fn send(self) -> String {
64
        format!(
65
            "{} {} ({} header(s))",
66
            self.method.unwrap(),
67
            self.url.unwrap(),
68
            self.headers.len()
69
        )
70
    }
71
}
72

73
fn main() {
74
    let response = RequestBuilder::new()
75
        .method("GET")
76
        .header("Accept", "application/json")
77
        .url("https://example.com/api")
78
        .send();
79
    println!("{response}");
80

81
    // Order does not matter — url first, then method, also compiles:
82
    let response2 = RequestBuilder::new()
83
        .url("https://example.com/users")
84
        .method("POST")
85
        .send();
86
    println!("{response2}");
87
}

Real output:

1
GET https://example.com/api (1 header(s))
2
POST https://example.com/users (0 header(s))

Forgetting a required slot is a compile error. Calling .send() with only the method set yields:

1
// does not compile (error[E0599]: no method named `send`)
2
let _ = RequestBuilder::new()
3
    .method("GET")
4
    .send(); // url is still Unset

The real error names the exact incomplete state:

1
error[E0599]: no method named `send` found for struct `RequestBuilder<Set, Unset>` in the current scope
2
  --> src/main.rs:33:10
3
   |
4
 6 |   struct RequestBuilder<M, U> {
5
   |   --------------------------- method `send` not found for this struct
6
...
7
33 | |         .send();
8
   | |         -^^^^ method not found in `RequestBuilder<Set, Unset>`
9
   |
10
   = note: the method was found for
11
           - `RequestBuilder<Set, Set>`

This is exactly the “compile-checked required fields” idea from the builder pattern, taken to its logical conclusion: type-state is how a builder enforces required fields. The two patterns are deeply related — the builder chapter covers the everyday ergonomic version, and this chapter covers the type-level machinery underneath it.

Tip: Many production crates use this exact shape. The HTTP client reqwest, for instance, returns typed builder states, and embedded HAL crates use type-state to model peripheral pin modes (input vs output) so you cannot read from a pin configured for output. You will meet more such crates in Section 23: Ecosystem.

Exercises

Exercise 1 — A connection lifecycle

Difficulty: Beginner

Objective: Build a type-state value that can only send while open.

Instructions: Create a Connection<S> with two states, Closed and Open. A new connection starts Closed. Provide connect(self) -> Connection<Open>, a send(&self, msg: &str) method that exists only when open, and close(self) -> Connection<Closed>. Store the address string and print it during transitions. Verify that calling send on a closed connection does not compile.

Solution

1
use std::marker::PhantomData;
2

3
struct Closed;
4
struct Open;
5

6
struct Connection<S> {
7
    addr: String,
8
    _state: PhantomData<S>,
9
}
10

11
impl Connection<Closed> {
12
    fn new(addr: &str) -> Connection<Closed> {
13
        Connection { addr: addr.to_string(), _state: PhantomData }
14
    }
15
    fn connect(self) -> Connection<Open> {
16
        println!("connecting to {}", self.addr);
17
        Connection { addr: self.addr, _state: PhantomData }
18
    }
19
}
20

21
impl Connection<Open> {
22
    fn send(&self, msg: &str) {
23
        println!("[{}] sending: {msg}", self.addr);
24
    }
25
    fn close(self) -> Connection<Closed> {
26
        println!("closing {}", self.addr);
27
        Connection { addr: self.addr, _state: PhantomData }
28
    }
29
}
30

31
fn main() {
32
    let conn = Connection::<Closed>::new("127.0.0.1:8080");
33
    let conn = conn.connect();
34
    conn.send("ping");
35
    let _conn = conn.close();
36
    // conn.send("late"); // would not compile: no `send` on Connection<Closed>
37
}

Real output:

1
connecting to 127.0.0.1:8080
2
[127.0.0.1:8080] sending: ping
3
closing 127.0.0.1:8080

Exercise 2 — A shared method across states

Difficulty: Intermediate

Objective: Add a method that works in every state by bounding the type parameter on a marker trait carrying an associated constant.

Instructions: Model a turnstile with states Locked and Unlocked. Define a TurnstileState trait with an associated const NAME: &'static str, implement it for both states, and add a status(&self) -> &'static str method available in every state that returns S::NAME. Locked::insert_coin transitions to Unlocked; Unlocked::push transitions back to Locked, carrying along a coin counter.

Solution

1
use std::marker::PhantomData;
2

3
trait TurnstileState {
4
    const NAME: &'static str;
5
}
6

7
struct Locked;
8
struct Unlocked;
9
impl TurnstileState for Locked { const NAME: &'static str = "locked"; }
10
impl TurnstileState for Unlocked { const NAME: &'static str = "unlocked"; }
11

12
struct Turnstile<S: TurnstileState> {
13
    coins: u32,
14
    _state: PhantomData<S>,
15
}
16

17
// One method, available in every state via the trait bound.
18
impl<S: TurnstileState> Turnstile<S> {
19
    fn status(&self) -> &'static str {
20
        S::NAME
21
    }
22
}
23

24
impl Turnstile<Locked> {
25
    fn new() -> Self {
26
        Turnstile { coins: 0, _state: PhantomData }
27
    }
28
    fn insert_coin(self) -> Turnstile<Unlocked> {
29
        Turnstile { coins: self.coins + 1, _state: PhantomData }
30
    }
31
}
32

33
impl Turnstile<Unlocked> {
34
    fn push(self) -> Turnstile<Locked> {
35
        println!("clack — you walked through (total coins: {})", self.coins);
36
        Turnstile { coins: self.coins, _state: PhantomData }
37
    }
38
}
39

40
fn main() {
41
    let t = Turnstile::<Locked>::new();
42
    println!("status: {}", t.status());
43
    let t = t.insert_coin();
44
    println!("status: {}", t.status());
45
    let t = t.push();
46
    println!("status: {}", t.status());
47
}

Real output:

1
status: locked
2
status: unlocked
3
clack — you walked through (total coins: 1)
4
status: locked

Exercise 3 — Two required fields via two type parameters

Difficulty: Advanced

Objective: Build a config builder that refuses to build() until both host and port are set, in any order.

Instructions: Create ConfigBuilder<H, P> with markers Missing and Provided. new() starts at <Missing, Missing>. host(self, &str) flips only H to Provided; port(self, u16) flips only P. A build(self) -> Config method exists only on ConfigBuilder<Provided, Provided>. Confirm that omitting either field fails to compile.

Solution

1
use std::marker::PhantomData;
2

3
struct Missing;
4
struct Provided;
5

6
struct ConfigBuilder<H, P> {
7
    host: Option<String>,
8
    port: Option<u16>,
9
    _h: PhantomData<H>,
10
    _p: PhantomData<P>,
11
}
12

13
impl ConfigBuilder<Missing, Missing> {
14
    fn new() -> Self {
15
        ConfigBuilder { host: None, port: None, _h: PhantomData, _p: PhantomData }
16
    }
17
}
18

19
impl<P> ConfigBuilder<Missing, P> {
20
    fn host(self, h: &str) -> ConfigBuilder<Provided, P> {
21
        ConfigBuilder { host: Some(h.to_string()), port: self.port, _h: PhantomData, _p: PhantomData }
22
    }
23
}
24

25
impl<H> ConfigBuilder<H, Missing> {
26
    fn port(self, p: u16) -> ConfigBuilder<H, Provided> {
27
        ConfigBuilder { host: self.host, port: Some(p), _h: PhantomData, _p: PhantomData }
28
    }
29
}
30

31
#[derive(Debug)]
32
struct Config {
33
    host: String,
34
    port: u16,
35
}
36

37
impl ConfigBuilder<Provided, Provided> {
38
    fn build(self) -> Config {
39
        // Unwraps are safe: the type `<Provided, Provided>` proves both are Some.
40
        Config { host: self.host.unwrap(), port: self.port.unwrap() }
41
    }
42
}
43

44
fn main() {
45
    let cfg = ConfigBuilder::new().host("localhost").port(5432).build();
46
    println!("{cfg:?}");
47
    // ConfigBuilder::new().host("localhost").build(); // no `build` on <Provided, Missing>
48
}

Real output:

1
Config { host: "localhost", port: 5432 }

Note the .unwrap() calls in build never panic: the type ConfigBuilder<Provided, Provided> is a compile-time proof that both fields were set, so the Options are guaranteed Some.

The Type-State Pattern

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

1. Forgetting PhantomData (unused type parameter)

2. Expecting the transition method to leave the old value usable

3. Reaching for dyn/trait objects to “store either state”

4. Over-applying it

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1 — A connection lifecycle

Exercise 2 — A shared method across states

Exercise 3 — Two required fields via two type parameters

1. Forgetting `PhantomData` (unused type parameter)

3. Reaching for `dyn`/trait objects to “store either state”