Releases: eemeli/yaml
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; useMISSING_CHAR
for it instead
Bugfixes
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 tokenCST.isCollection(token)
– check for block or flow collectionCST.isScalar(token)
– check for block or flow scalarCST.resolveAsScalar(token, strict, onError)
– get the value of a tokenCST.setScalarValue(token, value, ctx)
– set the value of a tokenCST.stringify(cst)
– stringify any CST contentCST.visit(cst, visitor)
– custom visitor for walking through the CSTCST.visit.itemAtPath(cst, path)
– Find the item atpath
fromcst
as the root.CST.visit.parentCollection(cst, path)
– Get the immediate parent collection of the item atpath
fromcst
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
andkeepNodeTypes
options completely - Move
mapAsMap
andmaxAliasCount
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
anddoc.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
toScalar
- 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 whenmerge: true
orversion: '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 fromcommon-tags
(for tests) - Update docs base to Slate 2.9.1
- Update dev dependencies
v1.10.2
- Allow for unindented comment after node props (prettier/prettier#10510)
v1.10.1
This release backports the following non-breaking fixes made during the work on yaml@2
on top of yaml@1.10.0
:
- Support for
__proto__
as mapping key & anchor identifier (#192) - Fix broken TS type for BigInt toggle
- Dump long keys properly (#195)
- When folding highly indented lines, require at least
minContentWidth
chars on the first line (#196) - Fix
YAML.stringify()
for certain null values (#197) - Do not break escaped chars with escaped newlines (#237, cdk8s-team/cdk8s#494)
- Set
type: "module"
within browser/dist/ (#208) - Use CommonJS for the browser endpoints
yaml/types
&yaml/util
(#208) - Always stringify non-Node object keys using explicit notation (#218)
- Specify node type of
Document.Parsed.contents
(#221) - Add missing type for CST
Node.rangeAsLinePos
(#222) - Prefer literal over folded block scalar when
lineWidth=0
is set (#232) - Allow for empty lines after node props (#242)
- Update dev dependencies
v2.0.0-3
This version yaml
has been published to npm using the next
dist-tag, so install it with:
npm install --save-exact yaml@next
This is the last release before the CST parser rewrite (#203), and some of the changes here are in preparation for that.
The preceding prerelease (2.0.0-2) had a visit()
bug that was identified immediately after release, and is fixed here.
BREAKING CHANGES
Drop 'yaml/parse-cst' endpoint (#223)
Users will need to update their code:
-import parseCST from 'yaml/parse-cst'
+import YAML from 'yaml'
+const parseCST = YAML.parseCST
Update build configs & minimum supported versions (#224)
- Drop IE 11 support
- Switch minimum Node.js target from 6.5 to 10.0
- Refactor browser exports as pure ES modules rather than CommonJS (#208)
- Add "default" fields to package.json "exports"
- Add
preserveModules: true
& treeshake config to Rollup configs
New Features
Bugfixes
- Remember source string for boolean scalars (#199)
- Add missing extension to Document.js import path (#210)
- Do not break escaped chars with escaped newlines (cdk8s-team/cdk8s#494)
- Always stringify non-Node object keys using explicit notation (#218)
- Add missing type for CST
Node.rangeAsLinePos
(#222) - Specify node type of
Document.Parsed.contents
(#221)
Internal Stuff
- Add issue templates (#219)
- Update dev dependencies
- Include Babel plugin for nullish coalescing operator
- Update playground to Webpack 5
v2.0.0-1
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 continues from where 2.0.0-0
left off to make incremental changes to the library, mostly in order to further improve JSON compatibility and to make custom tags easier to write. For details on the breaking changes, please see PRs #189 and #201.
It's likely that the next release after this will incorporate #203, which is a rather more significant change to the parsing internals and the CST API.
BREAKING CHANGES
Improve JSON compatibility (#189)
- Add
doc.toJS()
, replacing mostdoc.toJSON()
calls - Drop
keepBlobsInJSON
option - The
toJSON()
utility exported by 'yaml/util' is renamed astoJS()
. - Add
keepUndefined
option & by default returnundefined
forstringify(undefined)
(#187) - Add optional
replacer
argument forstringify
,new Document
&doc.createNode
- Add JSON reviver support to
parse()
anddoc.toJS()
- Encode strings with unpaired surrogate code points as double-quoted
- Allow third arg of
stringify
to be a number or string setting indent
Refactor tag resolve() API (#201)
All tag resolvers are now called with two arguments:
value: string | YAMLMap | YAMLSeq
onError(message: string): void
with the value being determined solely by the node's shape, rather than
any explicit tag it may have.
Also:
- Drop exports of
{ parseMap, parseSeq }
from 'yaml/util' - Refactor
resolveString()
arguments - Use
re.test(str)
rather thanstr.match(re)
for default tags - Refactor away
schema.tags.scalarFallback
New Features
- Remember source string for null scalars (#193)
- Support
asBigInt
option for sexagesimal integer values (04b2d65)
Bugfixes
- Correct the output of the readme example (#188)
- Support for
__proto__
as mapping key & anchor identifier (#192) - Dump long keys properly (#195)
- When folding highly indented lines, require at least minContentWidth chars on the first line (#196)
- Fix YAML.stringify() for certain null values (#197)
- Drop obsolete Travis CI badge from README (3b807a1)
Internal Refactorings
v2.0.0-0
This version yaml
has been published to npm using the next
dist-tag, so install it with:
npm install --save-exact yaml@next
Be aware that further breaking changes are likely before we get to a final 2.0.0 release. However, at least so far the basic YAML.parse()
and YAML.stringify()
APIs are pretty much unaffected by any of the breaking changes.
BREAKING CHANGES
Drop deprecated end points, members, options & defaults (#171)
- The following entry points are removed:
- 'yaml/map'
- 'yaml/pair'
- 'yaml/scalar'
- 'yaml/schema'
- 'yaml/seq'
- 'yaml/types/binary'
- 'yaml/types/omap'
- 'yaml/types/pairs'
- 'yaml/types/set'
- 'yaml/types/timestamp'
- The package.json
"exports"
no longer include an"./": "./"
escape hatch. Schema.defaultTags
andSchema.defaultPrefix
are removed.- The
tags
alias for thecustomTags
option is removed, andprettyErrors
is now default-true. - Custom tags that use
class
instead ofidentify()
are no longer supported.
Breaking changes to Document & createNode APIs (#186)
See the PR for usage examples of:
new YAML.Document(value, options?)
- The Document constructor gets a new first argumentvalue
. This allows for much more ergonomic document creation.doc.createNode(value, options?)
- The methodsYAML.createNode()
anddoc.schema.createNode()
are replaced by a singledoc.createNode()
. Their non-value arguments are also collected into an options object.doc.createPair(key, value, options?)
- The methoddoc.schema.createPair()
is replaced bydoc.createPair()
, and also uses an options bag instead of named positional arguments.
When creating a mapping from a JS Object, drop undefined values (#173)
When creating a YAML mapping from a JS Object, keys with undefined
values are not included. This matches the behaviour of JSON.stringify()
. In all other cases, the handling of undefined
is unchanged, so e.g. [1, undefined, 2]
will still result in a sequence of three items, the second of which has a null
value. This too matches the behaviour of JSON.stringify()
.
Previously, undefined
object values were mapped to null
.
Retain existing nodes when using set() in mappings & sequences (#185)
When overwriting a Scalar
value with a scalar using set(), the original node is retained.
New Features
v1.10.0
This will probably be the last minor release of yaml@1
. I'm aiming to release yaml@2
within a few months; prereleases of that will be published using the next
dist-tag on npm. Patch releases for 1.10 may still happen, if necessary.
New Features
- Use Rollup for Node.js & browser builds (#165)
- This removes most of the internal
dist/
paths from the release. If you want/need to use a class or function that is no longer public, please file an issue and we can add it to the exports. - Drop dependency on
@babel/runtime
. After this, the package has 0 runtime dependencies. 🎉 - Add exports
{ Alias, Collection, Merge, Node }
to 'yaml/types'
- This removes most of the internal
- Document
Schema.createPair()
& make itsctx
arg optional (#157) - Always indent top-level scalars with lines starting with document markers or % directives (#162)
- Use double-space when forcing top-level block scalar indent, for clarity (#162)
- Add
getNodes(): string[]
method to Anchors (#166) - Refactor Jest config, adding tests for compiled
dist/
endpoints - Rename & refactor source files. This should have no effect on the results, but lots of stuff moved around
Improved Errors & Warnings
- Throw more helpful error when setting Pair.commentBefore incorrectly (#157)
- Better errors for bad indents (#169)
- Drop incorrect error for flow mapping keys with length > 1024 chars
- Add errors for plain scalars that start with reserved indicators
- Add more explicit errors for block scalar values with bad indents
- Enable log prints during
npm start
debugging
Improved TypeScript declarations
- Fix/simplify export mapping of 'yaml/types' and 'yaml/util'
- Fix types, dropping
AST.{AstNode,ScalarNode,CollectionNode}
(#160) - Add missing
toString()
methods to AST nodes (#159) - Add directivesEndMarker to Document type (#167)
Bugfixes
- Use CommonJS for top-level default-exporting browser endpoints (#163)
- docs: Add note about simpleKeys for null values (#170)
- Update dev & playground dependencies, including eslint 7 & jest 26
- Update yaml-test-suite, fixing errors in remaining invalid-input tests
- Add explicit error for block scalars with more-indented leading empty lines (S98Z)
- Properly add error for tab-indented map values (4EJS)
- Add error for multiline implicit flow sequence pair key (DK4H & ZXT5)
- Require space after comma before comment in flow collections (CVW2)
- Use
mapAsMap: true
for out.yaml tests (4FJ6)