Course contentsShow
← TypeScript
Lesson 1654 of 1,79638. Common Patterns and AntipatternsFree lesson

The Maintenance Cost of Giant Object Type Unions

How large unions of object shapes slow down refactoring and type checking.

The Maintenance Cost of Giant Object Type Unions

What you'll learn: How large unions of object shapes can dramatically slow down both your refactoring process and TypeScript's type-checking performance.

The Problem with Massive Object Unions

Imagine you're building a notification system. You start with a simple discriminated union for different notification types. But as your product grows, you end up with something like this:

type Notification = 
  | { type: 'email'; recipient: string; subject: string; body: string }
  | { type: 'sms'; phoneNumber: string; message: string }
  | { type: 'push'; deviceToken: string; title: string; body: string }
  | { type: 'slack'; channel: string; message: string; attachments?: unknown }
  | { type: 'webhook'; url: string; payload: unknown }
  | { type: 'inApp'; userId: string; content: string; priority: number }
  // ... 20 more variants

When this union reaches dozens of object shapes, you hit two major costs:

Performance Degradation

TypeScript must check your code against every single variant in the union. Each property access, each function call, each narrowing operation multiplies the work. With 25+ object shapes, type-checking can slow to a crawl. Build times balloon. Your IDE starts lagging when you hover over variables.

Refactoring Nightmares

Need to add a timestamp property to all notifications? You must manually update every single object literal in the union. Miss one? No error until runtime. Want to rename body to content? Find-and-replace becomes dangerous because different variants might use the same property name for different purposes.

Why This Happens

Think of TypeScript's type-checker like a detective investigating every possible scenario. With a union of 30 object types, every time you access a property, the detective must verify: "Could this be variant 1? No. Variant 2? No. Variant 3?..." This exhaustive checking compounds quickly.

The maintenance cost comes from lack of shared structure. Each variant is an island. There's no inheritance, no base type, no shared properties that TypeScript can optimize around.

The Impact

Large object unions create a quadratic complexity problem: as variants grow, the interactions between them grow exponentially. Refactoring becomes archaeology—tracing each variant carefully. Team velocity drops because everyone fears touching the union.

Key Takeaway: Giant unions of object shapes create a maintenance debt that scales poorly—breaking them into smaller semantic groups, extracting common properties into base types, or using mapped types over shared discriminants dramatically improves both compiler performance and developer experience.