【TypeScript】enum（列挙型）完全ガイド｜数値・文字列・const enum・union型との使い分けまで徹底解説

この記事で学べること

• 数値 enum・文字列 enum・ヘテロジニアス enum の基本と違い
• const enum によるコンパイル最適化の仕組み
• 数値 enum の逆引き（reverse mapping）の使い方
• enum を型として使う・型の絞り込みとの組み合わせ
• enum vs union 型 vs const assertion（as const）の使い分け
• ステータス管理・API レスポンス分岐など実務でよく使うパターン
• よくあるエラーと解決方法

前提知識：TypeScript の基本型（string, number, boolean など）を理解していることを前提とします。基礎から学びたい方は【TypeScript】型の書き方 完全入門をご参照ください。

// 基本的な数値 enum
enum Direction {
  Up    // 0
  Down  // 1
  Left  // 2
  Right // 3
}

// アクセス方法
const dir: Direction = Direction.Up;  // 0
console.log(Direction.Up);    // 0
console.log(Direction[0]);    // "Up"（逆引き）

// 1 始まりにする
enum Status {
  Pending  = 1,
  Active   = 2,
  Inactive = 3,
}

// 一部だけ指定（後続は自動インクリメント）
enum HttpStatus {
  OK        = 200,
  NotFound  = 404,
  ServerError = 500,
}

enum Color {
  Red   = "RED",
  Green = "GREEN",
  Blue  = "BLUE",
}

console.log(Color.Red);    // "RED"
console.log(Color["RED"]); // undefined（文字列enumに逆引きなし）

// API レスポンスの方向性を定義するケース
enum SortOrder {
  Asc  = "asc",
  Desc = "desc",
}

function getUsers(order: SortOrder) {
  return fetch(`/api/users?sort=${order}`);
}
getUsers(SortOrder.Asc);

文字列 enum が数値 enum より好まれる理由：数値 enum はデバッグ時に 0 や 1 という値しか見えません。文字列 enum なら "asc"・"desc" のように意味が明確で、ログや API レスポンスで実際の値を確認しやすくなります。

// 通常 enum → コンパイル後にオブジェクトが残る
enum Direction { Up, Down, Left, Right }
const d = Direction.Up;  // → Direction.Up（参照が残る）

// const enum → コンパイル後にインライン展開
const enum Speed {
  Slow   = 1,
  Normal = 2,
  Fast   = 3,
}
const s = Speed.Fast;  // → const s = 3;（リテラルに展開）

const enum の制限：Babel や esbuild でトランスパイルする場合、const enum は正しく処理されないことがあります（Babel はデフォルトで const enum 非対応）。tsconfig の isolatedModules: true 環境では const enum はエラーになります。バンドラーを使うプロジェクトでは通常の enum か union 型を推奨します。

enum Status {
  Pending = 1,
  Active  = 2,
  Done    = 3,
}

// 数値 → 名前（逆引き）
console.log(Status[1]);  // "Pending"
console.log(Status[2]);  // "Active"

// 動的な値からラベル取得
function getStatusLabel(code: number): string {
  return Status[code] ?? "Unknown";
}
getStatusLabel(2);  // "Active"
getStatusLabel(9);  // "Unknown"

// TypeScript の enum は以下のような JS に変換される
var Status;
(function (Status) {
  Status[Status["Pending"] = 1] = "Pending";
  Status[Status["Active"]  = 2] = "Active";
  Status[Status["Done"]    = 3] = "Done";
})(Status || (Status = {}));
// Status[1] = "Pending" かつ Status["Pending"] = 1 の双方向マップが生成される

enum UserRole {
  Admin  = "admin",
  Editor = "editor",
  Viewer = "viewer",
}

function checkPermission(role: UserRole): boolean {
  return role === UserRole.Admin;
}

checkPermission(UserRole.Admin);   // OK
// checkPermission("admin");  // TS Error: Argument of type 'string' is not assignable
// checkPermission("superuser");  // TS Error

function handleRole(role: UserRole): string {
  switch (role) {
    case UserRole.Admin:  return "管理者";
    case UserRole.Editor: return "編集者";
    case UserRole.Viewer: return "閲覧者";
    default:
      const _exhaustive: never = role;  // 未処理ケースがあればコンパイルエラー
      return _exhaustive;
  }
}

