【入門編】関数引数における「Discriminated Unions」を用いた型安全なオプションオブジェクトの設計 – TypeScript コア・型システムの基礎解析バイブル

関数引数に「Discriminated Unions」で型安全なオプションオブジェクトを！TypeScriptの隠れた力でAPI設計を極める

皆さん、こんにちは！TypeScriptの世界へようこそ。私が皆さんのTypeScriptマスターへの道を、優しく、そして力強くナビゲートさせていただきます。今日は、関数引数の型定義、特に「Discriminated Unions（識別子付きユニオン）」という、ちょっと聞いただけではピンとこないかもしれませんが、実はAPI設計を劇的に改善してくれる強力なテクニックについて、じっくりと掘り下げていきましょう。

「単なるオプショナル引数だと、ちょっと不安…」「特定の引数の組み合わせだけを許可したいんだけど、どうすればいいんだろう？」そんな悩みを抱えているあなた。この記事を読み終える頃には、Discriminated Unionsを使いこなして、堅牢で分かりやすいAPIを設計できるようになっているはずですよ。さあ、一緒にTypeScriptの奥深い世界への扉を開きましょう！

なぜ「単なるオプショナル引数」では不十分なのか？

まずは、なぜ私たちがDiscriminated Unionsのようなテクニックに興味を持つのか、その理由から考えてみましょう。

皆さん、関数を定義する際に、引数がたくさんあると `?` をつけてオプショナル引数にすることがよくありますよね。例えば、こんな感じです。

// 例1: 単純なオプショナル引数
function processUserData(
name: string,
age?: number, // ageはオプショナル
email?: string // emailもオプショナル
): void {
console.log(`Name: ${name}`);
if (age !== undefined) {
console.log(`Age: ${age}`);
}
if (email !== undefined) {
console.log(`Email: ${email}`);
}
}

// 呼び出し例
processUserData(“Alice”);
processUserData(“Bob”, 30);
processUserData(“Charlie”, undefined, “charlie@example.com”); // ageは渡さないけどemailは渡す
processUserData(“David”, 25, “david@example.com”);

このコード、一見問題なさそうに見えますよね。でも、ここで少し立ち止まって考えてみてください。

`age` だけを渡して `email` を渡さない、あるいはその逆、といった呼び出しもできてしまいます。
もし、`age` が渡される場合は必ず `email` も渡す、といった特定の組み合わせのみを許可したい場合、この単純なオプショナル引数だけでは、コンパイル時にはエラーになりません。実行時になって初めて「あれ？この組み合わせは想定していなかったな」となる可能性があるんです。

これは、APIの利用者にとっては「どういう引数の組み合わせが正しいのか」が分かりにくく、開発者にとっては「予期せぬ引数の組み合わせによるバグ」に悩まされる原因になりかねません。APIの堅牢性（ロバストネス）が損なわれてしまうのです。

Discriminated Unionsの登場！型安全なオプションオブジェクトの設計

そこで登場するのが、今日の本題である「Discriminated Unions」です。これは、複数の型をユニオン型でまとめつつ、そのユニオンを構成する各型が持つ「識別子（タグ）」となるプロパティの値で、どの型であるかを明確に区別するという考え方です。

どういうことか、具体的な例を見ていきましょう。

例えば、ユーザーの通知設定を扱う関数があるとします。通知方法として「メール」と「SMS」があり、それぞれの設定内容が異なるとしましょう。

NGな例（単なるオプショナル引数 + 条件分岐）:

// ユーザー通知設定（NGな例）
interface NotificationSettings {
method: “email” | “sms”; // 通知方法
emailAddress?: string; // メールアドレス（emailの場合のみ必要）
phoneNumber?: string; // 電話番号（smsの場合のみ必要）
}

// 呼び出し例
sendNotification({ method: “email”, emailAddress: “test@example.com” }); // OK
sendNotification({ method: “sms”, phoneNumber: “123-456-7890” }); // OK

// 危険な呼び出し例（コンパイルエラーにならない！）
sendNotification({ method: “email” }); // emailAddressがない！
sendNotification({ method: “sms”, emailAddress: “test@example.com” }); // phoneNumberがない！

この例では、`settings.method` が `”email”` の場合は `emailAddress` が必須、`”sms”` の場合は `phoneNumber` が必須、というルールを強制したいのですが、TypeScriptはこれをコンパイル時にチェックしてくれません。実行時に `if` 文でチェックする必要があります。

OKな例（Discriminated Unions を使用）:

ここで、Discriminated Unionsの出番です！

まず、通知方法ごとに個別の型を定義します。そして、それぞれの型に、どの型であるかを識別するための「タグ」となるプロパティ（ここでは `method`）を持たせます。

// ユーザー通知設定（OKな例 – Discriminated Unions）

// 1. 各通知方法の型を定義
// email通知の設定
interface EmailNotification {
method: “email”; // ここが識別子（タグ）！ “email” というリテラル型
emailAddress: string; // emailの場合は必須
}

