Настройка TypeScript

На этой странице рассматривается расширенная настройка TypeScript в Deno, включая параметры компилятора, совместимость с tsconfig.json и выбор целевых библиотек. Введение в использование TypeScript с Deno см. в разделе Поддержка TypeScript.

Настройка TypeScript в Deno

Deno стремится упростить настройку TypeScript, руководствуясь следующими принципами:

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

Последний пункт предлагает более простой формат, чем поля references и extends в tsconfig.json, заменяя их рабочими пространствами deno.json и наследованием от корневого участника. См. раздел о проверке типов в рабочих пространствах.

Совместимость с `tsconfig.json`

Хотя использование файлов tsconfig.json не рекомендуется для проектов, ориентированных на Deno, существующие рабочие пространства Node.js + TypeScript с такими файлами будут работать в Deno без дополнительной настройки благодаря проверке типов и LSP.

В каждом каталоге рабочего пространства, содержащем deno.json или package.json, выполняется поиск файла tsconfig.json. Если он существует, на него добавляется ссылка как на «корневой» проект, а содержащиеся в нём ссылки рекурсивно включаются.

Как и в случае с tsc, область действия TSConfig определяется его корневыми полями. При пересечении областей действия:

Ссылка имеет приоритет над проектом, который на неё ссылается.
Для корневых ссылок foo/bar/tsconfig.json имеет приоритет над foo/tsconfig.json.
Если родительский deno.json содержит compilerOptions, он будет иметь приоритет над любым TSConfig.

Поддерживаются следующие поля:

tsconfig.json

{
  "extends": "...",
  "files": ["..."],
  "include": ["..."],
  "exclude": ["..."],
  "references": [
    { "path": "..." }
  ],
  "compilerOptions": {
    "...": "..."
  }
}

За исключением compilerOptions, эти поля нельзя указывать в deno.json.

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

Перенос compilerOptions из Node.js

В типичном tsconfig.json для Node.js большинство параметров предназначено для настройки вывода компиляции и взаимодействия модулей. Deno выполняет TypeScript напрямую и никогда не генерирует JavaScript, поэтому большинство этих параметров не действует и их можно удалить. Deno предупреждает об игнорируемых параметрах, если они указаны в tsconfig.json; перенос оставшихся параметров в compilerOptions файла deno.json позволяет отключить это предупреждение.

Параметр в вашем `tsconfig.json`	В Deno
`target`, `outDir`, `outFile`, `rootDir`	Удалите. Deno ничего не генерирует: код выполняется непосредственно в последней версии V8, а `deno check` выполняет проверку типов без создания выходных файлов.
`declaration`, `declarationMap`, `emitDeclarationOnly`	Удалите. Генерация не выполняется. Используйте `deno doc` для создания документации API.
`sourceMap`, `inlineSourceMap`, `inlineSources`	Удалите. Стек вызовов автоматически сопоставляется с исходным кодом TypeScript.
`esModuleInterop`, `allowSyntheticDefaultImports`	Удалите. Deno изначально использует ESM и обрабатывает взаимодействие с CommonJS во время выполнения.
`importHelpers`, `noEmitHelpers`, `downlevelIteration`	Удалите. Понижение уровня кода не выполняется, поэтому вспомогательный код не генерируется.
`resolveJsonModule`	Удалите. Импортируйте JSON с помощью атрибута: `import data from "./data.json" with { type: "json" }`.
`skipLibCheck`	Удалите. По умолчанию Deno не проверяет типы зависимостей (для включения проверки укажите `deno check --all`).
`module`, `moduleResolution`	Обычно удалите. По умолчанию Deno использует `nodenext`; поддерживаемые значения перечислены в таблице ниже.
`lib`, `types`	Обычно удалите. Значения по умолчанию Deno подходят для его среды выполнения; оставьте только `lib` для кода, работающего в нескольких средах выполнения (см. раздел о свойстве «lib»).
`strict`, `noImplicit`, `noUnused`, другие флаги проверки	Оставьте нужные параметры в `compilerOptions` файла `deno.json`. Обратите внимание, что значения Deno по умолчанию уже включают строгую проверку (см. таблицу ниже).
`paths`, `baseUrl`	Оставьте, если они нужны для сопоставления путей во время проверки типов, либо замените на карты импортов, которые также работают во время выполнения.

Параметры компилятора TS

Ниже приведена таблица параметров компилятора, которые можно изменить, их значений по умолчанию в Deno и примечаний к ним:

Параметр	По умолчанию	Примечания
`allowUnreachableCode`	`false`
`allowUnusedLabels`	`false`
`baseUrl`	`"./"`	Используется для разрешения записей с «голыми» спецификаторами в `paths` и `rootDirs`, но не для «голых» спецификаторов в импортах модулей.
`checkJs`	`false`
`jsx`	`"react"`
`jsxFactory`	`"React.createElement"`
`jsxFragmentFactory`	`"React.Fragment"`
`keyofStringsOnly`	`false`
`lib`	`[ "deno.window" ]`	Значение по умолчанию зависит от других параметров Deno. Если указать этот параметр, он переопределит значение по умолчанию. Подробнее см. ниже.
`module`	`"nodenext"`	Поддерживаемые значения: `["nodenext", "esnext", "preserve"]`.
`moduleResolution`	`"nodenext"`	Поддерживаемые значения: `["nodenext", "bundler"]`.
`noErrorTruncation`	`false`
`noFallthroughCasesInSwitch`	`false`
`noImplicitAny`	`true`
`noImplicitOverride`	`true`
`noImplicitReturns`	`false`
`noImplicitThis`	`true`
`noImplicitUseStrict`	`true`
`noStrictGenericChecks`	`false`
`noUncheckedIndexedAccess`	`false`
`noUnusedLocals`	`false`
`noUnusedParameters`	`false`
`paths`	`{}`
`rootDirs`	`null`
`strict`	`true`
`strictBindCallApply`	`true`
`strictFunctionTypes`	`true`
`strictNullChecks`	`true`
`strictPropertyInitialization`	`true`
`suppressExcessPropertyErrors`	`false`
`suppressImplicitAnyIndexErrors`	`false`
`useUnknownInCatchVariables`	`true`

Полный список параметров компилятора и описание их влияния на TypeScript см. в справочнике TypeScript.

Использование свойства «lib»

Если вы работаете над проектом, код которого предназначен для нескольких сред выполнения, например для браузеров, вы можете изменить типы по умолчанию с помощью свойства «lib» в compilerOptions.

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

"deno.ns" — включает все пользовательские API глобального пространства имён Deno, а также дополнения Deno к import.meta. Как правило, она не конфликтует с другими библиотеками или глобальными типами.
"deno.window" — это библиотека «по умолчанию», используемая при проверке основных скриптов среды выполнения Deno. Она включает "deno.ns", а также другие библиотеки типов для расширений, встроенных в Deno. Эта библиотека будет конфликтовать с такими библиотеками, как "dom" и "dom.iterable", которые входят в стандартную поставку TypeScript.
"deno.worker" — библиотека, используемая при проверке скриптов веб-воркеров Deno. Подробнее о веб-воркерах см. в разделе Проверка типов веб-воркеров.
"dom.asynciterable" — в настоящее время TypeScript не включает DOM-итераторы, которые реализованы в Deno (а также в нескольких браузерах), поэтому мы реализовали их самостоятельно до тех пор, пока они не появятся в TypeScript.
"deno.desktop" — библиотека, используемая при проверке приложений, созданных с помощью deno desktop. См. раздел Настольные приложения.

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

"dom" — основная библиотека глобальных объектов браузера, входящая в поставку TypeScript. Определения типов во многом конфликтуют с "deno.window", поэтому при использовании "dom" рассмотрите возможность использовать только "deno.ns", чтобы открыть API, специфичные для Deno.
"dom.iterable" — расширения с итераторами для библиотеки глобальных объектов браузера.
"scripthost" — библиотека для Microsoft Windows Script Host.
"webworker" — основная библиотека для веб-воркеров в браузере. Как и "dom", она будет конфликтовать с "deno.window" или "deno.worker", поэтому рассмотрите возможность использовать только "deno.ns", чтобы открыть API, специфичные для Deno.
"webworker.importscripts" — библиотека, предоставляющая API importScripts() в веб-воркере.
"webworker.iterable" — библиотека, добавляющая итераторы объектам в веб-воркере. Современные браузеры поддерживают эту возможность.

Поддержка Deno и браузера

Возможно, вы захотите написать код, который без проблем работает и в Deno, и в браузере. В этом случае перед использованием API, доступных только в одной из этих сред, необходимо проверять среду выполнения. В таком случае типичная конфигурация compilerOptions может выглядеть следующим образом:

deno.json

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
  }
}

Это позволит Deno корректно проверять типы в большинстве случаев.

Если в коде используются API, доступ к которым ограничен одним из флагов --unstable-*, добавьте также библиотеку deno.unstable:

deno.json

{
  "compilerOptions": {
    "lib": [
      "dom",
      "dom.iterable",
      "dom.asynciterable",
      "deno.ns",
      "deno.unstable"
    ]
  }
}

Обычно при использовании параметра "lib" в TypeScript необходимо также подключить библиотеку «es». В случае с "deno.ns" и "deno.unstable" библиотека "esnext" подключается автоматически.

Примечание

Если возникают ошибки типов, например не удаётся найти document или HTMLElement, вероятно, используемая вами библиотека зависит от DOM. Это часто встречается в пакетах, предназначенных как для браузера, так и для серверной среды. По умолчанию Deno включает только библиотеки, поддерживаемые напрямую. Если пакет корректно определяет среду выполнения, в которой он работает, использовать библиотеки DOM для проверки типов кода «безопасно».

