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.

Good type systems create pure & total functions. Where does that leave errors? In programming, we have 4 types of errors:

1. those we create in our domain
2. those we expect from infrastructure
3. situations where we cannot recover
4. those we weren’t expecting, hence “exceptional” situations

If a type system has Discriminated Unions (sum / variant types), then that’s what we use for 1 & 2, the majority of what programmers deal w/.

type FetchError 
  = BadURL 
  | BadBody 
  | BadStatus 
  | NetworkError 
  | Timeout

Unless you’re dealing w/important hardware situations like Rust’s panics, we just ignore 3 b/c you can’t do anything anyway. 4 will “go away” if you focus on 1 & 2.

Modelling errors w/Unions poses a problem from a Domain Driven Design perspective: how do you differentiate 2 paths; happy & unhappy? The FP world has settled on a Result type:

type Result<T, E>
  = Ok<T>
  | Err<E>

It has 2 type parameters; T type for happy path data, E error type for unhappy path.

type FetchResult<Array<Person>, FetchError>

However, E in practice never is just 1 error for long. As you start composing more functions together that can fail, you start creating anonymous unions. For example, if we read from an environment variable for our secrets:

type ReadSecrets = () =>
  Result<Secrets, ReadError>

… then call fetch, our return type for that function would be both errors:

type fetchPeople = () => 
  Result<Array<Person>, ReadError | FetchError>

Those anonymous unions of errors, e.g. ReadError | FetchError, start happening a lot. The type system ensures through exhaustiveness checking you handle all errors. You also discover more about your domain through what can go wrong.

Testing is straight forward b/c the happy path is just Ok<T>:

stubFetch = () => ok([ person ])

& unhappy is an Err<E>:

stubBadFetch = () => err(b00m b00m)

You still have the flexibility to recover from each error; e.g. if secrets can’t be read from environment variables, you can fetch from a service. Others, like a fetch error BadStatus<429>, you could retry. Why not try/catch? Result is type safe + ensures all are handled.

Result gives you a convention for error handling + separating happy/unhappy paths; u still retain the ability to create DDD Domain errors “PersonUnauthorized”, infrastructure “FetchError”, & Panics like “CantReadSecrets” that u can map to a throw/panic (or Effect.die). You no longer use try/catch unless you’re mapping known unsafe (or potentially unsafe) code to a Result:

try {
  const json = JSON.parse(data)
  return ok(json)
} catch(error) {
  return err(error)
}

We’ll talk more in the future about how to model Errors as Values & build applications on top of Result, and the benefits of doing so.

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.

While good type systems give you confidence “when it compiles, it works”, and enables fearless refactoring, we’re often getting data _into_ our type system that isn’t typed.

whatIsThisWhoKnows = await response.json()

How you handle this depends on the type system, but for Gradually Typed ones like Luau, Python, and TypeScript, you have 2 options with various trade offs: any and unknown (Python calls it Any / object).

const person = JSON.parse(data) as any
//  Compiler allows this dangerous code 
// because person's type is any
console.log(person.name)

Any turns the type system off. This sounds horrifying at first, but it’s also why gradual type systems are so popular; they enable you to git-r-done, you can integrate w/untyped code namely libraries/modules you didn’t write, or when dealing w/3rd party data that you aren’t really sure what the type is.

const figureOutWhatThisIs:any = JWT.validate(jsonWebToken) as any
console.log("figureOutWhatThisIs:", figureOutWhatThisIs)

Despite types software has a rule of “we have to run it to know what it does” and even in something type-powerful like Elm/Scala/Haskell, sometimes we need to run the code to “see” or log the data, especially from some 3rd party / code that isn’t ours. I can’t count how many times a REST API said it delivered one thing, but ended up delivering something either slightly or completely different. Other times you just set your types up wrong, and need to test ’em at runtime.

That said, if you want to be type-safe, and practice Type Driven Development, you should avoid any. Any turns off the type system, so all the work you did on creating types can be negated by one mis-typed any slipping in. Instead, we should be using types to _narrow_ what we want and instead using the unknown type helps us do that.

