TypeScriptの型システムは、単なる「静的検査のための道具」ではない。適切に設計された型は、それ自体がドキュメントであり、将来のバグをコンパイルエラーとして未然に防ぐ最強のガードレールだ。
コードレビューをしていて最も絶望的な光景の一つが、コンポーネントのプロパティやAPIのペイロード定義において、無数のプリミティブなリテラル型やユニオン型がインラインで乱雑に記述されている状態だ。
// ❌ 最悪なアンチパターン：何の意味も持たない「型の呪物」
function handleRequest(status: “success” | “error” | “loading” | “idle”, theme: “light” | “dark” | “system”, role: “admin” | “editor” | “viewer”) { … }
これを見た瞬間、私はこう問いかける。
「おい、この `status` と `theme` と `role` のユニオン型、もし将来仕様変更で値が増えたら、コードベース全体をgrepして修正地獄に落ちる覚悟はあるのか？」と。
今回は、プリミティブなリテラル集合が爆発しがちな現代のフロントエンド開発およびAPI連携において、「型エイリアスをどう命名し、どう構造化すれば、保守性と拡張性が劇的に跳ね上がるのか」を、コンパイラの型評価の挙動まで踏み込んで叩き込む。
—
1. プリミティブ集合の「意味論（Semantics）」による分離
多くのプログラマブルな設計ミスは、「プリミティブの値（Value）」そのものを型として扱おうとするところから始まる。しかし、TypeScriptにおける型とは「集合（Set）」である。
例えば、UIの状態、テーマ、権限を扱うアプリケーションを考えてみよう。これらをすべて一つの巨大なユニオン型にしたり、その都度インラインで書いたりするのは悪手だ。まずは「ドメインの概念」ごとに型エイリアスを切り出す。
ここで重要なのは、「何ができるか（構造）」ではなく、「ドメイン上で何を意味するか（名前）」で型を定義することだ。
悪い例：プリミティブの裸足の群れ
// 型の意図がコードから消え、ただの文字列の羅列になっている
type ButtonProps = {
variant: “primary” | “secondary” | “danger” | “ghost”;
size: “sm” | “md” | “lg” | “xl”;
state: “idle” | “loading” | “success” | “error”;
};
このコードの問題点は、`variant` や `size` が単なる「文字列の選択肢」として扱われている点だ。もしデザインシステムが拡張され、「ローディング中のバリエーション」や「レスポンシブなサイズ」を導入した瞬間、この型は破綻する。
良い例：ドメイン駆動型エイリアスと「公称型（Nominal-ish）」的アプローチ
TypeScriptの構造的型付け（Structural Subtyping）の特性を理解しつつ、意図を明確にする構造化を行おう。
/
- — デザインシステム・ドメイン基底型 —
/
// 1. カラー・バリエーションの原初集合
export const BUTTON_VARIANTS = [“primary”, “secondary”, “danger”, “ghost”, “link”] as const;
export type ButtonVariant = typeof BUTTON_VARIANTS[number];
// 2. サイズ体系の原初集合（スケール）
export const SPACING_SCALES = [“xs”, “sm”, “md”, “lg”, “xl”, “2xl”] as const;
export type SpacingScale = typeof SPACING_SCALES[number];
// 3. 非同期ライフサイクル状態の集合
export const ASYNC_STATUSES = [“idle”, “pending”, “resolved”, “rejected”] as const;
export type AsyncStatus = typeof ASYNC_STATUSES[number];
ここで `as const` を使い、配列から `typeof … [number]` で型を抽出している点に注目してほしい。
実務において、「値のリスト（配列）」と「型の定義」が乖離するバグは極めて多い。コンポーネント内でセレクトボックスの選択肢を描画する際、配列が必要になるが、その配列の型を手動で管理するのは保守性の観点から「罪」に近い。この手法であれば、値と型が完全に同期し、DRY原則が型レベルで担保される。
—
2. 複雑なプリミティブ集合の構造化：Omit / Pick / Template Literal Types の活用
実務では、単なる文字列の列挙だけでなく、APIレスポンスのステータスコードや、権限のスコープ（例: `read:users`, `write:posts`）のように、規則性を持った複雑なプリミティブ集合を扱うことが多い。
ここでテンプレートリテラル型（Template Literal Types）とマッピング型を駆使して、メンテナンス性の高い構造を作り上げる。
プロダクションコード例：権限管理システムにおけるドメイン型設計
以下のコードは、バックエンドのRBAC（ロールベースアクセス制御）と完全に同期させた、フロントエンド側の堅牢な型設計の実例である。
/
- リソースとアクションのプリミティブ定義
/
type DomainResource = “user” | “post” | “comment” | “billing”;
type DomainAction = “create” | “read” | “update” | “delete” | “approve”;
/
- 【高度な型エイリアス】
- リソースとアクションを掛け合わせた「粒度の細かい権限スコープ」を自動生成。
- 例: “user:create” | “user:read” | …
/
export type PermissionScope = `${DomainResource}:${DomainAction}`;
/
- ロール定義の集合
/
export type UserRole = “SuperAdmin” | “OrganizationAdmin” | “Editor” | “Guest”;
/
- ロールごとの権限マッピングを強制する型定義
- Mapped Types と Template Literal Types の融合
/
export type RolePermissions = {
readonly [K in UserRole]: ReadonlyArray
};
// — 実装例 —
export const ROLE_POLICY: RolePermissions = {
SuperAdmin: [“”], // すべての権限を持つ
OrganizationAdmin: [
“user:create”,
“user:read”,
“user:update”,
“user:delete”,
“post:approve”,
],
Editor: [“post:create”, “post:read”, “post:update”, “comment:read”, “comment:delete”],
Guest: [“post:read”, “comment:read”],
} as const;
/
- 型安全な権限チェック関数の実装
- コンパイル時に不正な権限文字列を完全に排除する
/
export function hasPermission(
role: UserRole,
requiredPermission: PermissionScope
): boolean {
const permissions = ROLE_POLICY[role];
// スーパーアドミンの全権限ワイルドカードを型安全にハンドリング
if (permissions.includes(“”)) {
return true;
}
// 配列の要素型が厳密に推論されているため、型安全に比較可能
return (permissions as readonly string[]).includes(requiredPermission);
}
// 使い方（IDEの補完が完璧に効き、タイポはコンパイルエラーになる）
const canDelete = hasPermission(“Editor”, “user:delete”);
// ❌ ざんねん！ “user:delete” は Editor に許可されていない、かつ
// もし存在しない文字列 “user:execute” を渡せば、即座にコンパイルエラー。
この設計が優れている理由（アーキテクチャ的視点）
1. 爆発するユニオンの自動生成
`DomainResource` と `DomainAction` がそれぞれ増えた際、`PermissionScope` 型は自動的にその直積（組合せ）を計算する。手動で文字列型を列挙する必要は一切ない。
2. イミュータビリティの徹底
`as const` と `readonly` 修飾子の組み合わせにより、ランタイムでの意図しないミューテーションを型レベルで封じ込めている。これにより、V8エンジンでのオブジェクトの最適化（Hidden Classの安定化）にも寄与する。
—
3. パフォーマンス上の注意点：型評価のコストと「肥大化」の罠
シニアエンジニアとして、型システムにおける「パフォーマンス」についても言及しておかなければならない。
TypeScriptの型チェッカー（tsc / TSServer）は、複雑なユニオン型や巨大なテンプレートリテラル型を評価する際、メモリとCPUを大量に消費する。
⚠️ 避けるべき「型の組合せ爆発」
以下のようなコードを書いた瞬間、IDEの補完が重くなり、CIでのビルド時間が跳ね上がる。
// ❌ 危険：数千・数万のユニオン型を無限に生成するアンチパターン
type Prefix = “get” | “post” | “put” | “delete”;
type Entity = “User” | “Post” | “Comment” | “Tag” | “Category” | “Like” | “Follow” | “Setting”;
type Version = “v1” | “v2” | “v3”;
// これらを無計画に掛け合わせると、コンパイラの計算量が爆発する
type MassiveEndpoint = `${Prefix}_${Entity}_${Version}`;
もしこのような広大な文字列集合を扱う必要がある場合は、すべての組合せをテンプレートリテラルで静的に展開するのではなく、ジェネリクスを活用して「必要な文脈で動的に推論・制限する」アプローチに切り替えるべきだ。
// ⭕️ 推奨：必要な部分だけを制限するジェネリックなアプローチ
function fetchApi
prefix: Prefix,
entity: TEntity,
version: TVersion
): Promise
return fetch(`/${version}/${prefix}/${entity.toLowerCase()}`).then(r => r.json());
}
コンパイラに無駄な組合せ計算をさせず、実行時に関数へ渡される瞬間にのみ型を確定させることで、TSServerのレスポンス速度（入力時のサクサク感）を維持できる。
—
4. チーフアーキテクトからの提言
コードレビューで「とりあえず `string` 型にしておこう」「ユニオンが長くなったから適当にインラインで書こう」というプルリクエストを見かけたら、それは技術的負債の第一歩であると認識してほしい。
プリミティブの集合を型エイリアスとして適切に命名し、構造化することは、「チーム全員の脳内にあるドメインモデルの解釈を、コードという単一の真実（Single Source of Truth）に同期させる作業」に他ならない。
- 型に名前をつけよ。
- 値のリストと型の定義を `as const` で結びつけよ。
- テンプレートリテラル型で組合せの自動化を図りつつ、コンパイラの負荷に配慮せよ。
この原則を死守すれば、あなたの書くTypeScriptコードベースは、大規模化しても決して崩壊することのない、美しく強靭な要塞となるだろう。さあ、今すぐプロジェクトのインラインユニオンをリファクタリングしに行こう。