Строгость сверх strict: noUncheckedIndexedAccess и exactOptionalPropertyTypes

Про эту дыру в учебнике говорилось не раз — в статьях про массивы, про индексные сигнатуры, про strictNullChecks, — и каждый раз с оговоркой «разберём в главе про настройку». Разбираем. Вот она ещё раз.

const lines = ["первая строка", "вторая строка"];
const line = lines[2];

console.log(typeof line);
console.log(line.toUpperCase());

Тип string[] описывает, что лежит внутри, но не сколько элементов там лежит. Длина известна только во время исполнения, поэтому lines[2] компилятор честно считает строкой. Флаг noUncheckedIndexedAccess меняет одно-единственное правило: результат обращения по индексу получает | undefined.

Что при этом происходит, можно потрогать прямо здесь. Песочница учебника компилирует со strict и без этого флага, зато написать союз с undefined руками никто не мешает — диагностики получатся ровно те же.

// то же самое, что делает флаг: обращение по индексу даёт «строку или ничего»
const lines: (string | undefined)[] = ["первая строка", "вторая строка"];

console.log(lines[2].toUpperCase());

const first = lines[0];
console.log(first.length);

Два разных текста на одну и ту же беду. TS2532: Возможно, объект равен undefined — там, где значение осталось безымянным выражением. TS18048: Возможно, "first" имеет значение undefined — там, где оно попало в переменную и компилятору есть кого назвать по имени.

Флаг трогает только чтение. Записать undefined по индексу он по-прежнему не даст: rows[0] = undefined — это TS2322, «Тип undefined не может быть назначен для типа string».

Массивы — половина дела. Индексные сигнатуры и Record флаг задевает сильнее: у них вообще нет способа узнать, есть ли ключ. Причём рядом, в той же стандартной библиотеке, живёт коллекция, которая честна без всяких флагов.

const prices: Record<string, number> = { "чай": 250, "кофе": 400 };
const cache = new Map<string, number>([["чай", 250], ["кофе", 400]]);

// два одинаковых по смыслу обращения к отсутствующему ключу
console.log(prices["какао"] * 2);
const fromMap = cache.get("какао");
console.log(fromMap * 2);

Результат исполнения одинаковый, отношение компилятора — разное. У Map.prototype.get в сигнатуре написано V | undefined, и strict требует проверки. У квадратных скобок такой подписи нет, поэтому та же ошибка проходит молча. noUncheckedIndexedAccess просто распространяет привычку get и at на индексный доступ.

Первое впечатление от флага — «теперь проверка на каждый чих». Оно преувеличено: четыре приёма закрывают почти всё, и три из них вы пишете не задумываясь ещё с части I.

const rows = ["альфа", "бета"];

const head = rows[0];
if (head !== undefined) {
  console.log(head.length);
}

console.log((rows[9] ?? "пусто").toUpperCase());

for (const row of rows) {
  console.log(row.length);
}

for (const [i, row] of rows.entries()) {
  console.log(i, row.toUpperCase());
}

Ни одной диагностики — и с включённым флагом её тоже не будет. for..of в списке не случайно: флаг добавляет undefined к обращению по индексу, а не к типу элемента массива. Перебор, map, filter и entries остаются чистыми, и именно поэтому цена флага оказывается ниже ожидаемой.

А вот цикл со счётчиком он не прощает.

const rows: (string | undefined)[] = ["альфа", "бета"];

for (let i = 0; i < rows.length; i++) {
  console.log(rows[i].length);
}

Человек видит: i меньше rows.length, значит элемент на месте. Компилятор такую связь не отслеживает — он не считает арифметику и не знает, что длина не изменится внутри тела цикла. Выходов три: перейти на for..of, вынести элемент в переменную и проверить её или поставить !, взяв ответственность на себя.

const rows: (string | undefined)[] = ["альфа", "бета"];
const pair: [string, number] = ["код", 42];

console.log(pair[0].toUpperCase(), pair[1] + 1);

const [first] = rows;
console.log(first.length);

Второй флаг чинит неточность в необязательных полях. Для strict запись page?: number означает number | undefined, а значит, положить туда undefined руками не запрещено. В системе типов «поля нет» и «поле есть, и в нём undefined» сливаются в одно. В JavaScript они не сливаются нигде.

interface Filter {
  query: string;
  page?: number;
}

const absent: Filter = { query: "кот" };
const explicit: Filter = { query: "кот", page: undefined };

console.log(absent.page, explicit.page);
console.log("page" in absent, "page" in explicit);
console.log(Object.keys(absent).length, Object.keys(explicit).length);
console.log(JSON.stringify(absent) === JSON.stringify(explicit));

Вот и развилка. Чтение поля и JSON.stringify разницы не видят — оба объекта выглядят одинаково. in и Object.keys видят прекрасно. Любой код, который перебирает ключи, — счётчик заполненных фильтров, сборка строки запроса, сравнение «изменилось ли что-нибудь» — на втором объекте посчитает не то, и найти это по логам почти невозможно: в JSON всё в порядке.

