Packages

yaml

2.9.1 · 11 Sep 2026ISC330.2M / weekRepositoryHomepagenpmAtom feed

Your version

2.0.0

major6 Apr 2022Where it was published

2.9.1 is the newest release of 2.x.

In short

30 breaking28 new1 fixed

  • Breaking

    The breaking changes introduced here are mostly originating from the v1 CST parser having become a rather difficult beast to work with.

  • Breaking

    The following is an overview of the breaking changes and new features introduced in each of the prerelease steps leading up to this release; the individual releases' notes and the PRs will contain more detail, along with specific migration guides.

  • Breaking

    Drop deprecated end points, members, options & defaults

  • Breaking

    Breaking changes to Document & createNode APIs

  • Breaking

    When creating a mapping from a JS Object, drop undefined values

  • Breaking

    Retain existing nodes when using set() in mappings & sequences

  • Breaking

    Improve JSON compatibility

  • Breaking

    Refactor tag resolve() API

Security

2 advisories affect 2.0.0; 2.8.3 fixes them

Release note

This update has been in the works for the last year and a half. Its prerelease versions have been thoroughly tested by a wide number of users, and I think it's finally ready for "actual" release, for use in the mythical "production".

The breaking changes introduced here are mostly originating from the v1 CST parser having become a rather difficult beast to work with. So it's here rewritten pretty much completely, now with a lexer as a first stage. Along the way, the whole project was rewritten in TypeScript and the export paths and options refactored pretty deeply.

If you've been using the library just via its parse(), parseDocument() and stringify() functions, then it's quite likely that none of the changes affect your experience in any way. However, if you've been doing something more involved, then I would strongly recommend that you review the library's documentation site for the v2 docs.

Going forward, it's finally time to start experimenting with new YAML spec features that may eventually be included in YAML 1.3 and later. Those will be made available by specifying the version: 'next' option. However, beware! Any features available this way may be removed or have their API broken by any minor release of this library, and no compatibility guarantees with other libraries are given. In general, semver compatibility is guaranteed for features that are explicitly included in the documentation; everything else should be considered as internal implementation details.

The following is an overview of the breaking changes and new features introduced in each of the prerelease steps leading up to this release; the individual releases' notes and the PRs will contain more detail, along with specific migration guides.

Breaking changes

  • Breaking

    Drop deprecated end points, members, options & defaults

  • Breaking

    Breaking changes to Document & createNode APIs

  • Breaking

    When creating a mapping from a JS Object, drop undefined values

  • Breaking

    Retain existing nodes when using set() in mappings & sequences

  • Breaking

    Improve JSON compatibility

  • Breaking

    Refactor tag resolve() API

  • Breaking

    Drop 'yaml/parse-cst' endpoint

  • Breaking

    Update build configs & minimum supported versions

  • Breaking

    Refactor options

  • Breaking

    Refactor parsing completely

  • Breaking

    Merge all of 'yaml/types' and some of 'yaml/util' into 'yaml'

  • Breaking

    Refactor node identification

  • Breaking

    Drop type property from all but Scalar nodes

  • Breaking

    Refactor as TypeScript

  • Breaking

    Make anchor & alias resolution lazier

  • Breaking

    Split flow collections into items in Parser

  • Breaking

    Make Pair not extend NodeBase; drop its prop forwarding (#245, #250)

  • Breaking

    Rename the tokens namespace as CST

  • Breaking

    Turn the Lexer, Parser & Composer into generators

  • Breaking

    Refactor Node range as [start, value-end, node-end]

  • Breaking

    Replace error.offset with error.pos: [number, number]

  • Breaking

    Fix empty lines & trailing comments

  • Breaking

    Drop Node.js 10 support

  • Breaking

    Allow disabling single & block quotes completely

  • Breaking

    The TS type of doc.directives now indicates it as optional

  • Breaking

    YAML.defaultOptions is removed

  • Breaking

    directives.marker is renamed as directives.docStart

  • Breaking

    Drop Node.js 12 support (end-of-life 2022-04-30)

New Features

  • Resolve known tags in core schema

  • Create intermediates for set() & setIn() on doc with empty contents

  • Fix intermediate collection creation for parsed documents

  • Improve quoted string flexibility

  • Add defaultKeyType option for finer control of scalar output

  • Remember source string for null scalars

  • Support asBigInt option for sexagesimal integer values

  • Refactor logging control, adding logLevel option

  • Add visit(node, visitor) to 'yaml'

  • Stringify top-level block scalars with header on marker line

  • Add a couple of things to 'yaml/util' that weren't exposed before

  • Add Collection, Value & Node visitor aliases

  • Add error codes

  • Always include offset in CST tokens

  • Add CST tools

  • Check key uniqueness; add uniqueKeys option

  • Drop special-casing COMMENT_SPACE error; use MISSING_CHAR for it instead

  • Support immediate map values for << merge keys, in addition to alias values

  • Add a new createNode option aliasDuplicateObjects

  • Add clone() methods to Document, Directives, Schema and all Nodes

  • Add keepSoureToken parse option, adding srcToken values to Nodes

  • Allow for custom schema id, provided that customTags is defined

  • Expose tags & types required by custom composers

  • Add a compatibility checker

  • Support for Non-YAML Schemas (#336, #337, #343, #344)

  • Add warning for aliases & anchors ending with a colon

  • Add directives.docEnd, for ... marker

  • Add YAML.visitAsync()

  • Allow for a 'next' YAML version

A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.