Карманная книга по TypeScript. Часть 8. Модули

Мы продолжаем серию публикаций адаптированного и дополненного перевода "Карманной книги по TypeScript".

Другие части:

• Часть 1. Основы
• Часть 2. Типы на каждый день
• Часть 3. Сужение типов
• Часть 4. Подробнее о функциях
• Часть 5. Объектные типы
• Часть 6. Манипуляции с типами
• Часть 7. Классы
• Часть 8. Модули

Обратите внимание: для большого удобства в изучении книга была оформлена в виде прогрессивного веб-приложения.

Определение модуля

В TS, как и в ECMAScript2015, любой файл, содержащий import или export верхнего уровня (глобальный), считается модулем.

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

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

Не модули

Для начала, давайте разберемся, что TS считает модулем. Спецификация JS определяет, что любой файл без export или await верхнего уровня является скриптом, а не модулем.

Переменные и типы, объявленные в скрипте, являются глобальными (имеют глобальную область видимости), для объединения нескольких файлов на входе в один на выходе следует использовать либо настроку компилятора outFile, либо несколько элементов script в разметке (указанных в правильном порядке).

Если у нас имеется файл, который не содержит import или export, но мы хотим, чтобы этот файл считался модулем, просто добавляем в него такую строку:

export {}

Модули в TS

Существует 3 вещи, на которые следует обращать внимание при работе с модулями в TS:

• Синтаксис: какой синтаксис я хочу использовать для импорта и экспорта сущностей?
• Разрешение модулей: каковы отношения между названиями модулей (или их путями) и файлами на диске?
• Результат: на что должен быть похож код модуля?

Синтаксис

Основной экспорт в файле определяется с помощью export default:

// @filename: hello.ts
export default function helloWorld() {
  console.log('Привет, народ!')
}

Затем данная функция импортируется следующим образом:

import hello from './hello.js'
hello()

В дополнению к экспорту по умолчанию, из файла может экспортироваться несколько переменных и функций с помощью export (без default):

// @filename: maths.ts
export var pi = 3.14
export let squareTwo = 1.41
export const phi = 1.61

export class RandomNumberGenerator {}

export function absolute(num: number) {
  if (num < 0) return num * -1
  return num
}

Указанные сущности импортируются так:

import { pi, phi, absolute } from './maths.js'

console.log(pi)
const absPhi = absolute(phi)
  // const absPhi: number

Дополнительный синтаксис импорта

Название импортируемой сущности можно менять с помощью import { old as new }:

import { pi as π } from './maths.js'

console.log(π)
        /*
          (alias) var π: number
          import π
        */

Разные способы импорта можно смешивать:

// @filename: maths.ts
export const pi = 3.14
export default class RandomNumberGenerator {}

// @filename: app.ts
import RNGen, { pi as π } from './maths.js'

RNGen
/*
  (alias) class RNGen
  import RNGen
*/

console.log(π)
/*
  (alias) const π: 3.14
  import π
*/

Все экспортированные объекты при импорте можно поместить в одно пространство имен с помощью * as name:

// @filename: app.ts
import * as math from './maths.js'

console.log(math.pi)
const positivePhi = math.absolute(math.phi)
  // const positivePhi: number

Файлы можно импортировать без указания переменных:

// @filename: app.ts
import './maths.js'

console.log('3.14')

В данном случае import ничего не делает. Тем не менее, весь код из maths.ts вычисляется (оценивается), что может привести к запуску побочных эффектов, влияющих на другие объекты.

Специфичный для TS синтаксис модулей

Типы могут экспортироваться и импортироваться с помощью такого же синтаксиса, что и значения в JS:

// @filename: animal.ts
export type Cat = { breed: string, yearOfBirth: number }

export interface Dog {
  breeds: string[]
  yearOfBirth: number
}

// @filename: app.ts
import { Cat, Dog } from './animal.js'
type Animals = Cat | Dog

TS расширяет синтаксис import с помощью import type, что позволяет импортировать только типы.

// @filename: animal.ts
export type Cat = { breed: string, yearOfBirth: number }
// 'createCatName' cannot be used as a value because it was imported using 'import type'.
// 'createCatName' не может использоваться в качестве значения, поскольку импортируется с помощью 'import type'
export type Dog = { breeds: string[], yearOfBirth: number }
export const createCatName = () => 'fluffy'

// @filename: valid.ts
import type { Cat, Dog } from './animal.js'
export type Animals = Cat | Dog

