В чём разница в TypeScript между опциональным свойством `prop?: T` и обязательным свойством `prop: T | undefined`?

В TypeScript оба варианта на первый взгляд кажутся похожими, но семантически они различаются. Опциональное свойство prop?: T говорит компилятору, что ключ prop может вообще отсутствовать в объекте. Обязательное свойство prop: T | undefined требует, чтобы ключ присутствовал, но допускает значение undefined.

Разница на уровне типов

Рассмотрим два интерфейса:

interface A { prop?: number; }
interface B { prop: number | undefined; }

const a1: A = {};              // OK
const a2: A = { prop: undefined }; // OK
const b1: B = {};              // Ошибка: prop отсутствует
const b2: B = { prop: undefined }; // OK

Тип A допускает объект без ключа prop, а тип B — нет. Это важно, когда объект сериализуется в JSON: в первом случае ключ может исчезнуть, во втором он всегда будет присутствовать (возможно, со значением undefined, которое JSON.stringify просто выбросит).

Проверка наличия ключа

Оператор in помогает различить эти случаи:

function check(obj: A | B) {
  if ('prop' in obj) {
    // для A: ключ есть, значение T | undefined
    // для B: всегда true
  }
}

С опциональным свойством можно отличить отсутствие ключа от явного undefined, что полезно при работе с API и частичными обновлениями (PATCH).

exactOptionalPropertyTypes

Начиная с TypeScript 4.4, флаг exactOptionalPropertyTypes ужесточает правила: при включённом флаге prop?: T больше не допускает явного присваивания undefined, только отсутствие ключа. Это делает разницу ещё более явной и помогает избежать случайной передачи undefined туда, где ожидается отсутствие свойства.

Практическое применение

• prop?: T — для необязательных полей конфигураций, DTO с частичным обновлением, опций функций.
• prop: T | undefined — когда ключ должен присутствовать всегда, но значение может быть неизвестно (например, результат поиска, кэш).

Итог: выбирайте prop?: T, если свойство может отсутствовать в объекте, и prop: T | undefined, если ключ обязателен, но значение может быть undefined. Это влияет на проверки in, сериализацию и поведение при включённом exactOptionalPropertyTypes.