Why Phantom types in Typescript? - Purpose & Use Cases

The Big Idea

What if your code could catch sneaky mistakes that look right but cause big problems?

The Scenario

Imagine you have different kinds of IDs in your program, like UserID and ProductID, both just numbers. You try to keep them separate by naming variables carefully, but nothing stops you from mixing them up by accident.

The Problem

Manually tracking which number means what is slow and risky. You might pass a ProductID where a UserID is expected, causing bugs that are hard to find. The compiler can't help because both are just numbers.

The Solution

Phantom types let you add invisible tags to your data types. These tags don't change the actual data but tell the compiler to treat them as different types. This way, you can't mix UserID and ProductID by mistake, and errors are caught early.

Before vs After

✗ Before

function getUserName(id: number) { /* ... */ }
function getProductName(id: number) { /* ... */ }
getUserName(productId); // No error, but wrong!

✓ After

type UserID = number & { readonly brand: unique symbol };
type ProductID = number & { readonly brand: unique symbol };
function getUserName(id: UserID) { /* ... */ }
function getProductName(id: ProductID) { /* ... */ }
const productId: ProductID = 123 as ProductID;
getUserName(productId); // Error: Type 'ProductID' is not assignable to type 'UserID'

What It Enables

Phantom types enable safer code by letting the compiler catch mix-ups between similar data types before your program runs.

Real Life Example

In a banking app, phantom types can keep AccountNumber and TransactionID separate, preventing costly mistakes like sending money to the wrong account.

Key Takeaways

Phantom types add invisible tags to data for extra safety.

They prevent mixing up similar types like IDs or units.

This leads to fewer bugs and more reliable programs.