TypeScript – Software, Fitness, and Gaming – Jesse Warden

Read the Book Domain Modelling Made Functional

JesterXL — Tue, 08 Apr 2025 01:04:27 +0000

Finally got around to reading Domain Modeling Made Functional, Tackle Software Complexity with Domain-Driven Design and F#, by Scott Wlaschin. Book basically covers:

Domain Driven Design
How to design with types
How to implement 1 and 2 in code & refactor it.

There’s other good content leveraging the above like balancing both exceptions vs. Result (e.g errors as values) & Persistence concerns (e.g. database).

My favorite, though, are his translations of OOP concepts to FP ones. This is a huge deal because most DDD (Domain Driven Design) content is heavily biased towards OOP, design patterns, and mutation, none of which is in the FP world. Additionally, despite Java’s & C#’s massive improvements, OOP devs don’t worship types like the FP community does, and sum types & records are perfect for modelling things in DDD style, with the compiler’s help. So having his translations from the OOP world to the FP one helped a lot. He even included Onion/Hexagonal architecture which I loved, omitting the parts that FP devs don’t need.

I’ve been meaning to read “The Blue Book” and “The Red Book”, famous DDD books, for a long time, but my patience of translating OOP things to my world is basically spent, so it was dope to get Scott’s explanation. The topics are vast so everything had external links if you wanted to learn more.

The biggest thing I took away was I am 90% on track. That was a HUGE sigh of relief; 90% of the book I’m either like “Yeah, I know this” or “whoa, cool, so I was doing it like you’re supposed too, rad”. That made me feel good; I don’t use F#, I use TypeScript, but it’s basically the same, just more verbose for unions, and doesn’t have those dope Monad helpers.

The other crazy thing was it was released in 2018. Excluding Continuous Delivery/TDD, everything in the book is just as relevant in today’s world in how I build software, and done the same way, so that was another self-esteem boost knowing the core techniques continue to be evergreen, and language agnostic (well… they _do_ assume your types don’t suck and even in 2025, there are popular languages who’s type systems aren’t that great).

One minor thing, it was hilarious to see DTO’s, Data Transfer Objects, embraced and encouraged. I haven’t used DTO’s or VO’s, ValueObjects, since my OOP days back in like 2011. I get why, and agree, no doubt, but… just funny in that:

most FP devs I work with have no idea what those are
most OOP devs under 32 have zero idea what those are, either

Really loved how both relational and NoSQL persistence were covered with raw SQL. Really helped solidify some feelings I’ve had and concerns, and squashed all anxiety after reading. I only have about 2 years of real Postegres and DynamoDB experience, but based on what I read, I was on the right track “thinking with an FP mindset” around persistence, and was missing a major core piece around how to save Unions/Sum Types/Variants, so the examples provided were awesome.

If you don’t know DDD and want to learn it, buy this book.

If you want to learn how to “design with types, first, not tests first”, buy this book.

If you know TypeScript, but aren’t really sure if the types are giving you value in your work, buy this book and see if it doesn’t give you a fresh perspective on how to approach your work.

https://pragprog.com/titles/swdddf/domain-modeling-made-functional

Error Handling for fetch in TypeScript

JesterXL — Tue, 18 Feb 2025 15:10:29 +0000

Introduction

The following post describes why and how you do error handling for fetch.

Why Care?

When you write code that does not handle errors, the code may break at runtime and when deployed to production. Getting PagerDuty calls at 3am are not fun, and are hard to debug because you’re sleepy. Doing error handling can both prevent those early morning PageDuty alerts, as well as ensure if they do occur, you have a better indication as to what went wrong, and if you need to act on it.

TypeScript can help you with types that make it more clear a piece of code can fail, and ensure you and other developers who build atop it months to years later also handle those errors. You just have to spend the time thinking about and writing the types.

Example of Code That Does Not Handle Errors

The following code is commonly used in Node.js and the Browser:

let value = await fetch('https://some.server.com/api/data').then( r => r.json() )

This code does not handle the following error conditions:
– if the URL is malformed
– if the fetch has a networking error
– if fetch gets a non-200 http status code response
– if the JSON sent back fails to parse
– if the JSON parses, but is in the incorrect type