never による網羅性チェック：switch 文の default ブランチで never 型変数に代入することで、enum に新しいメンバーを追加した際に「対応する case がない」とコンパイルエラーで検知できます。実務でのバグ防止に非常に有効なパターンです。

// ① enum
enum ColorEnum { Red = "red", Blue = "blue" }
type T1 = ColorEnum;  // ColorEnum 型

// ② union 型（文字列リテラル型）
type ColorUnion = "red" | "blue";
type T2 = ColorUnion;  // "red" | "blue"

// ③ const assertion（as const）
const COLOR = { Red: "red", Blue: "blue" } as const;
type T3 = typeof COLOR[keyof typeof COLOR];  // "red" | "blue"

モダンな TypeScript では union 型や const assertion が好まれます。enum は生成される JS コードが増え、Babel との互換性問題もあるため、新規プロジェクトでは as const + union 型の組み合わせを推奨する意見が増えています。ただし、逆引きが必要な場合やレガシーコードとの互換性を保つ場合は enum も有効です。

// const assertion を使った enum 代替
const UserRole = {
  Admin:  "admin",
  Editor: "editor",
  Viewer: "viewer",
} as const;

// 値の union 型を取得
type UserRoleType = typeof UserRole[keyof typeof UserRole];
// type UserRoleType = "admin" | "editor" | "viewer"

// 使用例
function checkPermission(role: UserRoleType): boolean {
  return role === UserRole.Admin;
}

enum ApiStatus {
  Success     = 200,
  Created     = 201,
  BadRequest  = 400,
  Unauthorized = 401,
  NotFound    = 404,
  ServerError = 500,
}

function handleResponse(status: ApiStatus) {
  switch (status) {
    case ApiStatus.Success:
    case ApiStatus.Created:
      return "成功";
    case ApiStatus.Unauthorized:
      return "認証エラー";
    case ApiStatus.NotFound:
      return "見つかりません";
    default:
      return "エラーが発生しました";
  }
}

enum FormState {
  Idle      = "idle",
  Submitting = "submitting",
  Success   = "success",
  Error     = "error",
}

// React のステート管理との組み合わせ
const [state, setState] = useState<FormState>(FormState.Idle);

async function handleSubmit() {
  setState(FormState.Submitting);
  try {
    await submitForm();
    setState(FormState.Success);
  } catch {
    setState(FormState.Error);
  }
}

enum Permission {
  None    = 0,
  Read    = 1 << 0,  // 1
  Write   = 1 << 1,  // 2
  Delete  = 1 << 2,  // 4
  Admin   = Read | Write | Delete,  // 7
}

// 権限チェック（ビット AND）
function hasPermission(userPerm: Permission, required: Permission): boolean {
  return (userPerm & required) === required;
}

const userPerm = Permission.Read | Permission.Write;  // 3
hasPermission(userPerm, Permission.Read);    // true
hasPermission(userPerm, Permission.Delete);  // false

// ❌ 文字列 enum で逆引き → undefined
enum Color { Red = "red" }
console.log(Color["red"]);  // undefined（逆引き不可）

// ✅ 解決: Record で逆引きマップを自前で作る
const ColorLabel: Record<Color, string> = {
  [Color.Red]: "赤",
};
ColorLabel[Color.Red];  // "赤"

// ❌ 数値 enum に存在しない値を渡す（型エラーにならないケース）
enum Dir { Up = 0, Down = 1 }
const d: Dir = 99;  // TypeScriptは数値なら代入を許す（注意）

// ✅ 解決: 文字列 enum にするか union 型にして型安全性を高める
enum StrDir { Up = "up", Down = "down" }
// const d: StrDir = "invalid";  // NG

TypeScript enum 完全まとめ

• 数値 enum：0 始まりの整数が自動割り当て。逆引き（reverse mapping）が使える
• 文字列 enum：意味のある文字列を割り当て。デバッグしやすく実務で人気。逆引きなし
• const enum：コンパイル時にインライン展開。Babel 環境では注意が必要
• switch + never で enum の網羅性チェック。新メンバー追加漏れをコンパイル時に検出
• 数値 enum は型が緩い（任意の数値を代入できる）。型安全性が重要なら文字列 enum か union 型を推奨
• モダンな選択肢：union 型や const assertion（as const）は型のみで実現でき、JS の出力コードを減らせる
• 逆引きが必要・ランタイムでキー列挙したい場合は enum が依然有効