lib: add experimental node:yaml module

doc/api/cli.md

@@ -1780,6 +1780,16 @@ added:
 
 Enable experimental support for the worker inspection with Chrome DevTools.
 
+### `--experimental-yaml`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+Enable the experimental [`node:yaml`][] module.
+
 ### `--force-context-aware`
 
 <!-- YAML
@@ -4323,6 +4333,7 @@ one is included in the list below.
 * `--experimental-wasi-unstable-preview1`
 * `--experimental-web-worker`
 * `--experimental-websocket`
+* `--experimental-yaml`
 * `--force-context-aware`
 * `--force-fips`
 * `--force-node-api-uncaught-exceptions-policy`
@@ -4997,6 +5008,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`node:sqlite`]: sqlite.md
 [`node:stream/iter`]: stream_iter.md
 [`node:vfs`]: vfs.md
+[`node:yaml`]: yaml.md
 [`permission.drop()`]: permissions.md#permissiondropscope-reference
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`session.connectToMainThread()`]: inspector.md#sessionconnecttomainthread

doc/api/errors.md

@@ -2318,6 +2318,17 @@ specific purpose. It is only used in the [WHATWG URL API][] support in the
 [`fs`][] module (which only accepts URLs with `'file'` scheme), but may be used
 in other Node.js APIs as well in the future.
 
+<a id="ERR_INVALID_YAML"></a>
+
+### `ERR_INVALID_YAML`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The input passed to [`yaml.parse()`][] is not valid YAML. The message names
+the problem and its line and column.
+
 <a id="ERR_IPC_CHANNEL_CLOSED"></a>
 
 ### `ERR_IPC_CHANNEL_CLOSED`
@@ -4858,6 +4869,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`util.inspect()`]: util.md#utilinspectobject-options
 [`util.parseArgs()`]: util.md#utilparseargsconfig
 [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
+[`yaml.parse()`]: yaml.md#yamlparseinput
 [`zlib`]: zlib.md
 [crypto digest algorithm]: crypto.md#cryptogethashes
 [debugger]: debugger.md

doc/api/index.md

@@ -71,6 +71,7 @@
 * [Web Crypto API](webcrypto.md)
 * [Web Streams API](webstreams.md)
 * [Worker threads](worker_threads.md)
+* [YAML](yaml.md)
 * [Zlib](zlib.md)
 
 <hr class="line"/>

doc/api/yaml.md

@@ -0,0 +1,80 @@
+# YAML
+
+<!--introduced_in=REPLACEME-->
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+<!-- source_link=lib/yaml.js -->
+
+The `node:yaml` module parses [YAML 1.2][] into JavaScript values. Enable it
+with [`--experimental-yaml`][] and import it with `node:`:
+
+```mjs
+import yaml from 'node:yaml';
+```
+
+```cjs
+const yaml = require('node:yaml');
+```
+
+Loading the module emits an `ExperimentalWarning`.
+
+## `yaml.parse(input)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `input` {string|ArrayBuffer|SharedArrayBuffer|TypedArray|DataView} The YAML
+  text. Binary input is decoded as UTF-8.
+* Returns: {any} The value of the document, or an array with the value of each
+  document when the stream holds more than one. An empty stream yields `null`.
+
+`parse()` uses the YAML 1.2 [core schema][]. Plain scalars resolve to null,
+booleans, numbers or strings. For example, `yes` and `no` are strings. Quoted
+and block scalars are strings unless a tag changes their type, as in
+`!!int "42"`. Mappings become plain objects and sequences become arrays, as
+with [`JSON.parse()`][].
+
+```mjs
+import yaml from 'node:yaml';
+
+const config = yaml.parse(`
+name: app
+ports:
+  - 8080
+  - 8443
+tls: true
+`);
+console.log(config);
+// { name: 'app', ports: [ 8080, 8443 ], tls: true }
+
+console.log(yaml.parse('--- 1\n--- 2\n'));
+// [ 1, 2 ]
+```
+
+Aliases to a collection refer to the same object. A collection may contain an
+alias to itself, so the result can contain cycles.
+
+The parser applies the core tags `!!str`, `!!int`, `!!float`, `!!bool`,
+`!!null`, `!!map` and `!!seq`. A tag must match its value: `!!int abc` throws
+an error. Other tags leave collections unchanged and make scalars strings.
+For example, `!custom 123` becomes `'123'`.
+
+Mapping keys become property names. Scalar keys use their string form, so
+`null`, `true` and `1` become `'null'`, `'true'` and `'1'`. Collection keys use
+their JSON text and are limited to 1024 characters. Duplicate keys throw.
+
+Invalid YAML throws an [`ERR_INVALID_YAML`][] `SyntaxError` with the line and
+column. The parser rejects disallowed control characters and nesting deeper
+than 1000 levels.
+
+[YAML 1.2]: https://yaml.org/spec/1.2.2/
+[`--experimental-yaml`]: cli.md#--experimental-yaml
+[`ERR_INVALID_YAML`]: errors.md#err_invalid_yaml
+[`JSON.parse()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
+[core schema]: https://yaml.org/spec/1.2.2/#103-core-schema

doc/node-config-schema.json

@@ -418,6 +418,10 @@
               "type": "boolean",
               "description": "experimental Web Storage API"
             },
+            "experimental-yaml": {
+              "type": "boolean",
+              "description": "experimental node:yaml module"
+            },
             "extra-info-on-fatal-exception": {
               "type": "boolean",
               "description": "hide extra information on fatal exception that causes exit"

doc/node.1

@@ -955,6 +955,9 @@ Enable experimental support for the Web Worker API.
 .It Fl -experimental-worker-inspection
 Enable experimental support for the worker inspection with Chrome DevTools.
 .
+.It Fl -experimental-yaml
+Enable the experimental \fBnode:yaml\fR module.
+.
 .It Fl -force-context-aware
 Disable loading native addons that are not context-aware.
 .
@@ -2304,6 +2307,8 @@ one is included in the list below.
 .It
 \fB--experimental-websocket\fR
 .It
+\fB--experimental-yaml\fR
+.It
 \fB--force-context-aware\fR
 .It
 \fB--force-fips\fR

lib/internal/bootstrap/realm.js

@@ -208,6 +208,7 @@ const builtinModulePolicies = [
   ['test', true, null],
   ['test/reporters', true, null],
   ['vfs', true, '--experimental-vfs'],
+  ['yaml', true, '--experimental-yaml'],
   ['zlib/iter', false, '--experimental-stream-iter'],
 ];
 

lib/internal/errors.js

@@ -1596,6 +1596,7 @@ E('ERR_INVALID_URL_SCHEME',
       `of scheme ${expected[0]}`;
     return `The URL must be ${res}`;
   }, TypeError);
+E('ERR_INVALID_YAML', '%s', SyntaxError);
 E('ERR_IPC_CHANNEL_CLOSED', 'Channel closed', Error);
 E('ERR_IPC_DISCONNECTED', 'IPC channel is already disconnected', Error);
 E('ERR_IPC_ONE_PIPE', 'Child process can have only one IPC pipe', Error);