Про esModuleInterop и совместимость модулей ES6 и CommonJS

Всем привет, хабровчане! Я (не)начинающий разработчик с относительно небольшим стажем, который пытается углубить свои знания в любимой технологии. В работе и повседневной жизни очень часто приходится работать с языком TypeScript, который мне очень нравится, но к своему стыду, сам очень плохо знаком с настройкой его конфигурации, поэтому решил восполнить этот пробел, ведя собственный Today I Learned. Некоторые опции tsconfig являются очень простыми и понятными. Другие же заставляют знатно напрячься. И даже если поверхностное назначение какой-то настройки является понятным, все равно возникает желание разобраться с принципом ее действия, понять, на какие структурные аспекты проекта она влияет, а также узнать, а как вообще людям жилось до ее появления.

Как раз об одном из них и пойдет разговор в этой статье, а именно об esModuleInterop. Действие опции проверялось при попытке подружить CommonJS-модуль с ES-модульным проектом. Поверхностная гуглешка не дала исчерпывающий ответ на ряд моих вопросов, поэтому приходилось обращаться к спецификации ES6, документации tsconfig (упаси боже читать документацию (шутка)), в личные блоги авторитетных в сообществе дядек (https://2ality.com/2014/09/es6-modules-final.html) и к описаниям модульных систем. На основе найденной информации я составил небольшое резюме, с попыткой собрать материал во едно. Надеюсь, кому-то он покажется интересным. Приятного чтения!

Небольшая предыстория

В июне 2015 года на свет появилась спецификация EcmaScript2015, которая подарила разработчикам нативную модульную систему с приятным синтаксисом по работе с зависимостями. До этого момента использовались синтетические модульные системы, которые пытались ограничить область видимости языковых единиц, к примеру IIFE, CommonJS, AMD с ее реализацией RequireJS, UMD и другие (источник).

Но сегодняшний день большая часть npm-пакетов для NodeJS написано с использованием модульной системы CommonJS. Попытка подружить их приводит к ряду (на мой взгляд) не критичных проблем. Однако в транспилятор tsc заложен механизм адаптации CommonJS модулей. Но сначала рассмотрим, как работали импорты до появлениях этих инструментов в babel и tsc.

Мой tsconfig:

{   "target": "es2022",   "module": "commonjs",   "rootDir": "./src",   "outDir": "./build",   "moduleResolution": "node",   // "esModuleInterop": true,   // "allowJs": true,   "importHelpers": false,   "forceConsistentCasingInFileNames": true,   "strict": true,   "skipLibCheck": true }

Использование CommonJS-пакетов с отключенными опциями

На самом деле при отсутствии этих опций мы уже можем работать с commonjs модулем. Чтобы импортировать сущности из этого модуля, можно воспользоваться именованным импортом или импортом пространства имен (не путать с namespace(-ом)).

Именованный импорт

Рассмотрим следующий пример:

// commonjs.js module.exports = {     sum: function (a, b) {         return a + b;     },     aboba: function() {         return undefined     } };  // index.ts import { aboba, sum } from './commonjs.js';  console.log(sum(1, 2)); console.log(aboba);

В результате имеем следующий транспилированный код:

// index.js "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); const commonjs_1 = require("./commonjs"); console.log((0, commonjs_1.sum)(1, 2)); console.log(commonjs_1.aboba);

Здесь можно увидеть, что tsc преобразовал код index.ts в commonjs-модуль. Это можно понять, взглянув на третью строчку, где транспилятор добавил признак «__esModule», чтобы пометить его как нативный es6 модуль (роль этого флага будет подробно рассматриваться в будущих примерах). В примере показано, что преобразованный index.js с помощью require загружает модуль commonjs.js, после чего идет обращение к импортированным sum и aboba.

Давайте еще остановимся на моменте вызова функции sum, которая почему-то оборачивается в круглые скобки, через запятую добавляется какой-то ноль, и только потом осуществляется сам вызов с переданными аргументами. На самом деле это прием, который использует транспилятор при импорте с помощью синтаксиса es6. Прием использует оператор «,», который возвращает последний элемент из этой последовательности. В данном случае будет возвращена ссылка на функцию sum. Дело в том, что при вызове sum напрямую через объект модуля, то контект this для этой функции будет определен как объект module.exports модуля commonjs.js. Извлекая sum из контекста модуля, транспилятор помещает ее в глобальный контекст, таким образом избегая нежелательных эффектов.

require-синтаксис

TypeScript предоставляет особый вид синтаксиса, который позволяет импортировать CommonJS и AMD модули подобно тому, как это делается в указанных модульных системах (ссылка на документацию https://www.typescriptlang.org/docs/handbook/2/modules.html).

// index.ts import module = require('./commonjs.js');  module.sum(1, 2);

Результат транспиляции:

"use strict"; Object.defineProperty(exports, "__esModule", { value: true }); const commonjsModule = require("./commonjs.js"); commonjsModule.sum(1, 2);

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

Еще один минус в пользу отказа от такого импорта — такой синтаксис импорта встроен в сам язык и не является частью стандарта es-модулей.

Импорт пространства имен

Следующий пример импорта:

import * as commonjsModule from './commonjs.js';  commonjsModule.sum(1, 2);

Результат транспиляции:

"use strict"; Object.defineProperty(exports, "__esModule", { value: true }); const commonjsModule = require("./commonjs.js"); commonjsModule.sum(1, 2);

Имеем, что импорт через пространство имен транспилируется в тот же самый код, что и при использовании require-синтаксиса. Почему для именованного импорта происходит перезатирание контекста модуля, а для других видов — я не могу ответить. Наверное, это какая-то особенность импортов и с этим нужно просто жить.

Промежуточное резюме

Наличие различных модульных систем, которые имеют разную внутреннюю организацию порождает множество вариации синтаксиса импорта/экспорта для работы с уже существующими модульными системами. Другая проблема — проблема с определениями типов при импорте. Современные версии TS-могут гибко определять импортируемые типы, однако для того же пространства имен происходит путаница.

Рассмотрим следующий пример для импорта пространства имен:

// commonjs.js module.exports = function () { }  // index.ts import * as commonjsModule from './commonjs.js';  commonjsModule();

В данном примере среда распознает commonjsModule одновременно и как module и как функцию без аргументов. Возможно в более ранних версиях TS сделал бы более жесткое предупреждение. Вообще стандарт ES6 для модулей требует, чтобы импорт namespace(-а) представлял собой объект с набором свойств, который описывает интерфейс модуля. А это значит, что на уровне организации ES6 и CommonJS модулей имеется несовместимость, поскольку CommonJS не удовлетворяет одному из требований спецификации (спецификация, документация tsconfig).

Еще одна проблема взаимодействия ES6 и CommonJS модулей — разная реализация импорта по умолчанию. Синтаксис ES6 предоставляет возможность экспортировать сущность через конструкцию export default (одна сущность на весь модуль). Такая конструкция дает разработчикам некоторые приятные возможности:

• разноcить сущности отдельно по собственным модулям (как, например, это реализовано в языке Java);

• пользоваться удобной и простой конструкцией импорта сущности по умолчанию.

Кроме того, экспорт по умолчанию может присутствовать в модуле совместно с именованным экспортом.

Напротив, CommonJS модули не могут использовать именованный и дефолтный экспорт одновременно.

// Именованный module.exports = {     sum: (a, b) => a + b,     aboba: function() { } };  // Импорт по умолчанию module.exports = function () {  }

Отсюда вытекает еще одна задача на пути к достижению совместимости ES и CommonJS -модулей.

Использование транспилятора для адаптации CommonJS модулей к ES6

Проблему совместимости решают различные транспиляторы кода. Среди популярных иснтрументов можно выделить tsc и babel. Так как эта статья появилась в результате разбора опций tsconfig, то далее будет рассматриваться код, сгенерированный утилитой tsc.

В контексте TS проблема совместимости решается при помощи опции esModuleInterop, которая в процессе компиляции добавляет хэлперы в ES6-модули, которые осуществляют преобразование зависимостей (CommonJS-модулей) в совместимые модули. Эти функции имеют имена _importDefault и _importStar.

__importDefault

Рассмотрим следующий пример:

// commonjs.s module.exports = {     sum: (a, b) => a + b,     aboba: function() {} };  // index.ts import commonjsModule from './commonjs.js';  commonjsModule.sum(1, 2);

В результате транспиляции получаем:

"use strict"; var __importDefault = (this && this.__importDefault) || function (mod) {     return (mod && mod.__esModule) ? mod : { "default": mod }; }; Object.defineProperty(exports, "__esModule", { value: true }); const commonjs_1 = __importDefault(require("./commonjs.js")); commonjs_1.default.aboba();

Как видно из примера загрузка CommonJS-модуля осуществляется при помощи require, вызов которой оборачивается в хэлпер. Хэлпер устроен достаточно просто. Он проверяет наличие признака __esModule. Если он выставлен, то переданный модуль является нативным ES6 модулем (как, например, index.ts, для которого транспилятор специально устанавливал этот флаг) и он возвращается как есть. Иначе импортированный объект оборачивается в default.

Кажется, что такая конструкция немного спорная, потому что в default помещается весь объект нашего модуля. Однако заранее узнать, что именно наодится в module.exports (объект со свойствами|константа|вызываемое выражение и другие) — невозможно. Подобное решение в целом удовлетворяет спецификации.

Примечание: В приведенном примере используется конструкция синтетического дефолтного импорта, которая доступна благодаря опции allowSyntheticDefaultImports, которая автоматически устанавливается в true, когда выставлен флаг esModuleInterop. В обычной ситуации TS-анализатор выкинул бы ошибку, что для модуля с отсутсвующим default-экспортом такая конструкция недопустима. Однако выставленный набор опции позволяет работать с commonjs модулем подобным образом.

__importStar

Рассмотрим следующий пример с тем же CommonJS модулем, но с импортом простнаства имен:

import * as commonjsModule from './commonjs.js';  commonjsModule.sum(1, 2); commonjsModule.aboba();

Результат:

"use strict"; var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {     if (k2 === undefined) k2 = k;     var desc = Object.getOwnPropertyDescriptor(m, k);     if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {       desc = { enumerable: true, get: function() { return m[k]; } };     }     Object.defineProperty(o, k2, desc); }) : (function(o, m, k, k2) {     if (k2 === undefined) k2 = k;     o[k2] = m[k]; })); var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {     Object.defineProperty(o, "default", { enumerable: true, value: v }); }) : function(o, v) {     o["default"] = v; }); var __importStar = (this && this.__importStar) || (function () {     var ownKeys = function(o) {         ownKeys = Object.getOwnPropertyNames || function (o) {             var ar = [];             for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;             return ar;         };         return ownKeys(o);     };     return function (mod) {         if (mod && mod.__esModule) return mod;         var result = {};         if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);         __setModuleDefault(result, mod);         return result;     }; })(); Object.defineProperty(exports, "__esModule", { value: true }); const commonjsModule = __importStar(require("./commonjs.js")); commonjsModule.sum(1, 2); commonjsModule.aboba();

Если вкратце, то эта функция перебирает каждое свойство из импортированного объекта с помощью require, и на их основе формирует новый объект, который удовлетворяет спецификации ES6-модуля, добавляя default для экспорта по умолчанию.

Резюме

В итоге получаем, что опция esModuleInterop с allowSyntheticDefaultExport (включается автоматически с esModuleInterop) облегчет нам взаимодействие с другими модульными системами, позволяя нам как разработчикам писать более привычные импорты с использованием современного синтаксиса с корректной поддержкой типов.

Немного про importHelpers

Как вы могли заметить, реализация совместимости модулей создает достаточно много бойлерплейта, который увеличивает размер скомпилированного кода. Подобный код будет добавлен в каждый модуль, использующий импорт CommonJS. Чтобы решить эту проблему можно воспользоваться флагом importHelpers, который будет брать реализацию этих функций из библиотеки tslib (ее так же нужно будет добавить в ваш package.json)

P.S.

Спасибо всем, кто дочитал до конца! Буду рад комментариям и предложениям