You can possibly glean those errors from stack traces, but those aren’t always easy to read, can sometimes be red herring to the real problem sending you in the wrong direction, and sometimes can be ignored altogether. The above are a bit harder to ascertain at 3am with little sleep.

Option 1: Add a catch

The first step is to handle all errors unrelated to types. You do this either using a try/catch or a .catch. The above code mixes async/await style and Promise chain style. While you can do that, it is recommended to follow one or the other so the code is easier to read and debug.

If you’re choosing the async await style, it could be re-written like so:

try {
    let response = await fetch('https://some.server.com/api/data')
    let json = response.json()
    ...
} catch(error) {
    console.log("error:", error)
}

If you’re using Promise chain style, it could look like so:

fetch('https://some.server.com/api/data')
    .then( r => r.json() )
    .catch( error => console.log("error:", error))

Option 2: Add the never Return Type

If this code is in a function, you do not want the TypeScript types to lie to you. Given TypeScript is a gradually typed language, this means there are cases where it’s “mostly typed”, but not entirely 100% accurate. Take a look at the following function wrapping our fetch call:

let getData = ():SomeType => {
    let response = await fetch('https://some.server.com/api/data')
    let json = response.json()
    return json as SomeType
}

The first of 2 issues here is your fetch call can fail with multiple issues, so if an error occurs, nothing is returned. The 2nd is the type casting as has no guarantee Instead, we should change our return type to accurately reflect that, changing from this:

let getData = ():SomeType => { ... }

To this:

let getData = ():SomeType | never => { ... }

The never indicates that the function will return your type _or_ never return. This forces all functions to handle that never; you or your fellow developers don’t have to remember this, TypeScript will tell you. In the case of using that function in an Angular router guard, a predicate function (a function that returns true or false), you can interpret that never as a false:

let canNavigate = async ():boolean => {
    try {
        let result = await getData()
        return result.userIsAllowed === true
    } catch(error) {
        return false
    }
}

Option 3: Add a Result Type

The above is a good first step, however, it now forces someone _else_ to handle the errors. Given TypeScript is gradual, if someone _else_ is not handling errors, your exception risks being uncaught. The best thing to do is never intentionally throw errors, nor allow ones in your code to propagate, since JavaScript is so bad at exception handling, and TypeScript never’s aren’t perfect. Instead, you return a single type that indicates the possibility of failure. There 3 common ones used in TypeScript:

– Promise – native to all browsers, Node.js, and handles synchronous and asynchronous code; Errors are `unknown`
– Observable – typically used in Angular, but supported everywhere you import the RxJS library, and handles synchronous and asynchronous code; Errors are typically typed Observable
– Result or Either – a TypeScript discriminated union; handles synchronous, Errors are typically just strings

The less uncommon are typed FP libraries like Effect or true-myth.

Let’s use Promise for now since the fetch and the above code uses Promises already. We’ll change our getData function from:

let getData = ():SomeType => {...}

To a type that more represents the possibility the function could succeed or fail:

let getData = ():Promise => {...}

While this doesn’t enforce someone adds a try/catch, there are some runtime enforcement’s and type helping TypeScript that will at least increase the chance the Promise‘s error condition is handled.

NOTE: I know it may be hard to divide “Promise is used for async” and “Promise is used to represent a function that can fail”. For now, just ignore the “Promises are required for async” part, and focus on Promise being a box that holds _either_ success or failure. The only way to _know_ typically if an either has success or failure is to open it, and those are done in type safe ways. JavaScript makes this confusing by newer versions of Node.js/Browser yelling at you for missing a catch in JavaScript, whereas TypeScript is more proactive via the compiler errors.

Uncaught promises will eventually explode. Using an Observable at least ensures it won’t “break out” of the Observable itself, resulting in an unhandled runtime exception.

However, using a Result can be the best option because it ensures a developer cannot get a the value they want unless they handle the error condition, or intentionally choose to ignore it. TypeScript enforces this. We’ll come back to the asynchronous version in another post, so just pay attention to the examples below in how they enforce the type check:

let getData = ():Result<SomeType> => {...}

This means to use that data, the developer must inspect the type. Inspecting a discriminant like this will ensure the user can only access value if it’s an Ok type, and the error property if it’s an Err type; the compiler is awesome like that:

