[marcopiraccini]

This is a proposal for a built-in YAML parser, with a basic implementation to discuss on: an experimental, parse-only node:yaml module behind --experimental-yaml.

const yaml = require('node:yaml');
yaml.parse('name: app\nports: [8080, 8443]\n');
// { name: 'app', ports: [ 8080, 8443 ] }

The parser supports the YAML 1.2 core schema, anchors, aliases, tags, and multi-document streams. It is written from scratch and has no external dependencies.

This gives Node.js a built-in YAML parser for future configuration support, following the discussion about .noderc in #53787, where the config file ended up JSON-only because core had no parser.

Bun parity

Bun ships Bun.YAML since v1.2.21. yaml.parse() follows Bun.YAML.parse() so that code written for it runs unchanged:

• parse(input) takes a string or binary input (ArrayBuffer, TypedArray, DataView) decoded as UTF-8.
• One document returns its value, a multi-document stream returns an array, an empty stream returns null.
• Invalid input throws a SyntaxError (here with the ERR_INVALID_YAML code and the line and column).
• Aliases of an anchored collection are the same object, and a collection may contain an alias to itself, so results can hold cycles.
• Core schema tags such as !!str and !!int are applied.

Not covered yet: Bun.YAML.stringify(value, replacer, space), Blob input, and importing .yaml files as modules. See the next steps.

Tests

Tests include the official YAML Test Suite, vendored at a fixed revision. Of 402 cases, 400 pass.

The two that fail, 2JQS and X38W, are documents with duplicate keys: two empty keys, and a key that is an alias of the previous key. The suite only checks that they parse, since duplicate keys are not a syntax error, and provides no expected output for them. The YAML 1.2 specification requires mapping keys to be unique, and this parser enforces it and throws Duplicate mapping key, as the yaml and js-yaml packages do by default. They are listed as known failures with that reason. If the reviewers prefer the JSON.parse() behavior, where the last value wins, the check can be removed and both pass.

Review guide

1. doc/api/yaml.md: API behavior.
2. lib/yaml.js: input validation and document return values.
3. lib/internal/yaml/parser.js: parser implementation.
4. test/parallel/test-yaml.js: API tests. test/parallel/test-yaml-test-suite.js: official suite runner.
5. The experimental flag follows the node:vfs setup in vfs: add minimal node:vfs subsystem #63115.

Next steps, if accepted

1. yaml.stringify(value, replacer, space) with Bun's semantics.
2. import data from './config.yaml' with { type: 'yaml' }.
3. YAML support in --experimental-config-file.
4. A yaml subsystem label and commit subsystem, as was done for vfs.
5. Graduation from the flag once the API has settled.

Refs:

• Support .noderc or similar file-based initialization configurations? #53787
• https://bun.com/docs/runtime/yaml

[nodejs-github-bot]

Review requested:

• @nodejs/config
• @nodejs/loaders
• @nodejs/startup

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.73%. Comparing base (d44625a) to head (bbfacd1).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #67157      +/-   ##
==========================================
+ Coverage   90.69%   90.73%   +0.03%     
==========================================
  Files         797      799       +2     
  Lines      278787   280456    +1669     
  Branches    53607    54257     +650     
==========================================
+ Hits       252858   254467    +1609     
- Misses      16292    16343      +51     
- Partials     9637     9646       +9     

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	97.49% <100.00%> (+0.39%)	⬆️
lib/internal/errors.js	98.81% <100.00%> (+<0.01%)	⬆️
lib/internal/yaml/parser.js	100.00% <100.00%> (ø)
lib/yaml.js	100.00% <100.00%> (ø)
src/node_builtins.cc	77.35% <100.00%> (-0.31%)	⬇️
src/node_options.cc	88.20% <100.00%> (+0.01%)	⬆️
src/node_options.h	95.72% <100.00%> (+0.01%)	⬆️

... and 35 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.