exactOptionalPropertyTypes разводит эти случаи. С ним page?: number читается буквально: либо ключа нет, либо в нём число. Строка с явным undefined становится ошибкой TS2375: Невозможно назначить тип "{ query: string; page: undefined; }" типу "Filter", когда свойство "exactOptionalPropertyTypes" имеет значение "true". Рассмотрите возможность добавления типа "undefined" к типам свойств цели. Отдельное присваивание filter.page = undefined даёт похожую TS2412.

В песочнице учебника этот флаг не включён, поэтому примеры выше выполняются, а не падают на компиляции. Тексты диагностик настоящие: сняты с tsc 6.0.3 с включённым флагом.

Чтение при этом не меняется: filter.page и с флагом остаётся number | undefined — поля-то может не быть. Меняется только запись, и только явная.

Иногда undefined в поле осмысленно: не «значение не задали», а «значение сняли». Под флагом это пишется прямо в типе.

interface Draft {
  title: string;
  cover?: string | undefined; // undefined здесь значит «обложку сняли»
}

const withCover: Draft = { title: "Статья", cover: "cover.png" };
const noCover: Draft = { title: "Статья", cover: undefined };

console.log("cover" in withCover, "cover" in noCover);
console.log(noCover.cover);

cover?: string | undefined под флагом означает «можно не указывать, а можно указать пустым», и это уже договор, записанный в типе, а не догадка читателя. Без флага две записи, cover?: string и cover?: string | undefined, значат ровно одно и то же — потому и кажется, что вторая избыточна.

«Лишний ключ в объекте» звучит безобидно ровно до первого слияния объектов. Форма редактирования профиля: пользователь поменял имя, город не трогал.

interface Profile {
  name: string;
  city?: string;
}

const saved: Profile = { name: "Рико", city: "Дубай" };

// патч из формы: имя поменяли, город не трогали
const changes: Partial<Profile> = { name: "Рико Р.", city: undefined };
const next: Profile = { ...saved, ...changes };

console.log(next.city);
console.log(Object.keys(next));

Город потерян, и виновата одна запись в патче. Spread копирует все собственные ключи объекта, не разбирая значений: city в changes есть, значит undefined ляжет поверх «Дубая». Строка city: undefined выглядит как «поле не меняли», а работает как «поле очистить».

Чинится это не в момент слияния, а в момент сборки патча: ключа, который не меняли, в объекте быть не должно.

interface Profile {
  name: string;
  city?: string;
}

const saved: Profile = { name: "Рико", city: "Дубай" };
// поле, которого пользователь не касался, приходит из формы как null
const form: { name: string; city: string | null } = { name: "Рико Р.", city: null };

// ключ появляется в патче, только если значение есть
const changes: Partial<Profile> = {
  name: form.name,
  ...(form.city !== null ? { city: form.city } : {})
};

console.log(Object.keys(changes));
console.log({ ...saved, ...changes });

Условный spread — обычный приём из части I, здесь он получает смысл на уровне типов. С включённым exactOptionalPropertyTypes первый вариант просто не собрался бы: { city: undefined } не подходит под Partial<Profile>, потому что под флагом Partial тоже становится точным.

Полезное следствие: под флагом Partial означает «часть полей», а не «все поля, любое из которых можно занулить». Разница видна как раз в функциях обновления.

Второй способ ничем не хуже первого, если undefined в патче действительно должен стирать поле: объявите это в типе — city?: string | undefined. Тогда договор один и для компилятора, и для того, кто будет читать код через полгода.

Оба флага не входят в strict не потому, что они хуже остальных. strict стоит в огромном числе проектов, и каждая новая проверка внутри него ломала бы чужие сборки при обновлении компилятора. Пополняется он редко и осторожно — так в него в своё время попали strictFunctionTypes и useUnknownInCatchVariables, — а проверки, дающие много шума в обычном коде, живут отдельными флагами.

Цена у флагов разная. exactOptionalPropertyTypes дешёвый: он всплывает только там, где undefined пишут явно, и в новом коде почти незаметен. noUncheckedIndexedAccess дорогой: на существующем проекте он выдаёт диагностики сотнями, и часть из них — на местах, где элемент действительно всегда есть. Разумный порядок — сначала первый, потом второй, каждый отдельным коммитом: иначе в куче ошибок непонятно, что вы чините.

Быстрее всего noUncheckedIndexedAccess окупается там, где ключ или индекс приходят снаружи: разбор аргументов, словари по строковому ключу, результаты split и регулярных выражений, данные из JSON.parse. Мешает — в коде, который ходит по массиву индексами: сортировки, обмены элементов местами, ручные алгоритмы. Обычный компромисс — включить флаг на весь проект, а в паре таких мест поставить ! с коротким комментарием почему.

Последняя пара спорна: во время отладки она мешает — закомментировали две строки, и компилятор перестал собирать проект. Ту же работу лучше делает линтер: он ругается предупреждением, а не ошибкой сборки, и умеет прощать имена вроде _unused. Про это — последняя статья главы.