How to model your entities with opaque and sum types in Typescript.

Guillaume Wuip
Feb 20 · 4 min read

Working on a new feature implies working on modeling the data that comes with it. This step provides a clean and readable basis to build from further down the line. Because of this we are putting a larger emphasis on making sure our model is as robust and maintainable as it could be. Here is how.

The scenario

Imagine we are working on a fancy chat application in which we send many kinds of messages. We could model them this way:

And we would define a union type Message that could be any of them:

Doing so helps a lot (we can for example define a list const messages: Message[] = … without having to deal with variations at that level) but it is not perfect.

How should we deal with this union in a function that receives a Message and that should act differently depending on the type of the message? We would have to set up a series of ifs and quickly code ourselves into a corner, like this:

We went through the trouble of strongly typing our messages yet we have to rely on fragile internal structure inspection to differentiate them. We want to differentiate the types of messages effortlessly.

Tagged Union

Enter tagged unions. In Typescript, a typed object is still only a classic Javascript object at runtime. We need to find a trick to differentiate two types with the same properties, like ImageMessage and AudioMessage.

We can add a tag to our types manually:

Our Message type can now be called a “tagged union”, which means a union of sub-types that all have a tag value (here, messageType). Now when we write our function, Typescript will refine the type when we check the tag value.

While this works great, it doesn’t scale so well. We have to test message.messageType everywhere in our codebase. This will necessarily create a lot of boilerplate and is not D.R.Y.

User type guard

We want to check the type of each message more easily. Typescript can help with that through user-defined type guards.

It is now cleaner to check for a TextMessage:

But we still have to do all our ifs each time we want to process messages differently based on type. In the end, we did not remove that much boilerplate so far — it is just moving it somewhere else — but at least it is D.R.Y: if the messageType values change, we simply update the type guard function.

Fold on things

Inspired by functional programming and particularly the library fp-ts, we decided to give the fold/match pattern a try for our entities sum types.

If you are not familiar with the concept, here is what it looks like. Using fp-ts Option, we can can use the fold function:

How does this help with our Message sum-type? We need a function that takes as many parameters as there are sub-types. Each one of these parameters should be a function as well, one that takes a Message and returns something. Finally, the parent function, given a Message, should return the correct sub-function result depending on its sub-type.

Now our renderMessage is way cleaner:

Creating a fold for every sum-type and for every union type is fastidious. We created @iadvize-oss/foldable-helpers to help with that:

We now have a Message sum-type with its fold function to match on members.

It is good enough to be used internally, but if we want to share the Message sum-type with the world, for example in a public library, we would want to consider subtype properties as private or opaque.

Expose opaque message entities

Let’s say we want to share the Message, TextMessage, ImageMessage and AudioMessage entities in a library as well as functional function like below:

We don’t want to share externally how we have modeled our entities and which properties we have on each type: forcing users to use our functions allows us to update the internal implementation without breaking someone else’s code.

We use @iadvize-oss/opaque-type to hide our type in an opaque one. It will wrap our internal types in an opaque shell. It will also provide a “runtime” type representation like below:

The user of our fabulous Message library can use it without having to rely on internal details. Breaking changes will only be real, functional breaking changes and never petty implementation details.

Having modeled our functional entities with a tagged-union, opaque types and a foldable interface we can now share them freely, assured we are still in control of the internal details.

Doing this certainly prevents technical “breakings” down the line but, regardless of the publicity of our codebase, it also greatly facilitates maintenance and refactoring while enforcing a consistent, strongly typed data structure.


A big thanks ❤️ to all my iAdvize colleagues that helped me write this post: Wandrille Verlut, Victor Graffard, Axel Cateland and Ben !

Guillaume Wuip

Written by

CS engineer student — Web developper

iAdvize Engineering

Publications from the iAdvize engineering team :)

More From Medium

More from iAdvize Engineering

More from iAdvize Engineering

More from iAdvize Engineering

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade