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.

Errors as Values moves errors from a random, runtime consequence to an iterative design process using types. u intentionally think about & design what could go wrong w/your code in functions, libraries/back-ends u integrate with & your application. Let’s fix fetch to see how this all works.

We’ve talked about the 4 error types in the past:

1. domain
2. infrastructure
3. panic
4. unforeseen

If u don’t know where an Error goes in the above list, 1st can u or the user do anything about it? If no, then 3.

2nd, ask your Product/Business Owner. If they look confused it’s 2, else it is 1.

fetch is infrastructure; we use it to make http calls, but it’s painful to work w/; Promise<Response> as a return value lies, having to check response.ok first, _then_ attempt response.json(), etc. Numerous exceptions, order of operation issues, none of it type-safe. 1 thing can go right: Your schema passes. Let’s narrow what can go wrong: only 4 things: it timed out, got a 4xx/5xx status, a network http 0 error, or your schema failed. Let’s model that as a Discriminated Union to narrow what can go wrong:

type FetchError = Timeout | BadStatus | NetworkErr | BadBody

Why not just a Union? When we get a BadStatus, what was the status code? When we get a BadBody was it the JSON failing to parse, or it parsed by didn’t match the schema, & on what part(s)? DU’s hold data + ensure we only access that data for that particular type.

type Timeout = { tag: 'Timeout', time: Seconds }
type BadStatus = { tag: 'BadStatus', code: HttpStatusCode }
type NetworkErr = { ... }
type BadBody = { tag: 'BadBody', zodErrors: ZodError[] }

Now we can write a more total, safer function to fetch data:

type get = <T>(s:ZodSchema<T>, url:string) =>
  Result<T, FetchError>

Then you wrap fetch with code to convert to our 4 errors:

try {

  const response = fetch(...)

  // handle bad status
  if(!response.ok) {
    return { tag: 'BadStatus', code: response.status }

  // handle timeouts
  if(error.name === 'AbortError') {
    return { tag: 'Timeout', ... }

Benefits of this hard work? Fetch is no longer imperative & its now type-safe. A single switch statement handles only 4 unhappy paths:

switch(r.tag) {
  case 'Timeout': ...
  case 'BadStatus': ...
  case 'NetworkErr': ...
  case 'BadBody': ...

BUT you still have the option to retry, convert to another error type, or recover, all in a type-safe way.

Our Product Owner wants a new Domain Error if account is not activated:

type NotActivated = { tag: 'NotActivated' }

if(!account.activated) {
  return err({ tag: 'NotActivated' })

Even in happy path, we can have errors; we model them intentionally in our Domain, the compiler ensures we handle them as our code grows.

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<Response>

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 = <T>(url:string) => 
  ResultAsync<T, FetchError>

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<T>”, but all kinds of bad things happen the type signature doesn’t tell you about. The ResultAsync<T, FetchError> 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<HttpResponse, never>

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.