TypeScriptのユニオン型（|）: 使い方とサンプル

ユニオン型は | で選択肢を並べます。string | number 型の値は、文字列か数値のどちらかです。ユニオン型は、正当に複数の形を取りうる値をTypeScriptが表す方法で、コンパイラーは、ある形に特有のものを使う前に、どの形なのかをチェックさせます。

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

typeof のチェックの各ブランチの中では、id は1つの型です。このステップを絞り込みといい、ユニオン型を実用的にしているのはこれです。

使えるのは共通のメンバーだけ

絞り込む前は、ユニオン型のすべてのメンバーが対応しているものしか使えません。toString() は文字列にも数値にもあるので使えますが、toUpperCase() は文字列にしかありません:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

2行目は、そのプロパティを持たないメンバーを名指ししています。逆方向にも同じルールが当てはまります。string | number の値は、数値かもしれないので、string 型の引数には渡せません（TS2345）。ユニオン型はより多くの値を受け付ける代わりに、チェックするまではできることが少なくなります。

ユニオン型の絞り込み

絞り込みには普通のJavaScriptのチェックを使います。TypeScriptは制御フローをたどり、除外されたメンバーを取り除いていくので、最後のチェックのあとには1つのメンバーだけが残ります:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

絞り込みの方法の一覧は、型の絞り込みのページにあります。

リテラル型のユニオン

リテラルの値のユニオン型は、許可する値の閉じた集合です。実際のコードでいちばんよく使われるユニオン型です:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

リテラルと比較すると絞り込まれます。if (current === "error") のあと、else のブランチでは current がほかの3つのどれかだとわかります。多くのコードベースでは、リテラルのユニオン型が enum の代わりになっています。as const と、配列からこうしたユニオン型を作る方法は リテラル型 を参照してください。

オブジェクト型のユニオン

メンバーがオブジェクト型の場合、すべてに共通するプロパティは直接使えます。それ以外は、in でプロパティがあるかをチェックします:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

複数のオブジェクトの形のユニオン型なら、kind: "cat" / kind: "fish" のような共通のリテラルのプロパティを使うパターンのほうがすっきりします。その1つのプロパティをチェックすればオブジェクト全体が絞り込まれ、それに対する switch は網羅性をチェックできます。このパターンが判別可能なユニオン型です。

配列とユニオン型

かっこの位置で意味がまったく変わります:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

(string | number)[] を反復すると、各要素はユニオン型なので、上の reduce のコールバックのように絞り込みが必要です。map や filter のようなメソッドは string[] | number[] にも使え、コールバックは string | number を受け取ります。

null と undefined を含むユニオン型

いちばんよく使われるユニオン型は「値か、何もないか」です: string | null、User | undefined。Array.prototype.find と Map.prototype.get が返すのはこれで、省略可能なプロパティ name?: string を読むと string | undefined になります。?.、??、null チェックによる扱い方には専用のページがあります: null と undefined。

既存のユニオン型から型のレベルでメンバーを取り除くには、組み込みのユーティリティを使います。Exclude<"a" | "b" | "c", "a"> は "b" | "c"、NonNullable<string | null> は string です。