Руководство по использованию ts-reset для TypeScript

Типизация в JavaScript всегда была проблемой для разработчиков. Из-за его динамической типизации разработчикам из языков со строгой типизацией, таких как C# или Java, трудно приспособится к использованию JavaScript. TypeScript был введён для решения этой проблемы, но всё ещё отсутствуют некоторые желаемые возможности.

Одним из примеров является функция JSON.parse(). TypeScript делает вывод, что результат этой функции имеет тип any, что создаёт некоторые проблемы. Поскольку создаёт ложное впечатление, что представленный ответ безопасен для работы. Это может привести к нежелательным ошибкам. Вместо этого более ожидаемым подходом было бы вернуть тип unknown, что потребовало бы дополнительной проверки от разработчика.

Нажмите ts-reset, кнопку сброса CSS для TypeScript, цель которой улучшение типов для распространённых JS API интерфейсов. В этом руководстве мы рассмотрим, как использовать и настраивать ts-reset для TypeScript приложений.

Что такое ts-reset

ts-reset — пакет с открытым исходным кодом, предоставляющий набор правил, изменяющих встроенные типы TypeScript. ts-reset помогает улучшить типы TypeScript и делает его более соответствующим ожиданиям пользователей. Это также делает код более читабельным м удобным для сопровождения и позволяет избежать ошибок, вызванных ошибками типов. Вы можете думать об этом пакете, как о версии css-reset для TypeScript, представляющая собой список правил, которые сбрасывают все стили браузера по умолчанию, устраняя возможные несоответствия между разными браузерами.

Зачем нужен ts-reset

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

1. .json (в fetch) и JSON.parse возвращают тип any.
2. .filter(Boolean) выдаёт ложные значения

Введение ts-reset помогает решить эти проблемы, делая типизацию ожидаемой:

1. .json (в fetch) и JSON.parse возвращают тип unknown.
2. .filter(Boolean) ведёт себя так как вы ожидаете

Подробнее об этом поговорим в следующем разделе. Сначала давайте посмотрим, ка настроить пакет в проекте.

Настройка ts-reset в проекте

Начать работу с ts-reset очень просто. Первый шаг — установка проекта:

npm i -D @total-typescript/ts-reset

Затем создайте файл reset.d.ts в своём проекте со следующим кодом:

// Не добавляйте в этот файл ни каких других строк кода!
import "@total-typescript/ts-reset";

Теперь вы готовы начать! Если не хотите такого глобального использования и предпочитаете включать его только на основе файлов или даже на основе функций, можете использовать встроенный/inline подход. Для этого просто добавьте нужный хелпер вверху файла:

// Делает возвращаемый тип JSON.parse unknown
import "@total-typescript/ts-reset/json-parse";

//теперь применяется ts-reset
const result = JSON.parse("{}"); // unknown

NB., Чтобы этот импорт работал, необходимо убедиться, что для модуля установлено значение NodeNext или Node16 в tsconfig.json.

Варианты использования ts-reset

Теперь рассмотрим некоторые варианты использования пакета ts-reset, для решения перечисленных ранее проблем.

Делаем, чтобы JSON.parse возвращал тип unknown

import "@total-typescript/ts-reset/json-parse";

Без ts-reset JSON.parse вернул бы any. Это может вызвать неприятности, трудно уловимые баги, потому что они отключают проверку типов для описываемых ими значений:

// До
const result = JSON.parse({}); // any

С ts-reset возвращаемый тип JSON.parse меняется на unknown. Теперь нужно либо проверить unknown, чтобы убедиться, что это правильный тип, либо преобразовать его с помощью as:

// После
import "@total-typescript/ts-reset/json-parse";

const result = JSON.parse("{}"); // unknown

Делаем, чтобы .json() возвращал unknown

import "@total-typescript/ts-reset/fetch";

Точно так же, как JSON.parse(), .json(), возвращает тип any, вводя нежелательный тип any в код вашего приложения, что также может привести к неприятным багам:

// До
fetch("/")
  .then((res) => res.json())
  .then((json) => {
    console.log(json); // any
  });

Заставляя res.json возвращать тип unknown, мы осознаём необходимость проверки результатов fetch, поскольку теперь мы не доверяем результату метода res.json():

// После
import "@total-typescript/ts-reset/fetch";

fetch("/")
  .then((res) => res.json())
  .then((json) => {
    console.log(json); // unknown
  });

Делаем, чтобы .filter(Boolean) фильтровал ложные значения

import "@total-typescript/ts-reset/filter-boolean";

Поведение .filter по умолчанию может показаться довольно разочаровывающим. Учитывая приведённый ниже код:

// До
const filteredArray = [1, 2, undefined].filter(Boolean); // (number | undefined)[]

Кажется, естественным, что TypeScript должен понять, что вы отфильтровали undefined из filteredArray. Вы можете заставить это работать, но нужно пометить его как предикат типа:

const filteredArray = [1, 2, undefined].filter((item): item is number => {
  return !!item;
}); // number[]

Использование .filter(Boolean) является очень распространённым сокращением для этого. Итак, это правило делает так, что .filter(Boolean) действует как предикат типа переданного массива, удаляя любые ложные значения из элементов массива.

// После
import "@total-typescript/ts-reset/filter-boolean";

const filteredArray = [1, 2, undefined].filter(Boolean); // number[]

Будущие проблемы совместимости

Поскольку пакет ts-reset не требует настройки со стороны пользователя, у него нет проблем с совместимостью. Обратите внимание, что ts-reset предназначен для использования в коде приложения, а не в коде библиотеки. Это связано с тем, что каждое правило, которое вы включаете, будет вносить изменения в глобальную область, а это означает, что пользователи, импортирующие вашу библиотеку, будут неосознанно использовать ts-reset.

Заключение

ts-reset — отличный пакет утилит, помогающий решить проблемы с типами в JavaScript. В этой статье мы узнали, как можно использовать ts-reset для улучшения типизации в TypeScript по умолчанию, чтобы сделать её более предсказуемой и защищённой от ошибок. ts-reset помогает типам TypeScript вести себя в нашем коде так, как ожидается. Надеюсь, вы получите удовольствие от использования ts-reset для создания отличных проектов на TypeScript!