Phantom types in Typescript - Step-by-Step Execution

Concept Flow - Phantom types

Define generic type with phantom parameter

↓

Use phantom type to tag data

↓

Create values with phantom types

↓

Type system enforces distinctions

↓

Prevent mixing incompatible types

↓

Safe code

Phantom types add extra type info that doesn't exist at runtime but helps TypeScript catch errors by distinguishing similar data.

Execution Sample

Typescript

type Phantom<T, PhantomType> = T & { __phantom?: PhantomType };

// Define two phantom types
type USD = { readonly USD: unique symbol };
type EUR = { readonly EUR: unique symbol };

// Create phantom types for money
const priceUSD: Phantom<number, USD> = 10 as Phantom<number, USD>;
const priceEUR: Phantom<number, EUR> = 15 as Phantom<number, EUR>;

// Function only accepts USD
function addUSD(a: Phantom<number, USD>, b: Phantom<number, USD>): Phantom<number, USD> {
  return (a + b) as Phantom<number, USD>;
}

This code uses phantom types to tag numbers as USD or EUR, so TypeScript prevents mixing them accidentally.

Execution Table

Step	Action	Type Checked	Result	Notes
1	Define Phantom generic type	Phantom<T, PhantomType>	Type created	Phantom adds phantom type info
2	Define USD and EUR phantom types	USD, EUR	Types created	Unique symbols used for tagging
3	Create priceUSD as Phantom<number, USD>	priceUSD	Value 10 tagged as USD	TypeScript treats as number with USD tag
4	Create priceEUR as Phantom<number, EUR>	priceEUR	Value 15 tagged as EUR	Different phantom tag from USD
5	Call addUSD(priceUSD, priceUSD)	Valid	Returns Phantom<number, USD>	Allowed: same phantom type
6	Call addUSD(priceUSD, priceEUR)	Error	Type error	Cannot mix USD and EUR phantom types
7	Return from addUSD	Phantom<number, USD>	Safe USD sum	Phantom type ensures safety

💡 Execution stops because mixing different phantom types causes a compile-time error.

Variable Tracker

Variable	Start	After Step 3	After Step 4	After Step 5	Final
priceUSD	undefined	10 (tagged USD)	10 (tagged USD)	10 (tagged USD)	10 (tagged USD)
priceEUR	undefined	undefined	15 (tagged EUR)	15 (tagged EUR)	15 (tagged EUR)
addUSD result	undefined	undefined	undefined	20 (tagged USD)	20 (tagged USD)

Key Moments - 3 Insights

Why can't I add priceUSD and priceEUR even though both are numbers?

Because priceUSD and priceEUR have different phantom types (USD vs EUR), TypeScript treats them as incompatible to prevent mixing currencies. See execution_table step 6.

Does the phantom type exist at runtime?

No, phantom types are only for TypeScript's type system and do not exist in the compiled JavaScript. They help catch errors during development without affecting runtime.

How does the phantom type prevent mixing incompatible types?

The phantom type adds a unique tag to the type signature, so TypeScript sees them as distinct types even if the underlying data is the same. This is shown in execution_table steps 3-6.

Visual Quiz - 3 Questions

Look at the execution_table at step 6. What happens when you try to add priceUSD and priceEUR?

A The addition works and returns a number

B TypeScript shows a type error preventing the operation

C The code runs but logs a warning

D The phantom types are ignored and addition succeeds

💡 Hint

Check execution_table row 6 where mixing USD and EUR phantom types causes an error.

According to variable_tracker, what is the value of addUSD result after step 5?

A 20 tagged as USD

B 25 tagged as EUR

C Undefined

D 10 tagged as USD

💡 Hint

Look at variable_tracker row for addUSD result after step 5.

If you remove the phantom type from priceUSD, what would happen when adding priceUSD and priceEUR?

A Runtime error would occur

B TypeScript would still prevent adding them

C TypeScript would allow adding them without error

D The phantom type would be inferred automatically

💡 Hint

Phantom types are what make TypeScript distinguish these values; without them, they are just numbers.

Concept Snapshot

Phantom types in TypeScript:
- Use a generic type with an unused type parameter to tag data.
- Phantom types add compile-time info only, no runtime cost.
- They help distinguish similar data (e.g., currencies) to prevent mixing.
- Example: type Phantom<T, P> = T & { __phantom?: P }.
- TypeScript enforces type safety using phantom tags.

Full Transcript

Phantom types are a way to add extra type information in TypeScript that does not exist at runtime but helps the compiler catch mistakes. We define a generic type that combines a real type with a phantom tag. For example, we tag numbers as USD or EUR using phantom types. When we create values with these tags, TypeScript treats them as different types even though they are both numbers. This prevents us from mixing currencies by mistake. The code example shows defining phantom types, creating tagged values, and a function that only accepts USD tagged numbers. The execution table traces each step: defining types, creating values, and calling the function. It shows that adding two USD values works, but mixing USD and EUR causes a type error. The variable tracker shows how values change with phantom tags. Key moments clarify that phantom types exist only at compile time and prevent mixing incompatible types. The quiz tests understanding of type errors, variable values, and the role of phantom types. The snapshot summarizes phantom types as compile-time tags that improve safety without runtime cost.