[TypeScript] オプショナルの`?`と`| undefined`の違い

背景

オプショナルなプロパティを持つオブジェクトの型定義において、TypeScriptの型システムでは?演算子と| undefined型の組み合わせがよく使われる。これらには微妙な違いがある。

例えば、以下のツイートで紹介されているものが分かりやすかったので、改めて違いを整理してみる。

if I may be so bold, I'd like to propose some much-needed nomenclature pic.twitter.com/tU230ozkQV

— Colin McDonnell (@colinhacks) February 24, 2025

// name is "key optional"
type User = { name?: string };

// name is "value optional"
type User = { name: string | undefined };

// name is "key-value optional"
type User = { name?: string | undefined };

これら3つの型定義は、オプショナルの扱い方が異なる。それぞれの特徴と使い方を見ていく。

1. name?: string - キーがオプショナル

type User = { name?: string };

この型定義では、nameプロパティはオブジェクトに存在しなくてもよい。存在する場合、その値はstring型でなければならない。

特徴

• nameプロパティがオブジェクトに含まれない場合でもエラーにならない。
• プロパティが存在する場合、string型である必要があるが、undefinedを明示的に代入することも可能。
• プロパティが存在しない場合と、name: undefinedが設定されている場合は異なる意味を持つ。

使用例

const user1: User = {}; // OK: nameがない
const user2: User = { name: 'Alice' }; // OK: nameが文字列
const user3: User = { name: undefined }; // OK: nameがundefined

注意点

nameプロパティが存在しない場合、user.nameにアクセスするとundefinedが返る。ただし、これはプロパティが「存在しない」ことを意味し、name: undefinedとは区別される。この柔軟性が便利な一方で、意図しないundefinedの代入に注意が必要だ。

2. name: string | undefined - 値がオプショナル

type User = { name: string | undefined };

この型定義では、nameプロパティは必ずオブジェクトに存在しなければならない。ただし、その値はstringまたはundefinedのどちらかでよい。

特徴

• nameプロパティがオブジェクトに含まれていないと型エラーになる。
• プロパティが存在する場合は、その値がundefinedでも問題ない。

使用例

const user1: User = { name: 'Alice' }; // OK: nameが文字列
const user2: User = { name: undefined }; // OK: nameがundefined
const user3: User = {}; // エラー: nameプロパティが必須

注意点

nameプロパティは必須であるため省略できない。この型は、プロパティの存在を保証しつつ、その値が不明な場合を許容したいときに適している。

3. name?: string | undefined - キーと値の両方がオプショナル

type User = { name?: string | undefined };

この型定義は、nameプロパティがオブジェクトに存在しなくてもよく、存在する場合でもその値がstringまたはundefinedでよいという、制約が最も緩い定義である。

特徴

• nameプロパティがなくてもエラーにならない。
• プロパティが存在する場合、その値はstringまたはundefinedのどちらでもよい。

使用例

const user1: User = {}; // OK: nameがない
const user2: User = { name: 'Alice' }; // OK: nameが文字列
const user3: User = { name: undefined }; // OK: nameがundefined

注意点

この型は最も柔軟性が高く、プロパティの不在、値がstring、値がundefinedのすべてのケースを許容する。そのため、制約を最小限にしたい場合、それが適しているが、意図しない動作を見逃すリスクもある。

比較と使い分け

以下に、3つの型定義の違いを表でまとめる。

実際の使用シナリオ

• ユーザープロフィールで名前が任意入力の場合。入力しない選択肢を許すが、入力するなら文字列を期待する。
• データベースから取得したデータで、名前が必ず記録されるが値が不明な場合にundefinedを使う。
• APIレスポンスでは名前を省略できる可能性があり、存在してもundefinedである場合を許容する。

まとめ

TypeScriptでオプショナルなプロパティを扱う際、?演算子はプロパティの存在をオプショナルにし、| undefinedは値のオプショナル性を表す。これらを組み合わせることで、状況に応じた柔軟な型定義が可能だ。フロントエンドエンジニアとして、APIやデータモデルの設計時にこれらの違いを理解し、データの実際の要件に合った型を選択することが重要である。例えば、プロパティが常に存在するが値が不明な場合はstring | undefinedを、プロパティ自体が省略可能な場合は?を使うべきだ。正確な型定義は、バグを減らし、コードの意図を明確に伝える助けとなる。