Поддержка TypeScript

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

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

Одно из основных преимуществ TypeScript заключается в том, что он делает ваш код безопасным с точки зрения типов, обнаруживая ошибки на этапе разработки, а не во время выполнения. TypeScript является надмножеством JavaScript, что означает, что синтаксически корректный JavaScript становится TypeScript с предупреждениями о «небезопасности».

Deno позволяет вам проверять типы вашего кода (без его выполнения) с помощью подкоманды deno check:

deno check module.ts
# or also type check remote modules and npm packages
deno check --all module.ts
# code snippets written in JSDoc can also be type checked
deno check --doc module.ts
# or type check code snippets in markdown files
deno check --doc-only markdown.md

При использовании команды deno run Deno пропустит проверку типов и запустит код напрямую. Для выполнения проверки типа модуля перед выполнением можно использовать флаг --check с deno run:

deno run --check module.ts
# or also type check remote modules and npm packages
deno run --check=all module.ts

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

Для того, чтобы этого избежать, необходимо:

• исправить проблему
• использовать псевдонимы // @ts-ignore или // @ts-expect-error для игнорирования ошибки
• или полностью пропустить проверку типов.

При тестировании кода проверка типов включена по умолчанию. Вы можете использовать флаг --no-check для пропуска проверки типов, если это предпочтительно:

deno test --no-check

Использование с JavaScript

Deno выполняет код JavaScript и TypeScript. При проверке типов Deno проверяет только файлы TypeScript по умолчанию. Если вы хотите проверить и файлы JavaScript, вы можете либо добавить псевдоним // @ts-check в начало файла, либо добавить compilerOptions.checkJs в свой файл deno.json.

// @ts-check

let x = "hello";
x = 42; // Type 'number' is not assignable to type 'string'.

{
  "compilerOptions": {
    "checkJs": true
  }
}

В файлах JavaScript нельзя использовать синтаксис TypeScript, например, аннотации типов или импорт типов. Однако можно использовать комментарии TSDoc для предоставления информации о типах компилятору TypeScript.

// @ts-check

/**
 * @param a {number}
 * @param b {number}
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

Предоставление файлов объявлений

При импорте не типизированных модулей JavaScript из кода TypeScript, возможно, потребуется предоставить информацию о типах для модуля JavaScript. Это не нужно, если JavaScript снабжён комментариями TSDoc. Без этой дополнительной информации о типах (в виде файла объявления .d.ts), TypeScript предположит, что всё, что экспортируется из модуля JavaScript, имеет тип any.

tsc автоматически обнаружит файлы d.ts которые являются соседними с файлом js и имеют такое же имя без расширения. Deno этого не делает. Вам необходимо явно указать, где найти файл .d.ts либо в файле .js (исходник), либо в файле .ts (импортер).

Предоставление типов в исходном файле

Рекомендуется указывать файл .d.ts в файле .js, так как это упрощает использование модуля JavaScript из нескольких модулей TypeScript: вам не придётся указывать файл .d.ts в каждом модуле TypeScript, который импортирует модуль JavaScript.

// @ts-self-types="./add.d.ts"

export function add(a, b) {
  return a + b;
}

export function add(a: number, b: number): number;

Предоставление типов в импортируемом файле

Если вы не можете изменить исходный код JavaScript, вы можете указать файл .d.ts в модуле TypeScript, который импортирует модуль JavaScript.

// @ts-types="./add.d.ts"
import { add } from "./add.js";

Это также полезно для пакетов NPM, которые не предоставляют информацию о типах:

// @ts-types="npm:@types/lodash"
import * as _ from "npm:lodash";

Предоставление типов для модулей HTTP

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

HTTP/1.1 200 OK
Content-Type: application/javascript; charset=UTF-8
Content-Length: 648
X-TypeScript-Types: ./add.d.ts

Заголовок X-TypeScript-Types указывает расположение файла .d.ts с информацией о типах для модуля JavaScript. Он разрешается относительно URL модуля JavaScript, как и заголовки Location.

Проверка типов для браузеров и веб-рабочих процессов

По умолчанию Deno проверяет типы модулей TypeScript так, как будто они выполняются в главном потоке среды выполнения Deno. Однако Deno также поддерживает проверку типов для браузеров, проверку типов для веб-рабочих процессов и проверку типов для комбинированных сред браузер-Deno, например, при использовании SSR (Server Side Rendering) с Deno.

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

Загруженные файлы библиотек могут быть изменены с помощью параметра compilerOptions.lib в конфигурационном файле deno.json или через комментарии /// <reference lib="..." /> в ваших файлах TypeScript. Рекомендуется использовать параметр compilerOptions.lib в файле конфигурации deno.json для указания используемых файлов библиотек.

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

{
  "compilerOptions": {
    "lib": ["dom"]
  }
}

Это включит проверку типов для браузерной среды, предоставив информацию о типах для глобальных объектов, таких как document. Однако это отключит информацию о типах для API, специфичных для Deno, таких как Deno.readFile.

Чтобы включить проверку типов для комбинированных браузерных и Deno сред, например, при использовании SSR с Deno, вы можете указать как файл библиотеки dom, так и файл библиотеки deno.ns (пространство имён Deno) в параметре compilerOptions.lib в файле конфигурации deno.json.

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

Это позволит включить проверку типов для браузерных и Deno сред, предоставив информацию о типах для глобальных объектов, таких как document, и API, специфичных для Deno, таких как Deno.readFile.

Для включения проверки типов для среды веб-рабочего процесса в Deno (т. е. кода, который выполняется с new Worker ), можно указать файл библиотеки deno.worker в параметре compilerOptions.lib в файле deno.json.

{
  "compilerOptions": {
    "lib": ["deno.worker"]
  }
}

Для указания используемых файлов библиотек в файле TypeScript можно использовать комментарии /// <reference lib="..." />:

/// <reference no-default-lib="true" />
/// <reference lib="dom" />

Расширение глобальных типов

Deno поддерживает глобальные типы в TypeScript. Это полезно при полифиллировании глобальных объектов или дополнении глобальной области видимости дополнительными свойствами. Следует избегать использования глобальных типов, когда это возможно, так как они могут привести к конфликтам имён и усложнить понимание вашего кода. Они также не поддерживаются при публикации в JSR.

Чтобы использовать глобальные типы в Deno, можно использовать синтаксис declare global или загрузить файл .d.ts , который расширяет глобальную область видимости.

Использование declare global для расширения глобальной области видимости

Вы можете использовать синтаксис declare global в любом из файлов TypeScript, импортируемых в ваш проект, для расширения глобальной области видимости дополнительными свойствами. Например:

declare global {
  interface Window {
    polyfilledAPI(): string;
  }
}

Это делает функцию polyfilledAPI доступной глобально при импорте определения типа.

Использование файлов .d.ts для расширения глобальной области видимости

Вы также можете использовать файлы .d.ts для расширения глобальной области видимости. Например, вы можете создать файл global.d.ts со следующим содержимым:

interface Window {
  polyfilledAPI(): string;
}

Затем вы можете загрузить этот файл .d.ts в свой TypeScript с помощью /// <reference types="./global.d.ts" />. Это расширит глобальную область видимости функцией polyfilledAPI.

Также вы можете указать файл .d.ts в файле конфигурации deno.json в массиве compilerOptions.types:

{
  "compilerOptions": {
    "types": ["./global.d.ts"]
  }
}

Это также расширит глобальную область видимости функцией polyfilledAPI.