Phantom Types for State
You'll learn: How to use generic "phantom" type parameters to track state transitions (like Unvalidated vs Validated) at compile time, preventing you from using data before it's ready.
What Are Phantom Types?
A phantom type is a generic type parameter that doesn't appear in the actual runtime value structure—it only exists at the type level to carry information. Think of it like a invisible tag on your data that the compiler can see but JavaScript never does.
The term "phantom" means it haunts your types without manifesting in the actual data.
Why Use Phantom Types for State?
Imagine a piece of user data that must be validated before being saved to a database. Without phantom types, nothing stops you from accidentally passing unvalidated data to a save function:
interface UserData {
email: string;
age: number;
}
function saveUser(user: UserData) {
// Save to database
}
const rawInput: UserData = { email: "bad-email", age: -5 };
saveUser(rawInput); // Compiles fine, but data is invalid!
Adding a Phantom Type Parameter
Here's the pattern: add a generic parameter that represents the state, but don't use it in any property:
interface UserData<State> {
email: string;
age: number;
// State doesn't appear here — it's "phantom"
}
type Unvalidated = { readonly _brand: unique symbol };
type Validated = { readonly _brand: unique symbol };
Now we can distinguish between validated and unvalidated data:
function validateUser(user: UserData<Unvalidated>): UserData<Validated> {
// Validation logic here
if (!user.email.includes("@")) throw new Error("Invalid email");
if (user.age < 0) throw new Error("Invalid age");
return user as UserData<Validated>;
}
function saveUser(user: UserData<Validated>) {
// Only accepts validated data
}
const rawInput: UserData<Unvalidated> = { email: "test@example.com", age: 25 };
// saveUser(rawInput); // ❌ Type error!
const validated = validateUser(rawInput);
saveUser(validated); // ✅ Works!
The State Transition Pattern
The real power emerges when modeling workflows with multiple stages:
type Draft = { readonly _tag: unique symbol };
type Reviewed = { readonly _tag: unique symbol };
type Published = { readonly _tag: unique symbol };
interface Article<State> {
title: string;
content: string;
}
function review(article: Article<Draft>): Article<Reviewed> {
// Review logic
return article as Article<Reviewed>;
}
function publish(article: Article<Reviewed>): Article<Published> {
// Publish logic
return article as Article<Published>;
}
// You can't skip steps:
const draft: Article<Draft> = { title: "Hello", content: "World" };
// publish(draft); // ❌ Can't publish without review!
const reviewed = review(draft);
const published = publish(reviewed); // ✅ Correct order enforced
How It Works
The phantom type parameter acts like a compile-time state machine. The data structure remains identical at runtime—no extra properties, no overhead. But TypeScript tracks which "phase" your data is in, preventing you from calling functions in the wrong order.
Key Takeaway: Phantom types let you encode state transitions directly in the type system, making illegal states unrepresentable and ensuring operations happen in the correct order—all with zero runtime cost.