let canNavigate = ():boolean => {
    let result = getData()
    if(result.type === 'Ok') {
        return result.value.userIsAllowed === true
    } else {
        return false
    }
}

Notice they can’t just write result.value because that property only exists if the Union type is of Ok; an Err does not have a value type, so the code won’t compile unless you first check the type using an if or switch statement.

Option 4: Check for an Ok Response

The fetch function has the built in ability check if the response is an http status code of 200 through 299 range, meaning it’s safe to use response.json() (or blob, or text, etc). If you didn’t get a 200-299 status code, you can be confident you did not get JSON back you were expecting.

fetch('https://some.server.com/api/data')
.then( r => {
    if(r.ok) {
        return r.json()
    } else {
        // we have an http error code
        return Promise.reject(new Error(`HTTP Error code: ${r.statusCode}, reason: ${r.statusText}`))
    }
})

Since much of parsing code isn’t setup to handle a response already in an non-200 state, there is no point in running that code, so you can choose to exit early, or throw an Error/return a rejected Promise so your catch will handle it early. Importantly, though, you have an opportunity to inspect what went wrong with the request, clearly indicating this is NOT a JSON parsing or type narrowing error, but a problem with the API response itself. This is important in that the type of error you get back can dictate how the developer’s code will respond. The only way it can do that is if you create a different type so the code can tell the difference in the errors returned.

Caveat: Some API’s will send back text or JSON error text in the body that you _do_ have to parse, but in a separate code path.

Option 5: Validate Your URL Beforehand

If the URL you send to fetch is malformed, it’ll throw an exception before it even makes a network request. While you can rely on the .catch in the fetch promise chain to handle this, another option is to run it through JavaScript’s URL class. One horrible side-effect of that class constructor is if it notices the url is malformed, it’ll throw an exception.

const getURL = (url:string):string | never => { ... }

Notice since the new URL can possibly fail, we type it as “either a URL string, or it’ll never return because it exploded”. We can later use that to our advantage to distinguish between “the server had a problem” and “your JSON is messed up” and “your URL is malformed, bruh”. You can replace with Promise/Observable/Result too. Example:

const getURL = (url:string):Result => {
    try {
        const urlValue = new URL(url)
        return Ok(urlvalue.href)
    } catch(error) {
        return Err(error.message)
    }
}

Option 6: Type Casting

Type casting, meaning converting from 1 type to the next, is all on the developer. Type narrowing can be a ton of work that is error prone, order important, and may/may not be thorough enough. This is particularly dangerous in JSON.parse because the return type says it’s an any. However, it’s _actually_ any | never, and in the case of response.json(), it’s Promise meaning someone else needs to handle the error scenario. You _can_ use unknown to ensure you, and your fellow developers, are forced to type narrow:

const result = JSON.parse(someString)
if(typeof result !== 'undefined'
    && typeof result?.prop !== null
    && typeof result?.prop === 'string'
    && ... {
        return Ok(result as YourType)
    } else {
        return Err('Failed to cast JSON.parse object to YourType.')
    }
)

…but that’s a lot of no fun, dangerous work. Better to use a library that has already solved this problem like Zod or ArkType. It’ll ensure the types match up, and if not, give you an error response that _somewhat_ gives you a clue as to why the decoding went wrong, way more thorough and verbose than JSON.parse’s not so great runtime error messages.

const json = JSON.parse(someString)
const { success, data, error } = YourType.safeParse(someObject)
if(success) {
    return Ok(data)
} else {
    return Err(error)
}

Conclusions

As you can see, fetch has a lot of things that can go wrong, some can be ignored, and some can actually allow another code path such as retry to happen IF you know what went wrong in the fetching process. TypeScript can help enforce these paths are safe, and you can open up these paths safely now that know what possible things can go wrong in fetch. These are a malformed URL, a networking error, your JSON parsing fails, your JSON does not math your expected type(es), or the server returned an error response. Hopefully some of the above ensures you aren’t awoken in the middle of the night from your, or someone else’s code on your team.

Encoders and Decoders in TypeScript

JesterXL — Tue, 18 Feb 2025 01:03:36 +0000

Encoding

Encoding in our context means converting a type to a string so we can save it to the web browser’s local storage. In soundly typed languages, this operation will never fail, but that is not true in JavaScript which TypeScript compiles to.

