yaml

yaml is a JavaScript/TypeScript library for parsing and stringifying YAML, the human-friendly data serialization standard. It supports both the YAML 1.1 and 1.2 specifications and all common data schemas, passes the full yaml-test-suite, and can accept any string as input without throwing, parsing as much YAML out of it as it can. Unlike many YAML libraries that only expose a JSON.parse/JSON.stringify-style surface, yaml exposes three progressively deeper API layers: simple parse/stringify functions, a mutable Document/AST layer that preserves comments and blank lines for round-trip editing, and a raw Lexer/Parser/Composer pipeline for tools that need to work directly with YAML source. It has zero runtime dependencies, ships its own TypeScript types, runs on Node.js and in browsers, and includes a command-line tool for validating, lexing, and inspecting YAML streams.

What You Get

• parse()/stringify() functions that mirror the JSON.parse/JSON.stringify API for drop-in YAML handling
• A Document class that preserves comments, blank lines, and anchors so files can be edited and re-serialized without clobbering formatting
• Full YAML 1.1 and 1.2 spec support, verified against the official yaml-test-suite
• Direct access to the Lexer, Parser, and Composer layers for building custom YAML tooling
• Zero runtime dependencies and bundled TypeScript types with no separate @types package needed
• A command-line tool (npx yaml) for validating, lexing, and inspecting YAML streams from the shell

Common Use Cases

• Loading and writing application configuration files (CI pipelines, Docker Compose, Kubernetes manifests, app configs)
• Programmatically editing existing YAML files (e.g. bumping a version field) while preserving comments and formatting
• Building developer tools that need to parse, lint, or transform YAML source, using the CST/Composer layers directly
• Converting between YAML and JSON/JS objects in build scripts and data pipelines

Under The Hood

Architecture — yaml is organized as a strict pipeline of four layers, each exported independently for tools that need to stop early: a Lexer (src/parse/lexer.ts) turns raw source into lexical tokens; a Parser (src/parse/parser.ts, ~970 lines) builds a lossless Concrete Syntax Tree (CST) from those tokens, preserving every character including comments and whitespace; a Composer (src/compose/composer.ts) walks the CST and resolves it into a Document (src/doc/Document.ts) containing typed content nodes (YAMLMap, YAMLSeq, Scalar, Alias, Pair); and the top-level parse/stringify/parseDocument functions (src/public-api.ts) compose these stages into a JSON.parse/JSON.stringify-shaped convenience API. Because the CST retains full source fidelity, a Document can be mutated and re-stringified without losing comments or formatting, which is the library’s core architectural differentiator versus JSON-style YAML parsers.

Tech Stack — Written entirely in TypeScript (99.3% of the codebase) with a small JavaScript sliver, compiled via Rolldown, and published with zero runtime dependencies. Development tooling is Vitest for tests, ESLint (typescript-eslint) for linting, and Prettier for formatting; the package targets modern Node.js (^20.19 || ^22.12 || >=24) and ships as an ESM-only package with bundled .d.ts declarations, so no separate @types/yaml package is needed.

Code Quality — The tests/ directory contains 23+ dedicated test files covering the lexer, CST, line-counter, visit/traversal, directives, collection access, and full compliance against the official yaml-test-suite and a JSON test suite, in addition to per-module tests under tests/doc/. src/public-api.ts shows careful, explicit handling of JSON.parse/JSON.stringify-compatible overloads (reviver/replacer disambiguation, indent-as-number-or-string handling, keepUndefined option) rather than loose any-typed shortcuts. Error handling is centralized through a dedicated YAMLError/YAMLParseError/YAMLWarning hierarchy (src/errors.ts) with a prettifyError helper that attaches line/column context via LineCounter, rather than throwing raw exceptions.

API Design — The public surface deliberately mirrors JSON.parse/JSON.stringify (parse(src, reviver?, options?), stringify(value, replacer?, options?)) so migrating from JSON handling is close to a drop-in swap, while still layering in a mutable Document API and raw Lexer/Parser/Composer/CST exports for consumers who need deeper control. Documentation is extensive (docs/01_intro.md through docs/10_yaml_syntax.md plus a dedicated errors guide and CLI guide) and the root src/index.ts barrel file gives a single, well-organized entry point to the entire public API surface.