Improve JSON compatibility

[eemeli]

The main intent here is to have the signatures and behaviour of YAML.parse() and YAML.stringify() more closely model that of JSON.parse() and JSON.stringify(). Mostly this is a matter of adding new features, but some breaking changes are also required.

YAML.parse(str, reviver?, options?)

Passing a function as a second arg will treat it as a reviver. Implementation follows the JSON spec, extending it naturally for Set and Map, which may be returned from !!set and !!omap collections, or by enabling the mapAsMap option. Calling YAML.parse(str, options) is still supported.

YAML.stringify(value, replacer?, options?)

Passing a function as a second arg will treat it as a replacer. Implementation follows the JSON spec, extending it naturally for Set and Map. Calling YAML.stringify(value, options) is still supported. For further JSON.stringify compatibility, using a number or string as the third options value will set the indent option accordingly.

Document#toJS({ mapAsMap, onAnchor, reviver })

Split from toJSON(), this is now the preferred way of getting "native" JavaScript output from a Document. mapAsMap overrides document & default settings, onAnchor is a callback for each aliased anchor in the document, and reviver is as in YAML.parse().

Document#toJSON()

Now always returns JSON-compatible output, which is a breaking change from the previous. Thanks to the split, the keepBlobsInJSON option is dropped.

import { toJS } from 'yaml/util'

This exposed utility function is renamed from toJSON to toJS, while keeping its signature and behaviour the same.

Well-formed YAML.stringify

Implements the ECMA-262 Stage 4 proposal. Always stringify scalars that include unpaired surrogate code points as double-quoted, and represent them with \u escape sequences.

---

Conceptually, the reviver and replacer that are added take place between the YAML Document and the native JS representations of the document. To put that another way, nothing changes here for YAML.parseDocument() or Document#toString().

The extension of the JSON spec of reviver and replacer to also cover Map and Set means that the key that's used in the callbacks is not always a string. For Set, we follow the pattern used by its iteration methods, and use the same value for both key and value. It's also good to note that as YAML supports collections as keys, the callbacks will also get called with their values, as appropriate.

With this PR, the codebase will also start to include some previously-avoided methods like Array.from and Object.values, which are not supported in all the environments that yaml@1 supported without any further transpilation. It's not quite clear yet just what the new minimum will be.

[ahmadnassri]

epic! found my way here by looking for a YAML.parse signature that behaves like JSON.parse... exactly what I needed!