TypeScriptの判別可能なユニオン（Discriminated Unions）を実務で使いこなすための型設計術

2026年5月29日

設計・アーキテクチャ

TypeScriptを用いたモダンなフロントエンド・バックエンド開発において、型の安全性とコードの可読性を両立させることは最優先の課題です。

特に複雑なビジネスロジックや非同期処理の状態管理を扱う際、開発者を強力にサポートしてくれる機能が判別可能なユニオン（Discriminated Unions）です。

この機能は、タグ付きユニオン（Tagged Unions）や代数的データ型（ADT）とも呼ばれ、TypeScriptの型システムの中でも最も実用性が高く、かつ洗練された概念の一つです。

2026年現在の開発現場においても、大規模プロジェクトでバグを未然に防ぎ、チーム全体の開発効率を最大化するために不可欠な技術となっています。

本記事では、この判別可能なユニオンの基礎から、実務で即座に役立つ高度な型設計術までを詳しく解説します。

目次 [ close ]

判別可能なユニオンの基本構造と3つの要素

判別可能なユニオンとは、複数の型を統合しつつ、特定のプロパティ（タグ）を利用して型を絞り込む仕組みのことです。

このパターンを成立させるためには、「共通の文字列リテラル型プロパティ」を持つ複数のオブジェクト型が必要になります。

具体的には、以下の3つの要素が組み合わさることで機能します。

1. 判別子となる共通プロパティ（タグ）

それぞれの型が、同じ名前のプロパティを保持している必要があります。

このプロパティの値は、'success' や 'error' といった文字列リテラル型で定義されることが一般的です。

2. ユニオン型の定義

これら複数の型を | （パイプ）で結合し、一つのユニオン型として定義します。

3. 型の絞り込み（Type Narrowing）

if 文や switch 文を使用して共通プロパティの値をチェックすることで、TypeScriptコンパイラに「現在はどの型であるか」を正しく認識させます。

実務での活用例：APIレスポンスの型定義

最も頻繁に利用されるシーンの一つが、サーバーからのAPIレスポンスのハンドリングです。

成功時と失敗時でデータ構造が異なる場合、判別可能なユニオンを使用しないと、プロパティの存在確認が煩雑になり、ランタイムエラーのリスクが高まります。

以下のコードは、標準的なAPIレスポンスを表現した例です。

TypeScript

/**
 * APIレスポンスを表現する判別可能なユニオン型
 */
type ApiResponse<T> = 
  | { status: 'loading' }
  | { status: 'success'; data: T; timestamp: number }
  | { status: 'error'; message: string; code: number };

function handleResponse(response: ApiResponse<string>) {
  // statusプロパティによって型が自動的に絞り込まれる
  switch (response.status) {
    case 'loading':
      console.log('データを読み込み中です...');
      break;
    case 'success':
      // ここでは response.data にアクセス可能
      console.log(`取得データ: ${response.data} (取得時刻: ${response.timestamp})`);
      break;
    case 'error':
      // ここでは response.message にアクセス可能
      console.error(`エラー発生 [${response.code}]: ${response.message}`);
      break;
  }
}

この設計の優れた点は、status が 'success' のブロック内では response.message にアクセスしようとするとコンパイルエラーが発生することです。

これにより、「データが存在しないのにデータにアクセスしてしまう」といった初歩的なミスを、IDE上の静的解析の時点で完全に防ぐことができます。

網羅性チェック（Exhaustiveness Check）による型安全性の最大化

判別可能なユニオンの真価を発揮させるテクニックとして、網羅性チェックが挙げられます。

これは、ユニオン型に含まれるすべてのケースが switch 文などで適切に処理されているかをコンパイラに検証させる手法です。

将来的に新しい状態（例えば 'maintenance' など）が追加された際、既存のコードで修正漏れがあれば即座にビルドエラーとして検知できます。

never型を利用した網羅性チェックの実装

以下の手法は、実務の現場でほぼ必須と言えるパターンです。

TypeScript

function assertNever(x: never): never {
  throw new Error(`予期しない値が渡されました: ${x}`);
}

function processResponse(response: ApiResponse<string>) {
  switch (response.status) {
    case 'loading':
      return '読み込み中';
    case 'success':
      return response.data;
    case 'error':
      return 'エラー';
    default:
      // もし ApiResponse に新しい型が追加されると、
      // ここで型エラーが発生し、修正の必要性を教えてくれる
      return assertNever(response);
  }
}

