12k
All articles

Малоизвестные возможности TypeScript, которые стоит изучить

Разберите семь малоизвестных возможностей TypeScript: const-параметры, NoInfer, функции утверждения и verbatimModuleSyntax, с версиями и примерами кода.

OpenReplay Team
OpenReplay Team
Малоизвестные возможности TypeScript, которые стоит изучить

Семь возможностей 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 type3.8Конфигурация сборки
Именованные элементы кортежей4.0Авторы хуков и API
Аннотации вариантности (in/out)4.7Авторы библиотек
Ключевое слово accessor4.9Пользователи декораторов
const-параметры типа5.0Авторы обобщённых API
verbatimModuleSyntax5.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

Несколько тем намеренно не вошли в статью, поскольку им посвящены отдельные материалы:

Заключение

Большинство этих возможностей либо заменяют обходные решения, либо переносят проверку из соглашений, соблюдаемых во время выполнения, в систему типов. 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) завершения асинхронной операции, а затем вызвать синхронную функцию-утверждение для результата, либо сделать так, чтобы асинхронная функция возвращала проверенное значение с суженным типом.

Open-source session replay

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

We use cookies to improve your experience. By using our site, you accept cookies.