関数オーバーロード vs Union型：コンパイラ挙動から見極めるAPI設計の境界線
TypeScriptの型システムは、その表現力の高さゆえに「どう書くか」の自由度が異常に高い。しかし、シニアエンジニアの責務は、動くコードを書くことではなく、「3年後のチームメンバーが改修で絶望しないための型構造（API Boundary）を定義すること」にある。
特に、入力値に応じて出力の型が厳密に変化する関数を設計する際、多くの開発者が直面するのが以下の二者択一だ。
1. 関数オーバーロード (Function Overloads)
2. 引数・戻り値のUnion型 (Union Types)
ネット上の入門記事では「オーバーロードは複雑だからUnion型にしよう」といった表層的な議論に終始しがちだが、コンパイラの型推論メカニズム、V8エンジン上の実行時挙動、そして大規模コードベースにおける保守性の観点から見れば、この二者の境界線は極めて明確に引かれている。
本稿では、TypeScriptコアの型評価アルゴリズムとランタイムの現実を踏まえ、この究極の選択に対する決定版の指針を提示する。
—
1. コンパイラ視点：型推論とホモモルフィックな評価のコスト
まず、TypeScriptコンパイラ（tsc）がこれらをどう処理しているか、その内部構造を理解する必要がある。
関数オーバーロードの内部メカニズム
オーバーロードは、コンパイラに対して「この関数には複数のシグネチャが存在し、上から順にマッチングを試みよ」と命令する手続き的な宣言である。
コンパイラは呼び出し側（Call Site）に遭遇すると、定義されたオーバーロードシグネチャを順番に走査し、最初に引数の型が割り当て可能（Assignable）になったシグネチャを採用する。
- メリット: 入力と出力の間に「1対1の厳密な相関関係（Dependent Types的な挙動）」を強制できる。
- デメリット: オーバーロードの数が増えるほど、コンパイラの型チェックフェーズにおけるAST（抽象構文木）の照合コストが増大し、大規模プロジェクトでの型推論（TSServer）のパフォーマンスを悪化させる。
Union型の内部メカニズム
引数や戻り値にUnion型を採用する場合、それは「直積集合（Cartesian Product）」ではなく「直和集合（Sum Types）」として評価される。
関数内部のロジックでは、型ガード（Type Guards: `typeof`, `in`, `instanceof`, ユーザー定義型ガード）を用いて、ランタイムの安全性担保とコンパイル時の絞り込み（Narrowing）を明示的に行う必要がある。
—
2. 実践的シナリオ：非同期イベントハンドラの設計における衝突
非同期処理やイベント駆動アーキテクチャにおいて、リクエストの型によってレスポンスの型が完全に分岐するAPIを設計するとしよう。ここでは、`fetchData` という汎用関数の設計を例に取る。
アプローチA：Union型による実装（脆弱な拡張性）
type FetchPayload =
| { type: ‘user’; id: string }
| { type: ‘metrics’; range: ’24h’ | ‘7d’ }
| { type: ‘audit’; limit: number; offset: number };
type FetchResponse
T extends ‘user’ ? { name: string; email: string } :
T extends ‘metrics’ ? { qps: number; latency: number } :
T extends ‘audit’ ? { logs: string[]; total: number } : never;
// Union型をそのまま受け取る関数設計
declare function fetchWithUnion
payload: FetchPayload
): Promise
この設計の何が問題か？ コンパイラは `payload` 全体のUnion型と、ジェネリック型 `T` の関連性を完璧に追うことができず、呼び出し側で以下のような型エラーやキャスト地獄を引き起こす。
// ❌ コンパイルエラーまたは意図しない型緩慢が発生しやすい
const res = await fetchWithUnion({ type: ‘user’, id: ‘123’ });
// res の型がすべての FetchResponse の Union になり、プロパティアクセスにガードが必須になる
アプローチB：関数オーバーロードによる実装（堅牢な型境界）
同一の関数名に対し、入力と出力のペアを完全に静的に結びつけるのがオーバーロードの真骨頂である。
// — シグネチャの定義（厳密な相関関係の構築） —
function fetchResource(payload: { type: ‘user’; id: string }): Promise<{ name: string; email: string }>;
function fetchResource(payload: { type: ‘metrics’; range: ’24h’ | ‘7d’ }): Promise<{ qps: number; latency: number }>;
function fetchResource(payload: { type: ‘audit’; limit: number; offset: number }): Promise<{ logs: string[]; total: number }>;
// — 実装シグネチャ（ランタイムの単一エントリポイント） —
async function fetchResource(
payload: FetchPayload
): Promise
// イベントループのキュー消費、ネットワークI/Oのモックなど
switch (payload.type) {
會 case ‘user’:
return { name: ‘Architect’, email: ‘core@ts.org’ };
case ‘metrics’:
return { qps: 10420, latency: 1.2 };
case ‘audit’:
return { logs: [‘SYS_INIT’, ‘AUTH_OK’], total: 2 };
default:
const _exhaustive: never = payload;
throw new Error(`Unrecognized payload type: ${_exhaustive}`);
}
}
// 🎯 呼び出し側：完全な型推論と補完がノーガードで実現する
const userResult = await fetchResource({ type: ‘user’, id: ‘uuid-999’ });
// userResult の型は自動的に { name: string; email: string; } に確定する
このアプローチでは、実装シグネチャ（Implementation Signature）は外部から隠蔽され、ユーザーは安全に定義されたオーバーロードシグネチャ群のみと対話する。
—
3. 保守性・拡張性の境界線：どちらを選ぶべきか？
大規模システムアーキテクチャの現場において、両者を使い分けるための絶対的な判断基準を以下に定義する。
| 評価軸 | 関数オーバーロード (Overloads) | Union型 (Union Types) |
| :— | :— | :— |
| 入力・出力の連動性 | 極めて高い（入力Aなら出力Aを完全に固定できる） | 低〜中（条件付き型を組み合わせる必要があり複雑化する） |
| 将来の機能拡張 (Open-Closed原則) | 要改修（新しい型を追加するたびにシグネチャの追記が必要） | 高（Payload側のUnion型に新しい型を追加するだけで拡張可能） |
| IDEの補完・DX | 最高峰（引数を打った瞬間に対応する戻り値が確定） | 中程度（エラーメッセージが複雑なUnionになりがち） |
| コンパイラ負荷 | 中〜高（シグネチャの数に比例してマッチングコスト増） | 低（集合演算として高速に処理される） |
境界線の結論
1. 「入力の形によって、返り値の構造が根本からガラリと変わる（かつ網羅性が静的に保証されるべき）」場合
👉 関数オーバーロードを採用せよ。APIクライアント、ビルダーパターン、ファクトリー関数などがこれに該当する。開発体験（DX）と呼び出し側の安全性が圧倒的に向上する。
2. 「データ構造そのものがドメインモデルとして定義されており、関数はそれを受け取って多態的に処理するだけ」の場合
👉 Union型を採用せよ。Reducerのディスパッチ関数、イベントリスナー、DOMのイベント処理などがこれに該当する。拡張性（Open-Closed Principle）が担保され、新しいデータ型を追加する際に既存のシグネチャを汚染せずに済む。
—
4. チーフアーキテクトからの警鐘
TypeScriptの型システムは強力だが、「型で複雑なパズルを解くこと」と「保守性の高いコードを書くこと」は同義ではない。
過剰な条件付き型（Conditional Types）や、何重にもネストしたオーバーロードは、コンパイル時間の肥大化を招き、エラーメッセージを解読不能なモンスターへと変貌させる。
APIを設計する際は、ランタイムのデータフローとメモリ上の実体を常に脳内に描きながら、「コンパイラに何を強制し、人間（開発者）に何を解放するか」のバランスをコントロールし続けなければならない。
型は単なるドキュメントではない。それはアプリケーションの信頼性を担保する最後の防壁である。設計の意図を正確に型に宿し、破られざる要塞を構築せよ。