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

When a Single Focused Type Is Better Than a Union

Recognizing cases where variations should be separate concerns entirely.

When a Single Focused Type Is Better Than a Union

You'll learn: How to recognize when variations should be separate concerns entirely, rather than cramming everything into one union type.


The Core Idea

Sometimes when you're designing types, you'll be tempted to create a union that handles every possible variation of something. But often, those variations represent fundamentally different concepts that deserve their own focused types.

Think of it like combining a hammer, screwdriver, and wrench into one "universal tool." Sure, they're all tools, but forcing them into a single interface makes each use case awkward. Sometimes it's better to have three separate, purpose-built tools.


When Union Bloat Happens

You'll know you've gone too far with unions when:

  • You have many optional properties that only make sense for specific variants
  • Different variants require completely different operations or methods
  • Client code always checks which variant it has before doing anything
  • Adding a new variant touches unrelated code across your system

The union becomes a "God type" that tries to be everything to everyone.


The Separate Types Approach

Instead of one mega-union, create distinct types for each concern:

// ❌ Bloated union trying to do too much
type DataSource = 
  | { type: 'api'; url: string; headers?: Record<string, string>; retries?: number }
  | { type: 'file'; path: string; encoding?: string }
  | { type: 'database'; connection: string; query: string; pool?: number }
  | { type: 'stream'; readable: ReadableStream; bufferSize?: number };

// ✅ Separate, focused types
type ApiSource = { url: string; headers?: Record<string, string>; retries?: number };
type FileSource = { path: string; encoding?: string };
type DatabaseSource = { connection: string; query: string; pool?: number };
type StreamSource = { readable: ReadableStream; bufferSize?: number };

Now each type has a clear, single purpose. Functions can accept the specific type they need, not a kitchen-sink union.


When This Matters

This pattern shines when:

  • Different contexts need different capabilities – API client vs file reader vs database layer
  • The variations are implementation details, not domain states
  • You're building library boundaries where callers shouldn't care about variants they don't use

If your union is modeling distinct states of one thing (like loading/success/error), keep the discriminated union. But if it's modeling different things that happen to share some category label, split them apart.


Key Takeaway: Not everything that could be grouped in a union should be. When variants represent separate concerns with different purposes and operations, focused individual types lead to clearer, more maintainable code than one sprawling union.