Аннотация /*#__PURE__*/

В системе сборки JavaScript выражение `/*

Основная идея аннотации заключается в указании компилятору, что конкретный вызов функции или выражение не имеет побочных эффектов. Это означает, что если результат вызова не используется, такой код можно полностью удалить без изменения поведения программы.

Механизм tree-shaking в Esbuild

Esbuild реализует tree-shaking на уровне анализа импортов и экспорта ES Modules. В отличие от более сложных систем, где анализ может выполняться в несколько проходов и учитывать разнообразные побочные эффекты, Esbuild стремится к максимально быстрому и детерминированному подходу.

Удаление неиспользуемого кода становится возможным при соблюдении нескольких условий:

  • использование ESM-структуры (import/export)
  • отсутствие побочных эффектов у удаляемого выражения
  • корректная маркировка чистых вызовов

Именно последнему условию и служит /*#__PURE__*/.

Семантика /#PURE/

Аннотация размещается непосредственно перед вызовом функции или созданием объекта:

const value = /*#__PURE__*/ createExpensiveObject();

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

Для Esbuild это сигнал:

  • вызов createExpensiveObject() не изменяет внешнее состояние
  • если value не используется, выражение можно удалить
  • побочные эффекты отсутствуют

Таким образом, аннотация превращается в инструмент тонкой настройки поведения оптимизатора.

Условия корректного удаления кода

Даже при наличии /*#__PURE__*/ Esbuild не всегда удаляет выражение. Оптимизация происходит только при соблюдении строгих условий:

1. Отсутствие использования результата

Если результат вызова сохраняется или передаётся дальше, удаление невозможно:

const obj = /*#__PURE__*/ createExpensiveObject();
console.log(obj);

2. Локальность выражения

Удаляемое выражение должно находиться в области, где его исключение не влияет на внешнюю логику модуля.

3. Отсутствие скрытых побочных эффектов

Если функция внутри аннотированного вызова изменяет глобальное состояние, удаление становится небезопасным. Esbuild в таких случаях сохраняет код, даже если аннотация присутствует.

Практическое применение в библиотеках

В библиотечном коде аннотация используется для ускорения tree-shaking на уровне потребителя.

Типичные сценарии:

  • ленивое создание объектов конфигурации
  • инициализация вспомогательных структур
  • построение метаданных
  • создание классов-обёрток

Пример:

export function createClient() {
  return /*#__PURE__*/ new HttpClient({
    timeout: 5000,
    retries: 3
  });
}

Если createClient не используется, Esbuild может удалить её полностью, включая создание HttpClient.

Влияние на размер бандла

При больших зависимостях даже небольшие участки неиспользуемого кода приводят к заметному увеличению итогового файла. Использование /*#__PURE__*/ позволяет:

  • уменьшить размер итогового бандла
  • ускорить загрузку модулей в браузере
  • снизить время парсинга JavaScript
  • улучшить эффективность кеширования

Особенно заметен эффект в UI-библиотеках и SDK, где часто присутствуют десятки вспомогательных функций.

Связь с архитектурой ES Modules

Esbuild опирается на статический анализ импортов. Это означает, что он может заранее определить, какие части кода используются, а какие нет.

Аннотация /*#__PURE__*/ дополняет эту модель, позволяя уточнить поведение внутри модулей:

  • импорт остаётся видимым на уровне графа зависимостей
  • внутренняя логика может быть дополнительно оптимизирована
  • удаление происходит внутри модуля, а не только между модулями

Таким образом, аннотация работает как локальный модификатор поведения оптимизатора.

Отличие от аналогичных систем

В других инструментах сборки поведение может отличаться:

  • в Webpack аннотация также используется, но анализ побочных эффектов сложнее и может зависеть от настроек
  • в Rollup tree-shaking более агрессивный, но чувствителен к структуре кода
  • Esbuild делает упор на скорость и предсказуемость, поэтому использует более строгую модель

В Esbuild важно, чтобы код был максимально «чистым» с точки зрения анализа, иначе оптимизация ограничивается.

Использование с конструкторами и объектами

Частый сценарий — создание объектов:

const config = /*#__PURE__*/ new Config({
  debug: false,
  cache: true
});

Если config не используется, весь вызов может быть исключён.

Однако при наличии статических побочных эффектов в конструкторе удаление не выполняется, даже если аннотация присутствует.

Влияние на инлайнинг и минимизацию

Esbuild выполняет не только tree-shaking, но и другие оптимизации:

  • удаление мёртвого кода
  • упрощение выражений
  • объединение констант
  • инлайнинг простых функций

/*#__PURE__*/ усиливает эффективность этих этапов, позволяя безопасно сокращать цепочки вызовов.

Пример:

const result = /*#__PURE__*/ computeA(computeB(computeC()));

Если result не используется, вся цепочка может быть удалена.

Ограничения аннотации

Несмотря на мощность, аннотация не является универсальным инструментом оптимизации.

Она не влияет на:

  • код с побочными эффектами
  • динамически вызываемые функции
  • рефлексивные конструкции
  • код, зависящий от runtime-условий

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

Взаимодействие с минификацией

Esbuild объединяет tree-shaking и минификацию в едином пайплайне. Аннотация помогает на этапе удаления кода, после чего оставшиеся выражения проходят через сокращение идентификаторов и упрощение синтаксиса.

Это особенно важно для библиотек, где:

  • исходный код читаем
  • итоговый бандл должен быть максимально компактным
  • структура модулей сохраняется, но упрощается

Поведение в сложных выражениях

Аннотация может применяться не только к простым вызовам, но и к вложенным структурам:

const data = /*#__PURE__*/ factoryA(factoryB(factoryC(input)));

Если результат не используется, вся цепочка может быть удалена, при условии отсутствия побочных эффектов в каждом звене.

Роль в экосистеме сборки

Аннотация /*#__PURE__*/ стала стандартом де-факто для обозначения чистых выражений в JavaScript. Esbuild поддерживает её как часть общей стратегии оптимизации, ориентированной на высокую скорость сборки без сложных эвристик.

Её использование особенно важно в коде, который:

  • публикуется как npm-библиотека
  • предназначен для повторного использования
  • должен быть оптимизируемым конечным потребителем

В таких условиях корректная маркировка чистых выражений становится частью архитектуры библиотеки, а не просто косметической оптимизацией.

Оглавление