Caveat: Much of the code below is psuedo types and code. Please refer to the 3 “Final Full Examples” at the bottom of each section to see _actual_ working code you can use and safely reference.

Caveat: You’ll see if(error instanceof Error) example code. The instanceof keyword isn’t great for runtime type checking in all cases, so in the future use Error.isError(error) where applicable. At the time of this writing, the proposal is Stage 3, which means browsers intend to implement, and TypeScript will start to implement as well.

JSON.stringify

The JSON.stringify function can fail for a variety of reasons (circular references, BigInt), and has various nuances where some data types are converted to null, or are omitted entirely.

That means, encoding is not a safe operation. While not the true type, you can think of JSON.stringify having the following type:

stringify = (data:uknown) => string | never

That means, it can either return a string, or throw an exception and never return anything. Exceptions aren’t good, thus we must wrap the unsafe operation JSON.stringify and return some other type indicating either a success with the encoding data, or error indicating why the encoding failed.

EncodeData Function Type

In TypeScript, that means the return type must be defined as some type of Result such as a Promise or Observable, because the encoding operation can possibly fail. Below, the encoder’s type gets some data, and returns a string if it works, else an error if it fails.

type encodeData = (data:Record) => Promise

Success example:

john = { name: 'John', age: 17 }
result = encodeData(john)
console.log(result.data) // '{ "name": "John", "age": 17 }'

Failure example:

azathoth = { name: 'A̸̰̘͖̔z̵̛̝̀̊͠a̷͖̓̊ṱ̴̯̾̍̓̕ḣ̵̖̘̺̙̇ǫ̸̲̐̓̉t̴̢̜̊͊͂ẖ̵͆͊̾͛', age: BigInt(9007199254740991) }
result = encodeData(azathoth)
console.log(result.error) // TypeError: Do not know how to serialize a BigInt

EncodeData Function Contents

To ensure the types above remain correct, we can simply wrap the JSON.stringify above in a try/catch.

try {
  const encodedString = JSON.stringify(data)
  return Ok(string)
} catch(error) {
  return Err(error.message)
}

EncodeData Can Return a String

If you’ve seen soundly typed languages like Elm, ReScript, Haskell, Scala, etc, you may have noticed many of their encoders do not fail. This is because the the types are sound, meaning it cannot go wrong going from one type to another. The developer is required to write the encoders by hand, however. There is no one size fits all function like JSON.stringify to magically convert your type to a string. This means our encodeData would have the changed type of:

type encodeData = (data:Record) => string

JavaScript has many mechanisms to encode more complex data types. The BigInt above that broke our original encoding, you can monkey patch BigInt.prototype.toJSON. For undefined and null, you can choose to manually include the property with a null value, or choose to omit it entirely, treating undefined and null as a missing value.

However, the correctness is hard to get correct with a Record without library support given JavaScript’s numerous data types, and various options in encoding the data. Often data is encoded to be _decoded_, which means the developer will encode knowing they’ll want to decode the data a specific way later.

Narrowed Encoder

This means, we’ll often narrow our types to be more specific than Record, and then create custom encoders and decoders for them which is easier to create, and easier to verify they are correct in most cases.

Say we have an enum we want to encode:

enum CowRace {
  Cow = 'cow',
  NotACow = 'not a cow'
}

The type for the encoder would be:

type encodeCowRace = (cowRace:CowRace) => string

The function implementation would look something like the following:

if(cowRace === CowRace.Cow) {
  return JSON.stringify('cow')
} else {
  return JSON.stringify('not a cow')
}

Much easier to unit test, verify it is correct with compiler support, and decode back from local storage.

Specific Encoders as Function Parameters

Now that we’ve established using type narrowing results in easier to encode types, and that those types will have an associated encode function, let’s look at ways to use them in saving data.

Let’s encode our CowRace enum above to localstorage. We have 3 types, 2 of which we’ve already covered; our CowRace enum:

enum CowRace {
  Cow = 'cow',
  NotACow = 'not a cow'
}

Our encoderCowRace function type:

type encodeCowRace = (cowRace:CowRace) => string

And our new type, the saveCowRaceToLocalStorage function:

type saveCowRaceToLocalStorage =
  (cowRace:CowRace, encodeCowRace:EncodeCowRace) =>
 string

