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

type AdminUser = {
type: 'ADMIN';
type NonAdminUser = {
type: 'NON_ADMIN';
type User = AdminUser | NonAdminUser;

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:

const filterAdmins = (
users: ReadonlyArray<User>
): ReadonlyArray<AdminUser> =>
users.filter(({ type }) => type === 'ADMIN');

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

Let’s write one that satisfy our needs:

const isAdminUser = (user: User): user is AdminUser =>
user.type === 'ADMIN';

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:

const filterAdmins = (
users: ReadonlyArray<User>
): ReadonlyArray<AdminUser> =>

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

Type Guards and Generic Tagged Unions

type PrivilegedContainer<T> = {
privilegedData: T;
type UnprivilegedContainer<T> = {
unprivilegedData: T;
type Container<T> =
| PrivilegedContainer<T>
| UnprivilegedContainer<T>;

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

const isPrivilegedContainer = <T>(
container: Container<T>
): container is PrivilegedContainer<T> =>
container.type === 'PRIVILEGED';

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

const getPrivilegedData = <T>(
containers: ReadonlyArray<Container<T>>
): ReadonlyArray<T> =>
.map(({ privilegedData }) => privilegedData);


const isAdminUser = (user: User): user is AdminUser =>
user.type === 'NON_ADMIN';

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.


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