Работа с YAML в TypeScript: полное руководство по парсингу и сериализации

Работа с YAML в TypeScript: парсинг, сериализация и практические примеры

YAML (YAML Ain't Markup Language) — это популярный формат сериализации данных, который часто используется для конфигурационных файлов, описания API и хранения структурированных данных. В экосистеме TypeScript существует несколько надежных инструментов для работы с YAML. В этой статье мы подробно рассмотрим библиотеку js-yaml, которая является де-факто стандартом для парсинга и сериализации YAML в TypeScript-проектах.

Установка и настройка

Для начала работы необходимо установить библиотеку js-yaml и её TypeScript-тайпинги:

npm install js-yaml
npm install --save-dev @types/js-yaml

После установки вы можете импортировать библиотеку в свой проект:

import * as yaml from 'js-yaml';
import * as fs from 'fs';

Основные возможности библиотеки js-yaml

• Парсинг YAML в объекты TypeScript — преобразование YAML-строки в типизированные структуры данных
• Сериализация объектов в YAML — обратное преобразование TypeScript-объектов в YAML-формат
• Поддержка кастомных типов — возможность определять собственные YAML-теги
• Валидация схем — проверка корректности структуры YAML-документа
• Работа с файлами — чтение и запись YAML-файлов через Node.js

Парсинг YAML в TypeScript

Библиотека js-yaml предоставляет два основных метода для парсинга: yaml.load() и yaml.safeLoad(). Рекомендуется использовать safeLoad() для предотвращения выполнения потенциально опасного кода:

import * as yaml from 'js-yaml';

const yamlString = `
name: PythonLib
version: 1.0.0
features:
  - parsing
  - serialization
  - validation
metadata:
  author: Developer
  created: 2024-01-15
`;

interface Config {
  name: string;
  version: string;
  features: string[];
  metadata: {
    author: string;
    created: string;
  };
}

const config: Config = yaml.load(yamlString) as Config;
console.log(config.name); // PythonLib
console.log(config.features); // ['parsing', 'serialization', 'validation']

Сериализация объектов в YAML

Для преобразования TypeScript-объекта обратно в YAML используется метод yaml.dump():

import * as yaml from 'js-yaml';

interface ServerConfig {
  host: string;
  port: number;
  ssl: boolean;
  paths: {
    static: string;
    uploads: string;
  };
}

const serverConfig: ServerConfig = {
  host: 'localhost',
  port: 3000,
  ssl: false,
  paths: {
    static: './public',
    uploads: './uploads'
  }
};

const yamlOutput = yaml.dump(serverConfig, {
  indent: 2,
  lineWidth: 80,
  noRefs: true
});

console.log(yamlOutput);
/*
host: localhost
port: 3000
ssl: false
paths:
  static: ./public
  uploads: ./uploads
*/

Работа с YAML-файлами в Node.js

Часто требуется загрузить конфигурацию из внешнего YAML-файла. Вот как это сделать с использованием модуля fs:

import * as yaml from 'js-yaml';
import * as fs from 'fs';
import * as path from 'path';

interface DatabaseConfig {
  host: string;
  port: number;
  database: string;
  username: string;
  password: string;
}

function loadYamlConfig<T>(filePath: string): T {
  try {
    const fileContent = fs.readFileSync(path.resolve(filePath), 'utf8');
    return yaml.load(fileContent) as T;
  } catch (error) {
    console.error(`Ошибка загрузки YAML-файла: ${filePath}`, error);
    throw error;
  }
}

// Использование
const dbConfig = loadYamlConfig<DatabaseConfig>('./config/database.yaml');
console.log(`Подключение к ${dbConfig.host}:${dbConfig.port}/${dbConfig.database}`);

Валидация YAML с помощью TypeScript

Для обеспечения типобезопасности можно использовать библиотеку zod или io-ts для валидации распарсенных YAML-данных:

import * as yaml from 'js-yaml';
import { z } from 'zod';

const AppConfigSchema = z.object({
  app: z.object({
    name: z.string().min(1),
    version: z.string().regex(/^\d+\.\d+\.\d+$/),
    debug: z.boolean().default(false)
  }),
  database: z.object