Типы и объявления типов

Информацию о предоставлении объявлений типов для модулей JavaScript (с помощью заголовков @ts-types, @ts-self-types, X-TypeScript-Types и файлов .d.ts) см. в разделе Предоставление файлов объявлений руководства по основам TypeScript.

Информацию о расширении глобальных типов с помощью файлов declare global или .d.ts см. в разделе Расширение глобальных типов.

Проверка типов веб-воркеров

Когда Deno загружает модуль TypeScript в веб-воркере, он автоматически проверяет типы модуля и его зависимостей с использованием библиотеки веб-воркеров Deno. Это может создать трудности в других контекстах, например в deno check или редакторах. Есть несколько способов указать Deno использовать библиотеки воркеров вместо стандартных библиотек Deno.

Директивы с тремя косыми чертами

Этот вариант связывает настройки библиотек с самим кодом. Добавьте следующие директивы с тремя косыми чертами в начало файла точки входа скрипта воркера, и Deno будет проверять его типы как скрипт воркера Deno независимо от способа анализа модуля:

/// <reference no-default-lib="true" />
/// <reference lib="deno.worker" />

Первая директива гарантирует, что никакие другие библиотеки по умолчанию не будут использоваться. Если её не указать, возникнет конфликт определений типов, поскольку Deno попытается применить также стандартную библиотеку Deno. Вторая директива указывает Deno применить встроенные определения типов для воркеров Deno и зависимые библиотеки (например, "esnext").

Недостаток этого подхода в том, что код становится менее переносимым на платформы, отличные от Deno, например tsc, поскольку только в Deno встроена библиотека "deno.worker".

Настройка «lib» в deno.json

В файле deno.json можно задать параметр «lib», чтобы указать Deno использовать файлы библиотек. Например:

deno.json

{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["deno.worker"]
  }
}

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

Важные моменты

Семантика объявлений типов

Файлы объявлений типов (файлы .d.ts) подчиняются той же семантике, что и другие файлы в Deno. Это означает, что файлы объявлений считаются объявлениями модулей (объявлениями UMD), а не внешними или глобальными объявлениями. Поведение Deno при обработке внешних или глобальных объявлений непредсказуемо.

Кроме того, если объявление типа импортирует что-либо ещё, например другой файл .d.ts, его разрешение подчиняется обычным правилам импорта Deno. Многие файлы .d.ts, которые создаются и доступны в интернете, могут быть несовместимы с Deno.

При использовании HTTPS-импортов из CDN, например esm.sh, объявления типов предоставляются по умолчанию (через заголовок X-TypeScript-Types). Это можно отключить, добавив ?no-dts к URL импорта. Обратите внимание: в большинстве случаев для импорта npm-пакетов рекомендуется использовать спецификаторы npm:.

Поведение JavaScript при проверке типов

При импорте кода JavaScript в TypeScript в Deno компилятор TypeScript всё равно анализирует модуль JavaScript, даже если для checkJs задано значение false (это поведение Deno по умолчанию). Компилятор пытается определить структуру экспортов этого модуля, чтобы проверить импорт в файле TypeScript.

Обычно это не вызывает проблем при импорте стандартного ES-модуля. Однако в некоторых случаях анализ TypeScript может завершиться неудачно, например для модулей с особой упаковкой или глобальных модулей UMD (Universal Module Definition). В таких ситуациях лучше всего предоставить сведения о типах одним из упомянутых ранее способов.

Внутреннее устройство

Чтобы эффективно использовать TypeScript с Deno, необязательно понимать внутреннее устройство Deno, но это может быть полезно.

Перед выполнением или компиляцией кода Deno строит граф модулей: разбирает корневой модуль, определяет все его зависимости, а затем рекурсивно получает и разбирает эти модули, пока не будут получены все зависимости.

Для каждой зависимости используются два возможных «слота»: слот кода и слот типов. По мере заполнения графа модулей, если модуль является или может быть преобразован в JavaScript, он помещается в слот кода, а зависимости, используемые только для типов, например файлы .d.ts, помещаются в слот типов.

После построения графа модулей, когда требуется проверить его типы, Deno запускает компилятор TypeScript и передаёт ему имена модулей, которые потенциально нужно преобразовать в JavaScript. В ходе этого процесса компилятор TypeScript запрашивает дополнительные модули, а Deno проверяет слоты зависимости: сначала предлагает слот типов, если он заполнен, и только затем — слот кода.

Это означает, что при импорте модуля .d.ts или использовании одного из описанных выше способов предоставления альтернативных модулей типов для кода JavaScript компилятору TypeScript при разрешении модуля передаётся именно такой модуль.

Настройка TypeScript