The type takes a cowRace enum, and your encoder function, and returns a string. The string is just whatever it was encoded too. The function may look something this:

encodedString = encodeCowRace(cowRace)
localStorage.setItem('cowrace', encodedString)
return encodedString

You’d invoke the saveCowRaceToLocalStorage like so:

result = saveCowRaceToLocalStorage(CowRace.Cow, encodeCowRace)
// result is "'cow'"

Generic Encoders as Function Parameters

The above uses a specific type and associated encoder function. What if you want a way to save to local storage that supports any type? In that case, you use a generic type parameter. Just like functions accept parameters, types accept parameters as well.

Let’s change our saveCowRaceToLocalStorage in 3 steps: update to accept a generic type, add a second parameter to accept any encoder, and finally add a return type. The generic implies “You can pass any type you want” which also means the developer passing the type must also create an encoder for it and pass it to us.

Step 1: Accept Generic Type Parameter

The first step is to change the name and 1st parameter type so we can save _anything_ to localstorage:

type saveAnythingLocalStorage<Type> = (data:Type) ...

That means now you can pass the cowRace parameter like before, but also the CowEnum type. Notice the cowRace is lowercase to be our enum value, and the CowRace type is uppercase to visually indicate a type:

saveAnythingLocalStorage<CowRace>(cowRace)

This also supports our Record:

saveAnythingLocalStorage>(john)

Step 2: Accept Generic Encoder

The type parameter is a type. The generic encoder is also a type, more specifically a function type. We have to narrow down what the encoder actually returns, though. We’ll stick to string for now since most encoders will be converting their types to strings for use as JSON strings, in our case saving to local storage so we can read out later.

type saveAnythingLocalStorage =
  (
    data:Type,
    encoder:(convertMe:Type) => string
  ) ...

The function reads “Call saveAnythingLocalStorage and pass it the data you want to save, and the encoder function which converts it to a string.”

Using our existing CowRace encoder above, encodeCowRace, we can call that new function like so:

saveAnythingLocalStorage<CowRace>(cowRace, encodeCowRace)

We _could_ also do a generic one for JSON.stringify and our Record, but that’s not safe given TypeScript thinks JSON.stringify has a return value of string, but we know it’s actually string | never. However, I’ve put here anyway so you know how to do it. TypeScript _is_ a gradually typed language after all, so good to get something work first, then make the types strong as you refactor.

saveAnythingLocalStorage>(john, JSON.stringify)

Step 3: Return Value

The last step is the return value. Since all of the encoders we’ve written cannot fail, we’ll simply return their value, a string which is their encoded representation.

type saveAnythingLocalStorage =
  (
    data:Type,
    encoder:(convertMe:Type) => string
  ) => string

The function implementation, regardless of inputs, looks like:

const encodedString = encoder(data)
return encodedString

Final Non-Failing Encoder Result

Putting it all together, our final happy path code looks like:

enum CowRace {
  Cow = 'cow',
  NotACow = 'not a cow'
}

type Encoder = (convertMe:Type) => string

const encodeCowRace = (cowRace:CowRace):string => {
  if(cowRace === CowRace.Cow) {
    return JSON.stringify('cow')
  } else {
   return JSON.stringify('not a cow')
  }
}

const saveAnythingLocalStorage = (data:Type, encoder:Encoder):string => {
  const encodedString = encoder(data)
  return encodedString
}

const cowRace = CowRace.Cow
const result = saveAnythingLocalStorage(cowRace, encodeCowRace)
// result is: 'cow'

Generic Encoders That Can Fail

In soundly typed languages, encoders cannot fail. In TypeScript, using JSON.stringify under the hood means they can fail. To make our encodeCowRace safer and the types more accurate, we can change the return value to some type of Either; a type indicating something can fail. The most common in TypeScript regardless of Browser or Node.js server is Promise, and for Angular an Observable. However, both don’t treat errors as values as well, so we’ll just make our own for now.

If it works, return the encoded string. If it fails, return the `Error` explaining why it failed:

type EncodeResult = string | Error

We’ll change the encoder that returns a string:

type EncodeCowRace = (cowRace:CowRace) => string

To instead return our Result type:

type EncodeCowRace = (cowRace:CowRace) => EncodeResult