const person = JSON.parse(data) as unknown
//  Compiler does NOT allow this, 
// have to type narrow first
console.log(person.name)

For now, recognize any is a tool to explicitly turn off the TypeScript compiler. If you can, try to use unknown instead, and type narrow to what you _think_ it should be. If it fails at runtime, type narrow to that, then try again. This ensures data coming from outside must be type narrowed first, and you can add extra unit & fuzz/property tests on this part as well to help.

if(personMaybe
  && typeof personMaybe === 'object'
  && 'name' in personMaybe
  && typeof personMaybe?.name === 'string') {
    // then we're probably safe here 
    // to cast as a Person
    const person = personMaybe as Person

However, while type narrowing to help the compiler is powerful, it’s also fraught with foot guns. We’ll see how we fix that with schemas.

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.

When we create Objects, all have the same thing in common: “property name and value”.

person = { first: 'Jesse', powerLevel: 9001 }

We access that person’s first property in 2 ways, either person.first, or person['first']. At runtime, accessing the first property will give us the first’s value, 'Jesse'.

Product types are usually a collection of types grouped together:

type Person = { first: string, powerLevel: 9001 }

We know how to access object values at runtime, but how do we access type property names?

We access them the same way we do objects using the name index method (e.g. person['first']), except it’s “type name and type value”:

type First = Person['first']

So type First is also just string. Sadly, u can’t do First.first, but if you remember “index” similar to how you access an Array’s items, like myList[2], basically the brackets [], that helps me remember.

A Money type may look like this:

type Money<C> = { currency: C, amount: number }

The reason you care about indexing is for some operations you want to keep safe, you need to know specific parts of the type. For Money that’d be Money['currency'].

With money, you don’t really care a/b the amounts when adding, you first ask “Are currencies the same type?” b/c you can’t just add USD (United States Dollars) + EUR (Euro)’s together. Each currency is worth a completely different amount. Converting them to & from each other, u have to know the exchange rate. It changes every second so we’ll assume u got it from somewhere.

This business rule, or “invariant”, is often baked into money libraries, like dinero.js. However, what a lot of those libraries have in common is they do not enforce those rules in the type system; instead, they go halfway then explode at runtime.

function add(a:Money, b:Money):Money {
  if(a.currency !== b.currency) {
    throw Error

Code like this assumes you’ll create the same types & ensure you don’t call add w/USD + EUR. That is not encoding the business logic in the type system. Instead, you’d do something like:

function add<C>(a:Money<C>, b:Money<C>):Money<C> {

Notice there’s only one C, or currency type parameter there, not two; so that means u HAVE to pass the same currency to add, USD or EUR. There are additional nuances around TypeScript & other languages inferring C is a Union so it could allow USD; use the NoInfer type for the 2nd parameter, but u get the point: types enforce the business rule. Indexing gives you ability query & refine the types when u’re working w/2 Product Types + u need to know details abt how to combine them. Math w/Money, math w/ temperatures & measurement (Metric vs Imperial), or account migration & other mapping operations that need to be type safe.

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.

Now that we have the Big 3® types covered (Branded “a thing”, Product “this AND that”, and Union “this OR that”), let’s see what you can do when you combine them with type parameters; like function parameters, except for types.

Array’s often hold critical data you need, yet have a flaw: you can’t guarantee there is anything in the Array. This makes working with Arrays’ a bit painful: you have to check first to see if your item is there, THEN use it:

// check for null
if(data[0]) {
  …
}

This gets worse if the Array isn’t in order:

// find it first
const maybeItem = data.find( i => i.name === 'desire' )
// then check for null
if(maybeItem) {
  …
}

This comes up with UI’s that have multiple Accounts, or in API’s when loading Feature Flags; the use case for both is “give me the important data first, and the remaining data, I can use if I need too later”. But the data isn’t shaped like that; it’s a list you must look inside and verify what you found isn’t null. Wouldn’t it be nice if you ALWAYS had at least the data you were looking for, and the rest of the data if you needed it?

You have 2 options: a custom Product Type or an Array that can’t be empty.

First option, make a Product Type where the first is always there, and the rest can be empty or full of items:

type AtLeast1 = { item: ?, data: Array }

But… what type of item is there, and full of what type of items? For that, we need a parameter to customize the type to whatever we need, so we’ll add a type parameter, usually called “T” which is short for “Type” (yes, it’s uppercased unlike TypeScript/Python/Lua/Ruby/etc function parameters). In TypeScript, Luau, and other languages, parameters are usually parentheses like (one, two), whereas type parameters use the less than and greater than symbols like .

type AtLeast1 = { item: T, data: Array<T> }

Using it:

type AtLeast1Account = AtLeast1

Now, you’re guaranteed to have the data you need, but the rest is there if you need it:

//  good
const account1 = { 
  item: primaryAccount, 
  data: [ secondaryAccount ] 
}

//  also good
const account2 = { 
  item: anotherPrimaryAccount, 
  data: [] 
}

The other option… define an Array where it HAS TO HAVE at least 1 item:

type NonEmptyArray = [ T, …Array[T] ]

//  does not compile
const empty:NonEmptyArray<string> = []

//  compiles
const hasOne:NonEmptyArray<string> = [""]

You can see now that you have the basic core types of Branded, Product, and Union/Discriminated Unions, once you combine with Type Parameters, you can create all kinds of types to ensure the data is in the shape of what you need and the types are easier to work with while flexible for your needs.

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.

Branded types allow us to differentiate between things & Product Types what things belong together. Unions/Discriminated Unions help us narrow things, identifying “what things are allowed?”

type AccountType = string means “Primary”, “Secondary”, and “Authorized” is fine, but so is “moo”, “”, & “”. That doesn’t restrict things enough. If our API’s only support those 3 account types, then we need a Union:

type AccountType = "Primary" | "Secondary" | "Authorized"

Unions come w/Exhaustiveness Checking so you no longer need to write a default case when you pattern match on what the type is:

switch(accountType) {
  case "Primary": …
  case "Secondary": …
  case "Authorized": …
}

The compiler ensures you handled all 3, default isn’t needed, & later when you add or change one, the compiler ensures all places that inspect the AccountType are updated. Useful for both encoding business rules, replacing magic strings w/”only these strings”, & help you have a place for additional domain discovery.

Discriminated Unions are often used to make Impossible Situations Impossible. In modelling state in UI’s you may have:

type Request = {
  loading: boolean
  data?: User
  error?: string
}

But states like this are possible & you must write unit tests to ensure they’re not & hope you don’t miss one:

{
  loading: true,
  data: user,
  error: "failed"
}

Instead, you can ensure those states can’t possibly happen, AND those states can’t access data they’re not allowed to:

type Request =
| { tag: "loading" }
| { tag: "success"; data: User }
| { tag: "error"; error: string }

Only the error state can access the error, only the success state can access data. If you mess it up in switch or if statements while type narrowing, the compiler will tell you and won’t compile the code:

switch(request.tag) {
  …
  case "success":
    return <Error data={request . error} />
    // ❌ fails to compile, error does not exist on Success
  case "error":
    return <Success data={request . data} /> 
    // ❌ fails to compile, data does not exist on Error

switch(request.tag) {
  …
  case "success":
    return <Success data={request . data} /> // ✅ works 
  case "error":
    return <Error data={request . error} /> // ✅ works

They’re also great for replacing Maybe’s (a nicer null). Instead of:

User | null

We can use:

type UserLookup =
| Found
| NotFound
type Found = { tag: 'found'; user: User }
type NotFound = { tag: 'not-found' }

Unions determine what is allowed & Discriminated Unions enhance that by defining what data is allowed in each alternative. Product Types are often called AND types like “this and that” while Unions are called OR types like “this or that”.