TypeScript Discriminated Unions

Discriminated unions model states safely with TypeScript. Here's how to use them effectively.

Basic Discriminated Union#

// Shape with discriminant property 'kind'
type Circle = {
  kind: 'circle';
  radius: number;
};

type Rectangle = {
  kind: 'rectangle';
  width: number;
  height: number;
};

type Triangle = {
  kind: 'triangle';
  base: number;
  height: number;
};

type Shape = Circle | Rectangle | Triangle;

// Type narrowing with discriminant
function calculateArea(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      // TypeScript knows shape is Circle
      return Math.PI * shape.radius ** 2;
    case 'rectangle':
      // TypeScript knows shape is Rectangle
      return shape.width * shape.height;
    case 'triangle':
      // TypeScript knows shape is Triangle
      return (shape.base * shape.height) / 2;
  }
}

const circle: Circle = { kind: 'circle', radius: 5 };
console.log(calculateArea(circle)); // 78.54

API Response States#

// Loading, success, error states
type LoadingState = {
  status: 'loading';
};

type SuccessState<T> = {
  status: 'success';
  data: T;
};

type ErrorState = {
  status: 'error';
  error: Error;
};

type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;

// Usage in component
function UserProfile({ state }: { state: AsyncState<User> }) {
  switch (state.status) {
    case 'loading':
      return <Spinner />;
    case 'success':
      return <div>{state.data.name}</div>;
    case 'error':
      return <div>Error: {state.error.message}</div>;
  }
}

// Type guard function
function isSuccess<T>(state: AsyncState<T>): state is SuccessState<T> {
  return state.status === 'success';
}

function getData<T>(state: AsyncState<T>): T | null {
  return isSuccess(state) ? state.data : null;
}

Redux Actions#

// Action types with discriminant
type AddTodoAction = {
  type: 'ADD_TODO';
  payload: { id: string; text: string };
};

type ToggleTodoAction = {
  type: 'TOGGLE_TODO';
  payload: { id: string };
};

type DeleteTodoAction = {
  type: 'DELETE_TODO';
  payload: { id: string };
};

type ClearCompletedAction = {
  type: 'CLEAR_COMPLETED';
};

type TodoAction =
  | AddTodoAction
  | ToggleTodoAction
  | DeleteTodoAction
  | ClearCompletedAction;

// Reducer with type narrowing
function todoReducer(state: Todo[], action: TodoAction): Todo[] {
  switch (action.type) {
    case 'ADD_TODO':
      return [
        ...state,
        { id: action.payload.id, text: action.payload.text, completed: false },
      ];
    case 'TOGGLE_TODO':
      return state.map(todo =>
        todo.id === action.payload.id
          ? { ...todo, completed: !todo.completed }
          : todo
      );
    case 'DELETE_TODO':
      return state.filter(todo => todo.id !== action.payload.id);
    case 'CLEAR_COMPLETED':
      return state.filter(todo => !todo.completed);
  }
}

Exhaustive Checking#

