Trabalhando com YAML em TypeScript: guia completo de parsing e serialização

Trabalhando com YAML em TypeScript: parsing, serialização e exemplos práticos

YAML (YAML Ain't Markup Language) é um formato popular de serialização de dados, frequentemente usado para arquivos de configuração, descrição de APIs e armazenamento de dados estruturados. No ecossistema TypeScript, existem várias ferramentas confiáveis para trabalhar com YAML. Neste artigo, abordaremos detalhadamente a biblioteca js-yaml, que é o padrão de facto para parsing e serialização de YAML em projetos TypeScript.

Instalação e configuração

Para começar, é necessário instalar a biblioteca js-yaml e suas definições de tipo para TypeScript:

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

Após a instalação, você pode importar a biblioteca no seu projeto:

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

Principais recursos da biblioteca js-yaml

• Parsing de YAML para objetos TypeScript — conversão de strings YAML em estruturas de dados tipadas
• Serialização de objetos para YAML — conversão inversa de objetos TypeScript para o formato YAML
• Suporte a tipos personalizados — possibilidade de definir tags YAML próprias
• Validação de esquemas — verificação da correção da estrutura do documento YAML
• Trabalho com arquivos — leitura e escrita de arquivos YAML via Node.js

Parsing de YAML em TypeScript

A biblioteca js-yaml fornece dois métodos principais para parsing: yaml.load() e yaml.safeLoad(). Recomenda-se usar safeLoad() para evitar a execução de código potencialmente perigoso:

import * as yaml from 'js-yaml';

const yamlString = `name: PythonLibversion: 1.0.0features:  - parsing  - serialization  - validationmetadata:  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); // PythonLibconsole.log(config.features); // ['parsing', 'serialization', 'validation']

Serialização de objetos para YAML

Para converter um objeto TypeScript de volta para YAML, utiliza-se o método 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: localhostport: 3000ssl: falsepaths:  static: ./public  uploads: ./uploads*/

Trabalhando com arquivos YAML no Node.js

Frequentemente, é necessário carregar uma configuração de um arquivo YAML externo. Veja como fazer isso usando o módulo 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(`Erro ao carregar arquivo YAML: ${filePath}`, error);    throw error;  }}

// Usoconst dbConfig = loadYamlConfig<DatabaseConfig>('./config/database.yaml');console.log(`Conectando a ${dbConfig.host}:${dbConfig.port}/${dbConf