Phantom Types：コンパイラを「厳格な門番」に変える型安全の極致
多くのエンジニアが `interface` と `type` の使い分けについて、「構造的型付けだからどちらでもいい」という結論で思考停止している。だが、TypeScriptの型システムは単なる「型チェックの道具」ではない。コンパイル時のみに存在するメタデータを活用し、実行時のバグを静的に封殺する「設計の言語」だ。
今回は、その最上位に位置するテクニックである「Phantom Types（幽霊型）」について深く掘り下げる。
—
1. なぜ「ただの文字列」でロジックを縛るのか？
実務でよくある `string` 型の乱用を考えてほしい。
`userId: string`, `orderId: string`, `token: string`。これらはすべて `string` として互換性を持ってしまう。`userId` を期待する関数に `orderId` を渡しても、コンパイラは何も警告しない。
Phantom Types は、実行時には何の影響も及ぼさない「タグ」を型に付与することで、この「意味の混同」をコンパイル時に完全に遮断する。
// 実行時のメモリを一切汚染しない「幽霊」
type Tagged
type UserId = Tagged
type OrderId = Tagged
function processOrder(id: OrderId) { / … / }
const uid = ‘user_123’ as UserId;
const oid = ‘order_999’ as OrderId;
processOrder(oid); // OK
processOrder(uid); // Error: Argument of type ‘UserId’ is not assignable to parameter of type ‘OrderId’.
ここでのポイントは、`__brand` プロパティが実行時には存在しても問題ない（あるいは不要なら消去可能）点だ。型システムが「意味論的な境界」を強制するため、テストコードを書く前にバグが消える。
—
2. 実践：Phantom Typesによる状態遷移の厳格制御
Webアプリの非同期処理において、「未ロード」「ロード中」「成功」「失敗」の遷移を `if` 文で管理するのは、複雑化するほど破綻する。これをPhantom Typesで「型レベルのステートマシン」として定義する。
// 状態を示す幽霊たち
interface Idle {}
interface Loading {}
interface Success
// 状態を内包するコンテナ
type AsyncResult
state: State;
value?: T;
error?: Error;
};
// 特定の状態でのみ実行可能な関数を定義
const fetchUser =
const renderData =
console.log(“Rendering:”, result.value);
};
// 使用例
const state = fetchUser
// renderData(state); // Error: Loading型はSuccess型に割り当てられない
この設計により、「データが取得できていないのにレンダリングしようとする」というフロントエンドの典型的なバグが、IDEの赤い波線によって開発中に修正されるようになる。
—
3. パフォーマンスとコンパイルの真実
「型を複雑にするとコンパイルが遅くなるのでは？」という懸念はもっともだ。しかし、Phantom Typesは構造的型付けの枠内で行われる単純な交差型（Intersection Types）の評価に過ぎない。
- 実行時オーバーヘッド: ほぼゼロ。JavaScriptに変換される際、型情報（ブランド）は消滅する。
- コンパイル速度: 型の再帰計算や条件付き型（Conditional Types）の深すぎるネストに比べれば、非常に軽量だ。
むしろ、実行時に「このIDは正しい形式か？」を検証するランタイムチェックの回数を大幅に減らせるため、トータルでのパフォーマンスは向上する。
—
4. プロダクションコードへの導入戦略
いきなり全コードに適用する必要はない。まずは以下の「境界線」に導入せよ。
1. 外部APIとの境界: `JSON.parse` の直後で `as` キャストを行い、Phantom Typeへ変換する。そこから先は「型安全な世界」として振る舞う。
2. ドメインモデル: ユーザーID、トランザクションIDなど、システム内で一意性が保証されるべき識別子。
3. UIの状態管理: ステップバイステップのフォームや、複雑な非同期フロー。
結論：型は「ドキュメント」ではなく「契約」である
多くの開発者が書く `interface` は、ただのデータの「形」を説明するカタログに過ぎない。しかし、Phantom Typesを使いこなす者は、「そのデータがどの状態にあり、何ができるのか」という契約をコンパイラに刻み込む。
型安全とは、単に `any` を避けることではない。「間違ったコードが書けない状況を、型レベルで設計すること」だ。
明日のコードレビューで、誰かの書いた `string` を `UserId` に変えてみてほしい。その瞬間、君のチームのコードベースは、一歩だけ「堅牢な城」に近づくはずだ。