Одной из интересных возможностей пакета typescript является то, что он содержит API для генерации TypeScript-кода, а также парсер для работы с написанным на TypeScript кодом. Кодогенерация часто используется для автоматического создания типов для работы с http api (типизация тела запроса, ответа, query параметров и тд.). В npm есть модули, генерирующие сервисы для работы с api на основе openapi, graphQl схем и тому подобное, и обычно возможностей существующих модулей хватает для решения большей части задач.

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

Кодогенерация

Рассмотрим для примера генерацию кода с декларацией простого union:

export type Numbers = "one" | "two" | "three";

Для начала сконфигурируем небольшой проект с помощью команды npm init. Затем установим npm пакет typescript командой npm install typescript. Также для дальнейшей работы нам нужно установить зависимость npm install @types/node --save-dev.

Для генерации указанного выше union Numbers понадобится следующий код:

// ./src/index.ts
import * as ts from "typescript";

const file = ts.createSourceFile("source.ts", "", ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });

const one = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("one"));
const two = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("two"));
const three = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("three"));

const decl = ts.factory.createTypeAliasDeclaration(
  [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)], // modifiers (export keyword)
  ts.factory.createIdentifier("Numbers"), // name
  undefined, // typeParameters
  ts.factory.createUnionTypeNode([ one, two, three ]), // type
)

const result = printer.printNode(ts.EmitHint.Unspecified, decl, file);
console.log(result);

Для компиляции и запуска этого файла добавим в проектtsconfig.json:

// ./tsconfig.json
{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "target": "esnext",
    "module": "CommonJS",
    "moduleResolution": "node",
    "types": [
      "node"
    ],
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  },
  "include": ["./src/**/*.ts"]
}

А также скрипты build и start в package.json:

// ./package.json
"scripts": {
  "build": "tsc",
  "start": "node dist/index.js"
}

Теперь мы можем скомпилировать и выполнить код из ./src/index.ts. Последовательно запускаем команды npm run build, npm run start. 

Результат выполнения скрипта — вывод в консоль строки:

Разберем подробнее код в ./src/index.ts. Вначале импортируется пакет typescript и создается специальный объект принтера, который используется в дальнейшем для форматированного вывода построенной typescript декларации:

const file = ts.createSourceFile("source.ts", "", ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });

// ...

const result = printer.printNode(ts.EmitHint.Unspecified, decl, file);
console.log(result);

Больший интерес представляет код, содержащийся между этими строками:

const one = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("one"));
const two = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("two"));
const three = ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("three"));

const decl = ts.factory.createTypeAliasDeclaration(
  [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)], // modifiers (export keyword)
  ts.factory.createIdentifier("Numbers"), // name
  undefined, // typeParameters
  ts.factory.createUnionTypeNode([ one, two, three ]), // type
);

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

Для идентификации названий нужных typescript сущностей можно использовать API для парсинга кода. То есть сначала пишем псевдокод, парсим его средствами typescript и получаем AST (abstract syntax tree), изучаем его и создаем на основе полученных знаний нужную нам конструкцию.

Парсинг typescript

Для демонстрации API парсинга создадим файл с кодом на typescript, который будем использовать для парсинга:

// ./union.ts
export type Numbers = "one" | "two" | "three";

Далее добавим в ./src/index.ts следующий код:

// ./src/index.ts
import * as fs from 'node:fs';
import * as path from 'path';

const schema = ts.createSourceFile(
  'x.ts',
  fs.readFileSync(path.resolve(process.cwd(), './union.ts'), 'utf-8'),
  ts.ScriptTarget.Latest,
  undefined,
);

console.log(schema.statements[0]);

Функция createSourceFile создаст AST-дерево для нашего файла union.ts и в поле statements будет массив ts сущностей, задекларированных в файле. Единственная сущность, находящаяся там — это экспортируемый юнион тип Numbers. Вывод в консоль в конце файла console.log(schema.statements[0]); отобразит структуру его AST:

NodeObject {
  pos: 0,
  end: 46,
  flags: 0,
  modifierFlagsCache: 0,
  transformFlags: 1,
  parent: undefined,
  kind: 265,
  symbol: undefined,
  localSymbol: undefined,
  modifiers: [
    TokenObject {
      pos: 0,
      end: 6,
      flags: 0,
      modifierFlagsCache: 0,
      transformFlags: 0,
      parent: undefined,
      kind: 95
    },
    pos: 0,
    end: 6,
    hasTrailingComma: false,
    transformFlags: 0
  ],
  name: IdentifierObject {
    pos: 11,
    end: 19,
    flags: 0,
    modifierFlagsCache: 0,
    transformFlags: 0,
    parent: undefined,
    kind: 80,
    escapedText: 'Numbers',
    jsDoc: undefined,
    flowNode: undefined,
    symbol: undefined
  },
  typeParameters: undefined,
  type: NodeObject {
    pos: 21,
    end: 45,
    flags: 0,
    modifierFlagsCache: 0,
    transformFlags: 1,
    parent: undefined,
    kind: 192,
    types: [
      [NodeObject],
      [NodeObject],
      [NodeObject],
      pos: 21,
      end: 45,
      hasTrailingComma: false,
      transformFlags: 1
    ]
  },
  jsDoc: undefined,
  locals: undefined,
  nextContainer: undefined
}

Анализ AST

AST удобнее анализировать в REPL-режиме, приостановив исполнение скрипта в дебагере IDE. Если вы пользуетесь VSCode, то настроить дебагер можно, добавив файл .vscode/launch.json со следующим содержимым:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run programm",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "npm: build",
      "sourceMaps": true,
      "smartStep": true,
      "internalConsoleOptions": "openOnSessionStart",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "console": "internalConsole",
      "outputCapture": "std"
    }
  ]
}

Далее установим брейкпоинт на строке с выводом в консоль и запустим дебагер (F5 hotkey):

Затем проанализируем AST в объекте schema.statements[0].

Наибольший интерес в нем на данный момент представляют поля kind, modifiers, name и type. kind — в этом поле хранится значение из enum ts.SyntaxKind, по которому можно определить название сущности, а затем найти необходимый для его создания конструктор в пространстве ts.factory.

Как мы видим, корневой элемент нашего дерева имеет kind === 265, то есть тип TypeAliasDeclaration, и для его создания используется следующая функция в ts.factory:

createTypeAliasDeclaration(
  modifiers: readonly ModifierLike[] | undefined,
  name: string | Identifier,
  typeParameters: readonly TypeParameterDeclaration[] | undefined,
  type: TypeNode
): TypeAliasDeclaration;

, где поля modifiers, name, type, содержат как раз те сущности, которые мы видели при выводе в консоль AST для объекта schema.statements[0]. Проанализировав эти поля в REPL, можно понять, какие объекты нам нужно передавать в конструктор.

Анализ AST в REPL дает нам возможность полностью ознакомиться со структурой AST, но отнимает много времени. Если нам нужно быстро выяснить, как создать определенную сущность в виде AST, можно воспользоваться онлайн-инструментом TypeScript AST Viewer. Если в нем написать создаваемый нами union Numbers, то он выведет нам следующую конструкцию для создания его AST:

Инструмент TypeScript AST Viewer удобен в использовании и сильно экономит время для анализа AST, но есть в нем и небольшие ограничения. Он не отображает jsDoc-комментарии. При работе с ними есть определенные особенности, о которых расскажу в конце статьи.

Работа с AST

Мы посмотрели, как извлекать информацию из AST в REPL, теперь рассмотрим пример, как работать с ним в TypeScript. 

Предположим, что у нас есть файл со следующим содержимым:

// ./numbers.ts
export interface Numbers {
  one: 1
  two: 2
  three: 3
}

и нам нужно его распарсить и сформировать массив строк со значениями ключей интерфейса Numbers: ['one', 'two', 'three'].

Для этого добавим в ./src/index.ts:

// ./src/index.ts
const numbersSource = ts.createSourceFile(
  'x.ts',
  fs.readFileSync(path.resolve(process.cwd(), './numbers.ts'), 'utf-8'),
  ts.ScriptTarget.Latest,
  undefined,
);

const numbersDecl = numbersSource.statements.find((node) => {
  return ts.isInterfaceDeclaration(node) && node.name.text === 'Numbers';
});

if (!numbersDecl || !ts.isInterfaceDeclaration(numbersDecl)) {
  throw new Error('no interface "Numbers" in file');
}

