Professional TypeScript: Improve Type Safety with Branded Types

Vinicius Albano — Wed, 08 Jan 2025 13:21:47 +0000

As developers grow in their careers, they increasingly focus on writing expressive, maintainable, and bug-resistant code. We refine naming conventions, adopt best practices like Clean Architecture and SOLID principles, and invest in robust testing strategies. Yet, one critical area that often receives less attention is how we represent our data types—the foundation of clean, understandable code. Without meaningful, type-safe representations of domain concepts, we risk introducing subtle bugs.

In this article, we’ll explore how branded types can help make your TypeScript code safer, clearer, and more expressive by distinguishing similar-looking data at the type level.

What Are Branded Types?

Branded types allow you to enhance the meaning of primitive types (like string or number) by “tagging” them with a unique marker. This marker differentiates otherwise identical primitives and helps the TypeScript compiler detect incorrect usage. Essentially, you use the same underlying data type but give it a custom “brand” to distinguish one domain concept from another.

Primitive types like string and number are general-purpose and lack inherent meaning. When used across a codebase, they make it easy to confuse one concept (like a UserName) with another (like an Email). Branded types solve this by assigning a unique identifier to each concept, transforming generic primitives into meaningful domain-specific types.

For example, while UserName, Email, and Password might all be strings, they represent different concepts in the system. Without branding, they could easily be mixed up, leading to potential bugs. Branded types help to prevent that.

Consider these type aliases:

type UserName = string;
type Email = string;
type Password = string;

At first glance, this seems helpful: UserName, Email, and Password convey intent. However, TypeScript still treats all three as string at the compiler level. Swapping their order in a function call will not raise any errors, since each one is just a string.

type UserName = string;
type Email = string;
type Password = string;

function signup(username: UserName, email: Email, password: Password) {
  // signup logic
}

// Variables look fine individually:
const username: UserName = 'johndoe';
const email: Email = 'john@doe.com';
const password: Password = 'p@ssw0rd';

// But swapping arguments causes no compile-time errors:
signup(username, password, email); // No error, but incorrect!

Because TypeScript does not differentiate these types at compile time, you’re not fully benefiting from type safety.

How Branded Types Work

The Brand type works by intersecting a base type (like string) with a unique marker using TypeScript’s unique symbol. This marker exists only at the type level and has no runtime representation. Because of this, branded types add compile-time safety without affecting runtime behavior. They allow TypeScript to distinguish between otherwise identical primitives like UserName and Email.

Here’s the key snippet:

declare const brand: unique symbol;

export type Brand<T, TBrand> = T & { [brand]: TBrand };

In this code, Brand takes two type parameters:

T: The base type (e.g., string, number)
TBrand: A distinguishing label (e.g., 'UserName')

By combining T with an object keyed by unique symbol, the result is a new type that behaves like T but carries an additional, invisible marker. This ensures that values branded with one label (e.g., UserName) cannot be used in a context expecting a different label (e.g., Email).

Applying Branded Types to Improve Safety

To implement branded types, redefine your domain-specific primitives:

type UserName = Brand<string, 'UserName'>;
type Email = Brand<string, 'Email'>;
type Password = Brand<string, 'Password'>;

Now, when you use these branded types, you must explicitly assert them:

const username = 'johndoe' as UserName;
const email = 'john@doe.com' as Email;
const password = 'p@ssw0rd' as Password;

signup(username, password, email);
// TypeScript error:
// Argument of type 'Password' is not assignable to parameter of type 'Email'.
//  Type 'Password' is not assignable to type '{ [brand]: "Email"; }'.
//    Types of property '[brand]' are incompatible.
//      Type '"Password"' is not assignable to type '"Email"'.ts(2345)

By adding this small, compile-time-only constraint, TypeScript ensures you can’t mix up arguments, reducing the risk of subtle bugs.

Enforcing Validation

Branded types, combined with validation functions, provide an additional layer of type safety. A validation function not only ensures the value meets certain criteria but also narrows its type. This guarantees that only validated data is passed into functions that rely on the branded type.

function isValidPassword(password: string): password is Password {
  return password.length >= 8;
}

const candidatePassword = 'p@ssw0rd'; // just a plain string

if (isValidPassword(candidatePassword)) {
  // Now candidatePassword is a Password
  signup(username, email, candidatePassword);
}

In this example, the isValidPassword function ensures that only passwords meeting the required criteria can be used with the Password type. The branded type, combined with the type guard, effectively enforces validation at compile time.

Improving Domain Clarity

Branded types also shine in domains where similar data is represented by the same primitive type. Consider a real-world example: in a system that manages both user and car data, you might have a UserId and a CarId, both represented by numbers. Without branded types, comparing or passing them interchangeably can easily lead to bugs.

With branded types, TypeScript enforces that UserId and CarId are treated as distinct types, even though they are both numbers. This improves both safety and readability.

type UserId = Brand<number, 'UserId'>;
type CarId = Brand<number, 'CarId'>;

const ids = [1 as UserId, 1 as CarId] as const;

const userId = ids[0]; // recognized as UserId
const carId = ids[1]; // recognized as CarId

console.log(userId === carId);
// TypeScript error:
// This comparison appears to be unintentional because 
// the types 'UserId' and 'CarId' have no overlap.ts(2367)

It’s now instantly clear which 1 refers to a user and which refers to a car. By making these distinctions explicit at the type level, you enhance readability, reduce errors, and accelerate the onboarding process for new team members.

Conclusion

Branded types are a lightweight but powerful addition to your TypeScript arsenal. They enhance your domain modeling by:

Providing stronger compile-time guarantees
Preventing subtle bugs caused by mixing up similar values
Enforcing validation flows and clean data pipelines
Improving readability and team collaboration

By incorporating branded types into your projects, you can build safer, more maintainable systems and better align your code with the real-world domain it represents. Start small—introduce branded types in a key part of your application—and see how they can transform your TypeScript code for the better.

References

Matt Pocock’s thread on Branded Types — An insightful thread that breaks down the concept of branded types in TypeScript.

TypeScript Docs: unique symbol — Official TypeScript documentation explaining unique symbol and its applications.

DEV Community: Vinicius Albano