Posttypescript, unions, node, programming

Understanding Discriminated Unions in TypeScript

Discriminated unions (also known as tagged unions) are a powerful TypeScript pattern that enables...

Date published

April 25, 2025

PostJul 15, 2025

Building Android Widgets in Expo with Custom Native Modules

A guide to creating Android home screen widgets using Expo modules, complete with state management,...

expo
reactnative
typescript

Read post

PostFeb 20, 2025

How to get the Oauth providre access tokens from next auth/authjs

Modify your nextauth client and add a callbacks section that will get the access token from the...

nextjs
authjs
typescript

Read post

PostFeb 20, 2025

How to select oauth scopes in next-auth / authjs

You can select the scopes you want to request from GitHub/your oauthprovider in the login page, and...

nextjs
authjs
oauth

Read post

What is a Discriminated Union?

A discriminated union is a data structure where:

Each possible type in the union contains a common property (the "discriminant")
This property has a different literal type for each variant
TypeScript uses this property to narrow down the type when checking conditions

The Problem with Regular Union Types

Consider our first example using regular union types:

typescript

1type ErrorResponse = {
2  message: string;
3  statusCode: number;
4  cause: string;
5};
6
7type SuccessResponse = {
8  statusCode: number;
9  data: Record<string, unknown>;
10};
11
12// Union type to represent the possible responses
13type Result = ErrorResponse | SuccessResponse;

When working with this type, we need to use property checking to determine which type we're dealing with:

typescript

1const fetchedData = await fetchData("https://example.com/api");
2
3// Check for a property that only exists in one variant
4if ("message" in fetchedData) {
5  // TypeScript narrows fetchedData to ErrorResponse
6  return { error: fetchedData.message };
7}
8
9// TypeScript narrows fetchedData to SuccessResponse
10const response = fetchedData.data;

This approach has several issues:

It relies on the presence of specific properties
You need to know which properties are unique to each type
There's no guarantee that you've exhaustively handled all possibilities
Refactoring can easily break the type narrowing

The Solution: Discriminated Unions

A better approach is to use a discriminated union with an explicit tag:

typescript

1type ErrorResponse = {
2  message: string;
3  statusCode: number;
4  cause: string;
5  response_type: "error";  // The discriminant
6};
7
8type SuccessResponse = {
9  message: string;
10  statusCode: number;
11  data: Record<string, unknown>;
12  response_type: "success";  // The discriminant
13};
14
15type Result = ErrorResponse | SuccessResponse;

With this pattern, type narrowing becomes explicit and reliable:

typescript

1const fetchedData = await fetchData2("https://example.com/api");
2
3if (fetchedData.response_type === "error") {
4  // TypeScript knows fetchedData is ErrorResponse
5  return { error: fetchedData.message };
6}
7
8// TypeScript knows fetchedData is SuccessResponse
9const response = fetchedData.data;

Understanding Discriminated Unions in TypeScript

Building Android Widgets in Expo with Custom Native Modules

How to get the Oauth providre access tokens from next auth/authjs

How to select oauth scopes in next-auth / authjs

Understanding Discriminated Unions in TypeScript

Building Android Widgets in Expo with Custom Native Modules

How to get the Oauth providre access tokens from next auth/authjs

How to select oauth scopes in next-auth / authjs

What is a Discriminated Union?

The Problem with Regular Union Types

The Solution: Discriminated Unions

Benefits of Discriminated Unions

Real-World Example: API Response Handling

Without Discriminated Unions:

With Discriminated Unions:

Best Practices

Conclusion

More posts

Building Android Widgets in Expo with Custom Native Modules

How to get the Oauth providre access tokens from next auth/authjs

How to select oauth scopes in next-auth / authjs

More posts

Building Android Widgets in Expo with Custom Native Modules

How to get the Oauth providre access tokens from next auth/authjs

How to select oauth scopes in next-auth / authjs

What is a Discriminated Union?

The Problem with Regular Union Types

The Solution: Discriminated Unions

Benefits of Discriminated Unions

Real-World Example: API Response Handling

Without Discriminated Unions:

With Discriminated Unions:

Best Practices

Conclusion