Перевод JS-проекта на TypeScript

По умолчанию компилятор видит только .ts и .tsx. В проекте, где четыреста файлов на JavaScript и один новый на TypeScript, это заметно с первой же строки: импорт старого модуля даёт TS7016: Не удалось найти файл объявления модуля "./utils.js" — и уточнение, что модуль получил неявный тип any.

allowJs: true снимает ограничение: .js-файлы попадают в программу как обычные исходники. Компилятор их разбирает, выводит из них типы, отдаёт подсказки редактору и — если сборкой занимается он же — компилирует наравне с .ts. Чего он при этом не делает, так это не жалуется: ошибки внутри старых файлов остаются невидимыми, пока не включён checkJs.

Стоит осознать, что вы получили в этот момент бесплатно. Вывод типов не требует аннотаций — об этом была статья про наведение в начале части. Компилятор знает форму каждого объектного литерала и тип каждой переменной в вашем старом коде, просто пока молчит о находках.

// обычный JavaScript: ни одной аннотации, а типы у компилятора уже есть
const rates = { usd: 92.5, eur: 99.1 };

console.log((rates.usd * 100).toFixed(2));

console.log((rates.rub * 100).toFixed(2));

Свойство "rub" не существует в типе "{ usd: number; eur: number; }" — компилятор перечислил в сообщении ровно то, что вывел из литерала двумя строками выше, без единой подсказки от автора. И обратите внимание на вывод: не падение, а NaN. Такие ошибки в JavaScript живут дольше всех — undefined * 100 не бросает исключение, а тихо расползается по отчёту.

allowJs — про состав сборки, checkJs — про придирки. Первый флаг ничего не ломает: он лишь пускает старые файлы внутрь.

checkJs: true включает для .js-файлов те же проверки, что работают в .ts. На проекте, который писали годами, это обычно означает несколько тысяч ошибок разом — цифру, после которой флаг выключают обратно и к миграции больше не возвращаются.

Поэтому у проверки есть вторая передача, файловая: checkJs остаётся выключенным, а в первую строку конкретного файла ставится комментарий // @ts-check. Проверяется только он. Очередь двигается по одному файлу, и в любой момент проект зелёный.

const cart = [
  { title: "Клавиатура", price: 4900 },
  { title: "Мышь", price: "1200" }
];

const total = cart.reduce((sum, item) => sum + item.price, 0);
console.log(total);

Оператор "+" невозможно применить к типам "number" и "string | number". Цена второго товара — строка, и reduce со второго шага перешёл на склейку: в консоли 49001200 вместо шести тысяч ста. Это типичная находка первого дня — ошибка не в новом коде, а в данных, которые лежали в проекте всё это время и никого не смущали.

Обратная директива — // @ts-nocheck в первой строке файла: он целиком выпадает из проверки, даже когда checkJs включён глобально. Ею закрывают то, что чинить некогда: сгенерированный код, древние скрипты сборки, файл, от которого зависит выкат.

Только не примите checkJs за «уже TypeScript». Это ступень помягче: к JavaScript-файлам компилятор относится снисходительнее и прощает привычные для языка вольности. Тот же самый код после переименования в .ts начинает ругаться — об этом дальше.

Хорошая цель на первую неделю — не «ноль ошибок», а «мы знаем их число». Включили checkJs, посчитали, выключили обратно.

Аннотацию в .js-файл не поставишь — это уже не JavaScript, и такой файл не запустит ни браузер, ни Node. Зато компилятор читает типы из комментариев JSDoc и понимает их всерьёз: те же проверки, те же коды ошибок, те же типы для всех, кто этот модуль импортирует.

/**
 * Цена с НДС, округлённая до рубля.
 * @param {number} price
 * @param {number} [rate] доля НДС, по умолчанию 0.2
 * @returns {number}
 */
function withVat(price, rate = 0.2) {
  return Math.round(price * (1 + rate));
}

/** @type {{ title: string, price: number }[]} */
const cart = [{ title: "Клавиатура", price: 4900 }];

console.log(withVat(cart[0].price));

Для среды выполнения это комментарии, и пример выше просто выполняется — песочница не пропускает .js через компилятор. А в проекте с // @ts-check в шапке вызов withVat("4900") дал бы TS2345: Аргумент типа "string" нельзя назначить параметру типа "number" — ровно то же самое, что сказала бы аннотация price: number в .ts-файле.

Зачем размечать то, что всё равно станет .ts? Ради соседей. Типы из JSDoc видны снаружи: новый .ts-файл, который импортирует размеченный модуль, получит настоящие типы вместо any. Поэтому общие модули — утилиты, клиент к API, форматтеры — размечают первыми, ещё до всякого переименования. А код, который переводить не собираются вовсе, так и живёт с типами в комментариях: скрипты сборки и старые страницы прекрасно себя чувствуют.

Одного JSDoc не переживает — переименования.

/**
 * @param {number} price
 * @returns {number}
 */
function withVat(price) {
  return price + price * 0.2;
}

console.log(withVat("4900"));

В .ts-файле компилятор JSDoc-типы не читает: там для этого есть синтаксис. Параметр остался голым, отсюда TS7006, а на исполнении "4900" + 980 честно склеилось в строку. Перенос делается почти механически по таблице выше, и редактор помогает: на такой функции у него есть быстрое действие «Annotate with type from JSDoc», которое переписывает сигнатуру за вас.

