js-yaml

js-yaml is a JavaScript implementation of a YAML parser and dumper that supports both the YAML 1.2 and legacy YAML 1.1 specifications, and passes the entire official YAML Test Suite. It exposes a small, focused API centered on load/loadAll for parsing and dump for serializing, with pluggable schemas (FAILSAFE, JSON, CORE, YAML11) that control which tags and types are recognized.

The library is widely used as the YAML engine inside build tools, linters, CI configuration loaders, and Node.js frameworks, and ships a minimal CLI for quick file inspection. Its only runtime dependency is argparse (used by the CLI), keeping the core parser dependency-free and easy to audit for supply-chain risk.

What You Get

• load() and loadAll() functions for parsing single or multi-document YAML strings into JavaScript values
• dump() for serializing JavaScript objects back into YAML with fine-grained formatting options (indentation, line width, quote style, key sorting)
• Four built-in schemas (FAILSAFE, JSON, CORE, YAML11) plus a defineScalarTag/defineSequenceTag/defineMappingTag API for registering custom tags
• A lower-level AST/event API (parseEvents, constructFromEvents, eventsToAst, present, visit) for tooling that needs to inspect or transform YAML structurally rather than just round-trip it
• A minimal js-yaml CLI binary for converting/validating YAML files from the command line
• Explicit safety controls (maxDepth, maxAliases, maxTotalMergeKeys) to guard against malicious or pathological YAML input

Common Use Cases

• Loading configuration files (CI pipelines, linters, build tools) written in YAML
• Serializing application data structures to human-editable YAML for config or fixture files
• Building developer tooling (formatters, migration scripts, codegen) that needs to read or rewrite YAML while preserving structure via the AST/visit API
• Safely parsing untrusted or user-submitted YAML with depth/alias limits to avoid billion-laughs-style denial-of-service inputs

Under The Hood

Architecture: js-yaml is organized as a clean pipeline of independent stages rather than a monolithic parser. src/parser/parser.ts (1,469 lines) tokenizes and parses raw YAML text into a flat stream of Event objects (document/sequence/mapping/scalar/alias/pop), which src/parser/constructor.ts then folds into native JavaScript values via constructFromEvents. A parallel path (src/ast/from_events.ts, src/ast/nodes.ts, src/ast/visit.ts) turns the same event stream into a mutable AST that tooling can traverse and rewrite, and src/ast/presenter.ts (1,011 lines) re-serializes that AST back to YAML text for dump(). This event-stream-as-common-currency design is what lets load, loadAll, dump, and the lower-level AST utilities in src/index.ts all share one core engine instead of duplicating parsing logic.

Tech Stack: The library is authored entirely in TypeScript (58% of bytes per GitHub’s language breakdown) and builds to dual CJS/ESM output (dist/js-yaml.cjs.js, dist/js-yaml.mjs) plus a browser UMD/ESM bundle, configured via package.json’s exports map. The only runtime dependency is argparse (used solely by the bin/js-yaml.mjs CLI); the core parser/serializer has zero runtime dependencies. The build pipeline uses Rollup with rollup-plugin-dts for type bundling, and tsc --noEmit for standalone type-checking.

Code Quality: Test coverage is substantial and multi-layered: 30 *.test.mjs files under test/core/ (split into units/, tags/, ast/, common/ subdirectories) cover individual tag types and API units, test/core/dump-fuzzy.test.mjs fuzz-tests the serializer, and test/core/pathological.test.mjs targets adversarial/edge-case input. test/spec/ runs the library against the full external YAML Test Suite (fetched via support/get-yaml-test-suite.mjs), giving spec-conformance coverage beyond hand-written unit tests. Linting is enforced via neostandard (an ESLint config), and the npm test script chains lint, build, type-check, and both test suites — a CI-strict pipeline that would fail on any regression.

API Design: The public surface is deliberately narrow — load/loadAll for parsing, dump for serialization — with sensible defaults (CORE_SCHEMA, no complex-key support by default) that cover the common case with minimal ceremony, while advanced needs (custom tags, complex map keys via realMapTag, structural rewriting via visit) are opt-in through documented escape hatches. Options objects are typed and merged against explicit DEFAULT_LOAD_OPTIONS/DEFAULT_PARSER_OPTIONS constants, and safety-relevant options (maxDepth, maxAliases) are surfaced prominently in the README rather than buried in advanced docs, reflecting a design that treats untrusted-input handling as a first-class concern.