Typestate Programming

The concept of typestates describes the encoding of information about the current state of an object into the type of that object. Although this can sound a little arcane, if you have used the Builder Pattern in Rust, you have already started using Typestate Programming!

  1. pub mod foo_module {
  2.     #[derive(Debug)]
  3.     pub struct Foo {
  4.         inner: u32,
  5.     }
  7.     pub struct FooBuilder {
  8.         a: u32,
  9.         b: u32,
  10.     }
  12.     impl FooBuilder {
  13.         pub fn new(starter: u32) -> Self {
  14.             Self {
  15.                 a: starter,
  16.                 b: starter,
  17.             }
  18.         }
  20.         pub fn double_a(self) -> Self {
  21.             Self {
  22.                 a: self.a * 2,
  23.                 b: self.b,
  24.             }
  25.         }
  27.         pub fn into_foo(self) -> Foo {
  28.             Foo {
  29.                 inner: self.a + self.b,
  30.             }
  31.         }
  32.     }
  33. }
  35. fn main() {
  36.     let x = foo_module::FooBuilder::new(10)
  37.         .double_a()
  38.         .into_foo();
  40.     println!("{:#?}", x);
  41. }

In this example, there is no direct way to create a Foo object. We must create a FooBuilder, and properly initialize it before we can obtain the Foo object we want.

This minimal example encodes two states:

  • FooBuilder, which represents an "unconfigured", or "configuration in process" state
  • Foo, which represents a "configured", or "ready to use" state.

Strong Types

Because Rust has a Strong Type System, there is no easy way to magically create an instance of Foo, or to turn a FooBuilder into a Foo without calling the into_foo() method. Additionally, calling the into_foo() method consumes the original FooBuilder structure, meaning it can not be reused without the creation of a new instance.

This allows us to represent the states of our system as types, and to include the necessary actions for state transitions into the methods that exchange one type for another. By creating a FooBuilder, and exchanging it for a Foo object, we have walked through the steps of a basic state machine.