null и undefined в TypeScript: проверки, операторы ?. и ??

При включённом strictNullChecks (он входит в strict) null и undefined становятся собственными типами. string никогда не может быть null; значение, которое может отсутствовать, должно указывать это в своём типе, например string | null, и TypeScript заставляет обработать этот случай, прежде чем использовать значение.

function initials(name: string | null | undefined): string {
  if (name == null) return "?"; // handles both null and undefined
  return name
    .split(" ")
    .map((part) => part[0])
    .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(null));           // ?
console.log(initials(undefined));      // ?

После проверки компилятор знает, что name имеет тип string, поэтому .split разрешён. Дальше на странице разобраны способы такой проверки и операторы, которые делают её короче.

strictNullChecks и ошибки «possibly null»

Если тип включает null или undefined, TypeScript отказывается использовать значение так, будто оно есть всегда:

// This does not compile: name may be null
function greet(name: string | null) {
  return "Hello, " + name.toUpperCase();
}

console.log(greet("ada"));

index.ts(3,22): error TS18047: 'name' is possibly 'null'.

Вариант с undefined это TS18048, 'x' is possibly 'undefined'. Без strictNullChecks null и undefined допустимы в любом типе, и этот код компилируется, а затем падает во время выполнения с TypeError, как только name окажется null. Этот класс ошибок и есть главная причина держать strict включённым.

Откуда эти типы берутся в повседневном коде:

Проверка на null и undefined

Каждая проверка ниже сужает тип внутри блока. Выберите ту, которая исключает то, что вам нужно.

function label(value: string | null | undefined): string {
  if (value === undefined) return "undefined";
  if (value === null) return "null";
  return value.toUpperCase(); // value is string here
}

function orNone(value: string | null | undefined): string {
  if (value == null) return "(none)"; // == null matches null AND undefined
  return `"${value}"`;
}

console.log(label(undefined), label(null), label("ok")); // undefined null OK
console.log(orNone(null), orNone(undefined), orNone("")); // (none) (none) ""

== null это единственное место, где нестрогое равенство идиоматично: оно истинно ровно для null и undefined и ни для чего больше. Проверка на истинность сочла бы пустую строку отсутствующим значением, а это часто ошибка.

Опциональная цепочка: ?.

a?.b читает b, если a не null и не undefined, а иначе останавливается и возвращает undefined. Тот же оператор работает для индексов, a?.[i], и для вызовов, fn?.().

interface User {
  name: string;
  address?: { city: string; zip?: string };
  tags?: string[];
  onLogin?: () => string;
}

const ada: User = { name: "Ada", address: { city: "London" }, onLogin: () => "welcome" };
const bob: User = { name: "Bob" };

console.log(ada.address?.city);        // London
console.log(bob.address?.city);        // undefined
console.log(ada.address?.zip?.length); // undefined
console.log(bob.tags?.[0]);            // undefined
console.log(ada.onLogin?.());          // welcome
console.log(bob.onLogin?.());          // undefined

Тип bob.address?.city это string | undefined: опциональная цепочка добавляет undefined к результату, поэтому её обычно сочетают с ??. Поведение во время выполнения это обычный JavaScript; подробности о прерывании вычисления см. в разделе опциональная цепочка.

Двойной вопросительный знак: ??

a ?? b возвращает a, если оно не null и не undefined, иначе возвращает b. Он заменяет старую идиому a || b, которая отбрасывает ещё и 0, "", false и NaN:

function pageSize(input: number | undefined): string {
  const withOr = input || 20;      // 0 is falsy, so it is replaced
  const withNullish = input ?? 20; // only undefined is replaced
  return `${withOr} vs ${withNullish}`;
}

console.log(pageSize(undefined)); // 20 vs 20
console.log(pageSize(0));         // 20 vs 0

const scores = new Map([["Ada", 90]]);
const score: number = scores.get("Linus") ?? 0; // number | undefined becomes number
console.log(score);                             // 0

На уровне типов ?? убирает null и undefined из левой части и объединяет остаток с правой частью, поэтому scores.get("Linus") ?? 0 можно присвоить в number.

Присваивание при null: ??=

a ??= b присваивает b переменной a, только если a равно null или undefined. Родственные операторы ||= и &&= присваивают, когда левая часть ложна или истинна.

interface Options {
  retries?: number;
  label?: string;
}

function withDefaults(opts: Options) {
  opts.retries ??= 3;   // assign only if null or undefined
  opts.label ||= "job"; // assign if falsy, so "" is replaced too
  return opts;
}

console.log(withDefaults({}));                       // { retries: 3, label: 'job' }
console.log(withDefaults({ retries: 0, label: "" })); // { retries: 0, label: 'job' }

retries: 0 переживает ??=, а пустой label заменяется через ||=. После opts.retries ??= 3 TypeScript сужает opts.retries до number до конца функции.

Необязательные свойства и | undefined

nickname?: string и nickname: string | undefined при чтении ведут себя одинаково, но различаются тем, обязан ли ключ существовать:

interface WithOptional { nickname?: string }            // key may be missing
interface WithUndefined { nickname: string | undefined } // key must be present

const a: WithOptional = {};
const b: WithUndefined = { nickname: undefined };

// @ts-expect-error: Property 'nickname' is missing in type '{}' but required in type 'WithUndefined'.
const c: WithUndefined = {};

console.log("nickname" in a, "nickname" in b); // false true
console.log(a.nickname === b.nickname);        // true: both read as undefined

Используйте ?, когда вызывающий код может опустить свойство, и | undefined, когда нужно, чтобы каждый вызывающий код передавал его явно, даже если значение undefined. Параметр exactOptionalPropertyTypes (не входит в strict) ещё сильнее ужесточает ?: тогда nickname?: string отвергает { nickname: undefined } и принимает только отсутствующий ключ или строку. Необязательные параметры функций (x?: number) ведут себя как необязательные свойства: внутри функции x имеет тип number | undefined.

null или undefined: что использовать

TypeScript не заставляет выбирать, но смешение обоих в одной кодовой базе означает, что каждая проверка должна обрабатывать два случая. Распространённое соглашение:

• Используйте undefined (и необязательные свойства) для «не задано» в собственных типах. Именно это JavaScript выдаёт по умолчанию: отсутствующие свойства, пропущенные аргументы, промахи find и Map.get.
• Принимайте null там, где его отдаёт API: в JSON нет undefined, а String.prototype.match и многие методы DOM возвращают null.
• Проверяйте через == null, если значение может быть любым из двух.

Единственный пробел это индексация массивов: users[5] имеет тип элемента, даже если индекс вне диапазона. Параметр noUncheckedIndexedAccess (не входит в strict) добавляет | undefined к каждому обращению по индексу, чтобы компилятор ловил и это.