En Bun, YAML es un ciudadano de primera clase junto con JSON y TOML. Puedes:

• Analizar cadenas YAML con Bun.YAML.parse
• importar y requerir archivos YAML como módulos en tiempo de ejecución (incluyendo soporte para recarga en caliente y modo watch)
• importar y requerir archivos YAML en aplicaciones frontend a través del bundler de bun

---

Conformidad

El analizador YAML de Bun actualmente pasa más del 90% de la suite de pruebas oficial de YAML. Aunque estamos trabajando activamente para alcanzar el 100% de conformidad, la implementación actual cubre la gran mayoría de casos de uso del mundo real. El analizador está escrito en Zig para un rendimiento óptimo y se mejora continuamente.

---

API de Runtime

Bun.YAML.parse()

Analiza una cadena YAML en un objeto de JavaScript.

import { YAML } from "bun";
const text = `
name: John Doe
age: 30
email: john@example.com
hobbies:
  - reading
  - coding
  - hiking
`;

const data = YAML.parse(text);
console.log(data);
// {
//   name: "John Doe",
//   age: 30,
//   email: "john@example.com",
//   hobbies: ["reading", "coding", "hiking"]
// }

YAML de múltiples documentos

Al analizar YAML con múltiples documentos (separados por ---), Bun.YAML.parse() devuelve un array:

const multiDoc = `
---
name: Document 1
---
name: Document 2
---
name: Document 3
`;

const docs = Bun.YAML.parse(multiDoc);
console.log(docs);
// [
//   { name: "Document 1" },
//   { name: "Document 2" },
//   { name: "Document 3" }
// ]

Características YAML Soportadas

El analizador YAML de Bun soporta la especificación completa YAML 1.2, incluyendo:

• Escalares: cadenas, números, booleanos, valores null
• Colecciones: secuencias (arrays) y mapeos (objetos)
• Anclas y Alias: nodos reutilizables con & y *
• Etiquetas: pistas de tipo como !!str, !!int, !!float, !!bool, !!null
• Cadenas multilínea: escalares literales (|) y plegados (>)
• Comentarios: usando #
• Directivas: %YAML y %TAG

const yaml = `
# Registro de empleado
employee: &emp
  name: Jane Smith
  department: Engineering
  skills:
    - JavaScript
    - TypeScript
    - React

manager: *emp  # Referencia a employee

config: !!str 123  # Tipo de cadena explícito

description: |
  Esta es una cadena multilínea
  literal que preserva
  saltos de línea y espaciado.

summary: >
  Esta es una cadena plegada
  que une líneas con espacios
  a menos que haya líneas en blanco.
`;

const data = Bun.YAML.parse(yaml);

Manejo de Errores

Bun.YAML.parse() lanza un SyntaxError si el YAML es inválido:

try {
  Bun.YAML.parse("invalid: yaml: content:");
} catch (error) {
  console.error("Falló al analizar YAML:", error.message);
}

---

Importación de Módulos

Módulos ES

Puedes importar archivos YAML directamente como módulos ES. El contenido YAML se analiza y pone disponible tanto como exportaciones predeterminadas como nombradas:

database:
  host: localhost
  port: 5432
  name: myapp

redis:
  host: localhost
  port: 6379

features:
  auth: true
  rateLimit: true
  analytics: false

Importación Predeterminada

import config from "./config.yaml";

console.log(config.database.host); // "localhost"
console.log(config.redis.port); // 6379

Importaciones Nombradas

Puedes desestructurar propiedades YAML de nivel superior como importaciones nombradas:

import { database, redis, features } from "./config.yaml";

console.log(database.host); // "localhost"
console.log(redis.port); // 6379
console.log(features.auth); // true

O combinar ambas:

import config, { database, features } from "./config.yaml";

// Usa el objeto config completo
console.log(config);

// O usa partes específicas
if (features.rateLimit) {
  setupRateLimiting(database);
}

CommonJS

Los archivos YAML también se pueden requerir en CommonJS:

const config = require("./config.yaml");
console.log(config.database.name); // "myapp"

// La desestructuración también funciona
const { database, redis } = require("./config.yaml");
console.log(database.port); // 5432

---

Recarga en Caliente con YAML

Una de las características más poderosas del soporte YAML de Bun es la recarga en caliente. Cuando ejecutas tu aplicación con bun --hot, los cambios en archivos YAML se detectan automáticamente y se recargan sin cerrar conexiones

Recarga en Caliente de Configuración

server:
  port: 3000
  host: localhost

features:
  debug: true
  verbose: false

import { server, features } from "./config.yaml";

console.log(`Iniciando servidor en ${server.host}:${server.port}`);

if (features.debug) {
  console.log("Modo depuración habilitado");
}

// Tu código de servidor aquí
Bun.serve({
  port: server.port,
  hostname: server.host,
  fetch(req) {
    if (features.verbose) {
      console.log(`${req.method} ${req.url}`);
    }
    return new Response("Hello World");
  },
});

Ejecuta con recarga en caliente:

bun --hot server.ts

Ahora cuando modificas config.yaml, los cambios se reflejan inmediatamente en tu aplicación en ejecución. Esto es perfecto para:

• Ajustar configuración durante el desarrollo
• Probar diferentes configuraciones sin reinicios
• Depuración en vivo con cambios de configuración
• Alternar flags de características

---

Gestión de Configuración

Configuración Basada en Entorno

YAML sobresale en gestionar configuración a través de diferentes entornos:

defaults: &defaults
  timeout: 5000
  retries: 3
  cache:
    enabled: true
    ttl: 3600

development:
  <<: *defaults
  api:
    url: http://localhost:4000
    key: dev_key_12345
  logging:
    level: debug
    pretty: true

staging:
  <<: *defaults
  api:
    url: https://staging-api.example.com
    key: ${STAGING_API_KEY}
  logging:
    level: info
    pretty: false

production:
  <<: *defaults
  api:
    url: https://api.example.com
    key: ${PROD_API_KEY}
  cache:
    enabled: true
    ttl: 86400
  logging:
    level: error
    pretty: false

import configs from "./config.yaml";

const env = process.env.NODE_ENV || "development";
const config = configs[env];

// Las variables de entorno en valores YAML se pueden interpolar
function interpolateEnvVars(obj: any): any {
  if (typeof obj === "string") {
    return obj.replace(/\${(\w+)}/g, (_, key) => process.env[key] || "");
  }
  if (typeof obj === "object") {
    for (const key in obj) {
      obj[key] = interpolateEnvVars(obj[key]);
    }
  }
  return obj;
}

export default interpolateEnvVars(config);

Configuración de Flags de Características

features:
  newDashboard:
    enabled: true
    rolloutPercentage: 50
    allowedUsers:
      - admin@example.com
      - beta@example.com

  experimentalAPI:
    enabled: false
    endpoints:
      - /api/v2/experimental
      - /api/v2/beta

  darkMode:
    enabled: true
    default: auto # auto, light, dark

import { features } from "./features.yaml";

export function isFeatureEnabled(featureName: string, userEmail?: string): boolean {
  const feature = features[featureName];

  if (!feature?.enabled) {
    return false;
  }

  // Verificar porcentaje de despliegue
  if (feature.rolloutPercentage < 100) {
    const hash = hashCode(userEmail || "anonymous");
    if (hash % 100 >= feature.rolloutPercentage) {
      return false;
    }
  }

  // Verificar usuarios permitidos
  if (feature.allowedUsers && userEmail) {
    return feature.allowedUsers.includes(userEmail);
  }

  return true;
}

// Usar con recarga en caliente para alternar características en tiempo real
if (isFeatureEnabled("newDashboard", user.email)) {
  renderNewDashboard();
} else {
  renderLegacyDashboard();
}

Configuración de Base de Datos

connections:
  primary:
    type: postgres
    host: ${DB_HOST:-localhost}
    port: ${DB_PORT:-5432}
    database: ${DB_NAME:-myapp}
    username: ${DB_USER:-postgres}
    password: ${DB_PASS}
    pool:
      min: 2
      max: 10
      idleTimeout: 30000

  cache:
    type: redis
    host: ${REDIS_HOST:-localhost}
    port: ${REDIS_PORT:-6379}
    password: ${REDIS_PASS}
    db: 0

  analytics:
    type: clickhouse
    host: ${ANALYTICS_HOST:-localhost}
    port: 8123
    database: analytics

migrations:
  autoRun: ${AUTO_MIGRATE:-false}
  directory: ./migrations

seeds:
  enabled: ${SEED_DB:-false}
  directory: ./seeds

import { connections, migrations } from "./database.yaml";
import { createConnection } from "./database-driver";

// Analizar variables de entorno con valores predeterminados
function parseConfig(config: any) {
  return JSON.parse(
    JSON.stringify(config).replace(
      /\${([^:-]+)(?::([^}]+))?}/g,
      (_, key, defaultValue) => process.env[key] || defaultValue || "",
    ),
  );
}

const dbConfig = parseConfig(connections);

export const db = await createConnection(dbConfig.primary);
export const cache = await createConnection(dbConfig.cache);
export const analytics = await createConnection(dbConfig.analytics);

// Ejecutar migraciones automáticamente si está configurado
if (parseConfig(migrations).autoRun === "true") {
  await runMigrations(db, migrations.directory);
}

Integración con Bundler

Cuando importas archivos YAML en tu aplicación y lo empaquetas con Bun, el YAML se analiza en tiempo de compilación y se incluye como un módulo de JavaScript:

bun build app.ts --outdir=dist

Esto significa:

• Cero sobrecarga de análisis YAML en tiempo de ejecución en producción
• Tamaños de bundle más pequeños
• Soporte de tree-shaking para configuración no usada (importaciones nombradas)

Importaciones Dinámicas

Los archivos YAML se pueden importar dinámicamente, útiles para cargar configuración bajo demanda:

const env = process.env.NODE_ENV || "development";
const config = await import(`./configs/${env}.yaml`);

// Cargar configuraciones específicas de usuario
async function loadUserSettings(userId: string) {
  try {
    const settings = await import(`./users/${userId}/settings.yaml`);
    return settings.default;
  } catch {
    return await import("./users/default-settings.yaml");
  }
}