【テクニカル・上級編】関数シグネチャにおける「オーバーロード」と「Union型」の設計判断基準 – TypeScript コア・型システムの基礎解析バイブル

関数シグネチャの極限設計：オーバーロードか、Union型か

TypeScriptの型システムは、単なる「静的検査のための注釈」ではない。それはコンパイル時における型レベルのチューリング完全な計算機であり、エディタの補完（IntelliSense）という名のランタイム前心理学を支配するインターフェースである。

シニアエンジニアやプラットフォームアーキテクトが日々直面する設計の分かれ道の一つに、「関数オーバーロード (Function Overloads)」と「Union型の引数/戻り値」の選択がある。
一見すると、どちらも複数の入力パターンを受け入れるための手段に過ぎないように見える。しかし、TypeScriptの型チェッカー（TSServer）の内部動作、コンパイル後のJavaScriptコードの性質、そしてV8エンジン等のJSランタイムにおけるインラインキャッシュ（IC）の最適化まで踏み込んだ時、両者の間には決定的なパラダイムの断絶が存在する。

本稿では、この二つのアプローチをコンパイラの挙動、メモリレイアウト、そしてイベントループの文脈から解体し、真に堅牢な型設計の基準を提示する。

—

1. コンパイラ内部における「オーバーロード」と「Union型」の決定的な違い

TypeScriptのコンパイラがコードを評価する際、オーバーロードとUnion型は全く異なるルートを通る。

Union型：単一の広範な型空間

Union型（例: `A | B`）を採用した場合、関数内部のロジックは「すべての可能性を包含したスーパーセット（和集合）」の型として処理されなければならない。
コンパイラは、関数本体の型チェックにおいて「引数が `A` であるか `B` であるか」を窄めるために、型ガード（`typeof`, `in`, `instanceof`, ユーザー定義型ガード）を強制する。

// Union型アプローチの例
function processValue(val: string | number): string {
// コンパイラはここで val が string か number かを静的に確定させる必要がある
if (typeof val === ‘string’) {
return val.toUpperCase();
}
return val.toFixed(2);
}

このアプローチの美しさは、関数の実装がシンプルになる点にある。しかし、「入力の型と出力の型に厳密な相関関係（コリレーション）がある場合」、Union型は破綻する。
例えば、「stringを渡したら必ずstringが返り、numberを渡したら必ずnumberが返る」という制約をUnion型だけで表現しようとすると、戻り値も `string | number` になり、呼び出し側の型推論が劣化する。

オーバーロード：個別のシグネチャによる多態性

一方、関数オーバーロードは、実装（Implementation）とは別に、「外側からどう見せるか」という複数の契約（Overload Signatures）をコンパイラに登録する手法である。

// オーバーロードアプローチの例
function processValue(val: string): string;
function processValue(val: number): number;
function processValue(val: string | number): string | number {
if (typeof val === ‘string’) {
return val.toUpperCase();
}
return val.toFixed(2);
}

コンパイル時、TSServerは呼び出し元が渡した実引数の型を、上から順のオーバーロードシグネチャと照合（Overload Resolution）する。
これにより、呼び出し元は「引数に `string` を渡せば、戻り値の型は完全に `string` である」という精緻な型情報を、内部の型ガードなしで即座に得る事ができる。

—

2. ケーススタディ：非同期イベントハンドラにおける型設計の極限

より実践的なシナリオとして、非同期メッセージパッシングやイベント駆動アーキテクチャのコアとなる「メッセージ送信関数」を設計してみよう。

ここでは、イベント名（`type`）に応じて、ペイロード（`payload`）の型が厳密に決まるシステムを想定する。

失敗例：ナイーブなUnion型による設計

一見、綺麗に見えるが、型安全性の防壁に穴が空くアンチパターン。

type AppEvent =
| { type: ‘LOGIN’; payload: { token: string } }
| { type: ‘LOGOUT’; payload: undefined }
| { type: ‘FETCH_DATA’; payload: { endpoint: string; timeout: number } };

// Union型をそのまま受け取る設計
function dispatchEvent(event: AppEvent): Promise {
// 実装側で分岐が必要になり、コードベースが肥大化する
// さらに、呼び出し側でオブジェクトの構築ミスを検知しにくい場合がある
return Promise.resolve(true);
}

