Course contentsShow
← TypeScript
Lesson 1356 of 1,79631. Type-Driven DesignFree lesson

Phantom Types for State

Using generic brand parameters to track state transitions like Unvalidated vs Validated at the type level.

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.