That means, the first part of our encodeCowRace function implementation is just wrapped with a try/catch:

try {
  if(cowRace === CowRace.Cow) {
    return JSON.stringify('cow')
  } else {
    return JSON.stringify('not a cow')
  }
...

The 2nd part, error is typed as unknown, so if it’s an Error, we’ll return that, else make a new Error and attempt to convert whatever to error was to a readable string inside it:

catch(error:unknown) {
  if(error instanceof Error) {
    return error
  } else {
    return new Error(`unknown encoding error: ${String(error)}`)
  }
}

That means our saveAnythingLocalStorage no longer “always succeeds”. So we’ll change it’s return type from a string…:

type saveAnythingLocalStorage =
  (
    data:Type,
    encoder:(convertMe:Type) => string
  ) => string

To the EncodeResult instead:

type saveAnythingLocalStorage =
  (
    data:Type,
    encoder:(convertMe:Type) => string
  ) => EncodeResult

Now the types are correct, the function is safe, and the developer can pass in any types they want to safely encode.

Final Can-Fail Decoding

Our final encoding example where the encoding can fail below:

enum CowRace {
  Cow = 'cow',
  NotACow = 'not a cow'
}

type EncodeResult = string | Error

type EncoderCanFail = (convertMe:Type) => EncodeResult

const encodeCowRace = (cowRace:CowRace):EncodeResult => {
  try {
    if(cowRace === CowRace.Cow) {
      return JSON.stringify('cow')
    } else {
      return JSON.stringify('not a cow')
    }
  } catch(error:unknown) {
    if(error instanceof Error) {
      return error
    } else {
      return new Error(`unknown encoding error: ${String(error)}`)
    }
  }
}

const saveAnythingLocalStorage2 = (data:Type, encoder:EncoderCanFail ):EncodeResult => {
  const encodedStringOrError = encoder(data)
  return encodedStringOrError
}

// success is string
const cowRace = CowRace.Cow
const result = saveAnythingLocalStorage2(cowRace, encodeCowRace)
// result is: 'cow'

// failure is Error
type CowIsCool = { race: CowRace, age: BigInt }
const encodeCowIsCool = (cool:CowIsCool):EncodeResult => {
  try {
    return JSON.stringify(cool)
  } catch(error) {
    if(error instanceof Error) {
      return error
    } else {
      return new Error(`unknown encoding error: ${String(error)}`)
    }
  }
}
const failCow = { race: CowRace.Cow, age: BigInt(9007199254740991) }
const resultBad = saveAnythingLocalStorage2(failCow, encodeCowIsCool)
console.log("resultBad:", resultBad)
// BigInt value can't be serialized in JSON

Decoding

Decoding works the same way as encoding, just in reverse. We give our decoder function a type we want to decode to, and a decoder to parse the string to our type.

Why not simply use JSON.parse and then cast the parsed result using as? A few reasons this is incorrect and dangerous:

JSON.parse can also throw an error
You can get an unknown return value, so you’ll have to type narrow to your type. (We’ll avoid doing type narrowing in this post and assume you’ll use something like Zod or ArkType heavily in your decoders).
as turns TypeScript type checking off, which is unsafe

Let’s first create a specific decoder, then we’ll make it generic just like we did for our encoder.

Specific Decoder

Our enum before is CowRace, so our decoder needs to convert a string to a CowRace. However, what if someone passes a string that is not "cow" or "not a cow" such as "bunny" or empty string? We have 2 choices. We can either assume anything that’s not "cow" is CowRace.NotACow, OR we can return an error.

It may be tempting to just use a default, but this makes it much harder to debug later when many downstream components and UI’s are getting default data, and you didn’t expect it to. We want to parse, don’t validate; meaning we want to parse our data, and if it doesn’t look correct, it should fail vs. “make an assumption that bites us later which it turns out the data is invalid and we have to backtrack to figure out where our code went wrong”.

So let’s type it correctly as a Result: either we got our data and it’s good, or we got something that is not an encoded CowRace enum.

type DecodeResult = CowRace | Error

Next up is to pass in our decoder, which takes a JSON string, parses it, and attempts to convert it to a CowRace enum.

type CowRaceDecoder = (jsonString:string) => DecodeResult

The internals look something like this:

const result = JSON.parse(jsonString)
if(result === 'cow') {
  return CowRace.Cow
} else if(result === 'not a cow') {
  return CowRace.NotACow
} else {
  return new Error(`Cannot decode ${result} to a CowRace.`)}
}

