YAML in TypeScript #

# Comments use the hash sign

# --- is the document separator (optional)
---
# Mapping (like an object in JSON)
server:
  host: localhost
  port: 5432
  ssl: true

# Sequence (like an array in JSON)
databasePool:
  - nama: primary
    host: db1.example.com
  - nama: replica
    host: db2.example.com

# Multi-line string
pesanSelamatDatang: |
  Selamat datang di MuslimApps!
  Semoga bermanfaat untuk umat.  

# Folded multi-line string (newlines become spaces)
deskripsi: >
  Aplikasi super untuk
  umat Muslim Indonesia.  

# Anchor (&) and alias (*) to avoid duplication
defaultLogging: &defaultLogging
  level: info
  format: json

service1:
  logging:
    <<: *defaultLogging  # Merge from the anchor
    level: debug          # Override one value

# TRAP: Values that get misinterpreted

# Norway problem — the country code "NO" is interpreted as the boolean false!
kodeNegara: NO    # false (not the string "NO"!)
kodeNegara2: "NO" # The correct "NO" — always quote ambiguous strings

# Surprising boolean values in YAML 1.1
aktif1: yes   # true
aktif2: on    # true
aktif3: y     # true
aktif4: no    # false
aktif5: off   # false
aktif6: n     # false

# Surprising octal numbers
izinFile: 0755  # 493 (decimal!) not the string "0755"
izinFile2: "0755" # "0755" the correct string

# Auto-parsed dates
tanggal: 2025-05-07  # A Date object, not a string!
tanggal2: "2025-05-07"  # The correct string if you need a string

# js-yaml — the most popular library, YAML 1.2
npm install js-yaml
npm install --save-dev @types/js-yaml

# yaml — a modern, more complete, TypeScript-first library
npm install yaml

import * as yaml from "js-yaml";
import { z } from "zod";

// Parse a YAML string into an object
const yamlString = `
server:
  host: localhost
  port: 3000
  ssl: false
database:
  url: postgresql://localhost:5432/muslimapps
  maxConnections: 10
fitur:
  jadwalSholat: true
  kiblat: true
  zakat: false
`;

// js-yaml returns unknown — DON'T cast directly to a type
const rawData = yaml.load(yamlString);
// Type: string | number | object | null | undefined

// Validate with Zod for type safety
const SchemaKonfigurasi = z.object({
  server: z.object({
    host: z.string(),
    port: z.coerce.number().min(1).max(65535),
    ssl: z.boolean().default(false),
  }),
  database: z.object({
    url: z.string().url(),
    maxConnections: z.number().int().min(1).max(100).default(10),
  }),
  fitur: z.record(z.string(), z.boolean()).optional(),
});

type Konfigurasi = z.infer<typeof SchemaKonfigurasi>;

function parseKonfigurasi(yamlInput: string): Konfigurasi {
  let raw: unknown;
  try {
    raw = yaml.load(yamlInput);
  } catch (err) {
    throw new SyntaxError(
      `YAML tidak valid: ${err instanceof Error ? err.message : String(err)}`
    );
  }

  const hasil = SchemaKonfigurasi.safeParse(raw);
  if (!hasil.success) {
    throw new TypeError(
      `Konfigurasi tidak valid:\n${JSON.stringify(hasil.error.flatten().fieldErrors, null, 2)}`
    );
  }

  return hasil.data;
}

const konfig = parseKonfigurasi(yamlString);
console.log(`Server: ${konfig.server.host}:${konfig.server.port}`);
// konfig.server.port → number (not string!)

import { parse, stringify, parseAllDocuments } from "yaml";
import { z } from "zod";

// Parse a YAML string
const data = parse(`
nama: Budi Santoso
usia: 25
email: [email protected]
`);
// data is typed any — still needs validation!

// Stringify: TypeScript → YAML
const objek = {
  nama: "MuslimApps",
  versi: "2.1.0",
  fitur: ["jadwal-sholat", "kiblat", "quran"],
  konfigurasi: {
    bahasa: "id",
    tema: "hijau",
  },
};

const yamlOutput = stringify(objek);
console.log(yamlOutput);
// nama: MuslimApps
// versi: 2.1.0
// fitur:
//   - jadwal-sholat
//   - kiblat
//   - quran
// konfigurasi:
//   bahasa: id
//   tema: hijau

// Stringify options
const yamlRapi = stringify(objek, {
  indent: 2,
  lineWidth: 80,
  defaultStringType: "QUOTE_DOUBLE", // Always quote strings
});

import { readFile } from "fs/promises";
import * as yaml from "js-yaml";
import { z } from "zod";
import path from "path";

