Skip to main content
On this page

@std/yaml

Overview Jump to heading

parse and stringify for handling YAML encoded data.

Ported from js-yaml v3.13.1.

Use parseAll for parsing multiple documents in a single YAML string.

This package generally supports YAML 1.2.x (latest) and some YAML 1.1 features that are commonly used in the wild.

Supported YAML 1.1 features include:

Unsupported YAML 1.1 features include:

  • Yes, No, On, Off literals for bool type
  • Sexagesimal numbers (e.g. 3:25:45)
import { parse, stringify } from "@std/yaml";
import { assertEquals } from "@std/assert";

const data = parse(`
foo: bar
baz:
  - qux
  - quux
`);
assertEquals(data, { foo: "bar", baz: [ "qux", "quux" ] });

const yaml = stringify({ foo: "bar", baz: ["qux", "quux"] });
assertEquals(yaml, `foo: bar
baz:
  - qux
  - quux
`);

Limitations

  • binary type is currently not stable.

Add to your project Jump to heading

deno add jsr:@std/yaml

See all symbols in @std/yaml on

What is YAML? Jump to heading

YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files and data exchange between languages with different data structures. It emphasizes simplicity and readability, making it easy for humans to write and understand.

Why use @std/yaml? Jump to heading

YAML is great for configuration files and data exchange where human readability is a priority. Use it when you need to represent complex data structures in a way that is easy to read and edit by humans. This module provides simple functions to parse and serialize YAML data.

Examples Jump to heading

Read a config file (with errors handled) Jump to heading

import { parse } from "@std/yaml";

const raw = await Deno.readTextFile("config.yaml");
let config;
try {
  config = parse(raw);
} catch (err) {
  if (err instanceof SyntaxError) {
    console.error("Invalid YAML:", err.message);
  }
  throw err;
}

// Narrow/validate as needed before using
if (
  typeof config === "object" && config !== null &&
  "port" in config && typeof config.port === "number"
) {
  console.log("Listening on", config.port);
}

Multiple documents in one file Jump to heading

import { parseAll } from "@std/yaml";

const docs = parseAll(`
---
name: dev
port: 3000
---
name: prod
port: 80
`);

// e.g. map env name to port
const envToPort = Object.fromEntries(docs.map((d) => [d.name, d.port]));
console.log(envToPort.dev, envToPort.prod);

Stringify with stable diffs (sorted keys, wrapped lines) Jump to heading

import { stringify } from "@std/yaml";

const data = {
  name: "service",
  description: "An example that demonstrates how long lines can be wrapped.",
  tags: ["alpha", "beta", "gamma"],
  nested: { z: 1, a: 2, m: 3 },
};

const yaml = stringify(data, { sortKeys: true, lineWidth: 60, indent: 2 });
console.log(yaml);

YAML anchors and merge keys (YAML 1.1) Jump to heading

import { parse } from "@std/yaml";

const cfg = parse(`
defaults: &base
  retries: 3
  timeout: 5s

serviceA:
  <<: *base
  timeout: 10s

serviceB:
  <<: *base
`);

console.log(cfg.serviceA.timeout); // "10s"
console.log(cfg.serviceB.retries); // 3

Skip unsupported values when stringifying Jump to heading

import { stringify } from "@std/yaml";

const obj = { ok: 1, skipMe: () => {} };
// By default, functions cause a TypeError. Use skipInvalid to omit them.
const yaml = stringify(obj, { skipInvalid: true });
console.log(yaml);

Write YAML back to disk Jump to heading

import { stringify } from "@std/yaml";

const settings = { port: 8080, features: { a: true, b: false } };
await Deno.writeTextFile("settings.yaml", stringify(settings, { indent: 2 }));

Tips Jump to heading

  • Use parseAll when you expect multiple YAML documents in one string.
  • Prefer JSON for machine↔machine interchange; YAML is great for hand-edited config.
  • For stable diffs in VCS, set sortKeys: true and a fixed indent/lineWidth when using stringify.

Did you find what you needed?

Edit this page
Privacy policy