That’s the happy path assuming JSON.parse works. If that fails, such as when localStorage.getItem returns a null value or a malformed JSON string, then we’ll need to handle that unhappy path as well:

} catch(error:unknown) {
  if(error instanceof Error) {
    return error
  } else {
    return new Error(`Unknown decoding error: ${String(error)}`)
  }
}

Finally, our CowRace function to read out of local storage and decode it in a type safe way looks something like:

type readCowRaceFromLocalStorage = (decoder:CowRaceDecoder) => DecodeResult

The internals look something like this:

const readString:string | null = localStorage.getItem('cowrace')
if(readString !== null) {
  const decodeResult = decoder(readString)
  return decodeResult
} else {
  return new Error('No CowRace encoded data found in localstorage.')
}

Generic Decoder

The above is specific to decoding our CowRace enum, but what if we wanted our local storage decoder to be generic? There are 3 things to make dynamic:

the key of where we read in local storage
the decoder type has to be generic
the decoder function needs to be updated

Let’s handle those 3 in order. The latter 2 should look familiar from the encoder exercise. We’ll cover the types first, then we’ll work on function implementation.

Step 1: Key

The key is just a string, so that type includes it as the first parameter:

type readAnythingFromLocalStorage = (key:string) => ...

That’d make your internals something like:

const readString:string | null = localStorage.getItem(key)

Step 2: Decoder

Next up is to pass our decoder. However, the return result is _too_ specific:

type DecodeResult = CowRace | Error

We need that result to return _any_ type. So let’s change that first via a type parameter:

// incorrect
type DecodeResult = Type | Error

HOWEVER, that may look right, but sadly, TypeScript unions “don’t know the difference” between the types they’re unifying if they’re objects like this. What’s to say you’re not passing an Error? Then what is type DecodeResult = Error | Error saying exactly? Yeah, I don’t know either.

So let’s whip out a discriminant so TypeScript knows the difference between _our_ generic type, and an Error.

// not quite correct
type DecodeResult = { tag: 'success', value: Type } | { tag: 'error', error: Error }

However, TypeScript may give you a compiler error when attempting to create those types like “Type ‘{ tag: “success”; value: CowRace; }’ is not assignable to type ‘DecodeResult’.” or “can’t assign Type ‘{ tag: “success”; value: CowRace; }’ is not assignable to type ‘DecodeResult’. to an Error”. TypeScript needs help, even with discriminants (our tag) to identify a type. You can’t always just make a local variable and type it. Creating the types through functions really helps TypeScript:

// almost correct
type DecodeResult = { tag: 'success', value: Type } | { tag: 'error', error: Error }

const DecodeSuccess = (value:Type):{ tag: 'success', value: Type } =>
    ({ tag: 'success', value })

const DecodeError = (error:Error):{ tag: 'error', error: Error } =>
    ({ tag: 'error', error })

… however, those copy pasta’d anonymous types everywhere are hard to read. You can DRY types just like you can DRY code. You do this by naming your types, just like how you name your variables:

// correct
type DecodeResult = DecodeSuccess | DecodeError
type DecodeSuccess = { tag: 'success', value: Type }
type DecodeError = { tag: 'error', error: Error }

const DecodeSuccess = (value:Type):DecodeSuccess =>
    ({ tag: 'success', value })

const DecodeError = (error:Error):DecodeError =>
    ({ tag: 'error', error })

We’ll now make the decoder more generic by including that new generic type parameter:

type Decoder<Type> = (jsonString:string) => DecodeResult<Type>

You can read that as “If I give you a JSON string, you’ll either give me the type I’m expecting back, or an Error”.

Step 3: Return Value

Now that we’ve got our return type setup, and the decoder type is now generic as well, let’s do the same for the read from local storage function’s 2nd parameter:

type readAnythingFromLocalStorage = <Type,>(
key:string,
decoder:Decoder<Type,>
) => ...

And the return value:

type readAnythingFromLocalStorage = <Type,>(
key:string,
decoder:Decoder<Type,>
):DecodeResult<Type>

Step 4: Function Implementations

