TypeScriptのオーバーロードは「型安全の守護神」か、それとも「設計の敗北」か
フロントエンドの現場で、コンポーネントのPropsやAPIクライアントの型定義を書いているとき、こんなコードに出会ったことはないだろうか？
// 悪い例：ユニオン型で無理やり吸収する
function fetchData(idOrQuery: string | { query: string }): Promise
if (typeof idOrQuery === ‘string’) {
// …
}
// …
}
この実装はTypeScriptの柔軟性を活かしているようで、実は「型システムの破壊」を招いている。呼び出し側は `idOrQuery` が何であるかを推論できず、結果として `if` 文や `as` による型アサーションの山が生まれる。
関数オーバーロードは、単なる記述のバリエーションではない。型レベルで「呼び出し側の意図」をコンパイラに正確に伝えるための、極めて高度なコミュニケーションツールだ。
本稿では、コードレビューで即座に「採用」と言わせるための、堅牢かつ美しいオーバーロードの極意を伝授する。
—
1. オーバーロードの核心：実装シグネチャは「隠蔽」せよ
まず心に刻んでほしいのは、「実装シグネチャは外部に公開されない」という事実だ。
TypeScriptのオーバーロードは、宣言部と実装部が分かれる。IDEが補完で表示するのはあくまで「宣言部」であり、実装部はその全てのパターンを安全に処理する「受け皿」でしかない。
ベストプラクティス：APIクライアントの設計
例えば、ID指定か検索クエリ指定かで戻り値の型が変わる設計を見てみよう。
type User = { id: string; name: string };
// 1. 宣言部：呼び出し側が見る「契約」
function fetchUser(id: string): Promise
function fetchUser(query: { q: string }): Promise
// 2. 実装部：内部の「処理」
// 「any」を使って型安全を崩すのではなく、内部で安全に分岐させる
function fetchUser(arg: string | { q: string }): Promise
if (typeof arg === ‘string’) {
return fetch(`/api/users/${arg}`).then(res => res.json());
}
return fetch(`/api/search?q=${arg.q}`).then(res => res.json());
}
ここがポイント:
- 実装部の引数は、宣言部の和集合（Union Type）で定義する。
- 戻り値も同様に和集合で定義するが、呼び出し側には宣言部の型が適用されるため、利用者は型安全を享受できる。
- 実装部の戻り値の型を `any` に逃げず、Unionで明示することで、内部リファクタリング時の型チェックが機能する。
—
2. 陥りやすい罠：オーバーロードの「順序」が命
TypeScriptのオーバーロード解決は、宣言順に上からマッチングを試みる。
これが理解できていないと、コンパイラは一生正しいシグネチャを推論してくれない。
// 間違い：汎用的な型を上に書いてしまうと、特殊な型が無視される
function process(arg: string): void; // 特殊ケース
function process(arg: any): void; // 汎用ケース
// もし `process(any)` を上に書くと、
// コンパイラは全ての入力を「any」として解釈し、最初の宣言が死ぬ。
鉄則：より具体的（狭い）な型を上に、より抽象的（広い）な型を下に書く。
—
3. 実務で「オーバーロード」を避けるべきタイミング
「何でもかんでもオーバーロード」は、コンパイラのパフォーマンスを低下させ、コードの可読性を損なう。以下の場合は、オーバーロードではなく「ユニオン型によるDiscriminated Union（判別可能なユニオン型）」を検討すべきだ。
1. 関数の責務が単一である場合:
もし引数が変わっても戻り値の型が変わらないなら、ただのユニオン型で十分だ。
2. 型定義が肥大化しすぎる場合:
オーバーロードの宣言が5つを超えたら、その関数は「役割を混同している」。関数を分割すべきだ。
3. コンポーネントのProps:
ReactのPropsであれば、ジェネリクスや条件付き型（Conditional Types）を活用する方が、JSXとの親和性が高い。
—
結論：コードの品格を上げるために
オーバーロードを使いこなすことは、「その関数がどう使われることを望んでいるか」という設計思想をコンパイラを通じてドキュメント化することに等しい。
綺麗なコードは、呼び出し側に対して「何を渡すべきか」「何が返ってくるか」を一切の迷いなく伝える。型システムを単なるエラーチェッカーとしてではなく、設計を具現化する言語として使い倒してほしい。
今日のレビューで、`any` を使った無理やりな関数を見つけたら、まずはこの「宣言と実装の分離」を提案してみよう。それが、あなたのチームのプロダクションコードを一段上のレベルへ引き上げるはずだ。
—
執筆後記:
TypeScriptの型システムは、パズルのように見えて実は論理学の結晶だ。オーバーロードは一見すると古いC++やJavaの遺物のように見えるかもしれないが、TypeScriptにおいては「コンパイラの推論エンジンを制御する最強のスイッチ」として機能する。この感覚を掴めれば、もう君はただのエンジニアではない。アーキテクトだ。