TypeScriptの「メソッドオーバーロード」を掌握せよ：型安全とDXを両立する設計の極意
TypeScriptのコードレビューをしていると、`any`の乱用や、冗長なユニオン型の分岐で苦しんでいるコードによく出会う。特に、APIクライアントや複雑なコンポーネントのProps設計において、引数のパターンごとに振る舞いを変えたい場合、多くのエンジニアが「if文による型ガード」で疲弊している。
だが、TypeScriptには「オーバーロード（Function Overloads）」という強力な武器がある。これを正しく使いこなせば、型定義は単なる制約ではなく、開発者を導く強力なドキュメントへと昇華する。
本稿では、インターフェースにおけるメソッドオーバーロードを「ただの機能」から「堅牢な設計パターン」へ引き上げるための知見を共有する。
—
なぜ「ユニオン型」ではなく「オーバーロード」なのか
よくある失敗例を見てみよう。
// 悪い例：実装側にif文が散らかる
interface Repository {
fetch(id: string | number): Promise;
}
この書き方では、`id`が`string`なのか`number`なのかを、呼び出し側で知る術がない。実装側も「とりあえず`any`で受けて`typeof`で分岐」という、TypeScriptの恩恵を自ら捨てるようなコードを書くことになる。
対して、オーバーロードは「型定義」と「実装」を分離する。 これにより、呼び出し側には意図した型のみを提示し、実装側は内部ロジックに集中できる。
—
インターフェースでの正しいメソッドオーバーロード設計
実務において最も頻出する「APIリクエストの抽象化」を例に、美しい設計を見ていく。
interface ApiClient {
// 1. オーバーロードシグネチャ（型定義）
// 呼び出し側に見えるのはこれらのみ。実装は含まない。
request(endpoint: ‘/users’, options: { page: number }): Promise
request(endpoint: ‘/posts’, options: { id: string }): Promise
// 2. 実装シグネチャ（結合型）
// 外部からは直接呼び出せない。内部ロジックのための定義。
request(endpoint: string, options: any): Promise
}
const client: ApiClient = {
async request(endpoint: string, options: any): Promise
// 実装側は、オーバーロードで定義された全ての可能性を包含する型で記述する
const response = await fetch(`${endpoint}?${new URLSearchParams(options)}`);
return response.json();
}
};
// 【利用側】型推論が完璧に機能する
// ここでは第二引数が { page: number } であることが即座に補完される
client.request(‘/users’, { page: 1 });
この設計が持つ「3つの真実」
1. 呼び出しの厳格化: `client.request(‘/users’, { id: ‘1’ })` のような誤った組み合わせは、コンパイル時に即座に弾かれる。
2. 型安全な抽象化: 実装側で`any`を使っているが、外部インターフェースが厳格に守られているため、システム全体としての型安全性は保証されている（カプセル化の原則）。
3. DX（開発体験）の向上: IDEの補完が「どのエンドポイントにどの型が必要か」を教えてくれるため、ドキュメントを見に行く手間が消える。
—
注意点：オーバーロードの「罠」
オーバーロードを多用する際に、必ず心に留めておくべき鉄則が一つある。
「実装シグネチャは、すべてのオーバーロードシグネチャの和集合でなければならない」
もし実装シグネチャを絞りすぎると、TypeScriptの型チェッカーは「実装と定義の不整合」としてエラーを吐く。また、逆に実装シグネチャの引数を広げすぎると、内部で型ガード（`typeof`や`instanceof`）が必要になり、コードが汚れる。
プロのテクニック：
もし内部の分岐が複雑になりすぎるなら、それは「オーバーロードで解決すべき範囲を超えている」というサインだ。その場合は、無理にメソッドをまとめず、`getUser()`や`getPost()`のようにメソッド自体を分割する設計を検討せよ。「まとめること」が必ずしも「美しい設計」ではない。
—
現場で即採用すべき「堅牢なコンポーネント設計」への応用
Reactなどのコンポーネント設計でも、この手法は生きる。例えば、特定のPropsによって戻り値の型が変わるようなUtility関数やフックの設計だ。
interface StorageHandler {
// JSONをパースして返す場合と、そのまま返す場合をオーバーロードで制御
getItem(key: string, parse: true): object | null;
getItem(key: string, parse?: false): string | null;
}
// 呼び出し例
const user = storage.getItem(‘user’, true); // 自動的に object 型として推論
const raw = storage.getItem(‘user’); // string 型として推論
このように、「関数の引数によって戻り値の型が変わる」という複雑なロジックを、オーバーロードを使って「静的な型定義」として表現する。これができれば、君の書くコードはバグの入り込む余地を大幅に減らすことができるだろう。
—
結論：コードは「対話」である
オーバーロードを使いこなすことは、コードを通じた「未来の自分やチームメンバーとの対話」だ。
「この引数を入れたら、この型が返ってくる」。その約束をインターフェースに刻み込むことで、ドキュメントに頼らずとも意図が伝わるコードが生まれる。
TypeScriptの型システムは、単なるバリデーターではない。それは、君が設計するアプリケーションの「骨格」そのものだ。今日から、曖昧なユニオン型を排除し、オーバーロードで明確な契約を定義することから始めてみてほしい。
それが、堅牢なプロダクションコードへの第一歩だ。