We have 2 functions to write: our CowRace decoder, and our generic “read anything from localStorage”.

While our CowRace decoder is returning a specific type, it’s still using the generic type we defined above. The signature looks something like:

const decodeCowRace = (json:string):DecodeResult => {

Notice how we specify CowRace in the DecodeResult‘s first type parameter; it can be generic, so we’re like “Cool, we’ll return a DecodeResult with a CowRace inside it”.

Now let’s parse our Enum from a string. Since we cannot gurentee the string read from an external localStorage is _our_ only 2 available enum strings, and JSON.parse are both dangerous operations, we’ll wrap in a try/catch:

try {
    const value = JSON.parse(json)
    if(value === 'cow') {
        return DecodeSuccess(CowRace.Cow)
    } else if(value === 'not a cow') {
        return DecodeSuccess(CowRace.NotACow)
    } else {
        return DecodeError(new Error(`Cannot decode ${result} to a CowRace.`))
    }
}

That’ll handle getting our data,but if the JSON.parse throws, let’s handle the error:

} catch(error) {
  if(error instanceof Error) {
    return DecodeError(error)
  } else {
    return DecodeError(new Error(`Unknown decode error: ${String(error)}`))
  }
}

That handles our decoder. Now let’s create the generic readAnythingFromLocalStorage:

const encodedString = localStorage.getItem(key)
if(encodedString !== null) {
  return decoder(encodedString)
} else {
  return DecodeError(new Error('Failed to find key in local storage'))

Final Decoder Code

The final code for decoder is as follows:

enum CowRace {
  Cow = 'cow',
  NotACow = 'not a cow'
}

type DecodeResult = DecodeSuccess | DecodeError
type DecodeSuccess = { tag: 'success', value: Type }
type DecodeError = { tag: 'error', error: Error }

const DecodeSuccess = (value:Type):DecodeSuccess =>
    ({ tag: 'success', value })

const DecodeError = (error:Error):DecodeError =>
    ({ tag: 'error', error })

type Decoder = (jsonString:string) => DecodeResult

const decodeCowRace = (json:string):DecodeResult => {
  try {
    const value = JSON.parse(json)
    if(value === 'cow') {
        return DecodeSuccess(CowRace.Cow)
    } else if(value === 'not a cow') {
        return DecodeSuccess(CowRace.NotACow)
    } else {
        return DecodeError(new Error(`Cannot decode ${result} to a CowRace.`))
    }
  } catch(error) {
    if(error instanceof Error) {
      return DecodeError(error)
    } else {
      return DecodeError(new Error(`Unknown decode error: ${String(error)}`))
    }
  }
}

const readAnythingFromLocalStorage = (
key:string,
decoder:Decoder
):DecodeResult => {
  const encodedString = localStorage.getItem(key)
  if(encodedString !== null) {
    return decoder(encodedString)
  } else {
    return DecodeError(new Error('Failed to find key in local storage'))
  }
}

localStorage.setItem('cowrace', JSON.stringify('cow'))
const result = readAnythingFromLocalStorage('cowrace',decodeCowRace)
// 'Cow'

localStorage.clear()
const result2 = readAnythingFromLocalStorage('cowrace',decodeCowRace)
// Error: Failed to find key in local storage

Note: < Type, > vs < Type >

You have noticed in some of the types above, we used a instead of a . For old school JavaScript functions, you can use the type parameters like so:

function<Type> nameOfFunction(...)

However, for Arrow functions, that syntax currently fails to parse in TypeScript.

type func = () => void // works
function <Type>() {} // works
func = () => undefined // fails
func = () => undefined // works

The parameters and return value are fine, it’s just the initial type parameter part in the front. There are a few options such as having the 1st parameter extends unknown, but mixing inheritance and type parameters doesn’t make much since and is a lot more to read. Types are hard enough to read, and TypeScript types are quite verbose, so anything you can do to shrink it helps.

Conclusions

As you can see, encoding and decoding in TypeScript can make your code safer, reduce the amount of type narrowing you need to do, especially if you use Zod. For consumers of your code and api’s, it gives them the flexibility of utilizing your API’s while providing their own types which includes their own encoders and decoders in a type-safe way. TypeScript can safely ensure all erros are typesafe, and those error scenarios are handled in developers who use your code.