Advanced Types - Unions, Intersections, and Type Guards

The $50,000 Payment Bug That Wasn't

It was Black Friday, 4:23 AM. I woke up to silence. No alerts. No errors. But something felt wrong.

I checked our payment processor dashboard: $127,000 in transactions. Normal for Black Friday. But then I saw the refund queue: $0.

Our refund processing had silently failed for 6 hours. The code:

// payment-processor.js - Old JavaScript
function processTransaction(transaction) {
  if (transaction.type === 'charge') {
    return chargeCard(transaction.amount, transaction.cardToken);
  } else if (transaction.type === 'refund') {
    return refundCard(transaction.amount, transaction.cardToken);
  }
  // What if transaction.type was 'authorization'?
  // Or 'void'? Or a typo like 'reund'?
  // Silently returns undefined!
}

A new transaction type had been added: 'authorization'. But this function didn't handle it. Result: 2,847 unprocessed authorizations. Customers couldn't complete purchases. Cart abandonment spiked. We estimated $50,000 in lost revenue.

The fix with TypeScript took 30 minutes:

type TransactionType = 'charge' | 'refund' | 'authorization' | 'void';

interface Transaction {
  id: string;
  type: TransactionType;
  amount: number;
  cardToken: string;
}

function processTransaction(transaction: Transaction): Promise<TransactionResult> {
  switch (transaction.type) {
    case 'charge':
      return chargeCard(transaction.amount, transaction.cardToken);
    case 'refund':
      return refundCard(transaction.amount, transaction.cardToken);
    case 'authorization':
      return authorizeCard(transaction.amount, transaction.cardToken);
    case 'void':
      return voidTransaction(transaction.id);
    default:
      // TypeScript ensures this is never reached
      const exhaustiveCheck: never = transaction.type;
      throw new Error(`Unhandled transaction type: ${exhaustiveCheck}`);
  }
}

Result: TypeScript would have caught the missing case at compile time. The bug would never have reached production.

This article covers union types, intersections, and type narrowing - the tools that prevent silent failures.

---

Union Types

A value that can be one of several types.

Basic Union Types

let value: string | number;

value = 'hello';  // ✓
value = 42;       // ✓
value = true;     // ✗ Error: boolean not assignable

function printId(id: string | number): void {
  console.log(`ID: ${id}`);
}

printId('abc-123');  // ✓
printId(12345);      // ✓
printId(true);       // ✗ Error

Union with Multiple Types

type Status = 'idle' | 'loading' | 'success' | 'error';

let requestStatus: Status;

requestStatus = 'loading';   // ✓
requestStatus = 'success';   // ✓
requestStatus = 'pending';   // ✗ Error: not in union

Union with null and undefined

function getUser(id: string): User | null {
  const user = database.find(id);
  return user || null;
}

const user = getUser('123');
// user is User | null
if (user) {
  console.log(user.name);  // TypeScript knows user is not null
}

---

Type Narrowing

Refining union types to more specific types.

typeof Type Guards

function printValue(value: string | number): void {
  if (typeof value === 'string') {
    // TypeScript knows value is string here
    console.log(value.toUpperCase());
  } else {
    // TypeScript knows value is number here
    console.log(value.toFixed(2));
  }
}

Truthiness Narrowing

function printName(name: string | null | undefined): void {
  if (name) {
    // TypeScript knows name is string here
    console.log(name.toUpperCase());
  } else {
    console.log('No name provided');
  }
}

Equality Narrowing

function handleStatus(status: 'success' | 'error' | 'pending'): void {
  if (status === 'success') {
    // status is exactly 'success'
    showSuccessMessage();
  } else if (status === 'error') {
    // status is exactly 'error'
    showErrorMessage();
  } else {
    // status is 'pending'
    showLoadingSpinner();
  }
}

in Operator Narrowing

interface Circle {
  kind: 'circle';
  radius: number;
}

interface Rectangle {
  kind: 'rectangle';
  width: number;
  height: number;
}

type Shape = Circle | Rectangle;

function getArea(shape: Shape): number {
  if ('radius' in shape) {
    // TypeScript knows shape is Circle
    return Math.PI * shape.radius ** 2;
  } else {
    // TypeScript knows shape is Rectangle
    return shape.width * shape.height;
  }
}

instanceof Narrowing

class ApiError extends Error {
  statusCode: number;
  
  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
  }
}

class NetworkError extends Error {
  retryCount: number;
  
  constructor(message: string, retryCount: number) {
    super(message);
    this.retryCount = retryCount;
  }
}

