Круг зависимостей: свой CommonJS против настоящего ESM

В статье про require загрузчик клал пустой module в кеш до того, как выполнить тело файла. Строчка незаметная, но на ней держится весь круг. Пусть notes.cjs первым делом подключает users.cjs, а тот — notes.cjs. Загрузчик начинает notes, доходит до require и начинает users, а users просит notes. Выполнять notes второй раз загрузчик не станет: запись уже в кеше. И users получает объект exports таким, какой он сейчас, — тело notes остановилось на строке с require и ещё ничего в него не записало.

Проверим на модели. load из статьи про require лежит в подложке, а файлы — те же, что потом пойдут в настоящий node. users берёт notes двумя способами: целым объектом и деструктуризацией поля limit. Функцию format, которая читает лимит обоими путями, notes вызовет, когда допишет свои поля. Прогноз: что напечатает строка «users видит notes.create» и какие два значения лимита окажутся в строке про Аню?

// files и load из статьи про require — в подложке
files["/app/notes.cjs"] = `
console.log("notes: начало");
const users = require("./users.cjs");
exports.limit = 100;
exports.create = (author, text) => users.format(author) + ": " + text;
console.log(exports.create("Аня", "привет"));
console.log("notes: конец");
`;
files["/app/users.cjs"] = `
console.log("users: начало");
const notes = require("./notes.cjs");
const { limit } = require("./notes.cjs");
console.log("users видит notes.create:", typeof notes.create);
exports.format = (name) => name + " (limit " + limit + ", notes.limit " + notes.limit + ")";
console.log("users: конец");
`;

load("/app/notes.cjs");

Правило чтения CommonJS-круга: опасно не само подключение, а чтение во время загрузки. Всё, что модуль в круге берёт у соседа на верхнем уровне файла, — деструктуризация, вызов его функции, проверка поля — берётся из недописанного объекта. То, что читается позже, внутри функций, видит объект законченным.

Кто из двух получит половину, решает порядок подключения, а не сами файлы. Запустите первым users.cjs — и недописанный объект достанется уже notes, а его вызов users.format упадёт с TypeError.

Такое undefined ничем не отличается от честного, поэтому Node подсказывает: когда модуль в круге читает у недописанного exports поле, которого там нет, печатается предупреждение Accessing non-existent property … of module exports inside circular dependency. Устроено оно небольшим приёмом, который стоит повторить: в прототип недописанного объекта Node ставит Proxy — объект, чья ловушка get срабатывает на чтение поля, как в модели реестра нативных модулей.

Почему прототип, а не обёртка вокруг exports. Обращение к полю сначала ищет его в самом объекте и только не найдя идёт по прототипу — значит, ловушка get в прототипе срабатывает ровно на отсутствующих полях, а записанные читаются как обычно. Объект при этом остаётся тем же самым: users держит ссылку на настоящий exports и увидит поля, когда notes их допишет. Обёртку пришлось бы отдавать вместо объекта, и снять её после загрузки было бы нельзя: ссылка на неё уже осталась бы у users. А прототип загрузчик просто возвращает на место, когда тело модуля выполнено.

Перепишем load. Если модуль найден в кеше, но ещё не loaded, — это круг, и загрузчик ставит сторожа в прототип, когда там обычный Object.prototype. После выполнения тела сторож снимается. Файлы прежние. Прогноз: сколько предупреждений напечатается, про какие поля и будет ли предупреждение, когда format прочитает notes.limit?

// files с notes.cjs и users.cjs, dirname и resolve — в подложке; load пишем заново
const cache = {};

// сторож для прототипа недописанного exports
const warnOnMissing = new Proxy({}, {
  get(target, prop) {
    if (prop in target) return target[prop];
    console.log(`предупреждение: обращение к ещё не записанному полю '${String(prop)}' внутри круга`);
    return undefined;
  },
});

function load(path) {
  const cached = cache[path];
  if (cached && !cached.loaded && Object.getPrototypeOf(cached.exports) === Object.prototype) {
    Object.setPrototypeOf(cached.exports, warnOnMissing);
  }
  if (cached) return cached.exports;
  const module = { exports: {}, loaded: false };
  cache[path] = module;
  const require = (spec) => load(resolve(path, spec));
  new Function("exports", "require", "module", files[path])(module.exports, require, module);
  module.loaded = true;
  if (Object.getPrototypeOf(module.exports) === warnOnMissing) {
    Object.setPrototypeOf(module.exports, Object.prototype);
  }
  return module.exports;
}

load("/app/notes.cjs");

Проверка Object.prototype перед установкой — тоже как в Node: сторож встаёт только на обычный объект. Если модуль успел заменить module.exports функцией или классом, подменённый прототип отнял бы у функции унаследованные call и bind.

