TypeScriptの判別可能なユニオン型（タグ付きユニオン）

判別可能なユニオン型（タグ付きユニオンとも呼ばれます）は、すべてのメンバーが1つのプロパティ、つまりタグを共有し、メンバーごとにそのリテラルの値が違うオブジェクト型のユニオンです。タグをチェックすると、どのメンバーなのかがTypeScriptにわかり、そのメンバーのほかのプロパティが使えるようになります。

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2; // shape is the circle member here
    case "rect":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
  }
}

const shapes: Shape[] = [
  { kind: "circle", radius: 1 },
  { kind: "rect", width: 2, height: 3 },
  { kind: "triangle", base: 4, height: 5 },
];

for (const s of shapes) console.log(s.kind, area(s).toFixed(2));
// circle 3.14
// rect 6.00
// triangle 10.00

case "circle" の中で shape.width を読むとコンパイルエラーになります。円のメンバーには width がないからです。タグは普通のデータです。実行時にはただの文字列のプロパティで、switch は普通のJavaScriptです。

ユニオン型が判別可能になる条件

タグによる絞り込みは、次の3つの条件がそろったときに働きます:

1. すべてのメンバーがオブジェクト型である。
2. すべてのメンバーが同じ名前のプロパティ（判別子）を持つ。名前は自由で、kind、type、status、tag がよく使われます。
3. 各メンバーで、そのプロパティがリテラル型である。文字列、数値、boolean のリテラル、または null/undefined です。

type UiEvent =
  | { type: "click"; x: number; y: number }
  | { type: "keypress"; key: string }
  | { type: "scroll"; delta: number };

type ApiResponse =
  | { ok: true; data: string }    // boolean literal tags
  | { ok: false; error: string };

type Message =
  | { version: 1; text: string }  // number literal tags
  | { version: 2; text: string; lang: string };

あるメンバーがタグをリテラルではなく普通の string として宣言していると、タグを比較してもユニオン型は絞り込まれなくなり、メンバー固有のプロパティには手が届かないままになります（TS2339）。

タグによる絞り込み

タグに対するチェックでTypeScriptが理解できるものなら、どれでもオブジェクトを絞り込みます。switch、if/else、=== と !==、そして const であれば分割代入したタグでもかまいません:

function describe(e: UiEvent): string {
  if (e.type === "click") return `click at ${e.x},${e.y}`;

  const { type } = e;        // destructured tags narrow too
  if (type === "keypress") return `key ${e.key}`;

  return `scroll by ${e.delta}`; // only "scroll" is left
}

"radius" in shape でプロパティの有無をチェックしても絞り込めますが、タグを比較するほうが読みやすく、網羅性のチェックもできるようになります。

網羅性チェック

このパターンの最大の利点は、ユニオン型が大きくなったときに表れます。明示的な戻り値の型があり default がなければ、switch がすべてのタグをカバーしなければならないことをTypeScriptは知っているので、ケースのない新しいメンバーはコンパイルエラーになります:

// This does not compile: the "square" case is missing
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "square"; size: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
  }
}

console.log(area({ kind: "square", size: 2 }));

index.ts(7,30): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.

このメッセージは、どのケースが足りないかを教えてくれません。assertNever ヘルパーなら教えてくれ、外部からのデータ（JSON、古いクライアント）が型の上では存在しえないタグを持っていたときには、実行時に例外も投げます:

type RequestState<T> =
  | { status: "idle" }
  | { status: "loading"; startedAt: number }
  | { status: "success"; data: T }
  | { status: "error"; error: string; retryable: boolean };

function assertNever(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}

function render(state: RequestState<string[]>): string {
  switch (state.status) {
    case "idle":
      return "Press load";
    case "loading":
      return `Loading since t=${state.startedAt}`;
    case "success":
      return `Loaded ${state.data.length} items: ${state.data.join(", ")}`;
    case "error":
      return `Failed: ${state.error}${state.retryable ? " (retry?)" : ""}`;
    default:
      return assertNever(state); // state is never here
  }
}

const states: RequestState<string[]>[] = [
  { status: "idle" },
  { status: "loading", startedAt: 1200 },
  { status: "success", data: ["a", "b"] },
  { status: "error", error: "timeout", retryable: true },
];

for (const s of states) console.log(render(s));
// Press load
// Loading since t=1200
// Loaded 2 items: a, b
// Failed: timeout (retry?)

