yaml 2.0.0-5

on Node.js NPM

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