Работа с YAML в JavaScript (Node.js): парсинг, генерация и валидация

Работа с YAML в JavaScript (Node.js): полное руководство

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

Популярные библиотеки для YAML в Node.js

Наиболее распространенные библиотеки для работы с YAML в среде Node.js:

• js-yaml — самая популярная и активно поддерживаемая библиотека. Поддерживает полный спектр операций: парсинг, сериализацию, кастомные схемы и типы.
• yaml (пакет yaml) — современная альтернатива с поддержкой строгого парсинга, комментариев и AST (абстрактного синтаксического дерева).
• yamljs — легковесная библиотека с простым API, подходит для базовых задач.

Установка библиотеки js-yaml

Для начала работы с YAML в Node.js установите библиотеку через npm:

npm install js-yaml

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

const yaml = require('js-yaml');
const fs = require('fs');

Парсинг YAML в JavaScript объект

Основная операция — преобразование YAML-строки в объект JavaScript:

const yamlString = `
server:
  host: localhost
  port: 8080
  ssl: true
databases:
  - name: users
    type: postgres
  - name: logs
    type: mongodb
`;

try {
  const data = yaml.load(yamlString);
  console.log(data.server.host); // "localhost"
  console.log(data.databases[0].name); // "users"
} catch (e) {
  console.error('Ошибка парсинга YAML:', e.message);
}

Метод yaml.load() безопасно преобразует YAML-строку в объект. Для загрузки из файла используйте:

try {
  const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
  console.log(config);
} catch (e) {
  console.error('Ошибка чтения конфигурации:', e);
}

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

Обратная операция — преобразование объекта в YAML-строку:

const configObject = {
  app: {
    name: "MyApp",
    version: "1.0.0"
  },
  features: ["auth", "logging", "analytics"],
  database: {
    host: "db.example.com",
    port: 5432
  }
};

const yamlString = yaml.dump(configObject, {
  indent: 2,
  lineWidth: 120,
  noRefs: true
});

console.log(yamlString);
// Вывод:
// app:
//   name: MyApp
//   version: 1.0.0
// features:
//   - auth
//   - logging
//   - analytics
// database:
//   host: db.example.com
//   port: 5432

Параметры метода yaml.dump():

• indent — количество пробелов для отступов (по умолчанию 2)
• lineWidth — максимальная длина строки (по умолчанию 80)
• noRefs — отключение использования якорей и ссылок
• skipInvalid — пропуск невалидных значений вместо выброса ошибки

Работа с кастомными типами YAML

js-yaml поддерживает кастомные схемы и типы данных. Например, можно добавить поддержку дат:

const yaml = require('js-yaml');

// Создание кастомной схемы с поддержкой дат
const schema = yaml.DEFAULT_SCHEMA.extend([
  new yaml.Type('tag:yaml.org,2002:timestamp', {
    kind: 'scalar',
    resolve: (data) => {
      return !isNaN(Date.parse(data));
    },
    construct: (data) => {
      return new Date(data);
    },
    instanceOf: Date,
    represent: (date) => {
      return date.toISOString();
    }
  })
]);

const yamlString = 'event_date: 2024-03-15T14:30:00Z';
const parsed = yaml.load(yamlString, { schema });
console.log(parsed.event_date instanceof Date); // true

Валидация YAML данных

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

function validateConfig(yamlContent) {
  try {
    const config = yaml.load(yamlContent);
    
    // Проверка обязательных полей
    if (!config.server) throw new Error('Отсутствует секция server');
    if (!config.server.host) throw