Малоизвестные возможности TypeScript, которые стоит изучить
Разберите семь малоизвестных возможностей TypeScript: const-параметры, NoInfer, функции утверждения и verbatimModuleSyntax, с версиями и примерами кода.
Семь возможностей TypeScript, которыми многие опытные разработчики до сих пор не пользуются: const-параметры типа (5.0), NoInfer (5.4), функции-утверждения (3.7), именованные элементы кортежей (4.0), аннотации вариантности (4.7), ключевое слово accessor (4.9), а также import type в сочетании с verbatimModuleSyntax (3.8 и 5.0).
Если вы освоили TypeScript во времена 4.x и с тех пор были заняты выпуском релизов, вы, скорее всего, по-прежнему пишете as const в местах вызова и добавляете лишние параметры типа, чтобы вывод типов не расширял их. В новых версиях и то и другое делается короче.
В статье по очереди разбирается каждая возможность: что она делает, в какой версии появилась, и приводится один короткий пример, который компилируется в режиме strict.
Ключевые выводы
const-параметр типа (TypeScript 5.0) выводит для["/", "/users"]типreadonly ["/", "/users"], если ограничение доступно только для чтения, напримерreadonly string[].NoInfer<T>(TypeScript 5.4) исключает параметр из источников вывода типов, поэтому значение по умолчанию не может расширить тип, заданный остальными аргументами.- Функция-утверждение с сигнатурой
asserts value is Tсужает тип аргумента во всей оставшейся части области видимости после вызова, а не только внутри блокаif. - При
verbatimModuleSyntaxимпорт удаляется только тогда, когдаtypeотносится ко всей инструкции.import { type X } from "./mod"превращается вimport {} from "./mod", поэтому модуль всё равно выполняется.
Продвинутые возможности TypeScript по версиям
В таблице перечислены все семь малоизвестных возможностей TypeScript с указанием версии, в которой они появились, и разработчиков, для которых они наиболее актуальны.
| Возможность | Появилась в | Основная аудитория |
|---|---|---|
| Функции-утверждения | 3.7 | Код приложений и библиотек |
import type | 3.8 | Конфигурация сборки |
| Именованные элементы кортежей | 4.0 | Авторы хуков и API |
Аннотации вариантности (in/out) | 4.7 | Авторы библиотек |
Ключевое слово accessor | 4.9 | Пользователи декораторов |
| const-параметры типа | 5.0 | Авторы обобщённых API |
verbatimModuleSyntax | 5.0 | Конфигурация сборки |
NoInfer<T> | 5.4 | Авторы обобщённых API |
Const-параметры типа (TypeScript 5.0)
В TypeScript 5.0 появился модификатор const для параметров типа. Он заставляет компилятор выводить типы литералов массивов и объектов так, как если бы вызывающая сторона написала as const. Вызывающему коду больше не нужно помнить об утверждении, чтобы получить литеральные типы.
Если нужен результат только для чтения, сочетайте модификатор const с readonly-ограничением. При изменяемом ограничении, например string[], TypeScript с 5.0 по 5.2 откатывался к string[]. Начиная с 5.3 компилятор выводит изменяемый кортеж. Кроме того, модификатор const действует только на литералы, записанные непосредственно в вызове. Переменная, объявленная ранее, сохраняет уже расширенный тип.
function defineRoutes<T extends readonly string[]>(paths: T): T { return paths; }
const a = defineRoutes(["/", "/users"]); // string[]
function defineRoutesExact<const T extends readonly string[]>(paths: T): T { return paths; }
const b = defineRoutesExact(["/", "/users"]); // readonly ["/", "/users"]
function defineRoutesMutable<const T extends string[]>(paths: T): T { return paths; }
const c = defineRoutesMutable(["/", "/users"]); // ["/", "/users"] (TS 5.3+; string[] in 5.0–5.2)
NoInfer для управления выводом типов (TypeScript 5.4)
NoInfer<T>, добавленный в TypeScript 5.4, не позволяет компилятору использовать указанный аргумент как источник вывода типов. Вместо того чтобы расширять тип, этот аргумент проверяется на соответствие типу, выведенному из остальных параметров. До версии 5.4 обычным обходным путём был второй параметр типа, ограниченный первым. Это работало, но добавляло параметр типа, который встречался в сигнатуре лишь один раз.
function createSelect<T extends string>(options: T[], initial: NoInfer<T>) {
return { options, value: initial };
}
createSelect(["draft", "published"], "draft"); // OK
createSelect(["draft", "published"], "archived");
// Error: Argument of type '"archived"' is not assignable
// to parameter of type '"draft" | "published"'.
Без NoInfer тип T расширился бы до "draft" | "published" | "archived", и опечатка скомпилировалась бы. Справочник по утилитарным типам описывает его наряду с Partial и Pick.
Функции-утверждения (TypeScript 3.7)
Функция-утверждение сужает тип своего аргумента во всей оставшейся части объемлющей области видимости, если она завершилась без исключения. Поэтому она хорошо подходит для защитных проверок в стиле fail-fast, которым не нужно ветвление. Type guard (value is T) сужает тип только внутри условия, в котором вызывается. Сигнатура asserts value is T, появившаяся в TypeScript 3.7, сужает тип для всего кода после вызова.
function assertIsDefined<T>(value: T, name = "value"): asserts value is NonNullable<T> {
if (value === undefined || value === null) {
throw new Error(`${name} is not defined`);
}
}
const root = document.getElementById("app"); // HTMLElement | null
assertIsDefined(root, "#app");
root.classList.add("ready"); // root: HTMLElement
У функций-утверждений есть один подвох. Если написать вспомогательную функцию как стрелочную и присвоить её const без аннотации типа, в месте вызова возникнет ошибка «Assertions require every name in the call target to be declared with an explicit type annotation». Используйте либо объявление функции (function declaration), либо явно укажите тип для const.
Именованные элементы кортежей (TypeScript 4.0)
Именованные элементы кортежей, добавленные в TypeScript 4.0, позволяют дать имя каждой позиции в типе кортежа. Эти имена отображаются во всплывающих подсказках редактора, подсказках по сигнатурам и сообщениях об ошибках. Метки кортежа влияют только на то, что показывают редакторы и сообщения об ошибках. Они не меняют тип кортежа, и вызывающий код может деструктурировать элементы под любыми именами. Начиная с TypeScript 5.2 в одном кортеже можно сочетать именованные и неименованные элементы.
Классический сценарий — тип возвращаемого значения в стиле хука:
type ToggleState = [isOn: boolean, toggle: () => void];
function useToggle(initial = false): ToggleState {
let isOn = initial;
return [isOn, () => { isOn = !isOn; }];
}
const [open, toggleOpen] = useToggle(); // any names work; labels show in hovers
Аннотации вариантности: in и out (TypeScript 4.7)
Аннотации вариантности, появившиеся в TypeScript 4.7, позволяют явно указать, является ли параметр типа ковариантным (out), контравариантным (in) или и тем и другим. Аннотации вариантности предназначены в основном для авторов библиотек. В коде приложений они почти никогда не нужны. В заметках к версии 4.7 они представлены как способ задокументировать намерение, а для глубоко рекурсивных типов — ускорить проверку типов. TypeScript сообщает об ошибке, если аннотация противоречит фактическому использованию параметра, но допускает аннотации строже необходимого.
interface Producer<out T> { get: () => T }
interface Consumer<in T> { accept: (value: T) => void }
interface Bad<in T> { get: () => T }
// Error: Type 'Bad<super-T>' is not assignable to type 'Bad<sub-T>'
// as implied by variance annotation.
Ключевое слово accessor (TypeScript 4.9)
В TypeScript 4.9 появились автоаксессоры. Автоаксессор объявляется как поле класса, но с префиксом accessor. Компилятор превращает его в пару геттер/сеттер, работающую с недоступным приватным полем. Таким образом, автоаксессор даёт декоратору единую точку для перехвата как чтения, так и записи поля.
В примере ниже используется стандартная сигнатура декоратора из TypeScript 5.0 с типами из встроенного в компилятор файла decorators.d.ts. Для него параметр experimentalDecorators должен быть отключён, поскольку у устаревших декораторов другая сигнатура.
function logged<This, V>(
target: ClassAccessorDecoratorTarget<This, V>,
context: ClassAccessorDecoratorContext<This, V>
): ClassAccessorDecoratorResult<This, V> {
return {
set(value) {
console.log(`set ${String(context.name)} =`, value);
target.set.call(this, value);
},
};
}
class Settings {
@logged accessor theme = "light";
}
import type с verbatimModuleSyntax (TypeScript 3.8 и 5.0)
При включённом verbatimModuleSyntax TypeScript удаляет импорт только тогда, когда type относится ко всей инструкции. Все остальные импорты выводятся в том виде, в каком они написаны. Синтаксис import type существует со времён TypeScript 3.8. Сам флаг появился в 5.0 и заменил importsNotUsedAsValues и preserveValueImports, которые были объявлены устаревшими в 5.0 и отсутствуют в TypeScript 7.
{ "compilerOptions": { "verbatimModuleSyntax": true } }
import type { User } from "./api"; // erased entirely
import { fetchUser, type Post } from "./api"; // emits: import { fetchUser } from "./api";
import { type Config } from "./config"; // emits: import {} from "./config";
На третьей строке, import { type Config }, многие спотыкаются. Встроенный модификатор type всё равно оставляет пустой импорт, поэтому модуль загружается и его побочные эффекты выполняются. После включения флага любой тип, импортированный без модификатора type, становится ошибкой компиляции. Миграция сводится в основном к замене именованных импортов, содержащих только типы, на import type.
Смежные темы по продвинутому TypeScript
Несколько тем намеренно не вошли в статью, поскольку им посвящены отдельные материалы:
- Практическое руководство по оператору satisfies в TypeScript
- Разбираемся с infer в TypeScript
- Как JavaScript наконец научился убирать за собой (ключевое слово
using) - Лучшие практики TypeScript для крупных проектов (включая branded-типы)
- 5 советов по улучшению кода на TypeScript
Заключение
Большинство этих возможностей либо заменяют обходные решения, либо переносят проверку из соглашений, соблюдаемых во время выполнения, в систему типов. const-параметры типа и NoInfer обеспечивают обобщённым API точный вывод типов, не требуя от вызывающей стороны дополнительных усилий. Функции-утверждения и именованные кортежи делают повседневный код приложений строже, а verbatimModuleSyntax делает генерируемые импорты предсказуемыми. Практичный первый шаг — включить verbatimModuleSyntax в одном пакете, исправить импорты типов, на которые укажет компилятор, а затем добавить const ко всем обобщённым функциям, которые сейчас требуют от вызывающего кода дописывать as const.
Часто задаваемые вопросы
Работает ли verbatimModuleSyntax в проектах, которые генерируют CommonJS?
Да, но файлы, компилируемые в CommonJS, должны использовать синтаксис TypeScript в стиле CommonJS: import fs = require('fs') для импорта и export = для экспорта. Инструкции import и export в стиле ESM в таких файлах приводят к ошибке компиляции. Актуальные версии сообщают о ней как TS1295 и предлагают изменить поле type в package.json или скорректировать настройки module. Файлы, компилируемые в ESM, сохраняют обычный синтаксис import и export.
Нужен ли isolatedModules, если включён verbatimModuleSyntax?
Нет. Согласно справочнику TSConfig, при включённом verbatimModuleSyntax параметр isolatedModules по умолчанию имеет значение true, поэтому его проверки для пофайловой транспиляции применяются автоматически, и явную запись можно удалить. Эти проверки важны для таких инструментов, как esbuild, SWC и Babel, которые компилируют каждый файл отдельно и не могут определить, является ли импортируемое имя типом или значением.
Может ли функция-утверждение быть асинхронной?
Нет. В TypeScript нет асинхронной сигнатуры утверждения, поэтому тип возвращаемого значения вида Promise<asserts value is T> недопустим. Эту возможность запрашивали в issue 37681 репозитория TypeScript, но в язык она не входит. Обычный обходной путь — сначала дождаться (await) завершения асинхронной операции, а затем вызвать синхронную функцию-утверждение для результата, либо сделать так, чтобы асинхронная функция возвращала проверенное значение с суженным типом.
Complete picture for complete understanding
Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.
Star on GitHub12k