function handleError(error: Error | ApiError | NetworkError): void {
  if (error instanceof ApiError) {
    console.log(`API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.log(`Network Error (retry ${error.retryCount}): ${error.message}`);
  } else {
    console.log(`Error: ${error.message}`);
  }
}

---

Discriminated Unions

Union types with a common literal property.

Basic Discriminated Union

interface LoadingState {
  status: 'loading';
}

interface SuccessState {
  status: 'success';
  data: string;
}

interface ErrorState {
  status: 'error';
  error: string;
}

type RequestState = LoadingState | SuccessState | ErrorState;

function renderUI(state: RequestState): string {
  switch (state.status) {
    case 'loading':
      return 'Loading...';
    case 'success':
      // TypeScript knows state has 'data'
      return `Data: ${state.data}`;
    case 'error':
      // TypeScript knows state has 'error'
      return `Error: ${state.error}`;
  }
}

Real-World Example: API Response

interface ApiSuccess<T> {
  success: true;
  data: T;
  timestamp: Date;
}

interface ApiError {
  success: false;
  error: {
    code: string;
    message: string;
  };
  timestamp: Date;
}

type ApiResponse<T> = ApiSuccess<T> | ApiError;

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    const data = await response.json();
    
    return {
      success: true,
      data,
      timestamp: new Date()
    };
  } catch (error) {
    return {
      success: false,
      error: {
        code: 'FETCH_ERROR',
        message: error instanceof Error ? error.message : 'Unknown error'
      },
      timestamp: new Date()
    };
  }
}

// Type-safe usage
const response = await fetchUser('123');

if (response.success) {
  // TypeScript knows response has 'data'
  console.log(`User: ${response.data.name}`);
} else {
  // TypeScript knows response has 'error'
  console.error(`Error ${response.error.code}: ${response.error.message}`);
}

Exhaustiveness Checking

type PaymentMethod = 'credit_card' | 'paypal' | 'bank_transfer' | 'crypto';

function processPayment(method: PaymentMethod, amount: number): void {
  switch (method) {
    case 'credit_card':
      chargeCreditCard(amount);
      break;
    case 'paypal':
      chargePayPal(amount);
      break;
    case 'bank_transfer':
      initiateBankTransfer(amount);
      break;
    case 'crypto':
      processCryptoPayment(amount);
      break;
    default:
      // Exhaustiveness check
      const exhaustiveCheck: never = method;
      throw new Error(`Unhandled payment method: ${exhaustiveCheck}`);
  }
}

// If we add a new payment method:
// type PaymentMethod = 'credit_card' | 'paypal' | 'bank_transfer' | 'crypto' | 'apple_pay';

// TypeScript will error at 'default' case - we forgot to handle 'apple_pay'!

This saved me from the Black Friday incident. Add a new case? TypeScript forces you to handle it.

---

Intersection Types

Combine multiple types into one.

Basic Intersection

interface Person {
  name: string;
  age: number;
}

interface Employee {
  employeeId: string;
  department: string;
}

type Worker = Person & Employee;

const worker: Worker = {
  name: 'John Doe',
  age: 30,
  employeeId: 'EMP-001',
  department: 'Engineering'
  // Must have ALL properties from both types
};

Intersection with Multiple Types

interface Timestamped {
  createdAt: Date;
  updatedAt: Date;
}

interface Identifiable {
  id: string;
}

interface Auditable {
  createdBy: string;
  updatedBy: string;
}

type AuditedEntity = Timestamped & Identifiable & Auditable;

const record: AuditedEntity = {
  id: '123',
  createdAt: new Date('2024-01-01'),
  updatedAt: new Date('2024-12-01'),
  createdBy: 'user-1',
  updatedBy: 'user-2'
};

Extending Interfaces vs Intersections

// With extends
interface Employee extends Person {
  employeeId: string;
}

// With intersection
type Employee = Person & {
  employeeId: string;
};

// Both work similarly, but extends is clearer for objects

---

Literal Types

Exact values as types.

String Literal Types

let direction: 'north' | 'south' | 'east' | 'west';

direction = 'north';  // ✓
direction = 'up';     // ✗ Error

function move(direction: 'north' | 'south' | 'east' | 'west'): void {
  console.log(`Moving ${direction}`);
}

Number Literal Types

type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;

function rollDice(): DiceRoll {
  return (Math.floor(Math.random() * 6) + 1) as DiceRoll;
}

type HttpSuccessCode = 200 | 201 | 204;
type HttpErrorCode = 400 | 401 | 403 | 404 | 500;
type HttpCode = HttpSuccessCode | HttpErrorCode;

Boolean Literal Types

type AlwaysTrue = true;
type AlwaysFalse = false;

// Useful for conditional types (advanced)

Combining Literals

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
type ContentType = 'application/json' | 'text/plain' | 'text/html';

interface RequestConfig {
  method: Method;
  contentType: ContentType;
  url: string;
}

const config: RequestConfig = {
  method: 'POST',
  contentType: 'application/json',
  url: '/api/users'
};

---

Type Predicates

Custom type guards for complex narrowing.

Basic Type Predicate

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function processValue(value: string | number): void {
  if (isString(value)) {
    // TypeScript knows value is string
    console.log(value.toUpperCase());
  } else {
    // TypeScript knows value is number
    console.log(value.toFixed(2));
  }
}

Object Type Predicates

interface User {
  id: string;
  name: string;
  email: string;
}

interface Admin {
  id: string;
  name: string;
  email: string;
  permissions: string[];
}

function isAdmin(user: User | Admin): user is Admin {
  return 'permissions' in user;
}

function displayUser(user: User | Admin): void {
  console.log(`${user.name} (${user.email})`);
  
  if (isAdmin(user)) {
    // TypeScript knows user is Admin
    console.log(`Permissions: ${user.permissions.join(', ')}`);
  }
}

Array Type Predicates

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every(item => typeof item === 'string');
}

function processInput(input: unknown): void {
  if (isStringArray(input)) {
    // TypeScript knows input is string[]
    input.forEach(str => console.log(str.toUpperCase()));
  }
}

Real-world pattern from my validation library:

interface ValidationResult<T> {
  valid: boolean;
  data?: T;
  errors?: string[];
}

function isValidUser(result: ValidationResult<unknown>): result is ValidationResult<User> {
  if (!result.valid || !result.data) {
    return false;
  }
  
  const data = result.data as any;
  return (
    typeof data.id === 'string' &&
    typeof data.name === 'string' &&
    typeof data.email === 'string'
  );
}

const result = validateInput(rawData);

if (isValidUser(result)) {
  // TypeScript knows result.data is User
  saveUser(result.data);
}

---

Assertion Functions

Functions that assert a condition or throw.

Basic Assertion Function

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) {
    throw new Error(message);
  }
}

function processUser(user: User | null): void {
  assert(user !== null, 'User must not be null');
  
  // After assertion, TypeScript knows user is not null
  console.log(user.name);
}

Type Assertion Functions

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== 'string') {
    throw new Error('Value must be a string');
  }
}

function processValue(value: unknown): void {
  assertIsString(value);
  
  // TypeScript knows value is string now
  console.log(value.toUpperCase());
}

Real-World Example

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${value}`);
}

type Status = 'pending' | 'approved' | 'rejected';

function handleStatus(status: Status): void {
  switch (status) {
    case 'pending':
      showPendingUI();
      break;
    case 'approved':
      showApprovedUI();
      break;
    case 'rejected':
      showRejectedUI();
      break;
    default:
      assertNever(status);  // Exhaustiveness check
  }
}

---

Real-World Patterns

1. Form State Management

type FormField = {
  value: string;
  error?: string;
  touched: boolean;
};

interface IdleFormState {
  status: 'idle';
  fields: Record<string, FormField>;
}

interface SubmittingFormState {
  status: 'submitting';
  fields: Record<string, FormField>;
}

interface SuccessFormState {
  status: 'success';
  submittedData: Record<string, string>;
}

interface ErrorFormState {
  status: 'error';
  fields: Record<string, FormField>;
  errorMessage: string;
}

type FormState = IdleFormState | SubmittingFormState | SuccessFormState | ErrorFormState;

function renderForm(state: FormState): string {
  switch (state.status) {
    case 'idle':
      return renderFields(state.fields);
    case 'submitting':
      return renderFields(state.fields) + ' <Spinner />';
    case 'success':
      return `Success! Submitted: ${JSON.stringify(state.submittedData)}`;
    case 'error':
      return renderFields(state.fields) + ` <Error>${state.errorMessage}</Error>`;
  }
}

2. Event Handling

interface ClickEvent {
  type: 'click';
  x: number;
  y: number;
  timestamp: number;
}

interface KeyPressEvent {
  type: 'keypress';
  key: string;
  altKey: boolean;
  ctrlKey: boolean;
  timestamp: number;
}

interface ScrollEvent {
  type: 'scroll';
  scrollTop: number;
  scrollLeft: number;
  timestamp: number;
}

type DomEvent = ClickEvent | KeyPressEvent | ScrollEvent;

function handleEvent(event: DomEvent): void {
  switch (event.type) {
    case 'click':
      console.log(`Clicked at (${event.x}, ${event.y})`);
      break;
    case 'keypress':
      console.log(`Key pressed: ${event.key}`);
      if (event.ctrlKey) {
        console.log('Ctrl was held');
      }
      break;
    case 'scroll':
      console.log(`Scrolled to top: ${event.scrollTop}`);
      break;
  }
}

3. Result Type Pattern

interface Success<T> {
  success: true;
  value: T;
}

interface Failure<E> {
  success: false;
  error: E;
}

type Result<T, E = Error> = Success<T> | Failure<E>;

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return {
      success: false,
      error: 'Division by zero'
    };
  }
  
  return {
    success: true,
    value: a / b
  };
}

