Работа с YAML в Node.js: библиотеки js-yaml и yaml

Работа с YAML в JavaScript (Node.js)

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

В этой статье мы рассмотрим обе библиотеки, научимся парсить YAML в объекты JavaScript, сериализовать объекты обратно в YAML, а также обрабатывать ошибки и работать с файлами.

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

Для начала установите одну из библиотек через npm:

# Установка js-yaml (рекомендуется для большинства проектов)
npm install js-yaml

# Установка более современной библиотеки yaml
npm install yaml

Библиотека js-yaml

js-yaml — это наиболее зрелая и широко используемая библиотека для работы с YAML в Node.js. Она поддерживает полную спецификацию YAML 1.2, включая сложные типы данных, теги и пользовательские схемы.

Парсинг YAML-строки

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

const yamlString = `
server:
  host: localhost
  port: 8080
  ssl: true
database:
  driver: postgresql
  host: db.example.com
  port: 5432
  credentials:
    user: admin
    password: secret
`;

try {
  const data = yaml.load(yamlString);
  console.log(data.server.host); // "localhost"
  console.log(data.database.credentials.user); // "admin"
} catch (e) {
  console.error('Ошибка парсинга YAML:', e.message);
}

Парсинг YAML-файла

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

try {
  const fileContents = fs.readFileSync('./config.yaml', 'utf8');
  const data = yaml.load(fileContents);
  console.log(data);
} catch (e) {
  console.error('Ошибка чтения файла:', e.message);
}

Сериализация в YAML

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

const config = {
  app: {
    name: "MyApp",
    version: "1.0.0"
  },
  features: {
    logging: true,
    cache: {
      ttl: 3600,
      type: "redis"
    }
  }
};

const yamlString = yaml.dump(config, {
  indent: 2,        // отступ в 2 пробела
  lineWidth: 80,    // максимальная длина строки
  noRefs: true,     // не использовать ссылки
  sortKeys: true    // сортировать ключи
});

console.log(yamlString);
// Вывод:
// app:
//   name: MyApp
//   version: 1.0.0
// features:
//   cache:
//     ttl: 3600
//     type: redis
//   logging: true

Работа с пользовательскими типами

js-yaml поддерживает кастомные теги YAML для обработки специальных типов данных:

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

// Создаём кастомный тип для даты
const DateType = new yaml.Type('!date', {
  kind: 'scalar',
  resolve: (data) => data.match(/^\d{4}-\d{2}-\d{2}$/),
  construct: (data) => new Date(data),
  instanceOf: Date,
  represent: (date) => date.toISOString().split('T')[0]
});

// Создаём схему с кастомным типом
const CUSTOM_SCHEMA = yaml.DEFAULT_SCHEMA.extend([DateType]);

const yamlString = `
event: !date 2025-12-31
name: "New Year Party"
`;

const data = yaml.load(yamlString, { schema: CUSTOM_SCHEMA });
console.log(data.event instanceof Date); // true
console.log(data.event.getFullYear());   // 2025

Библиотека yaml

yaml — это более современная библиотека, которая предлагает потоковый парсинг и лучшую поддержку Unicode. Она также реализует спецификацию YAML 1.2.

Базовый парсинг

const YAML = require('yaml');

const doc = YAML.parse(`
person:
  name: Иван
  age: 30
  hobbies:
    - программирование
    - чтение
`);

console.log(doc.person.name); // "Иван"
console.log(doc.person.hobbies[0]); // "программирование"

Сериализация с комментариями

Одно из главных преимуществ библиотеки yaml — сохранение комментариев и форматирования:

const YAML = require('yaml');

const doc = new YAML.Document();
doc.contents = {
  server: {
    host: 'localhost',
    port: 8080
  }
};

// Добавляем комментарий
doc.contents.server