// Ensure all cases are handled
function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${value}`);
}

type PaymentMethod =
  | { type: 'card'; cardNumber: string }
  | { type: 'paypal'; email: string }
  | { type: 'crypto'; wallet: string };

function processPayment(method: PaymentMethod) {
  switch (method.type) {
    case 'card':
      return chargeCard(method.cardNumber);
    case 'paypal':
      return chargePaypal(method.email);
    case 'crypto':
      return chargeCrypto(method.wallet);
    default:
      // TypeScript error if case is missing
      return assertNever(method);
  }
}

// Add new type - TypeScript will error at assertNever
type PaymentMethodV2 =
  | { type: 'card'; cardNumber: string }
  | { type: 'paypal'; email: string }
  | { type: 'crypto'; wallet: string }
  | { type: 'bank'; accountNumber: string }; // New type

State Machines#

// Authentication state machine
type AuthState =
  | { status: 'idle' }
  | { status: 'authenticating'; email: string }
  | { status: 'authenticated'; user: User }
  | { status: 'error'; error: string };

type AuthEvent =
  | { type: 'LOGIN'; email: string; password: string }
  | { type: 'LOGIN_SUCCESS'; user: User }
  | { type: 'LOGIN_FAILURE'; error: string }
  | { type: 'LOGOUT' };

function authReducer(state: AuthState, event: AuthEvent): AuthState {
  switch (state.status) {
    case 'idle':
      if (event.type === 'LOGIN') {
        return { status: 'authenticating', email: event.email };
      }
      return state;

    case 'authenticating':
      switch (event.type) {
        case 'LOGIN_SUCCESS':
          return { status: 'authenticated', user: event.user };
        case 'LOGIN_FAILURE':
          return { status: 'error', error: event.error };
        default:
          return state;
      }

    case 'authenticated':
      if (event.type === 'LOGOUT') {
        return { status: 'idle' };
      }
      return state;

    case 'error':
      if (event.type === 'LOGIN') {
        return { status: 'authenticating', email: event.email };
      }
      return state;
  }
}

Form Validation#

type ValidationResult =
  | { valid: true }
  | { valid: false; errors: string[] };

function validateEmail(email: string): ValidationResult {
  if (!email) {
    return { valid: false, errors: ['Email is required'] };
  }
  if (!email.includes('@')) {
    return { valid: false, errors: ['Invalid email format'] };
  }
  return { valid: true };
}

function handleValidation(result: ValidationResult) {
  if (result.valid) {
    console.log('Form is valid');
    // No errors property available here
  } else {
    console.log('Errors:', result.errors);
    // errors is available and typed as string[]
  }
}

HTTP Response Handling#

type HttpResponse<T> =
  | { status: 200; data: T }
  | { status: 201; data: T; location: string }
  | { status: 204 }
  | { status: 400; error: { message: string; field?: string } }
  | { status: 401; error: { message: string } }
  | { status: 404; error: { message: string } }
  | { status: 500; error: { message: string } };

function handleResponse<T>(response: HttpResponse<T>) {
  switch (response.status) {
    case 200:
    case 201:
      return { success: true, data: response.data };
    case 204:
      return { success: true, data: null };
    case 400:
      return {
        success: false,
        error: response.error.message,
        field: response.error.field,
      };
    case 401:
      redirectToLogin();
      return { success: false, error: 'Unauthorized' };
    case 404:
      return { success: false, error: 'Not found' };
    case 500:
      logError(response.error);
      return { success: false, error: 'Server error' };
  }
}

Event Handling#

type MouseEvent = {
  type: 'mouse';
  x: number;
  y: number;
  button: 'left' | 'right' | 'middle';
};

type KeyboardEvent = {
  type: 'keyboard';
  key: string;
  modifiers: {
    ctrl: boolean;
    shift: boolean;
    alt: boolean;
  };
};

type TouchEvent = {
  type: 'touch';
  touches: Array<{ x: number; y: number }>;
};

type InputEvent = MouseEvent | KeyboardEvent | TouchEvent;

function handleInput(event: InputEvent) {
  switch (event.type) {
    case 'mouse':
      console.log(`Mouse ${event.button} at (${event.x}, ${event.y})`);
      break;
    case 'keyboard':
      console.log(`Key ${event.key} pressed`);
      if (event.modifiers.ctrl) console.log('With Ctrl');
      break;
    case 'touch':
      console.log(`${event.touches.length} touch points`);
      break;
  }
}

Nested Discriminated Unions#

type TextNode = {
  type: 'text';
  content: string;
};

type ElementNode = {
  type: 'element';
  tag: string;
  children: ASTNode[];
};

type CommentNode = {
  type: 'comment';
  content: string;
};

type ASTNode = TextNode | ElementNode | CommentNode;

function renderNode(node: ASTNode): string {
  switch (node.type) {
    case 'text':
      return node.content;
    case 'element':
      const children = node.children.map(renderNode).join('');
      return `<${node.tag}>${children}</${node.tag}>`;
    case 'comment':
      return `<!-- ${node.content} -->`;
  }
}

// Recursive rendering
const ast: ElementNode = {
  type: 'element',
  tag: 'div',
  children: [
    { type: 'text', content: 'Hello' },
    {
      type: 'element',
      tag: 'span',
      children: [{ type: 'text', content: 'World' }],
    },
  ],
};

console.log(renderNode(ast)); // <div>Hello<span>World</span></div>

Factory Functions#

// Type-safe factory functions
type NotificationVariant =
  | { type: 'success'; message: string }
  | { type: 'error'; message: string; code: number }
  | { type: 'warning'; message: string }
  | { type: 'info'; message: string; link?: string };

function createNotification(
  type: 'success' | 'warning',
  message: string
): Extract<NotificationVariant, { type: typeof type }>;
function createNotification(
  type: 'error',
  message: string,
  code: number
): Extract<NotificationVariant, { type: 'error' }>;
function createNotification(
  type: 'info',
  message: string,
  link?: string
): Extract<NotificationVariant, { type: 'info' }>;
function createNotification(
  type: string,
  message: string,
  extra?: number | string
): NotificationVariant {
  switch (type) {
    case 'success':
      return { type: 'success', message };
    case 'error':
      return { type: 'error', message, code: extra as number };
    case 'warning':
      return { type: 'warning', message };
    case 'info':
      return { type: 'info', message, link: extra as string | undefined };
    default:
      throw new Error(`Unknown type: ${type}`);
  }
}

const success = createNotification('success', 'Done!');
const error = createNotification('error', 'Failed', 500);

Best Practices#

Design:
✓ Use literal types for discriminant
✓ Name discriminant consistently (type, kind, status)
✓ Keep discriminant at top of type
✓ Use assertNever for exhaustive checks

Type Safety:
✓ Prefer switch over if/else
✓ Create type guards for reuse
✓ Use Extract/Exclude for filtering
✓ Document state transitions

Avoid:
✗ Optional discriminant properties
✗ Non-literal discriminant types
✗ Overlapping discriminant values
✗ Missing exhaustive checks

Discriminated unions model complex states type-safely. Use them for API responses, Redux actions, state machines, and any scenario with multiple variants. The discriminant property enables TypeScript to narrow types automatically in switch statements.