const result = divide(10, 2);

if (result.success) {
  console.log(`Result: ${result.value}`);
} else {
  console.error(`Error: ${result.error}`);
}

---

Common Mistakes I Made

1. Not Narrowing Unions

Bad:

function getLength(value: string | string[]): number {
  return value.length;  // Error! What if it's an array of arrays?
}

Good:

function getLength(value: string | string[]): number {
  if (typeof value === 'string') {
    return value.length;
  } else {
    return value.length;  // Array length
  }
}

2. Forgetting Exhaustiveness Checks

Bad:

type Status = 'idle' | 'loading' | 'success' | 'error';

function handle(status: Status): void {
  if (status === 'idle') return;
  if (status === 'loading') return;
  // Forgot 'success' and 'error'!
}

Good:

function handle(status: Status): void {
  switch (status) {
    case 'idle':
      return;
    case 'loading':
      return;
    case 'success':
      return;
    case 'error':
      return;
    default:
      const exhaustive: never = status;
      throw new Error(`Unhandled status: ${exhaustive}`);
  }
}

3. Using Type Assertions Instead of Narrowing

Bad:

function process(value: string | number): void {
  const str = value as string;  // Unsafe!
  console.log(str.toUpperCase());  // Might crash
}

Good:

function process(value: string | number): void {
  if (typeof value === 'string') {
    console.log(value.toUpperCase());  // Safe
  }
}

