Trabalho com YAML em TypeScript: bibliotecas e exemplos |…

Trabalho com YAML em TypeScript: parsing, geração e validação

\n\n

YAML (YAML Ain't Markup Language) — um dos formatos de serialização de dados mais populares, amplamente utilizado em arquivos de configuração, DevOps (Docker, Kubernetes, Ansible) e pipelines de CI/CD. No ecossistema TypeScript, a biblioteca js-yaml é usada para trabalhar com YAML, oferecendo suporte completo à especificação YAML 1.2, incluindo estruturas complexas, tags e tipos de dados personalizados.

\n\n

Instalação e configuração

\n\n

Para começar, instale a biblioteca e seus tipos via npm:

\n\n

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

\n\n

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

\n\n

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

\n\n

Parsing de YAML em TypeScript

\n\n

A função principal para ler YAML é yaml.load(), que converte uma string YAML em um objeto JavaScript/TypeScript. Veja um exemplo com um arquivo de configuração:

\n\n

// config.yaml\n// server:\n//   port: 3000\n//   host: "localhost"\n// database:\n//   url: "mongodb://localhost:27017/mydb"\n//   poolSize: 10\n// features:\n//   - logging\n//   - authentication\n\ninterface Config {\n  server: {\n    port: number;\n    host: string;\n  };\n  database: {\n    url: string;\n    poolSize: number;\n  };\n  features: string[];\n}\n\nconst yamlContent = fs.readFileSync('config.yaml', 'utf8');\nconst config = yaml.load(yamlContent) as Config;\n\nconsole.log(config.server.port); // 3000\nconsole.log(config.features); // ['logging', 'authentication']

\n\n

Para parsing seguro (sem execução de código), use yaml.load() — ele é mais seguro que yaml.eval(), que pode executar código JavaScript arbitrário.

\n\n

Geração de YAML a partir de objetos TypeScript

\n\n

A operação inversa — converter um objeto TypeScript em uma string YAML — é feita pela função yaml.dump(). Isso é útil para criar arquivos de configuração dinamicamente:

\n\n

interface DeploymentConfig {\n  apiVersion: string;\n  kind: string;\n  metadata: { name: string; labels?: Record<string, string> };\n  spec: { replicas: number; selector: Record<string, string> };\n}\n\nconst deployment: DeploymentConfig = {\n  apiVersion: 'apps/v1',\n  kind: 'Deployment',\n  metadata: {\n    name: 'my-app',\n    labels: { app: 'my-app', tier: 'backend' }\n  },\n  spec: {\n    replicas: 3,\n    selector: { matchLabels: { app: 'my-app' } }\n  }\n};\n\nconst yamlString = yaml.dump(deployment, {\n  indent: 2,\n  lineWidth: 120,\n  noRefs: true,\n  sortKeys: true\n});\n\nconsole.log(yamlString);\n// apiVersion: apps/v1\n// kind: Deployment\n// metadata:\n//   labels:\n//     app: my-app\n//     tier: backend\n//   name: my-app\n// spec:\n//   replicas: 3\n//   selector:\n//     matchLabels:\n//       app: my-app

\n\n

Trabalho com tipos personalizados

\n\n

A biblioteca js-yaml suporta esquemas e tipos de dados personalizados. Isso é especialmente útil ao trabalhar com datas, expressões regulares ou objetos especiais:

\n\n

import * as yaml from 'js-yaml';\n\n// Criando um tipo personalizado para datas\nconst DateType = new yaml.Type('!date', {\n  kind: 'scalar',\n  resolve: (data: string) => !isNaN(Date.parse(data)),\n  construct: (data: string) => new Date(data),\n  instanceOf: Date,\n  represent: (date: Date) => date.toISOString()\n});\n\n// Criando um esquema com suporte a tipos padrão e personalizados\nconst schema = yaml.DEFAULT_SCHEMA.extend([DateType]);\n\nconst yamlWithDates = `\nevent: !date 2024-12-25T10:00:00Z\ntitle: "Seminário de Natal"\n`;\n\nconst parsed = yaml.load(yamlWithDates, { schema });\nconsole.log(parsed.event instanceof Date); // true\nconsole.log(parsed.event.toLocaleDateString('pt-BR')); // 25/12/2024

\n\n