YAML di Bun

In Bun, YAML è un cittadino di prima classe insieme a JSON e TOML. Puoi:

Parsare stringhe YAML con Bun.YAML.parse
import e require file YAML come moduli a runtime (incluso hot reloading e supporto modalità watch)
import e require file YAML nelle app frontend tramite il bundler di bun

Conformità

Il parser YAML di Bun attualmente supera oltre il 90% della suite di test YAML ufficiale. Mentre stiamo attivamente lavorando per raggiungere il 100% della conformità, l'implementazione attuale copre la stragrande maggioranza dei casi d'uso reali. Il parser è scritto in Zig per prestazioni ottimali e viene continuamente migliorato.

API Runtime

`Bun.YAML.parse()`

Parsa una stringa YAML in un oggetto 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 multi-documento

Quando si parsa YAML con più documenti (separati da ---), Bun.YAML.parse() restituisce 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" }
// ]

Caratteristiche YAML supportate

Il parser YAML di Bun supporta la specifica YAML 1.2 completa, incluse:

Scalari: stringhe, numeri, booleani, valori null
Collezioni: sequenze (array) e mapping (oggetti)
Ancore e Alias: nodi riutilizzabili con & e *
Tag: suggerimenti di tipo come !!str, !!int, !!float, !!bool, !!null
Stringhe multi-linea: scalari letterali (|) e piegati (>)
Commenti: usando #
Direttive: %YAML e %TAG

const yaml = `
# Employee record
employee: &emp
  name: Jane Smith
  department: Engineering
  skills:
    - JavaScript
    - TypeScript
    - React

manager: *emp  # Reference to employee

config: !!str 123  # Explicit string type

description: |
  This is a multi-line
  literal string that preserves
  line breaks and spacing.

summary: >
  This is a folded string
  that joins lines with spaces
  unless there are blank lines.
`;

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

Gestione errori

Bun.YAML.parse() lancia un SyntaxError se il YAML non è valido:

try {
  Bun.YAML.parse("invalid: yaml: content:");
} catch (error) {
  console.error("Failed to parse YAML:", error.message);
}

Importazione Modulo

ES Modules

Puoi importare file YAML direttamente come ES modules. Il contenuto YAML viene parsato e reso disponibile sia come export default che named:

yaml

database:
  host: localhost
  port: 5432
  name: myapp

redis:
  host: localhost
  port: 6379

features:
  auth: true
  rateLimit: true
  analytics: false

Importazione Default

import config from "./config.yaml";

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

Importazioni Named

Puoi destrutturare le proprietà di livello superiore del YAML come importazioni named:

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

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

O combina entrambi:

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

// Use the full config object
console.log(config);

// Or use specific parts
if (features.rateLimit) {
  setupRateLimiting(database);
}

CommonJS

I file YAML possono anche essere richiesti in CommonJS:

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

// Destructuring also works
const { database, redis } = require("./config.yaml");
console.log(database.port); // 5432

Hot Reloading con YAML

Una delle funzionalità più potenti del supporto YAML di Bun è l'hot reloading. Quando esegui la tua applicazione con bun --hot, le modifiche ai file YAML vengono automaticamente rilevate e ricaricate senza chiudere le connessioni

Hot Reloading della Configurazione

yaml

server:
  port: 3000
  host: localhost

features:
  debug: true
  verbose: false

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

console.log(`Starting server on ${server.host}:${server.port}`);

if (features.debug) {
  console.log("Debug mode enabled");
}

// Your server code here
Bun.serve({
  port: server.port,
  hostname: server.host,
  fetch(req) {
    if (features.verbose) {
      console.log(`${req.method} ${req.url}`);
    }
    return new Response("Hello World");
  },
});

Esegui con hot reloading:

bash

bun --hot server.ts

Ora quando modifichi config.yaml, le modifiche vengono immediatamente riflesse nella tua applicazione in esecuzione. Questo è perfetto per:

Regolare la configurazione durante lo sviluppo
Testare impostazioni diverse senza riavvii
Debug live con modifiche alla configurazione
Toggle dei feature flag

Gestione della Configurazione

Configurazione basata su ambiente

YAML eccelle nella gestione della configurazione attraverso diversi ambienti:

yaml

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];

// Environment variables in YAML values can be interpolated
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);

Configurazione Feature Flags

yaml

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;
  }

  // Check rollout percentage
  if (feature.rolloutPercentage < 100) {
    const hash = hashCode(userEmail || "anonymous");
    if (hash % 100 >= feature.rolloutPercentage) {
      return false;
    }
  }

  // Check allowed users
  if (feature.allowedUsers && userEmail) {
    return feature.allowedUsers.includes(userEmail);
  }

  return true;
}

// Use with hot reloading to toggle features in real-time
if (isFeatureEnabled("newDashboard", user.email)) {
  renderNewDashboard();
} else {
  renderLegacyDashboard();
}

Configurazione Database

yaml

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";

// Parse environment variables with defaults
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);

// Auto-run migrations if configured
if (parseConfig(migrations).autoRun === "true") {
  await runMigrations(db, migrations.directory);
}

Integrazione Bundler

Quando importi file YAML nella tua applicazione e la bundlizzi con Bun, il YAML viene parsato a build time e incluso come modulo JavaScript:

bash

bun build app.ts --outdir=dist

Questo significa:

Zero overhead di parsing YAML a runtime in produzione
Dimensioni del bundle più piccole
Supporto tree-shaking per configurazione non usata (import named)

Importazioni Dinamiche

I file YAML possono essere importati dinamicamente, utile per caricare configurazione on demand:

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

// Load user-specific settings
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");
  }
}

Conformità ​

API Runtime ​

Bun.YAML.parse() ​

YAML multi-documento ​

Caratteristiche YAML supportate ​

Gestione errori ​

Importazione Modulo ​

ES Modules ​

Importazione Default ​

Importazioni Named ​

CommonJS ​

Hot Reloading con YAML ​

Hot Reloading della Configurazione ​

Gestione della Configurazione ​

Configurazione basata su ambiente ​

Configurazione Feature Flags ​

Configurazione Database ​

Integrazione Bundler ​

Importazioni Dinamiche ​

Conformità

API Runtime

`Bun.YAML.parse()`

YAML multi-documento

Caratteristiche YAML supportate

Gestione errori

Importazione Modulo

ES Modules

Importazione Default

Importazioni Named

CommonJS

Hot Reloading con YAML

Hot Reloading della Configurazione

Gestione della Configurazione

Configurazione basata su ambiente

Configurazione Feature Flags

Configurazione Database

Integrazione Bundler

Importazioni Dinamiche