v2.3.0-0

This release is made available first as a prerelease to gauge the effects of the TypeScript changes, which add a second optional generic type argument Strict to Document instances. While this change appears to improve the TS usage experience at least with basic patterns, it's possible that it doesn't take into account some usage that would be negatively affected by the change.

Comments are requested, both for and against the change.

New Features

• Improve TS developer experience (#441)

Bugfixes

• Use correct argument order when stringifying flow collection comments (#443)

v2.2.1

• Quote top-level map keys containing document markers (#431)

v2.2.0

New Features

• Add flowCollectionPadding toString option (#420)
• Use indicator line for props on block collection values of mappings (#425)

Bugfixes

• Minor relaxation of types for custom tags (#429)

v2.1.3

• Set correct node-end position for block collections with comments (#413)

v2.1.2

• Set correct node-end position for empty values with comments (#413)

v2.1.1

No changes in executable code, only TS types.

• Revert "Use TS named tuple for range (#385)" -- see #393
• Fix types for compatibility with TS 4.2 and 4.7
• Add CI workflow for testing published type in a range of TS versions

v2.1.0

Fixes for TypeScript users. Arguably this could've been a patch release as well.

• Improve/specify/fix TS types for Document & collection access methods (#383)
• Use TS named tuple for range (#385)
• Rename internal Document option as _directives to resolve type conflict with ToString options (#389)
• Update tsc target to ES2020 to match Node.js support
• Update dev dependencies, including jest 28

v2.0.1

• Fix tags and anchors on map keys (#378)

v2.0.0

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

v2.0.0-0

• Drop deprecated end points, members, options & defaults (#171)
• Breaking changes to Document & createNode APIs (#186)
• When creating a mapping from a JS Object, drop undefined values (#173)
• Retain existing nodes when using set() in mappings & sequences (#185)

v2.0.0-1

• Improve JSON compatibility (#189)
• Refactor tag resolve() API (#201)

v2.0.0-3

• Drop 'yaml/parse-cst' endpoint (#223)
• Update build configs & minimum supported versions (#224)

v2.0.0-4

• Refactor options (#235)
• Refactor parsing completely (#203)
• Merge all of 'yaml/types' and some of 'yaml/util' into 'yaml' (#234)
• Refactor node identification (#233)
• Drop type property from all but Scalar nodes (#240)
• Refactor as TypeScript (#233)

v2.0.0-5

• Make anchor & alias resolution lazier (#248)
• Split flow collections into items in Parser (#249)
• Make Pair not extend NodeBase; drop its prop forwarding (#245, #250)
• Rename the tokens namespace as CST (#252)
• Turn the Lexer, Parser & Composer into generators (#253)
• Refactor Node range as [start, value-end, node-end] (#259)
• Replace error.offset with error.pos: [number, number] (#260)

v2.0.0-6

• Fix empty lines & trailing comments (#278)
• Drop Node.js 10 support

v2.0.0-9

• Allow disabling single & block quotes completely (#326)

v2.0.0-10

• The TS type of doc.directives now indicates it as optional (#344)

v2.0.0-11

• YAML.defaultOptions is removed (#346)
• directives.marker is renamed as directives.docStart (#371)

v2.0.0

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

New Features

v2.0.0-0

• Resolve known tags in core schema (#172)
• Create intermediates for set() & setIn() on doc with empty contents (#174)
• Fix intermediate collection creation for parsed documents (#174)
• Improve quoted string flexibility (#177)
• Add defaultKeyType option for finer control of scalar output (#179)

v2.0.0-1

• Remember source string for null scalars (#193)
• Support asBigInt option for sexagesimal integer values

v2.0.0-3

• Refactor logging control, adding logLevel option (#215)
• Add visit(node, visitor) to 'yaml' (#225)

v2.0.0-4

• Stringify top-level block scalars with header on marker line
• Add a couple of things to 'yaml/util' that weren't exposed before

v2.0.0-5

• Add Collection, Value & Node visitor aliases
• Add error codes
• Always include offset in CST tokens
• Add CST tools (#252)

v2.0.0-6

• Check key uniqueness; add uniqueKeys option (#271)
• Drop special-casing COMMENT_SPACE error; use MISSING_CHAR for it instead

v2.0.0-7

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

v2.0.0-8

• Add a new createNode option aliasDuplicateObjects (#299)
• Add clone() methods to Document, Directives, Schema and all Nodes (#304)

v2.0.0-9

• Add keepSoureToken parse option, adding srcToken values to Nodes (#309)
• Allow for custom schema id, provided that customTags is defined (#325)
• Expose tags & types required by custom composers (#325)

v2.0.0-10

• Add a compatibility checker (#335)
• Support for Non-YAML Schemas (#336, #337, #343, #344)

v2.0.0-11

• Add warning for aliases & anchors ending with a colon (#370)
• Add directives.docEnd, for ... marker (#371)
• Add YAML.visitAsync() (#372)

v2.0.0

• Allow for a 'next' YAML version

v2.0.0-11

This version of yaml has been published to npm using the next dist-tag, so install it with:

npm install --save-exact yaml@next

BREAKING CHANGES

YAML.defaultOptions is removed (#346)

For a while, it's been undocumented, but still available. Since the options refactor of #235, it has only provided defaults for Parse & Document options, and not any of the others, so its name is a bit misleading as well.

If you're using YAML.defaultOptions, you'll need to explicitly set the options in the appropriate parse*() and new Document() calls after this change.

directives.marker is renamed as directives.docStart (#371)

The behaviour of the property stays the same as before.

New Features

• Add warning for aliases & anchors ending with a colon (#370)
• Add directives.docEnd, for ... marker (#371)
• Add YAML.visitAsync() (#372)

Bugfixes

• Flow collection keys in block maps (redhat-developer/vscode-yaml#712)
• Error on %YAML directives with content after version (#348)
• Use correct check for empty null source (#366)
• Do not throw during composition, even for bad tokens (#367)
• Error on invalid %YAML directives
• Empty block scalars with chomp=keep & trailing whitespace
• Parse ? : x as { ? { : x } }
• Do not consider tabs as indent for flow collections
• Include trailing more-indented empty lines in block scalar contents
• Should complain about -, and -] in flow collections
• Update dev dependencies, including @types/node downgrade

Test Improvements

• Update yaml-test-suite, skipping some new tests
• Don't needlessly skip yaml-test-suite B63P test
• test-events: Do not skip events for only apparently empty documents
• yaml-test-suite: Skip in.json tests when expecting errors