const numbers = numbersDecl.members.reduce<string[]>((acc, node) => {
  if (ts.isPropertySignature(node) && ts.isIdentifier(node.name)) {
    acc.push(node.name.escapedText.toString())
  }

  return acc
}, [])

console.log(numbers); // [ 'one', 'two', 'three' ]

Взаимодействие с AST в TypeScript не сильно отличается от работы с ним в REPL, за исключением того, что элементы statements являются инстансами NodeObject и ничего не знают о полях members, name и прочих. Для того чтобы обратиться к нужным нам полям, надо сначала проверить, что объект является инстансом конкретного класса, у которого имеются данные поля. Для этих целей в typescript есть огромное количество гардов, например, те, что мы использовали в коде выше: ts.isInterfaceDeclaration, ts.isPropertySignature и ts.isIdentifier.

Особенности работы с jsDoc

При анализе AST в REPL у инстансов NodeObject можно заметить поле jsDoc. Как видно из названия, в нем хранится информация о jsDoc-комментариях и тегах для данного узла дерева.

Парсинг jsDoc

Создадим простой файл с классом и комментарием к методу:

// ./comments.ts
export class Greetings {
  /**
   * приветствует мир
   * @deprecated метод устарел
   */
  hello() {
    console.log('hello world')
  }
}

А затем распарсим его и проанализируем его AST в REPL:

// ./src/index.ts
const commentsSource = ts.createSourceFile(
  'x.ts',
  fs.readFileSync(path.resolve(process.cwd(), './comments.ts'), 'utf-8'),
  ts.ScriptTarget.Latest,
  true, // setParentNodes Важно указать true, если нужно работать с jsDoc комментариями
);

console.log(commentsSource.statements[0]);

Посмотрим, как выглядит AST jsDoc-комментария для метода hello класса Greetings

Как видим, в нем есть информация о тексте комментария, а также массив с тегами, состоящий из одного элемента.

Для получения jsDoc-комментариев и тегов в typescript существуют специальные методы:

// ./src/index.ts
const greetingsClass = commentsSource.statements[0];
if (ts.isClassDeclaration(greetingsClass)) {
  const jsDoc = ts.getJSDocCommentsAndTags(greetingsClass.members[0]);
  console.log(jsDoc[0].comment); // приветствует мир

  const deprecated = ts.getJSDocDeprecatedTag(greetingsClass.members[0])
  console.log(deprecated.comment); // метод устарел
}

Для корректной работы этих методов важно указывать при вызове createSourceFile пятый параметр метода (setParentNodes) равным true.

Генерация кода с jsDoc комментариями

При анализе AST видно, что jsDoc-комментарии хранятся в поле jsDoc у инстансов NodeObject. Но методов по добавлению этого поля к существующему объекту или конструкторов, принимающих jsDoc, в API typescript нет. Данная проблема озвучена в ишьюсе, и вот один из вариантов генерации typescript кода рассмотренного ранее класса Greetings:

// ./src/index.ts
/** комментарий для метода hello */
const comment: any = ts.factory.createJSDocComment('приветствует мир', [
  ts.factory.createJSDocUnknownTag(ts.factory.createIdentifier('deprecated')), // тег @deprecated
])

/** метод hello */
const methodDeclaration = ts.factory.createMethodDeclaration(
  undefined,
  undefined,
  ts.factory.createIdentifier('hello'),
  undefined,
  undefined,
  [],
  undefined,
  ts.factory.createBlock(
    [
      ts.factory.createExpressionStatement(
        ts.factory.createCallExpression(
          ts.factory.createPropertyAccessExpression(
            ts.factory.createIdentifier('console'),
            ts.factory.createIdentifier('log')
          ),
          undefined,
          [ts.factory.createStringLiteral('hello world')]
        )
      ),
    ],
    true
  )
)

/** класс Greetings */
const classDeclaration = ts.factory.createClassDeclaration(
  [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
  'Greetings',
  undefined,
  undefined,
  [comment, methodDeclaration]
)

console.log(printer.printNode(ts.EmitHint.Unspecified, classDeclaration, file))

Вызов console.log в конце отобразит наш класс Greetings с jsDoc комментариями для метода hello:

Решение не очень элегантное, так как приходится добавлять any к объекту комментария, но все же позволяет добавить jsDoc к методу.