Trabalhando com YAML em JavaScript (Node.js): parsing, geração e validação

Trabalhando com YAML em JavaScript (Node.js): guia completo

YAML (YAML Ain't Markup Language) é um formato de serialização de dados legível por humanos, amplamente utilizado para arquivos de configuração, descrição de APIs, pipelines de CI/CD e troca de dados. No ecossistema Node.js, existem várias bibliotecas poderosas para trabalhar com YAML. Neste artigo, vamos detalhar as principais ferramentas, suas capacidades e exemplos de uso.

Bibliotecas populares para YAML em Node.js

As bibliotecas mais comuns para trabalhar com YAML no ambiente Node.js:

• js-yaml — a biblioteca mais popular e ativamente mantida. Suporta uma gama completa de operações: parsing, serialização, esquemas e tipos personalizados.
• yaml (pacote yaml) — uma alternativa moderna com suporte a parsing estrito, comentários e AST (árvore sintática abstrata).
• yamljs — uma biblioteca leve com API simples, adequada para tarefas básicas.

Instalação da biblioteca js-yaml

Para começar a trabalhar com YAML em Node.js, instale a biblioteca via npm:

npm install js-yaml

Após a instalação, importe a biblioteca para o seu projeto:

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

Parsing de YAML para objeto JavaScript

A operação principal — converter uma string YAML em um objeto JavaScript:

const yamlString = `server:  host: localhost  port: 8080  ssl: truedatabases:  - 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('Erro de parsing YAML:', e.message);}

O método yaml.load() converte com segurança uma string YAML em um objeto. Para carregar de um arquivo, use:

try {  const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));  console.log(config);} catch (e) {  console.error('Erro ao ler configuração:', e);}

Serialização de objeto JavaScript para YAML

A operação inversa — converter um objeto em uma string 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);// Saída:// app://   name: MyApp//   version: 1.0.0// features://   - auth//   - logging//   - analytics// database://   host: db.example.com//   port: 5432

Parâmetros do método yaml.dump():

• indent — número de espaços para indentação (padrão 2)
• lineWidth — comprimento máximo da linha (padrão 80)
• noRefs — desabilitar uso de âncoras e referências
• skipInvalid — pular valores inválidos em vez de lançar erro

Trabalhando com tipos personalizados YAML

js-yaml suporta esquemas e tipos de dados personalizados. Por exemplo, você pode adicionar suporte a datas:

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

// Criando um esquema personalizado com suporte a datasconst 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 inst