Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve JSON compatibility #189

Merged
merged 12 commits into from
Sep 6, 2020
Merged

Improve JSON compatibility #189

merged 12 commits into from
Sep 6, 2020

Conversation

eemeli
Copy link
Owner

@eemeli eemeli commented Aug 30, 2020

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.

As replacer & options have different shapes, YAML.stringify and the
Document constructor can still accept the options as the second
argument.

The behaviour of the replacer should match the JSON.stringify equivalent
exactly for the values both support. Map is treated equivalently to an
Object; others act like arrays.
BREAKING CHANGE: The `toJSON()` utility exported by 'yaml/util' is
renamed as `toJS()`.
@eemeli eemeli added the enhancement New feature or request label Aug 30, 2020
@eemeli eemeli added this to the yaml 2 milestone Aug 30, 2020
@ahmadnassri
Copy link

ahmadnassri commented Sep 1, 2020

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

@eemeli eemeli mentioned this pull request Sep 2, 2020
@eemeli eemeli merged commit f6a9f6f into master Sep 6, 2020
@eemeli eemeli deleted the json-like branch September 6, 2020 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants