yaml 2.0.0-4

on Node.js NPM

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