【実務・中級編】Type Aliasで実現する「条件付き型」によるAPIレスポンスの動的変換 – TypeScript コア・型システムの基礎解析バイブル

型は「ドキュメント」ではなく「契約」である：Conditional TypesによるAPIレスポンスの静的安全性

TypeScriptを単なる「JavaScriptに型を付ける道具」だと思っているなら、今すぐその認識を改めるべきだ。コンパイラにとって、型定義とは実行時の挙動を制限する「契約（Contract）」そのものだ。

特に、外部APIと対峙するフロントエンドにおいて、レスポンスの構造がフラグひとつで変わるような「不整合なAPI」を扱うとき、多くのエンジニアは安易に `any` を使ったり、巨大でスカスカな `interface` を作ってごまかす。だが、それは技術的な敗北だ。

今回は、Conditional Types（条件付き型）を駆使し、APIのレスポンス形状を型レベルで完全に掌握する、実務直結の設計パターンを伝授する。

—

1. なぜ「雑な型定義」がバグを生むのか

例えば、以下のようなAPIを考えてみよう。`status` フラグによって `data` の中身が変わる典型的なパターンだ。

// よくある「ダメな」型定義
interface ApiResponse {
status: ‘success’ | ‘error’;
data?: any; // ここでanyを使うのは思考停止の証拠
message?: string;
}

この定義では、`status === ‘success’` であることをコード側でチェックしても、`data` が存在するかどうかをTSは保証できない。結果として、開発者は不要な `if` 文や `as` キャストを連発することになる。これは保守性の崩壊を招く。

—

2. 解決策：Conditional Typesによる「判別可能な共用体」の動的生成

Conditional Typesは、型計算機としてのTypeScriptの真骨頂だ。これを使えば、APIの構造を「型の関係性」として定義できる。

実装例：型安全なレスポンスハンドラ

// 成功時と失敗時の構造を明確に分離する
type SuccessResponse = {
status: ‘success’;
data: T;
};

type ErrorResponse = {
status: ‘error’;
message: string;
};

// これがConditional Typesの神髄
// Tがどのステータスかによって型を自動的に絞り込む
type ApiResponse = S extends ‘success’
? SuccessResponse
: ErrorResponse;

// 使用例：APIクライアントの型
async function fetchUser(
status: S
): Promise> {
// 実際の実装は省略。戻り値の型がstatusに応じて動的に解決される
return {} as any;
}