// SMS通知の設定
interface SmsNotification {
method: “sms”; // ここも識別子（タグ）！ “sms” というリテラル型
phoneNumber: string; // smsの場合は必須
}

// 2. 上記の型をユニオン型でまとめる
type NotificationSettings = EmailNotification | SmsNotification;

// 3. 関数を定義
function sendNotificationWithDiscriminatedUnion(settings: NotificationSettings): void {
// ここで、TypeScriptの強力な機能（制御フロー解析）が発揮されます！
// settings.method の値によって、settings の型が絞り込まれます。

if (settings.method === “email”) {
// このブロック内では、settings は EmailNotification 型として扱われます。
// なので、emailAddress が必ず存在することが型システムによって保証されます！
console.log(`Sending email to ${settings.emailAddress}…`);
} else if (settings.method === “sms”) {
// このブロック内では、settings は SmsNotification 型として扱われます。
// なので、phoneNumber が必ず存在することが型システムによって保証されます！
console.log(`Sending SMS to ${settings.phoneNumber}…`);
} else {
// これで、予期しない method の値も型安全に扱えます。
const _exhaustiveCheck: never = settings; // never型に代入することで、網羅性をチェック
console.error(`Unknown notification method: ${(_exhaustiveCheck as any).method}`);
}
}

// 呼び出し例
sendNotificationWithDiscriminatedUnion({ method: “email”, emailAddress: “test@example.com” }); // OK!
sendNotificationWithDiscriminatedUnion({ method: “sms”, phoneNumber: “123-456-7890” }); // OK!

// 危険な呼び出し例 – コンパイルエラーになります！
// sendNotificationWithDiscriminatedUnion({ method: “email” });
// Argument of type ‘{ method: “email”; }’ is not assignable to parameter of type ‘NotificationSettings’.
// Property ‘emailAddress’ is missing in type ‘{ method: “email”; }’ but required in type ‘EmailNotification’.

// sendNotificationWithDiscriminatedUnion({ method: “sms”, emailAddress: “test@example.com” });
// Argument of type ‘{ method: “sms”; emailAddress: string; }’ is not assignable to parameter of type ‘NotificationSettings’.
// Object literal may only specify known properties, and ‘emailAddress’ does not exist in type ‘SmsNotification’.

// sendNotificationWithDiscriminatedUnion({ method: “push”, token: “abc” });
// Argument of type ‘{ method: “push”; token: string; }’ is not assignable to parameter of type ‘NotificationSettings’.
// Type ‘{ method: “push”; token: string; }’ is not assignable to type ‘EmailNotification’.
// Types of property ‘method’ are incompatible.
// Type ‘”push”‘ is not assignable to type ‘”email”‘.

いかがでしょうか？これがDiscriminated Unionsの力です！

Discriminated Unionsの仕組みを分解してみよう！

なぜ、Discriminated Unionsを使うと、あんなに型安全になるのでしょうか？その秘密を、もう少し詳しく見ていきましょう。

1. 識別子（タグ）としてのリテラル型

Discriminated Unionsの核となるのは、ユニオンを構成する各型が持つ「識別子（タグ）」となるプロパティです。上記の例では、`method` プロパティがその役割を果たしています。

`EmailNotification` では、`method` は `”email”` というリテラル型です。これは、「`method` プロパティの値は、文字列の`”email”`でなければならない」ことを意味します。
`SmsNotification` では、`method` は `”sms”` というリテラル型です。

このように、ユニオンを構成する各型が、それぞれ異なるリテラル型を識別子として持つことで、TypeScriptは「もし `method` が `”email”` なら、このオブジェクトは `EmailNotification` 型である」と判断できるようになるのです。

2. 制御フロー解析（Control Flow Analysis）による型絞り込み

TypeScriptのコンパイラは、コードの実行フローを解析する能力に長けています。これを「制御フロー解析」と呼びます。

`sendNotificationWithDiscriminatedUnion` 関数の中で、`if (settings.method === “email”)` という条件分岐を見たとき、TypeScriptは以下のように理解します。

「この `if` ブロックの中では、`settings.method` は `”email”` であることが保証されている。」
「`settings` 型は `EmailNotification | SmsNotification` であった。そして、`EmailNotification` 型は `method: “email”` を持ち、`SmsNotification` 型は `method: “sms”` を持つ。」
「`settings.method` が `”email”` であるということは、`settings` は `EmailNotification` 型であるに違いない！」

この結果、`if` ブロックの中では、TypeScriptは自動的に `settings` の型を `EmailNotification` に絞り込んでくれます。そのため、`settings.emailAddress` にアクセスしても、型エラーは一切発生しないのです。これは、開発者が明示的に型キャストしたり、`undefined` チェックを繰り返したりする必要がなくなる、ということを意味します。

3. 網羅性チェック（Exhaustiveness Checking）

さらに、Discriminated Unionsは、定義したすべてのケースを処理しているかどうかのチェック（網羅性チェック）も容易にします。

`else` ブロックで `const _exhaustiveCheck: never = settings;` としている部分に注目してください。

