Модули: TypeScript

Включение

Есть два способа включить поддержку TypeScript во время выполнения в Node.js:

1. Для полной поддержки всего синтаксиса и функций TypeScript, включая использование любой версии TypeScript, используйте сторонний пакет.

2. Для облегченной поддержки можно использовать встроенную возможность удаления типов.

Полная поддержка TypeScript

Чтобы использовать TypeScript с полной поддержкой всех функций TypeScript, включая tsconfig.json, можно воспользоваться сторонним пакетом. В этих инструкциях в качестве примера используется tsx, однако доступно множество других похожих библиотек.

1. Установите пакет как зависимость для разработки с помощью используемого в проекте менеджера пакетов. Например, с npm:

   npm install --save-dev tsx
   bashcopy

2. Затем можно запустить код TypeScript следующим образом:

   npx tsx your-file.ts
   bashcopy

   Или, в качестве альтернативы, запустить с помощью node следующим образом:

   node --import=tsx your-file.ts
   bashcopy

Удаление типов

По умолчанию Node.js выполняет файлы TypeScript, содержащие только удаляемый синтаксис TypeScript. Node.js заменяет синтаксис TypeScript пробелами, проверка типов не выполняется. Чтобы отключить эту возможность, используйте флаг --no-strip-types.

Node.js игнорирует файлы tsconfig.json, поэтому функции, зависящие от настроек внутри tsconfig.json, например пути или преобразование нового синтаксиса JavaScript в более старые стандарты, намеренно не поддерживаются. Чтобы получить полную поддержку TypeScript, см. раздел Полная поддержка TypeScript.

Возможность удаления типов разработана как облегченная. Намеренно не поддерживая синтаксис, требующий генерации кода JavaScript, и заменяя встроенные типы пробелами, Node.js может выполнять код TypeScript без необходимости в картах исходного кода.

Удаление типов совместимо с большинством версий TypeScript, но мы рекомендуем версию 5.8 или новее со следующими настройками tsconfig.json:

{
  "compilerOptions": {
     "noEmit": true, // Optional - see note below
     "target": "esnext",
     "module": "nodenext",
     "rewriteRelativeImportExtensions": true,
     "erasableSyntaxOnly": true,
     "verbatimModuleSyntax": true
  }
}
jsoncopy

Используйте параметр noEmit, если планируете выполнять только файлы *.ts, например скрипт сборки. Этот флаг не понадобится, если вы планируете распространять файлы *.js.

Определение системы модулей

Node.js поддерживает синтаксис как CommonJS, так и ES Modules в файлах TypeScript. Node.js не преобразует одну систему модулей в другую: если нужно, чтобы код выполнялся как ES-модуль, необходимо использовать синтаксис import и export, а если нужно, чтобы код выполнялся как CommonJS, необходимо использовать require и module.exports.

• Для файлов .ts система модулей определяется так же, как и для файлов .js. Чтобы использовать синтаксис import и export, добавьте "type": "module" в ближайший родительский package.json.
• Файлы .mts всегда выполняются как ES-модули, подобно файлам .mjs.
• Файлы .cts всегда выполняются как модули CommonJS, подобно файлам .cjs.
• Файлы .tsx не поддерживаются.

Как и в файлах JavaScript, расширения файлов обязательны в инструкциях import и выражениях import(): import './file.ts', а не import './file'. Из соображений обратной совместимости расширения файлов также обязательны в вызовах require(): require('./file.ts'), а не require('./file'); это аналогично тому, как расширение .cjs обязательно в вызовах require в файлах CommonJS.

Параметр tsconfig.json allowImportingTsExtensions позволит компилятору TypeScript tsc проверять типы файлов со спецификаторами import, содержащими расширение .ts.

Возможности TypeScript

Поскольку Node.js только удаляет встроенные типы, любые возможности TypeScript, предполагающие замену синтаксиса TypeScript новым синтаксисом JavaScript, вызовут ошибку.

Наиболее заметные возможности, требующие преобразования:

• Объявления Enum
• namespace с кодом времени выполнения
• свойства параметров
• псевдонимы импорта

Поддерживаются namespace, не содержащие кода времени выполнения. Этот пример будет работать правильно:

// This namespace is exporting a type
namespace TypeOnly {
   export type A = string;
}
tscopy

Этот пример приведет к ошибке ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX:

// This namespace is exporting a value
namespace A {
   export let x = 1
}
tscopy

Поскольку декораторы в настоящее время являются предложением TC39 на этапе 3, они не преобразуются и вызовут ошибку синтаксического анализатора. Node.js не предоставляет полифилы и поэтому не будет поддерживать декораторы, пока они не будут поддерживаться в JavaScript изначально.

Кроме того, Node.js не читает файлы tsconfig.json и не поддерживает функции, зависящие от настроек внутри tsconfig.json, например пути или преобразование нового синтаксиса JavaScript в более старые стандарты.

Импорт типов без ключевого слова type

Из-за особенностей удаления типов ключевое слово type необходимо для корректного удаления импортов типов. Без ключевого слова type Node.js будет рассматривать импорт как импорт значения, что приведет к ошибке во время выполнения. Параметр tsconfig verbatimModuleSyntax можно использовать, чтобы привести поведение в соответствие с этим.

Этот пример будет работать правильно:

import type { Type1, Type2 } from './module.ts';
import { fn, type FnParams } from './fn.ts';
tscopy

Это приведет к ошибке во время выполнения:

import { Type1, Type2 } from './module.ts';
import { fn, FnParams } from './fn.ts';
tscopy

Формы ввода, не являющиеся файлами

Удаление типов можно включить для --eval и STDIN. Система модулей определяется с помощью --input-type, как и для JavaScript.

Синтаксис TypeScript не поддерживается в REPL, --check и inspect.

Карты исходного кода

Поскольку встроенные типы заменяются пробелами, карты исходного кода не нужны для корректного отображения номеров строк в трассировках стека; Node.js их не создает.

Удаление типов в зависимостях

Чтобы отговорить авторов пакетов от публикации пакетов, написанных на TypeScript, Node.js отказывается обрабатывать файлы TypeScript в папках, расположенных внутри пути node_modules.

Псевдонимы путей

tsconfig "paths" не преобразуются и поэтому приводят к ошибке. Ближайшая доступная возможность — импорт подмодулей, с ограничением: они должны начинаться с #.