TypeScriptの「型広げ（Type Widening）」を完全掌握せよ：推論結果を意図通りに固定するベストプラクティス
コードレビューをしていて、次のようなバグに遭遇したことはないか？
// どこにでもあるような設定オブジェクト
const config = {
theme: “dark”,
retries: 3,
};
// 「よし、次は ‘light’ テーマを代入しよう」
config.theme = “light”; // 💥 エラーにはならない？ いや、なるべきだ！
いや、待ってほしい。もしこの `config` が以下のように定義されていたらどうだろう？
function applyTheme(theme: “dark” | “light”) {
// …
}
applyTheme(config.theme); // 💥 ここで型エラーが発生する！
// 理由: config.theme の型が ‘string’ に広げられているからだ。
TypeScriptを書く上で、私たちが最も頻繁に遭遇し、かつ見落としがちな罠が 「型広げ（Type Widening）」 である。
今回は、この型広げがコンパイラの内部でどのように発生し、なぜ私たちの意図をすり抜けてバグを生むのか、そしてそれをどうコントロールすべきかについて、フロントエンドからバックエンドまでを貫くチーフアーキテクトの視点から徹底的に解説しよう。
—
1. 型広げ（Type Widening）とは何か？ コンパイラの裏側を覗く
TypeScriptのコンパイラ（`tsc`）は、変数を初期化する際、右辺の値からその型を推論する。このとき、「再代入される可能性がある」と判断されたコンテキスト（例: `let` 宣言、ミュータブルなオブジェクトのプロパティ）において、リテラル型を一般的なプリミティブ型へと「拡張（Widening）」する処理が行われる。
これが型広げだ。
let status = “success”;
// コンパイラの評価:
// let なので再代入されると仮定し、
// “success” (リテラル型) -> string (プリミティブ型) へと広げる。
もし、あなたがこの変数を「”success”という値しか持たない定数」として扱いたかった場合、この広げられた `string` 型は、後々タイポや不正な値の混入を許す温床となる。
—
2. 型広げを制御する3つのアプローチとそのコスト
型広げを防ぎ、推論結果を意図通りに固定するには主に3つのアプローチがある。それぞれの特性とコンパイル時の挙動を理解し、適材適所で使い分けなければならない。
アプローチ A: `as const`（Const Assertion）
現在、最も強力でモダンなアプローチが `as const` だ。
const config = {
theme: “dark”,
retries: 3,
} as const;
// 評価される型:
// {
// readonly theme: “dark”;
// readonly retries: 3;
// }
- メリット: 再帰的にすべてのプリミティブがリテラル型になり、かつ `readonly`（イミュータブル）になる。
- ユースケース: 設定オブジェクト、アクション定義、ルーティングのパスなど、変更されるべきではない静的なデータ構造。
アプローチ B: 明示的な型注釈（Type Annotation）
変数を宣言する際に、左辺で型を明示する方法。
type Theme = “dark” | “light”;
let currentTheme: Theme = “dark”;
// currentTheme は常に “dark” または “light” であり、
// 勝手に string に広げられることはない。
- メリット: 再代入を許可しつつ、取りうる値の範囲を厳格に制限できる。
- ユースケース: 状態管理（State）の初期値や、後から値が変わりうる変数。
アプローチ C: ジェネリクス制約による推論のハック（高度）
APIクライアントなどを設計する際、ユーザーが渡したオブジェクトのリテラル型を保持させたい場合に使う。
// ❌ 悪い例: 引数の型が string に広げられてしまう
function registerEndpoint(endpoint: { path: string, method: string }) {}
registerEndpoint({ path: “/api/v1/users”, method: “GET” });
// method は “GET” ではなく string として推論される
// ✅ 良い例: ジェネリクスと extends を使って広げさせない
function registerEndpoint
endpoint: T
) {}
—
3. 【実践】プロダクションコードで使える堅牢な設計パターン
では、実際のフロントエンド・API連携の現場でどのようにこれらを適用すべきか。
「APIから取得したステータスを元に、型安全にUIを制御するモジュール」を例に、美しいプロダクションコードを見ていこう。
/
- 1. ドメインの定数定義
- as const を使い、イミュータブルかつ厳密なリテラル型として固定する
/
export const TASK_STATUS = {
TODO: “TODO”,
IN_PROGRESS: “IN_PROGRESS”,
DONE: “DONE”,
} as const;
// 2. オブジェクトの値からユニオン型を導出する（型広げの恩恵を逆手に取る）
export type TaskStatus = typeof TASK_STATUS[keyof typeof TASK_STATUS];
// 結果: “TODO” | “IN_PROGRESS” | “DONE”
/
- 3. アプリケーション層での利用
/
interface Task {
id: string;
title: string;
status: TaskStatus; // 厳格に縛られた型
}
// モックAPIからのレスポンスをハンドリングする関数
function handleTaskTransition(task: Task, nextStatus: TaskStatus): Task {
// コンパイル時に nextStatus の値が正当なものか完全に保証される
return {
…task,
status: nextStatus,
};
}
// — 使用例 —
const myTask: Task = {
id: “uuid-001”,
chno: 1,
title: “TypeScriptの型広げを極める”,
status: TASK_STATUS.TODO, // 完璧な補完と型安全
};
// 誤った値を渡そうとすると、当然コンパイルエラーになる
// handleTaskTransition(myTask, “INVALID_STATUS”);
// ❌ Argument of type ‘”INVALID_STATUS”‘ is not assignable to parameter of type ‘TaskStatus’.
この設計が優れている理由
1. DRY原則の徹底: 値（Runtime）と型（Type-level）の定義が一箇所に集約されている。`TASK_STATUS` の値を変更すれば、自動的に `TaskStatus` 型も追従する。
2. 型広げの完全な制御: `as const` によって、誤って `TASK_STATUS.TODO` がただの `string` に化けるのを防いでいる。
—
4. パフォーマンス上の注意点：`as const` の濫用は禁物
ここでチーフアーキテクトとして一つ警鐘を鳴らしておきたい。`as const` は強力だが、巨大なJSONデータや、数千行に及ぶ設定ファイルに安易に適用すると、TypeScriptの型チェッカー（TSServer）に深刻な負荷をかける。
- 何が起きるか: すべてのプロパティが個別のリテラル型、かつ `readonly` としてメモリ上にキャッシュされるため、型チェックのメモリ消費量が増大し、エディタの補完（IntelliSense）が重くなる。
- 対策:
- 画面描画に直接関係しない巨大な外部データや、動的に変化するデータには `as const` を使わない。
- 必要な箇所（APIのエンドポイント定義、ステータス定義、UIのバリエーションなど）に絞って適用する。
—
5. まとめ
TypeScriptにおける「型広げ」は、言語のデフォルトの親切心（動的言語から移行してきたプログラマへの配慮）であるが、大規模なモダンフロントエンド開発においては、バグの温床になり得る。
- 変数の再代入が必要なら 「明示的な型注釈」 を使う。
- オブジェクトや配列を定数として完全にロックしたいなら 「as const」 を使う。
- 値から型を導出する際は 「typeof と keyof のコンボ」 を活用する。
この3つを使いこなせるようになれば、あなたの書くTypeScriptコードから「意図しない型の拡大によるバグ」は完全に駆逐されるはずだ。
次のコードレビューでは、同僚の `let` やオブジェクト宣言に潜む「意図せぬ広がり」に目を光らせてみてほしい。