ケースを追加せずに5つ目の status を追加すると、assertNever(state) の行で Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never' が報告され、メンバーが名指しされます。詳しくは never のページを参照してください。

ありえない状態をありえなくする

上の RequestState は、よくある弱い形の代わりになります:

// Every combination is allowed, including nonsense
type LooseState<T> = {
  loading: boolean;
  data?: T;
  error?: string;
};

const nonsense: LooseState<string[]> = { loading: true, data: ["a"], error: "timeout" };

省略可能なフィールドでは「データとエラーの両方を持つ読み込み中」も型チェックを通り、読む人はどの組み合わせが本当に起こりうるかを推測しなければなりません。判別可能なユニオン型なら、data は success の状態にしか、error は error の状態にしか存在しないので、state.data を読むコードは先に success の状態であることを証明しなければなりません。型そのものが正しい状態を文書化しています。

結果のモデル化: 成功か失敗か

「うまくいったか、いかなかったか」なら boolean のタグで十分です。この Result 型は、不正な入力のような想定される失敗に対して、例外を投げる代わりによく使われます:

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parsePort(text: string): Result<number> {
  const n = Number(text);
  if (!Number.isInteger(n)) return { ok: false, error: `"${text}" is not a whole number` };
  if (n < 1 || n > 65535) return { ok: false, error: `${n} is out of range` };
  return { ok: true, value: n };
}

for (const input of ["8080", "http", "70000"]) {
  const result = parsePort(input);
  if (result.ok) {
    console.log("port", result.value);   // result.value exists only here
  } else {
    console.log("error:", result.error); // result.error exists only here
  }
}
// port 8080
// error: "http" is not a whole number
// error: 70000 is out of range

呼び出し側は、先に result.ok をチェックしなければ result.value を読めません。例外や null を返す方法では、まさにこのチェックを忘れがちです。

状態機械とリデューサー

状態用とアクション用の2つの判別可能なユニオン型で、状態機械を表せます。リデューサーはアクションで分岐して次の状態を返し、コンパイラーは返した各オブジェクトが正しい状態であるかをチェックします:

type State =
  | { name: "idle" }
  | { name: "playing"; track: string; position: number }
  | { name: "paused"; track: string; position: number };

type Action =
  | { type: "play"; track: string }
  | { type: "pause" }
  | { type: "resume" }
  | { type: "stop" };

function reduce(state: State, action: Action): State {
  switch (action.type) {
    case "play":
      return { name: "playing", track: action.track, position: 0 };
    case "pause":
      return state.name === "playing" ? { ...state, name: "paused" } : state;
    case "resume":
      return state.name === "paused" ? { ...state, name: "playing" } : state;
    case "stop":
      return { name: "idle" };
  }
}

const actions: Action[] = [{ type: "play", track: "Intro" }, { type: "pause" }, { type: "resume" }, { type: "stop" }];

let state: State = { name: "idle" };
for (const a of actions) {
  state = reduce(state, a);
  console.log(a.type.padEnd(6), "->", state.name);
}
// play   -> playing
// pause  -> paused
// resume -> playing
// stop   -> idle

{ ...state, name: "paused" } がコンパイルできるのは、先に state が再生中のメンバーに絞り込まれているので、コピーが track と position を持つからです。{ name: "paused" } だけを返すとエラーになります。一時停止の状態にはトラックが必要だからです。Redux のリデューサーや React の useReducer が使っているのと同じ形です。

型の拡大の落とし穴

タグはリテラル型のままでなければなりません。型注釈なしで変数に作ったオブジェクトは、タグが string に広げられ、どのメンバーにも一致しなくなります:

type Shape = { kind: "circle"; radius: number } | { kind: "rect"; width: number; height: number };
declare function area(shape: Shape): number;

const c = { kind: "circle", radius: 2 }; // kind: string
area(c);
// error TS2345: Argument of type '{ kind: string; radius: number; }' is not assignable to parameter of type 'Shape'.

const ok1: Shape = { kind: "circle", radius: 2 };        // annotate the variable
const ok2 = { kind: "circle", radius: 2 } as const;      // or keep the literal with as const
area({ kind: "circle", radius: 2 });                     // or build it where Shape is expected

その背景にあるルール、つまり変更可能なプロパティは型が広がることは、リテラル型 のページで説明しています。