Tagged Unions and Type Guards in TypeScript

This article is a continuation of the series of articles on tagged unions in TypeScript. If you haven’t read it yet, you can access the first article here.

Even thought most of the benefits stemming from using tagged unions are immediately available to developers because the TypeScript compiler understands them on the intrinsic level, sometimes we need to help it out to follow through on our intentions regarding structural transformations.

Filtering arrays

For the purpose of the following example, let’s define some structures that describe different types of users:

It should be relatively easy to define a function that filters out non-admin users (or filters in admins), right? Let’s try to write it then:

Unfortunately, it didn’t work as we expected. The type of the array after using .filter is still the original type instead of the planned narrowed one. It appears that TypeScript doesn’t infer anything from the filter function’s callback. For that to happen, we need to use a type guard.

Type Guards

What is a type guard in TypeScript? In plain words, it’s a function that accepts one and only one argument of type A and returns a boolean value, describing if the aforementioned argument of type A is as well of type B. One-argument functions that return boolean values are formally called predicate functions or simply predicates.

Let’s write one that satisfy our needs:

The only shocking part here might be the substitution of boolean with user is AdminUser, which, in the end, is also a boolean statement nevertheless.

We can now use this new function in the filterAdmins function:

Now the TypeScript compiler reports no errors, as it understands the type narrowing hidden in the isAdminUser predicate.

Type Guards and Generic Tagged Unions

It is possible to implement type guards for generic tagged unions, as visible in the following example — let’s define some containers first for data requiring privileged and unprivileged access:

Similarly to what we have seen before, we can define a generic type guard isPrivilegedContainer with a type parameter T:

Now, we can write a function that returns a collection of privileged data:


Since type guards are a way of providing hints to the compiler about types, we can leverage it in wrong ways too, giving the compiler a wrong piece of information. For instance, we can misdefine theisAdminUser function in the following fashion and the TSC won’t report any problems:

This might happen because of copy-pasting, that’s why it is crucial that we test our code before it is shipped to a production system.


The TypeScript Compiler is definitely smart in terms of inferring types but it’s not an omnipotent tool and sometimes we need to help it by providing some type hints. We can use type guards to inform the compiler about some operations that might narrow types. Type guards can be used as well to narrow generic types.

I presented one of the obvious usages which is leveraging type narrowing against collections of tagged unions. It should be clear though that type guards are a powerful tool that, if used improperly, might introduce a lot of subtle hard-to-find type errors.

Full-stack Software Developer that loves building products.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store