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

v2.0.0-10

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

• The TS type of doc.directives now indicates it as optional. Its actual value has not changed, but the type needs to account for what might happen if doc.setSchema() is called with a null version argument. (#344)

New Features

Add a compatibility checker (#335)

Adds a new schema option compat: string | Tags. If set, warns during composition about compatibility issues with the given schema. When stringifying, uses scalar styles that are parsed correctly by the compat schema as well as the actual schema.

Support for Non-YAML Schemas

While YAML is a superset of JSON, it isn't a strict superset of other JSON-based configuration languages. Feature-wise, though, these languages are as a rule a subset of YAML features, so let's build some groundwork for supporting them as well by making additional aspects of this library configurable.

• Add commentString option, refactor internals to support it (#336)
• Add toStringDefaults option (#337)
• Add collectionStyle option (#343)
• Allow for Schema instance as schema option (#344)

Test Improvements

• Add json-test-suite as git submodule (#340)
• Update to latest yaml-test-suite data
• Add {} and [] indicators to flow maps & sequences in test-events output (used by the YAML Test Matrix)
• Use --target es5 in test:dist:types script (#334)

Bugfixes

• Allow for custom schemas in TS types (#325)
• Flow collection expected-end error (#328)
• parser: flow-error-end token should not advance offset
• Handle duplicate flow : indicators correctly
• Correctly stringify non-finite scalars with format: 'EXP'
• Allow block map with flow collection key as explicit key
• Do not use negative indent for any parser tokens

v2.0.0-9

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

npm install --save-exact yaml@next

Hopefully the breaking change for singleQuote: false won't cause anyone issues. Otherwise, small improvements only.

BREAKING CHANGES

Allow disabling single & block quotes completely (#326)

The options for representing scalar values are refactored, such that blockQuote (new) and singleQuote (expanded) allow setting a preference as well as preventing said styles from being used at all. This changes how singleQuote: false is handled. To retain the previous behaviour, use singleQuote: null or leave the option unset.

New Features

• 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)

Bugfixes

• cst: Specify resolveAsScalar return type
• lexer: Reset flow-key flag on comma in flow collection (#316)
• lexer: Allow unindented comment in flow collection
• Support seq-of-maps merge key values (#321)
• compose: Indent level of empty block scalars with keep chomping (#313)
• Honor singleQuote option more widely
• Get rid of extra whitespace around empty map values
• Drop ...expansion from public TS interfaces (#334)

v2.0.0-8

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

npm install --save-exact yaml@next

This release doesn't really do anything major, it's really just an accumulation of small things over the past few weeks.

New Features

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

Bugfixes

• lexer: Cache line end positions (#298)
• Handle doc.createNode(doc) the same as doc.createNode(doc.contents) (#303)
• Allow for collection setIn() to handle objects, including duplicates
• Fix parsing errors with CRLF line endings (#306, #307)

v2.0.0-7

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

npm install --save-exact yaml@next

This release doesn't really do anything major, it's really just an accumulation of small things over the past few weeks. Thanks in particular to @ingydotnet for his continuing help in finding corner cases of invalid input being parsed as valid.

New Features

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

Bugfixes

• Anchors for duplicate objects that stringify as strings (#287)
• Complain about empty aliases & anchors
• Do not throw for "%" as document
• Complain about plain scalars starting with , or %
• Use correct character set for tags

v2.0.0-6

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

npm install --save-exact yaml@next

The "big" thing here is the change to empty-line handling, which should allow for empty spaces before, between and after comments lines to be better represented. This also allowed me to un-skip the final block of tests that had been failing since the new parser was introduced.

Otherwise, mostly bugfixes. Feels like actually releasing v2.0.0 might happen pretty soon.

BREAKING CHANGES

Fix empty lines & trailing comments (#278)

An empty line in the source is represented by an empty line in the comment or commentBefore value, and a bare # is represented by a line consisting of a single space character. This relatively small change allows for any combination of comment and blank lines to be cleanly represented by a single string, with the cost of a comment consisting of a single space character being unrepresentable.

The handling of trailing comments is also simplified somewhat; they now need to be more indented than their parent collection to attach to the preceding rather than the following node.

Drop Node.js 10 support

As Node.js 10 is now out of maintenance support, it's dropped from the CI tests. The library should continue to work fine with it, but that is no longer guaranteed.

New Features

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

Bugfixes

• docs: typo fix (#270)
• Clarify value-end & node-end meaning in ranges (#262)
• Clarify sortMapEntries non-effect on parsing (#267)
• Use correct range-end offsets for empty flow collections (#275)
• Always require space after tags & anchors

v2.0.0-5

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

npm install --save-exact yaml@next

This one's mostly about improvements and refactorings on the previous, by changing how anchors work and making the new CST easier to work with. The following is an overview of the changes included here; you are encouraged to also consult the individual PRs, as well as the updated documentation site.

BREAKING CHANGES

Make anchor & alias resolution lazier (#248)

Previously, the source of an alias node was a JS reference to the actual node object that it referred to, and doc.anchors provided separately from that the string identifiers used by YAML anchors.

Scalar and collection nodes now get a new anchor?: string property, and the source of an alias is a string identifier. The doc.anchors instance is completely dropped. The createAlias() method is moved to the document instance, and its handling of corner cases is changed a bit.

As a consequence of these changes, assigning the same anchor to multiple nodes will no longer automatically rename an earlier anchor with the same name.

Node creation options are somewhat clarified and streamlined, and the replacer is moved from the options object to be an optional second argument of the createNode() method, matching the new Document() interface.

Split flow collections into items in Parser (#249)

The shape of FlowCollection items changes from CST.Token[] to CST.CollectionItem[], so that it now matches the items of BlockMap and BlockSequence. This means that the corresponding composer is completely rewritten.

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

While the inheritance of the class is just an implementation detail, dropping the prop forwarding means that a user that previously set the commentBefore, comment or spaceBefore property of a pair will now need to set it for the appropriate key or value.

Rename the tokens namespace as CST (#252)

Turn the Lexer, Parser & Composer into generators (#253)

All of the parsing stages now provide generators, so that their output may be iterated, rather than needing to provide them with a callback function. As a convenience, a compose() method is also added:

import { Composer, Parser } from 'yaml'

const src = 'foo: bar\nfee: [24, "42"]'
const tokens = new Parser().parse(src)
const docs = new Composer().compose(tokens)

Array.from(docs, (doc) => doc.toJS())
> [{ foo: "bar", fee: [24, "42"] }]

Refactor Node range as [start, value-end, node-end] (#259)

For block values, value-end and node-end are always the same as the previous end value. For flow collections and documents, node-end is the same as the previous end position, while value-end marks the end of the actual value.

Replace error.offset with error.pos: [number, number] (#260)

In addition to dropping error.offset, the shape of error.linePos is changed to a matching tuple of { line, col } values. For many errors, it's still impossible or unwieldy to determine their full position range, so their ranges get assigned as [n, n+1].

New Features

• Add Collection, Value & Node visitor aliases
• Add error codes
• Always include offset in CST tokens

Add CST tools (#252)

The following functions are added. See the updated docs for more on their usage.

import { CST } from 'yaml'

• CST.createScalarToken(value, ctx) – create a new token
• CST.isCollection(token) – check for block or flow collection
• CST.isScalar(token) – check for block or flow scalar
• CST.resolveAsScalar(token, strict, onError) – get the value of a token
• CST.setScalarValue(token, value, ctx) – set the value of a token
• CST.stringify(cst) – stringify any CST content
• CST.visit(cst, visitor) – custom visitor for walking through the CST
• CST.visit.itemAtPath(cst, path) – Find the item at path from cst as the root.
• CST.visit.parentCollection(cst, path) – Get the immediate parent collection of the item at path from cst as the root.

Bugfixes

• Do not trim plain values during composition
• Fix flow comment parsing
• Properly complain about &a ? b
• Fix line comment handling in flow collections
• For block scalars, use an empty string rather than undefined to mark empty values in the CST
• Add @types/node as explicit dev dependency (#251)

Internal Stuff

• Combine doc/Schema.ts & tags/* under schema/
• Drop Babel from Node.js build; specify CI min as Node.js 10.14.2 (due to Jest)
• Include test for d.ts output (#245)
• Drop the catch-all Options type

v2.0.0-4

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

npm install --save-exact yaml@next

This release encompasses most of the big-picture changes of the whole yaml@2 update. The following is an overview; you are encouraged to also consult the individual PRs, as well as the updated documentation site.

BREAKING CHANGES

Refactor options (#235)

This does a bunch of stuff that changes (and breaks!) the options used by yaml by moving them closer to where they're actually used. Each of the following changes is described in more detail in the PR #235. The new options structure is also well documented.

• Drop the keepCstNodes and keepNodeTypes options completely
• Move mapAsMap and maxAliasCount from DocumentOptions to ToJSOptions
• Move indent, indentSeq & simpleKeys from DocumentOptions to ToStringOptions
• Move BigInt option from scalarOptions to ParseOptions
• Drop special options for !!binary
• Move all other scalar options to ToStringOptions
• Refactor doc.setSchema()
• Drop Document.defaults and doc.getDefaults()
• Drop scalarOptions
• Drop options from the tag interface
• Un-document the YAML.defaultOptions export

Refactor parsing completely (#203)

Effectively replace everything in /src/cst/ and /src/resolve/ with new code, and redefine the CST level API.

Parser is a new parser that generates CST node trees from its input, internally using Lexer to split the input into tokens. They're both capable of dealing with input coming in chunks. Composer then turns the CST into a Document.

The intent here is to keep the parse(), parseDocument(), parseAllDocuments(), and Document APIs pretty much exactly as they were, while redoing the parser completely. The parseCST() API is completely dropped, in favour of Lexer and Parser. The shape of YAMLError changes a bit (#243), and YAMLParseError replaces the previous parse error classes.

Documents now include a new doc.directives member, which replaces doc.tagPrefix and doc.setTagPrefix(), as well as doc.directivesEndMarker and doc.version.

For more information, please consult the updated documentation site.

Merge all of 'yaml/types' and some of 'yaml/util' into 'yaml' (#234)

The endpoint 'yaml/types' is completely removed. This is how you'll need to update your imports, if using:

-import { Alias, Pair, Scalar, YAMLMap, YAMLSeq } from 'yaml/types'
+import { Alias, Pair, Scalar, YAMLMap, YAMLSeq } from 'yaml'

-import { YAMLError, YAMLParseError, YAMLWarning } from 'yaml/util'
+import { YAMLError, YAMLParseError, YAMLWarning } from 'yaml'

Refactor node identification (#233)

• The base class used by nodes is no longer exported.
• Internally, all instanceof checks are dropped
• New type guard functions are introduced:

import {
  isAlias, isCollection, isDocument, isMap,
  isNode, isPair, isScalar, isSeq,
} from 'yaml'

isNode(foo) // All take a single parameter and return true or false

Drop type property from all but Scalar nodes (#240)

• For continuing scalar use, move the constants from Type to Scalar
• For collections, introduce a flow: boolean property to control whether they use block or flow representation
• Drop the Merge class; use duck-typing instead to handle << merge pairs when merge: true or version: '1.1' is set

Refactor as TypeScript (#233)

New Features

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

import { debug, warn, foldFlowLines } from 'yaml/util'

Bugfixes

• Preserve newlines within comments (#116)
• Fix the range of empty scalars (#231)
• Prefer literal over folded block scalar when lineWidth=0 is set (#232)
• Handle String, Number, Boolean & BigInt scalar wrappers (#236)

Internal Stuff

• Add CodeQL CI action
• Use own source template tag rather than the one from common-tags (for tests)
• Update docs base to Slate 2.9.1
• Update dev dependencies