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

The Module Boundary Smell

Giant unions crossing module boundaries signal missing domain boundaries.

The Module Boundary Smell

What you'll learn: How giant unions crossing module boundaries signal architectural problems where domain boundaries should exist instead.

The Problem

When you find yourself passing massive union types across module boundaries—especially unions with 10, 20, or more string literals or object variants—you've likely encountered a module boundary smell. This pattern suggests your modules are doing too much or that important domain concepts are missing.

// app/api/routes.ts
export type ApiResponse = 
  | { type: 'user-created'; userId: string; email: string }
  | { type: 'user-updated'; userId: string; changes: object }
  | { type: 'order-placed'; orderId: string; items: any[] }
  | { type: 'order-shipped'; orderId: string; trackingNumber: string }
  | { type: 'payment-processed'; paymentId: string; amount: number }
  | { type: 'payment-failed'; paymentId: string; reason: string }
  | { type: 'inventory-updated'; sku: string; quantity: number }
  | { type: 'notification-sent'; notificationId: string }
  // ... 15 more variants

This union crosses the module boundary from your API layer to everywhere else. Every consumer must handle (or ignore) all 23 cases, even when they only care about user-related events.

Why This Smells

Mixing unrelated concerns: Users, orders, payments, and inventory are distinct domains. Lumping them into one union couples unrelated parts of your system.

Single point of change: Adding a new payment type requires modifying this central union, creating merge conflicts and forcing recompilation of distant code.

Poor discoverability: Finding "what events relate to orders" requires scanning the entire union rather than looking at an OrderEvents module.

The Fix: Domain-Specific Boundaries

Split the union along natural domain lines:

// domains/users/events.ts
export type UserEvent = 
  | { type: 'user-created'; userId: string; email: string }
  | { type: 'user-updated'; userId: string; changes: object };

// domains/orders/events.ts
export type OrderEvent =
  | { type: 'order-placed'; orderId: string; items: any[] }
  | { type: 'order-shipped'; orderId: string; trackingNumber: string };

// domains/payments/events.ts
export type PaymentEvent =
  | { type: 'payment-processed'; paymentId: string; amount: number }
  | { type: 'payment-failed'; paymentId: string; reason: string };

Now each module exposes a focused union. Code that processes payments imports PaymentEvent, not the entire application's event catalog. Your module boundaries now reflect your domain boundaries.

Key Takeaway: When a giant union type crosses module boundaries, it's usually hiding missing domain concepts. Split it into smaller, semantically-grouped types that live within focused modules—your architecture will be clearer and more maintainable.