v2.0.0

[eemeli]

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 (Drop deprecated end points, members, options & defaults #171)
• Breaking changes to Document & createNode APIs (Breaking changes to Document & createNode APIs #186)
• When creating a mapping from a JS Object, drop undefined values ([Bug?] undefined is converted to null #173)
• Retain existing nodes when using set() in mappings & sequences (Update value with saving comment #185)

v2.0.0-1

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

v2.0.0-3

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

v2.0.0-4

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

v2.0.0-5

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

v2.0.0-6

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

v2.0.0-9

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

v2.0.0-10

• The TS type of doc.directives now indicates it as optional (Allow for Schema instance as schema option #344)

v2.0.0-11

• YAML.defaultOptions is removed (Remove YAML.defaultOptions #346)
• directives.marker is renamed as directives.docStart (Add directives.docEnd, for ... marker #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 (Resolve known tags in core schema #172)
• Create intermediates for set() & setIn() on doc with empty contents (Document setIn() should work if document contents are empty #174)
• Fix intermediate collection creation for parsed documents (Document setIn() should work if document contents are empty #174)
• Improve quoted string flexibility (Improve quoted string flexibility #177)
• Add defaultKeyType option for finer control of scalar output (Surrounding array with items with quotes #179)

v2.0.0-1

• Remember source string for null scalars (Store the source string and outputs it in toString()/String(). #193)
• Support asBigInt option for sexagesimal integer values

v2.0.0-3

• Refactor logging control, adding logLevel option (Refactor logging control, adding logLevel option #215)
• Add visit(node, visitor) to 'yaml' (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 (Add CST tools #252)

v2.0.0-6

• Check key uniqueness; add uniqueKeys option (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 (Add a new createNode option aliasDuplicateObjects #299)
• Add clone() methods to Document, Directives, Schema and all Nodes (Add clone() methods to Document, Directives, Schema and all Nodes #304)

v2.0.0-9

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

v2.0.0-10

• Add a compatibility checker (Add compat option #335)
• Support for Non-YAML Schemas (Add commentString option #336, Add toStringDefaults option #337, Add collectionStyle option #343, Allow for Schema instance as schema option #344)

v2.0.0-11

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

v2.0.0

• Allow for a 'next' YAML version

---

This discussion was created from the release v2.0.0.

[ssbarnea]

Can we please get some examples about how to port older typescript code to the new 2.0 version? We now gets lots of errors and is not clear how we should update the imports. Few examples below:

test/utils/yaml.test.ts:2:48 - error TS2307: Cannot find module 'yaml/types' or its corresponding type declarations.
2 import { Node, Scalar, YAMLMap, YAMLSeq } from "yaml/types";

src/utils/yaml.ts:3:29 - error TS2305: Module '"yaml"' has no exported member 'parseCST'.

3 import { Document, Options, parseCST } from "yaml";

src/utils/docsParser.ts:4:10 - error TS2305: Module '"yaml/util"' has no exported member 'YAMLError'.

4 import { YAMLError } from "yaml/util";

If someone already made the switch, it would be awesome to put a link here, as it would make easier to figure out the list of changes we will need.

[eemeli]

The types previously exported from 'yaml/util' should now be available from 'yaml': #234.

The API replacing parseCST is provided by the Parser class, documented here: https://eemeli.org/yaml/#parser

Note that the v2 CST is rather different from the v1 CST.