Самый злой вариант круга — модуль, который отдаёт себя через module.exports = …. Тот, кто получил объект раньше, остаётся со старым пустым объектом навсегда: присваивание поменяло поле module.exports, а не содержимое объекта, который уже раздан. Сторожа Node снимает только с того, что лежит в module.exports после выполнения тела, — со старого объекта его никто не снимет. Поэтому предупреждение, пришедшее, когда все модули давно загружены, почти всегда значит одно: у кого-то в руках старый объект модуля, который заменил module.exports.

TypeScript, собирая import и export в CommonJS, в начале файла ставит exports.__esModule, а обращения пишет как notes_1.limit — чтением поля при каждом использовании. На такой exports Node сторожа не ставит, и в скомпилированном проекте круг проходит без предупреждения.

Теперь ES-модули. Их загрузчик моделировать не нужно: он встроен в браузер, а связывание и порядок выполнения модулей задаёт сама спецификация языка — те же, что у Node. Песочнице учебника не хватает только файлов. Имя модуля превращает в адрес карта импортов — та, что давала адрес пакету dayjs, а файл заменяет Blob: URL.createObjectURL выдаёт куску текста адрес вида blob:…, и import загружает по нему модуль, как по адресу файла.

Функция modules в подложке делает оба шага: каждому исходнику — blob-адрес, всем именам — одна карта импортов на странице примера. Модули поэтому подключают друг друга именами из карты, а не путями: относительный путь считается от адреса модуля, а у blob-адреса нет папки. Дальше import("main") запускает настоящий граф модулей.

Сравним счётчик в двух системах. Сначала по-старому: counter.cjs кладёт count в exports и отдаёт функцию, которая его увеличивает; загружает его load из статьи про require. Потом тот же счётчик ES-модулем, а main импортирует его дважды: именами и целиком, через import * as. В конце main ещё раз просит counter через import() и сравнивает результат с тем, что дал import * as. Прогноз: какой count напечатают после двух вызовов increment и совпадут ли объекты?

// в подложке: load из статьи про require и modules — blob-адреса и карта импортов
files["/app/counter.cjs"] = `
let count = 0;
exports.count = count;
exports.increment = () => { count += 1; };
`;
const counterCjs = load("/app/counter.cjs");
counterCjs.increment();
counterCjs.increment();
console.log("CommonJS: count =", counterCjs.count);

modules({
  counter: `
export let count = 0;
export function increment() { count += 1; }
`,
  main: `
import { count, increment } from "counter";
import * as counter from "counter";
increment();
increment();
console.log("ESM: count =", count);
import("counter").then((again) => console.log("тот же объект модуля:", again === counter));
`,
});
import("main");

Счётчик CommonJS остался нулём, хотя increment отработал дважды. exports.count = count скопировал число в поле объекта при загрузке, и дальше переменная count внутри модуля и поле exports.count живут отдельно. ESM напечатал 2: import { count } не копирует значение, а связывает имя в main с переменной count в counter. Это называют живой привязкой: читать через неё — всё равно что читать саму переменную модуля, сколько бы раз та ни менялась.

Объект модуля тоже один. import * as counter и import("counter") вернули одно и то же пространство имён: модуль с одним адресом браузер выполняет один раз, как обещала статья о модулях, и дальше всем отдаёт один результат. Писать в привязку, правда, нельзя: count = 5 в main бросит TypeError — менять переменную может только модуль, который её объявил.

Вернёмся к кругу. Порядок у ES-модулей другой, и объясняет его статичность импортов: граф известен до выполнения первой строки. Поэтому загрузка идёт в три этапа. Сначала браузер или Node собирает все модули графа, читая их import. Потом связывает: у каждого модуля заводятся переменные его экспортов, и имена импортов подключаются к ним. И только потом выполняет тела — от зависимостей к тем, кто их импортирует. В круге обход начинает с notes, спускается в users, из users натыкается на уже начатый notes и возвращается. Первым выполняется тело users, за ним — notes.

Что увидит users, если на верхнем уровне читает limit? Переменная в notes уже заведена связыванием, но до строки export const limit = 100 дело не дошло, и она во временной мёртвой зоне, как любой const до объявления. Объявления функций устроены иначе: они готовы ещё при связывании, до выполнения тела. Именно это в задаче сборщика заставило настоящий ESM напечатать function.

Модули те же, что в CommonJS, только на import и export. Прогноз: какой модуль напечатает «начало» первым, что покажет typeof create и чем кончится чтение limit?

// modules — в подложке; notes и users те же, только на import и export
modules({
  notes: `
import { format } from "users";
console.log("notes: начало");
export const limit = 100;
export function create(author, text) {
  return format(author) + ": " + text;
}
console.log(create("Аня", "привет"));
console.log("notes: конец");
`,
  users: `
import { limit, create } from "notes";
console.log("users: начало");
console.log("users видит create:", typeof create);
export function format(name) {
  return name + " (limit " + limit + ")";
}
console.log("users видит limit:", limit);
console.log("users: конец");
`,
});
import("notes").catch((err) => console.log(err.name));