JSDoc-типы — не «типы для бедных», а тот же самый компилятор. Меняется только место, где написана аннотация.

Очередь на переименование выстраивают снизу вверх: сначала листья — модули, которые сами ничего не импортируют, затем их потребители, точка входа последней. Тогда каждый новый .ts-файл опирается на уже типизированный код, а не на any, и типы не приходится переписывать по второму разу.

Бесплатным переименование не бывает даже там, где код заведомо рабочий. Вот файл, который годами считал итоги и ни разу не ошибся.

// файл только что переименовали из totals.js в totals.ts, код не трогали
const totals = {};

function addLine(name, sum) {
  totals[name] = (totals[name] || 0) + sum;
}

addLine("Клавиатура", 4900);
addLine("Клавиатура", 100);
console.log(totals["Клавиатура"]);

Пять сообщений, три из них — TS7053: Элемент неявно имеет тип "any", так как выражение типа "any" не может использоваться для индексации типа "{}". Ни одно не про ошибку в логике. У параметров нет типов — это знакомая TS7006; а тип {}, выведенный из пустого литерала, не имеет ни одного свойства, поэтому запись по ключу компилятору непонятна. Вывод при этом правильный: типы живут только на этапе сборки, код как считал, так и считает.

Занятная деталь: переименование само по себе эти сообщения не породило — те же пять компилятор выдал бы и на .js, стоило включить там checkJs с noImplicitAny. Изменилось другое: у старого файла проверку можно было просто не включать, а .ts проверяется без всяких флагов. Настоящая поблажка для JavaScript-файлов работает на другом — на дописывании свойства через точку: const config = {}; config.retries = 3; в .js проходит молча, а в .ts даёт TS2339; запись по вычисляемому ключу, как в примере выше, ею не прикрыта. Добрая половина «внезапных» ошибок первого дня — вот такие: не новые баги, а старые вопросы, которые наконец задали вслух.

const totals: Record<string, number> = {};

function addLine(name: string, sum: number): void {
  totals[name] = (totals[name] || 0) + sum;
}

addLine("Клавиатура", 4900);
addLine("Клавиатура", 100);
console.log(totals["Клавиатура"]);

Починка уместилась в три аннотации, поведение не изменилось ни на йоту. Таким коммит и должен быть: переименовали, расставили типы, ничего не переписали. Смешивать переименование с рефакторингом — верный способ получить ревью на восемьсот строк, где не видно ни того ни другого.

// старый способ делать «классы» — до появления class в языке
function Timer() {
  this.count = 0;
}

console.log(typeof Timer);

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

const config = { retries: 3, url: "/api" };

// @ts-expect-error старая форма кладёт сюда строку, чиним вместе с формой
config.retries = "3";

console.log(config.retries, typeof config.retries);

// @ts-expect-error гасит ровно одну ошибку — ту, что на следующей строке. Текст после директивы компилятор не читает, но пишут его для людей: подпорка без объяснения через месяц неотличима от небрежности. И посмотрите на вывод: диагностику мы заглушили, а в поле по-прежнему строка. Директива чинит сборку, а не код.

const config = { retries: 3, url: "/api" };

// @ts-expect-error подпорка, поставленная на время миграции
config.retries = 5;

console.log(config.retries);

Вот главное отличие от старой директивы // @ts-ignore: @ts-expect-error требует, чтобы ошибка под ним была. Как только строку починили, подпорка сама поднимает руку — Unused '@ts-expect-error' directive. (по-английски даже при --locale ru: перевод у этой строки есть, но подставить его компилятор здесь не берётся). Долг не забывается: о нём напоминают ровно в тот день, когда его можно списать.

А самая опасная подпорка выглядит безобиднее всех.

type User = { name: string };

const user = JSON.parse("{\"name\":\"Рико\"}") as any;

console.log(user.name);
console.log(user.profile.email);

as any гасит не одну ошибку, а все, что могли бы вырасти из этой переменной: компилятор молчит, TypeError приезжает в браузер. У этой двери есть честный аналог — unknown с проверкой перед использованием, о котором была статья про данные извне. В миграции разница простая: @ts-expect-error и @ts-nocheck находятся поиском по проекту и когда-нибудь исчезают, а as any расползается и остаётся навсегда.

Подпорка хороша, пока она заметна. Если её не видно в поиске и она не жалуется сама — это уже не подпорка, а новый легаси.

Флаги удобно включать в том порядке, в каком растёт доверие к проекту: сначала компилятор просто присутствует, потом смотрит, потом требует.

Два пункта здесь важнее прочих. Первый — tsc в CI с самого начала, ещё когда он не находит ни одной ошибки: иначе к третьей неделе выяснится, что половина новых файлов не проверялась вообще. Второй — strict в конце, а не в начале. Свежий tsconfig.json включает строгость сразу, и для нового проекта это правильно; для старого она превращает первый день в стену из тысяч TS7006. Что именно за ней стоит, разбирала вторая статья этой главы.

Прогресс удобно мерить не ошибками, а файлами: сколько модулей уже .ts, сколько ещё под // @ts-nocheck. Число ошибок скачет от каждого флага и ничего не говорит команде, а число переведённых файлов растёт монотонно, и по нему видно, что миграция жива.

Худшая миграция — трёхмесячная ветка «переводим на TypeScript». Хорошая незаметна: каждый день пара файлов, и main всегда собирается.