このように default 句で never 型に代入しようとすることで、「すべての分岐を網羅しているか」を静的に保証できます。

仕様変更が多いプロジェクトにおいて、このチェック機構があるだけでリファクタリングの心理的負荷は大幅に軽減されます。

柔軟な型設計のための「タグ」の命名規則と設計思想

判別可能なユニオンを設計する際、タグとして使用するプロパティ名に悩むことがありますが、一般的には type、status、kind といった名称が好まれます。

重要なのは、プロジェクト全体で一貫した命名規則を持つことです。

また、タグの値は単なる文字列ではなく、その型が何を表現しているのかを直感的に理解できる単語を選ぶべきです。

複雑なネスト構造への対応

時には、一つの判別可能なユニオンの中に、さらに別のユニオンが含まれるような複雑な構造が必要になる場合があります。

そのような場合でも、各階層で適切にタグを設定することで、型安全性を維持したまま深いプロパティへのアクセスが可能になります。

設計パターン	メリット	適したシーン
フラットなユニオン	理解が容易でシンプル	状態の種類が数個程度のUIコンポーネント
ネストされたユニオン	責任範囲が明確に分離される	大規模なドメインモデルや複雑なフォーム
ジェネリクスとの併用	再利用性が極めて高い	共通のAPIクライアントやライブラリ開発

アンチパターンの回避：オプショナルプロパティの乱用に注意

初心者が陥りやすいミスとして、すべてのプロパティを一つの型にまとめ、それらをオプショナル（?）にする設計があります。

これは「判別可能なユニオン」とは対極にあるアプローチであり、型安全性を著しく損なわせます。

TypeScript

// アンチパターン：何が含まれているか不明確
type BadResponse = {
  status: 'loading' | 'success' | 'error';
  data?: string;
  error?: string;
};

この定義では、status が 'success' なのに data が undefined である、という矛盾した状態を許容してしまいます。

「その状態の時に必ず存在するデータは何か」を突き詰め、矛盾した状態を型レベルで作成不能にすること（Make Illegal States Unrepresentable）が、優れた型設計の極意です。

ReduxやuseReducerとの相性

現代のReact開発においても、判別可能なユニオンは不可欠な存在です。

特に useReducer を使用する際の Action 型の定義では、判別可能なユニオンが標準的に利用されています。

TypeScript

type Action =
  | { type: 'SET_USER'; payload: { name: string } }
  | { type: 'LOGOUT' }
  | { type: 'INCREMENT_COUNTER'; step: number };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'SET_USER':
      // action.payload に安全にアクセス可能
      return { ...state, user: action.payload.name };
    case 'LOGOUT':
      return { ...state, user: null };
    case 'INCREMENT_COUNTER':
      // action.step に安全にアクセス可能
      return { ...state, count: state.count + action.step };
  }
}

このようにアクションごとに異なるペイロードの構造を厳密に定義することで、ディスパッチ側のミスも即座に発見できるようになります。

ユーザー定義ガードとの組み合わせ

関数の外部から受け取ったデータが判別可能なユニオンに適合しているかを確認するために、ユーザー定義型ガード（Type Predicates）を併用するケースも多いです。

is キーワードを用いることで、複雑な判定ロジックを関数化し、再利用性を高めることができます。

TypeScript

function isSuccessResponse(response: ApiResponse<any>): response is { status: 'success'; data: any; timestamp: number } {
  return response.status === 'success';
}

これにより、大規模なアプリケーションでもロジックを分散させることなく、一貫した型チェックを適用することが可能となります。

まとめ

TypeScriptの判別可能なユニオンは、単なる機能の一つではなく、堅牢なアプリケーションを構築するための「思考のフレームワーク」でもあります。

共通のタグを用いて型を排他的に扱うことで、コードの意図が明確になり、実行時エラーの可能性を劇的に低減させることができます。

実務においては、単にユニオン型を定義するだけでなく、網羅性チェックを組み合わせることで、将来の変更にも耐えうる柔軟なコードベースを維持しましょう。

もし、現在のプロジェクトで if (data.prop !== undefined) のような場当たり的なチェックが散見されるのであれば、本記事で紹介した判別可能なユニオンへの置き換えを検討してみてください。

型を味方につけることで、エンジニアとしての設計能力は飛躍的に向上し、結果としてユーザーに信頼される高品質なプロダクトを届けることができるはずです。