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.

Type safety is a spectrum. A gradual type system widens the spectrum in a good & bad way; u have flexibility to discover your domain as it emerges w/less strict types + integrate w/less typed & legacy systems. That has a cost in safety. Sometimes u can narrow what’s allowed through types, then expand to other possibilities as you learn more. Whatever you choose, aim to design Total Functions; every input returns a sensible value.

Most functions we create are called Partial Functions; functions that throw/crash, or return nonsensical inputs for some inputs.

type Divide = (a:number, b:number) => number

Divide looks like a normal function; notice I only provided the type signature. From that you can figure out how the function works:

divide(12, 6) // 2
divide(2, 1) // 2

What about 2 / 0? That’s infinity. Technically it’s a number type, but is that what I want? What about 0 / 0? That’s NaN. While it’s called “NOT a number”, it’s also technically a number. Perhaps I just want numbers I can show the user? That means division can fail, so let’s fix the type:

type Divide = (…, …) => Result
divide = (a, b) => {
let n = a / b
if(nIsAGoodInteger(n)) {
return ok(n)
} else {
return err(…)
}

Now it’s more clear; infinity, negative infinity, & NaN will cause an error. But this is awkward to use; math requires error checking now? Blech… what if we ensure the inputs are good instead?

type Divide = (a:number, b:PositiveInteger) => number

Much easier to work w/ + expected outputs. More total.

What about fetch? Many would say:

type fetch = (url:string) => Promise

but technically it can also crash; u have no internet, u provide a bad URL, JSON fails to parse, blah blah blah. A more total signature would be:

type safeFetch = (url:string) => ResultAsync

We “expect” some type to be returned from our service; that implies a Schema is involved. It’s not a Result, but a ResultAsync, which implies a Promise. The error is specifically a FetchError type. The name has “safe” in it, implying no exceptions thrown. All that from just reading the type signature. More total.

Partial functions have type signatures that lie to you. They say “Oh yeah I return a Promise”, but all kinds of bad things happen the type signature doesn’t tell you about. The ResultAsync is extremely clear & thorough.

Once u start composing these functions together to make programs, that makes your code more total. “when it compiles it works” is more likely to be true. Your app’s type signature, whether UI or API, is more likely to be total.

type AWSLambda = (event:APIGatewayProxyEvent) => ResultAsync

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.

To do anything of value in software, we have to get unsafe data from outside our type system into it. We saw how unknown forces us to type narrow, but type narrowing is dangerous, tedious, and it’s hard to be thorough.

cow = JSON.parse(json)
if(cow 
  && 'age' in cow 
  && typeof cow?.age === 'number')
  // could be NaN

Then comes the architecture problem; how do you DRY (Don’t Repeat Yourself) this? Multiple parts of your code have:

type Cow = { age: number }

But later the back-end changes age to be optional:

type Cow = { age?: number }

So you have to update both your types and parsing code. This occurs a lot, which then creates Shotgun Parsing all throughout your code:

if(cow.age) {
  // use age
} else {
  // throw an error
}

This is because despite types, no one can trust the data. No code knows where the data came from; “Maybe age hasn’t been validated yet? Better validate just in case.” You started coupling the types through your code in hopes everyone would know “what a Cow is”, but now all the code is repeatedly validating the data. Worse, only parts are validated:

if(cow.name) {
// if no name, throws an error
// what about age? Who knows

Even code formatting, e.g. Oxcfmt/Prettier/Biome, is bypassed b/c data is at runtime, so Python snake case data:

{ first_name: 'Moo', last_name: 'Cow' }

Can start infecting your camelCase style code. Since validation is often impromptu, it’s not all the same or thorough. Empty strings ”, NaN for numbers, and optional properties on data cause runtime errors or null checks like if(thing?.and?.some?.prop) adding lots of validation code repeatedly.

Lastly, the data you get isn’t always what you want. REST API’s can send back 100 JSON values, but you only need 2, forcing you to write & maintain a lot of parsing code you’ll never use. JSON can have optional values, but you require that data, knowingly parsing the thing you don’t like.

Schema’s solve all this. 1 source of truth, it either parses or it doesn’t, the type is validated data all of your code can trust, use without modifying, and not have to validate. The shape can be what you want/need instead of coupling to what the back-end gives you, then having to update all your code when the back-end changes. Zod/ArkType/Effect all provide schemas:

// define your parsing functions
cowSchema = z.object({
  // a number that is not NaN and positive
  age: z.number().gte(0),
  // a string name instead of Python's snake case first_name
  name: z.string().transform( d => ({ …d, name: d.first_name }) )
})

// use it to create your type
type Cow = z.infer<typeof cowSchema>

// parse your data
json = JSON.parse(data)
cow = cowSchema.parse(json)
// cow is a Cow type and safe to use!

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.