Типизация API при использовании TypeScript

API SWC в связке с TypeScript описывается через набор строго типизированных интерфейсов, которые позволяют контролировать конфигурацию трансформации, парсинга и минификации на уровне компиляции. Основная ценность типизации заключается в снижении количества ошибок, связанных с неверной структурой опций, несовместимыми комбинациями флагов и неправильными AST-параметрами.

В экосистеме SWC типизация строится вокруг пакета @swc/core, который экспортирует основные функции трансформации и сопутствующие интерфейсы. Ключевые точки входа:

  • transformSync
  • transform
  • parseSync
  • parse
  • minify

Каждая функция принимает строго определённый набор опций, описанных TypeScript-интерфейсами. 

import { transformSync, TransformOptions } from "@swc/core";

Тип TransformOptions является центральной точкой конфигурации. Он агрегирует вложенные структуры: настройки ECMAScript, TypeScript, JSX, minify-параметры и плагины.

Интерфейс TransformOptions и его структура

TransformOptions представляет собой сложный композиционный тип: 

export interface TransformOptions {
  jsc?: JscConfig;
  module?: ModuleConfig;
  minify?: boolean;
  isModule?: boolean;
  sourceMaps?: boolean | "inline";
  configFile?: boolean;
}

Каждое поле раскрывается в отдельные интерфейсы.

JscConfig как ядро компиляции

jsc определяет поведение JavaScript/TypeScript компилятора внутри SWC: 

export interface JscConfig {
  parser?: ParserConfig;
  transform?: TransformConfig;
  target?: EcmaVersion;
}

Здесь важна строгая типизация связей между parser и transform. Например, включение TypeScript-парсера влияет на доступные AST-узлы.

Типизация парсера и контроль синтаксиса

ParserConfig задаёт язык исходного кода: 

export interface ParserConfig {
  syntax: "typescript" | "ecmascript" | "jsx";
  tsx?: boolean;
  decorators?: boolean;
  dynamicImport?: boolean;
}

TypeScript усиливает контроль над допустимыми комбинациями. Например, поле tsx имеет смысл только при syntax: “typescript”.

Корректная типизация позволяет обнаруживать ошибки на этапе компиляции: 

const options: TransformOptions = {
  jsc: {
    parser: {
      syntax: "typescript",
      tsx: true
    }
  }
};

При попытке использовать tsx с syntax: “ecmascript” TypeScript выявит логическую несогласованность в конфигурации.

Строгая типизация модульной системы

SWC поддерживает несколько стратегий обработки модулей, описанных через ModuleConfig: 

export interface ModuleConfig {
  type: "es6" | "commonjs" | "umd" | "amd" | "systemjs";
  strict?: boolean;
  lazy?: boolean;
}

Типизация здесь предотвращает использование несуществующих модульных форматов. Это особенно важно при миграции проектов между различными сборочными системами.

Типизация функции transformSync

Функция трансформации является одной из наиболее используемых точек входа: 

function transformSync(
  code: string,
  options?: TransformOptions
): TransformOutput;

Возвращаемый тип TransformOutput также строго определён: 

export interface TransformOutput {
  code: string;
  map?: string;
  warnings?: string[];
}

Статическая типизация гарантирует, что результат трансформации всегда содержит поле code, а map и warnings являются опциональными.

Типизация AST и работа с узлами

При работе на уровне AST используется набор интерфейсов, соответствующих спецификации ESTree и расширениям SWC.

Базовый узел: 

export interface BaseNode {
  type: string;
  span: Span;
}

Каждый конкретный узел расширяет базовый: 

export interface Identifier extends BaseNode {
  type: "Identifier";
  value: string;
}

Типизация AST обеспечивает:

  • безопасный доступ к полям узлов
  • контроль типов при обходе дерева
  • предотвращение обращения к несуществующим свойствам

Visitor API и типизация обхода дерева

SWC предоставляет visitor-паттерн для трансформации AST. В TypeScript он описывается через generics и интерфейсы: 

export interface Visitor {
  visitIdentifier?(n: Identifier): Identifier;
  visitFunction?(n: FunctionDeclaration): FunctionDeclaration;
}

Более гибкий вариант использует обобщённый тип: 

export interface Visitor<T = unknown> {
  visit(node: BaseNode): T;
}

Это позволяет строить универсальные трансформации, сохраняя типовую безопасность.

Типизация minify API

Минификация имеет отдельный набор строго типизированных параметров: 

export interface MinifyOptions {
  compress?: boolean | CompressOptions;
  mangle?: boolean | MangleOptions;
  format?: FormatOptions;
}

Каждый вложенный тип описывает отдельный этап оптимизации.

CompressOptions 

export interface CompressOptions {
  dead_code?: boolean;
  drop_console?: boolean;
}

TypeScript предотвращает передачу недопустимых флагов и помогает поддерживать предсказуемую конфигурацию сборки.

Связь типизации SWC с конфигурационными файлами

При использовании swc.config.json или .swcrc типизация не применяется напрямую, но может быть восстановлена через вспомогательные утилиты: 

import type { TransformOptions } from "@swc/core";

const config: TransformOptions = require("./.swcrc");

Такой подход позволяет использовать JSON-конфигурацию, сохраняя преимущества TypeScript при проверке структуры.

Дискриминированные объединения в конфигурации

Многие части API SWC используют discriminated unions для строгого контроля допустимых комбинаций: 

type Syntax =
  | { syntax: "ecmascript"; jsx?: boolean }
  | { syntax: "typescript"; tsx: boolean };

Это исключает ситуацию, когда JSX-параметры применяются к неподходящему синтаксису.

Типизация ошибок и диагностических данных

SWC возвращает структурированные ошибки, которые также типизированы: 

export interface SwcError {
  message: string;
  code: number;
  location?: {
    line: number;
    column: number;
  };
}

Это позволяет интегрировать SWC в IDE и системы анализа кода с точной локализацией ошибок.

Расширение типов через пользовательские конфигурации

TypeScript позволяет расширять стандартные интерфейсы SWC для проектных нужд: 

interface CustomTransformOptions extends TransformOptions {
  enableLogging?: boolean;
  projectName?: string;
}

Такой подход сохраняет совместимость с базовым API и добавляет проектно-специфичные параметры без потери типобезопасности.

Типизация асинхронного API

Асинхронные функции используют Promise-обёртки с теми же типами результата: 

function transform(
  code: string,
  options?: TransformOptions
): Promise<TransformOutput>;

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

Совместимость типов и строгий режим TypeScript

При включённом strict режиме TypeScript усиливает контроль над использованием SWC API:

  • запрещает any в конфигурации
  • проверяет обязательные поля интерфейсов
  • контролирует соответствие union-типов
  • выявляет избыточные свойства

Это делает интеграцию SWC предсказуемой даже в крупных монорепозиториях.

Типизация и интеграция с инструментами сборки

В связке с Webpack, Vite или Rollup типы SWC используются для описания плагинов и трансформационных шагов: 

interface SwcLoaderOptions extends TransformOptions {
  exclude?: string[];
  include?: string[];
}

Такая типизация обеспечивает единообразие конфигураций между разными инструментами сборки и снижает риск расхождений в поведении трансформации кода.

Оглавление