`never` 型は、「決して到達しない値」を表す型です。
もし、`NotificationSettings` 型に新しいケース（例えば `PushNotification`）が追加されたのに、`if` や `else if` でそのケースを処理し忘れた場合、`settings` はその新しいケースの型を持つ可能性があります。
しかし、`else` ブロックでは、`settings` は `EmailNotification` でも `SmsNotification` でもない、未知の型になってしまいます。
その未知の型を `never` 型に代入しようとすると、TypeScriptは「`never` 型に代入できない！」とコンパイルエラーを出してくれるのです。

この仕組みにより、将来的に通知方法が増えた際にも、漏れなく対応できているかをコンパイル時に検知できるようになります。これは、APIの保守性を高める上で非常に強力な機能です。

陥りやすい文法エラーと解決策

Discriminated Unionsは非常に強力ですが、いくつか初心者がつまずきやすいポイントもあります。

1. 識別子プロパティの型がリテラル型になっていない

最もよくある間違いは、識別子となるプロパティの型を、単純な文字列型 (`string`) にしてしまうことです。

// NG: method が string 型になっている
interface EmailNotificationNG {
method: string; // ここが string だと、型が絞り込めない！
emailAddress: string;
}
interface SmsNotificationNG {
method: string; // ここも string
phoneNumber: string;
}
type NotificationSettingsNG = EmailNotificationNG | SmsNotificationNG;

function processNotificationNG(settings: NotificationSettingsNG) {
// if (settings.method === “email”) { // ここで settings の型は絞り込まれない！
// console.log(settings.emailAddress); // Error: Property ‘emailAddress’ does not exist on type ‘SmsNotificationNG’.
// }
}

この場合、`settings.method` が `”email”` であることをチェックしても、TypeScriptは `settings` の型を `EmailNotificationNG` に絞り込むことができません。なぜなら、`SmsNotificationNG` の `method` も `string` 型であり、`”email”` という値を取りうる可能性があるからです。

解決策: 識別子となるプロパティには、必ず リテラル型 (`”email”` や `”sms”`) を指定してください。

2. オブジェクトリテラルでプロパティを省略してしまう

先ほどのNG例でも見ましたが、Discriminated Unionsの型定義に従って、必要なプロパティを省略してオブジェクトを作成すると、コンパイルエラーになります。

// NG: emailAddress を省略してしまった
sendNotificationWithDiscriminatedUnion({ method: “email” });

これは、本来はエラーとして検知してほしい挙動なので、むしろ「期待通りの動作」です。

解決策: 型定義をよく確認し、その型のオブジェクトを作成する際は、定義されている全ての必須プロパティを含めるようにしてください。

3. 網羅性チェックの `never` 型でエラーが出る

網羅性チェックのために `const _exhaustiveCheck: never = settings;` と書いた際に、なぜかエラーが出てしまうことがあります。これは、TypeScriptが `settings` の型を `never` に代入できると判断してしまっている場合に起こります。

考えられる原因としては、

ユニオンの型定義に漏れがあり、`else` ブロックに到達した `settings` が `never` 型になりうる場合。
型推論の挙動により、`else` ブロックに到達した `settings` が `never` 型ではないと判断されている場合。

解決策:

まずは、ユニオンの型定義に漏れがないか、`else` ブロックに到達する可能性のあるケースがないかを確認してください。
それでも解決しない場合は、`else` ブロックの直前で `console.log(settings)` などを挟んで、`settings` の実際の型を確認してみると良いでしょう。
稀なケースですが、型ガード (`if (settings.method === “email”)` のようなもの) が不十分で、`else` ブロックに到達した `settings` がユニオンのいずれかの型に絞り込まれてしまう場合、`never` 型への代入はエラーになります。その場合は、型ガードをより厳密にするか、`else` ブロックのロジックを見直す必要があります。

まとめ：Discriminated Unionsで、より洗練されたAPI設計を

今日は、TypeScriptの「Discriminated Unions」という強力なテクニックについて、その仕組みから具体的な使い方、そして陥りやすいエラーとその解決策までをじっくりと解説しました。

Discriminated Unionsを使うことで、

関数引数の組み合わせを型安全に保証できる
APIの意図がコード上で明確になり、可読性が向上する
網羅性チェックにより、将来的なバグを防ぎやすくなる

といった、多くのメリットを享受できます。

これは、単にコードが動く、というレベルを超えて、「どのようにコードを書けば、より安全で、より保守しやすく、より意図が伝わりやすいか」という、API設計の本質に迫るための重要なテクニックです。

最初は少し難しく感じるかもしれませんが、今回ご紹介したコード例を実際に動かしてみたり、ご自身のプロジェクトで試してみたりすることで、その真価を実感できるはずです。

ここをクリアすれば、TypeScriptの型システムをさらに深く理解し、より洗練された開発ができるようになりますよ。ぜひ、このDiscriminated Unionsをあなたの武器として、TypeScriptの世界をもっともっと楽しんでくださいね！

それでは、また次回の記事でお会いしましょう！