Текст сообщения у Chrome и Firefox разный, поэтому в песочнице напечатано только имя ошибки, а подлинный текст покажет следующий раздел: там те же модули запускает настоящий Node.

Сравните с CommonJS. Там круг отдаёт undefined без всякого исключения, и ошибка всплывает где-то дальше, в чужой функции. ESM падает на той самой строке, где читается недописанное. А если чтение отложить в функцию, живая привязка решит задачу сама: к вызову format переменная уже заполнена. Круг в ESM безопасен, пока на верхнем уровне модуля никто не читает то, что объявлено по другую сторону круга.

Модели наши, поэтому сверим их с Node. Первый прогон — файлы из раздела про CommonJS без единой правки. Расширение .cjs говорит Node «это CommonJS», а .mjs — «это ES-модуль» при любых настройках проекта; как то же объявляют полем type в package.json, разберёт статья «package.json как договор». Прогноз: совпадут ли строки с моделью и где встанут предупреждения?

console.log("notes: начало");
const users = require("./users.cjs");
exports.limit = 100;
exports.create = (author, text) => users.format(author) + ": " + text;
console.log(exports.create("Аня", "привет"));
console.log("notes: конец");

notes: начало
users: начало
users видит notes.create: undefined
users: конец
Аня (limit undefined, notes.limit 100): привет
notes: конец
(node:<pid>) Warning: Accessing non-existent property 'limit' of module exports inside circular dependency
(Use `node --trace-warnings ...` to show where the warning was created)
(node:<pid>) Warning: Accessing non-existent property 'create' of module exports inside circular dependency

Шесть строк слово в слово повторяют модель: notes.create при загрузке пустой, деструктурированный limit навсегда undefined, notes.limit при вызове — 100. Предупреждений два, про те же поля, но стоят они не на месте обращения, а в самом конце. Node не печатает их внутри get: он передаёт текст в process.emitWarning, а тот выводит предупреждение в поток ошибок, когда синхронный код уже закончился. (node:<pid>) — номер процесса, при записи его заменили меткой. Где именно случилось обращение, покажет флаг из подсказки: node --trace-warnings notes.cjs печатает под каждым предупреждением стек, и первая его строка, которая ведёт не во внутренности Node, а в ваш файл, — это users.cjs со строкой и столбцом обращения.

Второй прогон — те же модули файлами notes.mjs и users.mjs. От песочницы они отличаются только путями в import: у файла на диске папка есть. Прогноз: какие строки успеют напечататься и с каким кодом завершится процесс?

import { format } from "./users.mjs";
console.log("notes: начало");
export const limit = 100;
export function create(author, text) {
  return format(author) + ": " + text;
}
console.log(create("Аня", "привет"));
console.log("notes: конец");

users: начало
users видит create: function
file://<пример>/users.mjs:7
console.log("users видит limit:", limit);
                                  ^

ReferenceError: Cannot access 'limit' before initialization
    at file://<пример>/users.mjs:7:35
    at <внутренние кадры node>

Node.js v<версия>

Всё как в песочнице: users выполнился первым и упал на limit, до notes: начало дело не дошло. Текст Cannot access 'limit' before initialization — от движка V8, поэтому Chrome пишет так же, а Firefox — по-своему. Над ним Node показал файл, строку и стрелку под именем, а необработанная ошибка завершила процесс с кодом 1. <пример>, <внутренние кадры node> и v<версия> — метки записи: полный путь у каждого свой, а номера строк во внутренних файлах и сама версия Node меняются от выпуска к выпуску.

Круг чинят не наугад, а от места чтения. Сначала найдите, что читается во время загрузки: в CommonJS это поле из предупреждения и строка из --trace-warnings, в ESM — строка со стрелкой. Дальше — один из четырёх приёмов, от надёжного к хрупкому.

Второй приём в CommonJS требует дисциплины: деструктуризация на верхнем уровне файла — самый частый способ его нарушить, и выглядит она невинно. В ESM тот же приём ничего не стоит, потому что привязки живые. Зато чтения на верхнем уровне ESM не прощает вовсе, и это его достоинство: круг с ошибкой падает при запуске, а не через неделю в редкой ветке кода.

Если круг проходит через ES-модуль, подключённый через require, половины не будет: Node 26 сразу бросает ошибку с кодом ERR_REQUIRE_CYCLE_MODULE.

Круг бывает и уровнем выше: два сервиса, которые требуют друг друга в конструкторе, замыкаются в контейнере зависимостей, и ловит такой круг уже контейнер, а не загрузчик модулей. Его разберёт статья «Nest can't resolve dependencies».