// 呼び出し側のコード
// 開発者がうっかり間違ったペイロードを渡しても、オブジェクト全体としての型が一致しないエラーになり、
// 「どこが間違っているのか」のコンパイラメッセージが複雑怪奇になる。
dispatchEvent({
type: ‘LOGIN’,
payload: { token: 12345 } // Error: Type ‘number’ is not assignable to type ‘string’.
});

このアプローチの最大の問題は、関数の引数が「1つの大きなオブジェクト（Discriminated Union）」に依存しているため、引数をバラバラに（カリー化や個別引数として）受け取ることが不可能になる点だ。

正解：オーバーロードによる入力の分離と厳密な型束縛

ここで、イベントの `type` と `payload` を引数の分割（2引数）として受け取りつつ、オーバーロードによって型を完璧に束縛する設計に昇華させる。

// — 型定義層 —
interface EventPayloads {
LOGIN: { token: string; rememberMe?: boolean };
LOGOUT: undefined;
FETCH_DATA: { endpoint: string; timeout: number };
}

type EventType = keyof EventPayloads;

// — オーバーロードシグネチャ群 —
// 1. payloadがundefinedのイベント (LOGOUT)
function sendTypedEvent(
type: K,
…args: EventPayloads[K] extends undefined ? [] : [payload: EventPayloads[K]]
): Promise;

// — 実装シグネチャ —
function sendTypedEvent(type: EventType, payload?: any): Promise {
// V8のインラインキャッシュを汚染しないためのプリミティブな処理
const serialized = JSON.stringify({ type, payload, timestamp: performance.now() });

// 非同期イベントループのキュー（Microtask / Task Queue）への効率的なディスパッチを想定
return new Promise((resolve) => {
setTimeout(() => {
// 内部処理
resolve(true);
}, 0);
});
}

// ==========================================
// 呼び出し側の極限のDX（Developer Experience）
// ==========================================

// Case 1: payloadが必要なケース（型補完が完璧に効き、不正な型はコンパイルエラー）
sendTypedEvent(‘LOGIN’, { token: ‘sec_Token_xyz’ });

// Case 2: payloadが不要なケース（第2引数を渡すと即座にコンパイルエラーになる）
sendTypedEvent(‘LOGOUT’);
// sendTypedEvent(‘LOGOUT’, { invalid: true }); // ❌ 引数の数が多すぎるとコンパイルエラー

このオーバーロード設計により、呼び出し側は余計なオブジェクトのリテラル構築から解放され、関数シグネチャレベルで引数の数と型が完全に検証される。

—

3. ランタイムパフォーマンスとV8エンジンの視点

TypeScriptの型はコンパイル時に消去（Type Erasure）されるため、実行時のJavaScriptコードには直接残らない。しかし、「どのように型を設計したか」は、V8などのJSエンジンにおける最適化（JITコンパイル）に間接的な影響を与える。

1. Hidden Classes (Shapes) の安定性
Union型を多用し、動的に異なる構造のオブジェクトを単一の関数に流し込むと、V8のインラインキャッシュ（IC）がメガモルフィック（Megamorphic：多態的）になり、プロパティアクセスの最適化が破綻する。
オーバーロードを用いて、各シグネチャごとの入力パターンを静的に分離・明確化することは、結果として呼び出し側が渡すオブジェクトの形状（Shape）を安定させ、V8のICヒット率を向上させる土壌を作る。

2. イベントループとメモリフットプリント
シニアアーキテクトとして意識すべきは、高頻度で実行されるホットパス（Hot Path）におけるメモリ割り当て（Allocation）である。
上記の `sendTypedEvent` の例では、レストパラメータ（`…args`）と条件付き型タプルを活用することで、不要な中間オブジェクト（ラッパーオブジェクト）の生成を抑制している。これにより、V8のガベージコレクタ（GC）へのプレッシャーを極限まで低減できる。

—

4. どちらを選択すべきかの判定基準（アーキテクトのマトリクス）

実務においてどちらを採用すべきか、以下のマトリクスを絶対的な判断基準としてほしい。

チーフアーキテクトの結論

ドメインモデルのデータ構造（状態そのもの）を表現する場合：`Discriminated Union` を採用せよ。
関数のインターフェース（振る舞い・API）において、入力と出力の型に厳密な相関を持たせたい場合、または引数のオーバーロード構造が異なる場合：迷わず 関数オーバーロード を採用せよ。

型システムは防壁である。曖昧さを許容するUnion型は柔軟性をもたらすが、戦場の最前線（コアロジック）においては、オーバーロードがもたらす厳格な型契約こそが、システムを破滅から守る唯一の盾となる。