How to model your entities with opaque and sum types in Typescript.
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.
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.
We can add a tag to our types manually:
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
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
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.
renderMessage is way cleaner:
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
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.
@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.