Модули и резолюция

Когда JavaScript-пакет не везёт своих типов, сообщество публикует их отдельно как @types/<name>, собранный из репозитория DefinitelyTyped. TypeScript подхватывает их автоматически из node_modules/@types — импортировать их не нужно. Пакету со своими объявлениями @types не нужен вовсе.

module.exports = x заменяет объект модуля — модуль и есть x. export default x добавляет один именованный экспорт default в объект пространства имён, где лежат и все прочие экспорты. Поэтому require() на ES-модуле отдаёт { default: x }, а импорт по умолчанию из CommonJS работает лишь через хелпер interop.

module определяет, какой синтаксис модулей эмитит tsc: commonjs переписывает import/export в require и exports.x, а esnext оставляет их ES-модулями. На то, что вы пишете, опция не влияет. При node16 формат выбирается для каждого файла — по полю type ближайшего package.json.

namespace — доэсэмный способ группировать код: он эмитит IIFE, навешивающий свойства на глобальный объект, а одноимённые блоки сливаются даже из разных файлов. ES-модули вытеснили его: модуль ограничен своим файлом, его импорты статически анализируемы, bundler умеет их тряхнуть. Оставьте namespace только для .d.ts.

allowSyntheticDefaultImports работает только на уровне типов: он гасит ошибку нет экспорта по умолчанию, чтобы import fs from 'fs' прошёл проверку, и ничего не эмитит. esModuleInterop меняет эмит — оборачивает require в __importDefault, чтобы импорт получил module.exports, — и включает первый флаг.

tsc видит всю программу и понимает, что имя используется лишь в позиции типа, — импорт вырезается. Однофайловый транспилятор — esbuild, SWC, Babel — видит один файл, без межфайловых типов, и не знает, тип import { User } или значение. import type кладёт ответ в синтаксис.

node10 — легаси-алгоритм CommonJS: идти вверх по node_modules, угадывать расширение, игнорировать карту exports. node16/nodenext моделируют реальный Node: учитывают exports, решают CommonJS или ESM для каждого файла, требуют явное расширение в относительных ESM-импортах. bundler учитывает exports, но разрешает импорты без расширения.

ESM-import/export — статические объявления: что модуль берёт и что отдаёт, видно из одного синтаксиса, поэтому bundler строит граф, ничего не выполняя, и выбрасывает экспорты без ссылок. require() — обычный вызов, а module.exports изменяем: доказать ненужность нельзя, и остаётся всё.

Дополнение модуля: declare module 'lib' { ... } в файле-модуле — в нём нужен import или export верхнего уровня. Ваши интерфейсы тогда сливаются с интерфейсами библиотеки; слияние добавляет члены, но не меняет тип существующего. Без импорта или экспорта файл — скрипт, и блок заменит типы.

С литеральным спецификатором import('./m.js') типизирован — компилятор резолвит файл и выводит Promise<typeof import('./m.js')>. С вычисляемым резолвить нечего, поэтому результат — any, и всё дальше не проверяется. Ожидайте в unknown, сузьте type guard-ом, который смотрит форму в рантайме, и бросайте исключение, если он не прошёл.

Типы резолвятся лениво, поэтому циклическая ссылка на тип законна и проверка молчит. Значенческий цикл в эмитируемом JavaScript ей не виден: модуль, вычисляемый вторым, получает ещё пустой exports соседа, и entity_1.Entity в месте extends читается как undefined. Сотрите чисто типовые рёбра через import type, а общее значение вынесите в третий модуль.

Он заставляет tsc отвергать всё, что однофайловый транспилятор не скомпилирует корректно. esbuild, SWC и Babel видят по одному файлу, без межфайловых типов, поэтому реэкспорт типа надо писать export type { T }, а const enum нельзя заинлайнить между файлами. Это контракт совместимости.

paths — алиас только на этапе компиляции. Он говорит проверяющему, куда резолвится @app/x, но в эмите tsc оставляет спецификатор как есть — и Node видит буквальный @app/x и бросает MODULE_NOT_FOUND. Нужен резолвер в рантайме: alias у bundler-а, subpath imports Node или загрузчик tsconfig-paths.