Type Driven Development: Typestate

Part 21 – Typestate

This is a series of posts I’m writing about using types as another tool in software development, Continuous Delivery, & keeping LLM’s honest. They’re also a design & refactoring tool, a communication tool, and reduce how many tests you have to write.

Parts

1. Part 1 – Branded Types
2. Part 2 – Product Types
3. Part 3 – Union & Discriminated Unions
4. Part 4 – Non-Empty Collections
5. Part 5 – Indexed Types
6. Part 6 – unknown vs any
7. Part 7 – Result
8. Part 8 – Schema
9. Part 9 – Total Function
10. Part 10 – Errors as Values
11. Part 11 – Property Tests
12. Part 12 – Type Proofs
13. Part 13 – Exhaustiveness Checking
14. Part 14 – Parse, Don’t Validate
15. Part 15 – Anti-Corruption Layer
16. Part 16 – Opaque Types
17. Part 17 – Maybe
18. Part 18 – Smart Constructors
19. Part 19 – Pipeline
20. Part 20 – Railway Oriented Programming
21. Part 21 – Typestate
22. Part 22 – Capabilities
23. Part 23 – Immutability
24. Part 24 – Making Impossible States Impossible
25. Part 25 – Type Driven Development: How to do it
26. Part 26 – Final Thoughts

We’ve shown how you can compose total functions together using pipeline & Railway Oriented Programming, while still having the order be imperative & easy to read. The downside is you are doing that order manually with just basic type support, e.g. “which .andThen goes in what order”. Sometimes in your domain, if things happen in the wrong order, bad things happen.

submitForm( userData )

.andThen( processOrder )

.andThen( ship )

.andThen( sendEmail )

A bunch wrong here, let’s cover ship first. Orders go through a lot of steps to get them to a shipping state:

type Order = ‘draft’ | ‘submited’ | ‘paid’ | ‘ship’ | ‘shipped’

The bad thing is it accepts an Order in any state:

type Ship = (order: Order) => Result<void, Error>

So either ship just handles all of that internally, or it’s not that smart and just assumes to ship an Order in any state. Either painful business logic in code we have to test mixed in with side-effects, or bugged code.

The fix, be explicit on the transitions; what state is allowed to move to the next state? You do this with Typestate: defining functions that take moar specific types in and returning specific types. Here, we’ll redefine the Order states as a Discriminated Union & functions for enforced transitions:

type Draft = { tag: ‘draft’, items: Item[] }

type Submittted = { tag: ‘submitted’, items: NonEmptyArray<Item> }

type Paid = { tag: ‘paid’; id: PaymentID }

type Submit = (order: Draft) => Result<Submitted, string>

type Pay = (o: Submitted) => Result<Paid, string>

type Ship = (o: Paid) => Result<Shipment, string>

I always think of wiring up these transition functions as “setting up the Roomba”:

submit( userData ) // Submitted comes out, goes into pay

.andThen( pay ) // Paid comes out, goes into ship

.andThen( ship ) // Shipment comes out, goes into email

.andThen( sendEmail )

The same could be done for the UI; instead of submit taking some form that _maybe_ the UI validated, instead, enforce submit to only take a validated form, that way you can’t submit data that wasn’t validated:

type Form = NotValidated | ValidForm

type Submit = (form: ValidForm) => Result<…, …>

Once you build these Typestate types and transition functions, it helps ensure you can’t assemble them in the wrong order; the compiler will help you put them in the right order. This includes those larger functions you’ve created where you may not be aware of what’s inside because of their abstraction, but that’s ok; they’re Total Functions, so all you need is the top-level type signature, the compiler will do the rest… (well, and you attempting to interpret TypeScript’s sometimes obtuse compiler errors).