// @filename: app.ts
import type { createCatName } from './animal.js'
const name = createCatName()

Такой импорт сообщает транспиляторам, вроде Babel, swc или esbuild, какой импорт может быть безопасно удален.

Синтаксис ES-модулей с поведением CommonJS

Синтаксис ES-модулей в TS напрямую согласуется с CommonJS и require из AMD. Импорт с помощью ES-модулей в большинстве случаев представляет собой тоже самое, что require в указанных окружениях, он позволяет обеспечить полное совпадение TS-файла с результатом CommonJS:

import fs = require('fs')
const code = fs.readFileSync('hello.ts', 'utf8')

Синтаксис CommonJS

CommonJS — это формат, используемый большинством npm-пакетов. Даже если вы используете только синтаксис ES-модулей, понимание того, как работает CommonJS, поможет вам в отладке приложений.

Экспорт

Идентификаторы экпортируются посредством установки свойства exports глобальной переменной module:

function absolute(num: number) {
  if (num < 0) return num * -1
  return num
}

module.exports = {
  pi: 3.14,
  squareTwo: 1.41,
  phi: 1.61,
  absolute
}

Затем эти файлы импортируются с помощью инструкции require:

const maths = require('maths')
maths.pi
  // any

В данном случае импорт можно упростить с помощью деструктуризации:

const { squareTwo } = require('maths')
squareTwo
  // const squareTwo: any

Взаимодействие CommonJS с ES-модулями

Между CommonJS и ES-модулями имеется несовпадение, поскольку ES-модули поддерживают "дефолтный" экспорт только объектов, но не функций. Для преодоления данного несовпадения в TS используется флаг компиляции esModuleInterop.

Настройки, связанные с разрешением модулей

Разрешение модулей — это процесс определения файла, указанного в качестве ссылки в строке из инструкции import или require.

TS предоставляет две стратегии разрешения модулей: классическую и Node. Классическая стратегия является стратегией по умолчанию (когда флаг module имеет значение, отличное от commonjs) и включается для обеспечения обратной совместимости. Стратегия Node имитирует работу Node.js в режиме CommonJS с дополнительными проверками для .ts и .d.ts.

Существует большое количество флагов, связанных с разрешением модулей: moduleResolution, baseUrl, paths, rootDirs и др.

Настройки для результатов разрешения модулей

Имеется две настройки, которые влияют на результирующий JS-код:

• target — определяет версию JS, в которую компилируется TS-код
• module — определяет, какой код используется для взаимодействия модулей между собой

То, какую цель (target) использовать, зависит от того, в какой среде будет выполняться код (какие возможности поддерживаются этой средой). Это может включать в себя поддержку старых браузеров, более низкую версию Node.js или специфические ограничения, накладываемые такими средами выполнения, как, например, Electron.

Коммуникация между модулями происходит через загрузчик модулей (module loader), определяемый в настройке module. Во время выполнения загрузчик отвечает за локализацию и установку всех зависимостей модуля перед его выполнением.

Ниже приведено несколько примеров использования синтаксиса ES-модулей с разными настройками module:

import { valueOfPi } from './constants.js'

export const twoPi = valueOfPi * 2

ES2020

import { valueOfPi } from './constants.js'
export const twoPi = valueOfPi * 2

CommonJS

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_js_1 = require("./constants.js");
exports.twoPi = constants_js_1.valueOfPi * 2;

UMD

(function (factory) {
  if (typeof module === "object" && typeof module.exports === "object") {
    var v = factory(require, exports);
    if (v !== undefined) module.exports = v;
  }
  else if (typeof define === "function" && define.amd) {
    define(["require", "exports", "./constants.js"], factory);
  }
})(function (require, exports) {
  "use strict";
  Object.defineProperty(exports, "__esModule", { value: true });
  exports.twoPi = void 0;
  const constants_js_1 = require("./constants.js");
  exports.twoPi = constants_js_1.valueOfPi * 2;
});

Пространства имен (namespaces)

TS имеет собственный модульный формат, который называется namespaces. Данный синтаксис имеет множество полезных возможностей по созданию сложных файлов определений и по-прежнему активно используется в DefinitelyTyped. Несмотря на то, что namespaces не признаны устаревшими (deprecated), большая часть его возможностей нашла воплощение в ES-модулях, поэтому настоятельно рекомендуется использовать официальный синтаксис.

---

VPS серверы от Маклауд быстрые и безопасные.

Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!