---

Your Challenge

Build a type-safe state machine for a shopping cart:

// TODO: Define discriminated union for cart states

type CartState = /* Define these states:
  - Empty: { status: 'empty' }
  - WithItems: { status: 'with_items', items: CartItem[], total: number }
  - CheckingOut: { status: 'checking_out', items: CartItem[], total: number }
  - PaymentProcessing: { status: 'payment_processing', orderId: string }
  - Completed: { status: 'completed', orderId: string, confirmationNumber: string }
  - Failed: { status: 'failed', error: string, items: CartItem[] }
*/

interface CartItem {
  productId: string;
  name: string;
  price: number;
  quantity: number;
}

// TODO: Implement these functions with proper type narrowing

function addToCart(state: CartState, item: CartItem): CartState {
  // Add item to cart
}

function removeFromCart(state: CartState, productId: string): CartState {
  // Remove item
}

function checkout(state: CartState): CartState {
  // Start checkout process
}

function processPayment(state: CartState, paymentMethod: string): Promise<CartState> {
  // Process payment
}

function renderCart(state: CartState): string {
  // Render UI based on state - use exhaustiveness checking!
}

// Requirements:
// 1. Use discriminated unions for all states
// 2. Type narrowing in all functions
// 3. Exhaustiveness checking in renderCart
// 4. Type predicates for validation
// 5. No 'any' or type assertions

---

Key Takeaways

1. Union types - value can be one of several types

2. Type narrowing - refine unions to specific types

3. Discriminated unions - common literal property for switching

4. Intersection types - combine multiple types

5. Literal types - exact values as types

6. Type predicates - custom type guards with is

7. Assertion functions - throw or narrow with asserts

8. Exhaustiveness checking - ensure all cases handled

---

What I Learned

The Black Friday payment incident cost us $50,000 in lost revenue. The root cause? A silent failure when handling an unexpected value.

In JavaScript:

if (transaction.type === 'charge') { /* ... */ }
else if (transaction.type === 'refund') { /* ... */ }
// Silently does nothing for other types!

The new 'authorization' type slipped through. No errors. No warnings. Just lost sales.

In TypeScript with discriminated unions:

type TransactionType = 'charge' | 'refund' | 'authorization' | 'void';

switch (transaction.type) {
  case 'charge': /* ... */ break;
  case 'refund': /* ... */ break;
  case 'authorization': /* ... */ break;
  case 'void': /* ... */ break;
  default:
    const exhaustive: never = transaction.type;
    // Compiler error if we missed a case!
}

Add a new transaction type? TypeScript forces you to handle it. No silent failures. No lost revenue.

Union types and exhaustiveness checking turned runtime disasters into compile-time catches.

The $50,000 lesson: Make invalid states unrepresentable. Make unhandled cases impossible.

---

Next: Generics

In the next article, we'll explore TypeScript's generic type system. You'll learn how generics helped me build a type-safe cache that prevented a 12-hour database outage.