ユニオン型と型ガード
APIのレスポンスや状態管理では、「文字列または数値」「成功または失敗」といった複数のパターンを持つ値を扱う場面がよくあります。TypeScriptではこれをユニオン型(| で区切る型)で表現します。ここでは、ユニオン型・リテラル型・型ガード・判別可能ユニオンをまとめて扱います。
1. ユニオン型
「文字列または数値のどちらか」のように、複数の型のいずれかを受け取れる値を表したいときは、ユニオン型を使います。書き方は以下のとおりです。
型1 | 型2 | /* ... */
次のコードは、id として string と number のどちらでも受け取れる関数の例です。以下のコードで hello.ts を書き換えます。
function formatId(id: string | number): string {
return `ID: ${id}`;
}
console.log(formatId(123));
console.log(formatId("abc"));
以下のコマンドでコンパイルします。
npx tsc hello.ts
続いて、生成された hello.js を実行します。
node hello.js
以下のような実行結果が表示されます。
ID: 123
ID: abc
123(number)と "abc"(string)のどちらも受け付けられ、それぞれ ID: 123 と ID: abc が出力されました。
コードを解説します。
function formatId(id: string | number): string {
id の型として string | number を指定しています。呼び出し側は文字列か数値のどちらかを渡すことができ、それ以外の型を渡そうとするとコンパイルエラーになります。
2. リテラル型
決まった選択肢の中から1つだけを許可する型を作りたいときは、リテラル型を使います。値そのものを型として扱う仕組みで、ユニオン型と組み合わせて表現するのが一般的です。書き方は以下のとおりです。
type 型名 = "値1" | "値2" | "値3";
次のコードは、状態を表す Status を「success」「error」「loading」の3つに絞ったリテラル型で定義し、それを引数に受け取る関数の例です。候補にない値を渡すとどうなるかも確認します。以下のコードで hello.ts を書き換えます。
type Status = "success" | "error" | "loading";
function showMessage(status: Status) {
console.log(`現在の状態: ${status}`);
}
showMessage("success");
showMessage("pending");
"pending" は Status の候補にないため、以下のコマンドでコンパイルすると、エラーが表示されます。
npx tsc hello.ts
Argument of type '"pending"' is not assignable to parameter of type 'Status'.
Argument of type '"pending"' is not assignable to parameter of type 'Status'. のエラーが表示されれば、リテラル型で列挙した候補以外の文字列をコンパイル時にエラーとして検出できていることが動作確認できます。
コードを解説します。
type Status = "success" | "error" | "loading";
Status は「success か error か loading のいずれかの文字列」しか許容しない型です。文字列値そのものが型として扱われ、それをユニオン型で並べています。
showMessage("pending");
"pending" は Status の候補に含まれない文字列のため、コンパイル時にエラーとして検出されます。if (status === "sucess") のような書き間違いも即座に指摘されるため、有限の選択肢を扱う場面で有効です。
3. 型ガード
ユニオン型を受け取った関数の中で、値がどちらの型なのかによって処理を分岐したいときは、型ガードを使います。typeof や instanceof を条件式に書くと、その分岐内で型が絞り込まれます。書き方は以下のとおりです。
if (typeof 値 === "型名") {
// このブロック内では、値は指定した型として扱える
}
次のコードは、string | number を受け取り、型ごとに異なる整形処理を行う関数の例です。以下のコードで hello.ts を書き換えます。
function formatId(id: string | number): string {
if (typeof id === "string") {
return `ID: ${id.toUpperCase()}`;
}
return `ID: ${id.toFixed(0)}`;
}
console.log(formatId("abc"));
console.log(formatId(123.7));
以下のコマンドでコンパイルします。
npx tsc hello.ts
続いて、生成された hello.js を実行します。
node hello.js
以下のような実行結果が表示されます。
ID: ABC
ID: 124
"abc" は string として大文字化され、123.7 は number として小数点以下を切り捨てた形で出力されました。
コードを解説します。
if (typeof id === "string") {
return `ID: ${id.toUpperCase()}`;
}
typeof id === "string" が true のとき、TypeScriptは id を string 型として扱います。そのため、string にしかない toUpperCase() メソッドを呼び出せます。
return `ID: ${id.toFixed(0)}`;
if を抜けたあとの id は number 型として扱われます。toFixed() は number のメソッドで、指定した桁数に丸めた文字列を返します。
4. 判別可能ユニオン
複数のオブジェクトをまとめてユニオン型にしたいときは、判別可能ユニオン(discriminated union)を使います。各オブジェクトに共通の判別子プロパティを持たせ、その値で分岐することで、分岐先ごとに扱えるプロパティを型で区別できます。書き方は以下のとおりです。
type 型名A = { 判別子: "値A"; プロパティ名: 型 };
type 型名B = { 判別子: "値B"; プロパティ名: 型 };
type ユニオン型名 = 型名A | 型名B;
次のコードは、APIレスポンスを「成功」と「失敗」の2種類のオブジェクトで表し、status プロパティで分岐する例です。以下のコードで hello.ts を書き換えます。
type SuccessResponse = { status: "success"; data: string };
type ErrorResponse = { status: "error"; message: string };
type ApiResponse = SuccessResponse | ErrorResponse;
function handleResponse(response: ApiResponse) {
if (response.status === "success") {
console.log(`データ: ${response.data}`);
} else {
console.log(`エラー: ${response.message}`);
}
}
handleResponse({ status: "success", data: "取得したデータ" });
handleResponse({ status: "error", message: "サーバエラー" });
以下のコマンドでコンパイルします。
npx tsc hello.ts
続いて、生成された hello.js を実行します。
node hello.js
以下のような実行結果が表示されます。
データ: 取得したデータ
エラー: サーバエラー
成功時は data、失敗時は message を参照して、それぞれのメッセージが出力されました。
コードを解説します。
type SuccessResponse = { status: "success"; data: string };
type ErrorResponse = { status: "error"; message: string };
type ApiResponse = SuccessResponse | ErrorResponse;
SuccessResponse と ErrorResponse の両方に status という共通プロパティを持たせ、その値をリテラル型("success" / "error")で区別しています。ApiResponse はこの2つのユニオン型です。
if (response.status === "success") {
console.log(`データ: ${response.data}`);
} else {
console.log(`エラー: ${response.message}`);
}
response.status の値で分岐したとき、"success" の分岐内では SuccessResponse として扱われて data のみアクセスでき、else の分岐では ErrorResponse として扱われて message のみアクセスできます。「成功確認なしに data を参照する」ミスを型レベルで防げるため、APIレスポンスの成功/失敗を型で表現するときによく使われます。