// Schema for the application configuration file
const SchemaAppConfig = z.object({
  app: z.object({
    nama: z.string(),
    versi: z.string().regex(/^\d+\.\d+\.\d+$/, "Format versi harus X.Y.Z"),
    env: z.enum(["development", "staging", "production"]).default("development"),
  }),
  server: z.object({
    port: z.coerce.number().default(3000),
    host: z.string().default("0.0.0.0"),
    corsOrigins: z.array(z.string().url()).default([]),
  }),
  database: z.object({
    host: z.string(),
    port: z.coerce.number().default(5432),
    nama: z.string(),
    poolMin: z.number().int().min(1).default(2),
    poolMax: z.number().int().max(50).default(10),
  }),
  redis: z.object({
    host: z.string().default("localhost"),
    port: z.coerce.number().default(6379),
    ttlDefault: z.number().int().positive().default(3600),
  }).optional(),
  logging: z.object({
    level: z.enum(["debug", "info", "warn", "error"]).default("info"),
    format: z.enum(["json", "text"]).default("json"),
  }).default({ level: "info", format: "json" }),
});

type AppConfig = z.infer<typeof SchemaAppConfig>;

async function muatKonfigurasi(namaFile = "config.yaml"): Promise<AppConfig> {
  const filePath = path.resolve(process.cwd(), "config", namaFile);

  let isiFile: string;
  try {
    isiFile = await readFile(filePath, "utf-8");
  } catch (err) {
    const error = err as NodeJS.ErrnoException;
    if (error.code === "ENOENT") {
      throw new Error(`File konfigurasi tidak ditemukan: ${filePath}`);
    }
    throw new Error(`Gagal membaca file konfigurasi: ${error.message}`);
  }

  let rawData: unknown;
  try {
    rawData = yaml.load(isiFile);
  } catch (err) {
    throw new SyntaxError(
      `File ${namaFile} bukan YAML yang valid: ${err instanceof Error ? err.message : String(err)}`
    );
  }

  if (rawData === null || rawData === undefined) {
    throw new Error(`File konfigurasi kosong: ${filePath}`);
  }

  const hasil = SchemaAppConfig.safeParse(rawData);
  if (!hasil.success) {
    const errors = hasil.error.flatten().fieldErrors;
    const pesanError = Object.entries(errors)
      .map(([field, msgs]) => `  ${field}: ${(msgs ?? []).join(", ")}`)
      .join("\n");
    throw new TypeError(`Konfigurasi tidak valid:\n${pesanError}`);
  }

  return hasil.data;
}

// Example config/config.yaml that gets read:
// app:
//   nama: MuslimApps
//   versi: "2.1.0"
//   env: production
// server:
//   port: 3000
//   corsOrigins:
//     - "https://muslimapps.id"
// database:
//   host: db.internal
//   nama: muslimapps_prod

import * as yaml from "js-yaml";

// A YAML file with multiple documents
const multiDokumen = `
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: muslimapps-backend
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: muslimapps-backend-svc
spec:
  type: ClusterIP
  port: 3000
`;

// loadAll with a callback for each document
const dokumen: unknown[] = [];
yaml.loadAll(multiDokumen, (doc) => {
  dokumen.push(doc);
});

console.log(`Jumlah dokumen: ${dokumen.length}`); // 2

// Or use the yaml library for a more modern API
import { parseAllDocuments } from "yaml";

const allDocs = parseAllDocuments(multiDokumen);
const objects = allDocs.map((doc) => doc.toJSON());

const yamlDenganAnchor = `
# Anchor definition
defaultConfig: &default
  timeout: 30
  retries: 3
  logLevel: info

# Alias usage — inherits everything from &default
serviceA:
  <<: *default
  port: 3001

serviceB:
  <<: *default
  port: 3002
  logLevel: debug  # Override one value

# Anchor for strings
dbPassword: &dbPass "rahasia123"
primaryDB:
  password: *dbPass
replicaDB:
  password: *dbPass
`;

const config = yaml.load(yamlDenganAnchor) as Record<string, unknown>;

// Anchors are resolved at parse time — the result is a plain object
console.log((config.serviceA as Record<string, unknown>).timeout); // 30
console.log((config.serviceB as Record<string, unknown>).logLevel); // "debug"

import { stringify } from "yaml";

interface KonfigurasiDeployment {
  namaAplikasi: string;
  versi: string;
  replicas: number;
  environment: Record<string, string>;
  healthCheck: {
    path: string;
    intervalDetik: number;
  };
}

const deployment: KonfigurasiDeployment = {
  namaAplikasi: "muslimapps-api",
  versi: "2.1.0",
  replicas: 3,
  environment: {
    NODE_ENV: "production",
    LOG_LEVEL: "info",
  },
  healthCheck: {
    path: "/health",
    intervalDetik: 30,
  },
};

// Serialize to YAML
const yamlOutput = stringify(deployment, {
  indent: 2,
  lineWidth: 0, // Don't wrap long lines
});

console.log(yamlOutput);
// namaAplikasi: muslimapps-api
// versi: 2.1.0
// replicas: 3
// environment:
//   NODE_ENV: production
//   LOG_LEVEL: info
// healthCheck:
//   path: /health
//   intervalDetik: 30

// Write to a file
import { writeFile } from "fs/promises";
await writeFile("deployment.yaml", yamlOutput, "utf-8");