v3.0.0-0

[eemeli]

This is the first v3 prerelease, so handle with care and expect everything/anything to still change. Adding this as a dependency with a non-exact range like ^3.0.0-0 will almost certainly eventually break your build when new prereleases are made available. This version has been published to npm using the next dist-tag, so install it with:

npm install --save-exact yaml@next

I don't have a clear idea how close or far this is from the eventual v3 final release; see its milestone for a very rough and incomplete idea of what's on the table so far.

BREAKING CHANGES

Drop separation between Node.js and browser builds (#649)

The dual browser + Node.js build using Rollup is dropped, and replaced by a single Rolldown build producing ES modules.

The most significant change for users is that the default export is dropped, and so the following change may be required to user code:

-import YAML from 'yaml'
+import * as YAML from 'yaml'

The minimum supported Node.js and TypeScript versions are updated to what's needed for require(esm) support, i.e. Node.js 20.19 and TS 5.9; similarly, the library is now tested in Chrome 93 and Firefox 94, though no specific versions of browsers are explicitly supported without transpilation.

Getting the test:dist task to work with Jest was too much hassle, so this also includes a switch from it to Vitest, which effectively "just works". It's also configurable to run (most of) the whole test suite in browsers, so that's now done rather than the minimal smoke test that was used before.

All of the above also allows dropping the tests from the playground repo, so it doesn't need to be handled as a git submodule any more, and it's only the playground now.

After these changes, the deployed on-disk size of the library is reduced from around 1.2 MB to 0.3 MB, and the compressed size reduces from 107 kB to 71 kB.

Be more strict and less custom (#655)

The general thrust here is ensure/enforce that values within a Document are wrapped in Node values, and to remove the custom instance checks. By only releasing the package as an ESM module, we avoid any dual package hazard, and so can simply rely on native isinstance checks.

With the changes here, when a value is added using e.g. doc.add() or .addIn(), the values are automatically wrapped/represented using appropriate Node instances. Node creation is also refactored, but that should be an implementation detail.

The root value of a document is now available as its .value (previously .contents), and it is no longer allowed to be null, but must instead be a Node. Similarly, all mapping keys (i.e. pair.key values) must be Nodes, and cannot be null. Mapping values (pair.value) can still be null, or a Node value.

Internally, the Node-ness of Document values is no longer checked, but is assumed. So assigning non-Node values to doc.value or to collection .items is likely to cause misbehaviour.

The second keepScalar argument of the .get() and .getIn() accessors is dropped. This used to default to false, which meant that scalar values were returned "unwrapped" from their surrounding Scalar. The new behaviour corresponds to having this argument set true, as the accessors always return a Node value.

Replace generators with arrays during parsing (#645)

There's quite a bit of unnecessary complexity in the parser stages that's removed by replacing their liberal use of generators with arrays. This was mostly in place to support parsing incomplete/chunked input, but I don't think that functionality is used at all, or almost at all. And so that's now dropped, for an improvement in performance.

These changes have no impact on users of the parse() or parseDocument() APIs, or even most users of the lower-level parser APIs; see the changes made to src/cli.ts for some idea of how user code may need to change.

Bugfixes

• docs: Drop gtag tracking
• Include labels in the Range tuple type (Update the Range type to labeled tuple for improved type hints #640)

---

This discussion was created from the release v3.0.0-0.