What should YAML.stringify(undefined) return?

[eemeli]

At the moment, YAML.stringify() or YAML.stringify(undefined) returns a string '\n', following the logic of always returning a string, and always including a newline \n as its last character. That seemed like a good idea at the time when I implemented it, but now when working on yaml@2 that could be changed.

JSON.stringify(undefined) returns the value undefined, i.e. not a string. Which can be rather surprising, esp. as e.g. TypeScript's typing for it does not even include that possibility.

Thoughts on this? I think the following are the sane options that are available. If you prefer one over another, please react with the matching emoji and/or comment below.

• 😕 return '' - empty string
• 👍 return '\n' - keep the status quo
• 😄 return 'null\n' - represent it as a null, as is done for undefined values in arrays
• 👀 return undefined - match JSON.stringify
• 🚀 throw an error

[dota17]

Matching JSON.stringify is a general choice. There is a slight difference between null and undefined.
null - an empty or non-existent value.
undifined - a variable has been declared, but not defined. lack of a value.
But in YAML V1.2 SPEC，there is no clear definition of null:

1 "the empty scalar as “null”"
2 "Represents the lack of a value."

Considering the compatibility，

console.log(YAML.stringify([1,undefined, ,2]))
- 1
- null
- null
- 2

Returning 'null\n' is a better choice.

[eemeli]

It may also be relevant to note that JSON.stringify([1, undefined, , 2]) returns '[1,null,null,2]'.

[kirbysayshi]

Just came to this after being surprised that:

• require('yaml').stringify({ hello: undefined }) -> '? hello\n'

I would have expected "hello" to be absent, especially considering:

• JSON.stringify({ hello: undefined }) -> '{}'

Regarding the conversation above, keep in mind that arrays in JS are different than Objects in terms of semantics. Non-serialized arrays can have "holes" and also want to preserve key index ordering, which is why

• JSON.stringify(['a', undefined, 'b']) -> '["a",null,"b"]'

indexing [2] should always be "b". But that's different for an object, which doesn't need to worry about ordered indexing.

While I'm not a YAML expert, I'd recommend hemming as close as possible to JSON and have two separate rules for objects vs arrays (lists)!

[eemeli]

The behaviour of undefined as an array or object value already (2.0.0-0) matches that of JSON. This issue is specifically about YAML.stringify(undefined), i.e. with it as a top-level scalar value.

[dota17]

I see. In view of this, matching JSON.stringify may be better. @eemeli Which one do you prefer?

It may also be relevant to note that JSON.stringify([1, undefined, , 2]) returns '[1,null,null,2]'.

[eemeli]

I asked the question because I'm not sure myself. :)

Given the other JSON compatibility changes that are coming in #189, returning undefined probably makes the most sense. But I probably shouldn't short-circuit it as is done now, in case anyone is using a schema that does include a YAML representation for undefined.

[kirbysayshi]

The behaviour of undefined as an array or object value already (2.0.0-0) matches that of JSON. This issue is specifically about YAML.stringify(undefined), i.e. with it as a top-level scalar value.

Ah, my apologies! yaml was recently added to my package tree, and I assumed it was the latest version that was being discussed here. Sorry for the confusion and distraction!

[ingydotnet]

Starting from the other side, YAML.parse('') currently returns null, which is a single value. The YAML spec says that a YAML stream represents zero or more documents (values). An empty YAML stream should be understood to mean zero documents.

Therefore, YAML.parse('') should either throw an error (if it intends to always return a single value), or it could return undefined where that means no values.

Note that JSON.parse('') throws an error.

If YAML.parse('') returns undefined then it seems logical that YAML.stringify(undefined) should return '' (the shortest representation of an empty stream).

Since "\n" is also an empty YAML stream, it seems fine to return that as you do now. However, please change YAML.parse("\n") to return undefined. :-)

[perlpunk]

Related issue in js-yaml: nodeca/js-yaml#565

[eemeli]

The way I see it, YAML.parse() and YAML.stringify() provide an API for dealing with exactly one YAML document and its native representation. Starting from there, parsing an empty string is asking for the JS representation of a single YAML document with empty contents. For JSON, that doesn't exist, but in YAML an empty string is a valid way of representing a null value. Happily, this round-trips pretty well and is stringified more explicitly as null\n.

I'd be really rather leery of YAML.parse('') returning anything other than null, given that that's what e.g. # foo\n also gets parsed as; in that case we can more clearly see the intermediate YAML.Document object as needing to exist, with empty contents and a ' foo' comment.

But of course JavaScript has more than one empty value, and that's where it all gets tricky. Not to mention that we could tell YAML.stringify() and YAML.stringify(undefined) apart from each if we really wanted to, and treat them as different from each other. I don't think we should, but that's a possibility.

I'm currently finding myself arguing internally for pretty much all of the possibilities, one after the other. That of course would be a "fun" way of dealing with this (literally) undefined behaviour; select an option randomly each time.

[ingydotnet]

The way I see it, YAML.parse() and YAML.stringify() provide an API for dealing with exactly one YAML document and its native representation.

If you want to start there, then YAML.parse('') should throw an error, since there are no documents available.

I don't know of any other YAML implementation that returns their language's equivalent of null.

JSON.parse throws an error.

But of course JavaScript has more than one empty value, and that's where it all gets tricky. Not to mention that we could tell YAML.stringify() and YAML.stringify(undefined) apart from each if we really wanted to, and treat them as different from each other. I don't think we should, but that's a possibility.

If you want to consider undefined as a first class JS object (and I don't think you should), you should stringify it something like: !!javascript/undefined ''. JSON.stringify(undefined) and JSON.stringify() both return undefined. Obviously it is meant to convey "nothing", where JSON.stringify is a function meant to return a string.

Hence, I think you can safely follow in JSON footsteps here... But I think JSON.parse('') would have done better and more consistent to return undefined from a rountripping perspective at least... Then again maybe it's better to purposefully not roundtrip when you are talking about nothing and an API that wants one thing.

[eemeli]

I decided to go with undefined. That matches JSON.stringify(), and it's at least not wrong. I also added a new keepUndefined option, which keeps undefined values in mappings. That allows for local tags like !js/undefined to be used, should that be desirable.

Thank you everyone for your feedback!

[ingydotnet]

I wonder if keepUndefined option is even needed. The only undefined value of concern here is the top level node. I'd just make every other undefined value serialize. This is how js-yaml does it, which is in line with this:

$ node -e 'a=[];a[2]=42;console.log(require("js-yaml").dump(a))'
- !<tag:yaml.org,2002:js/undefined> ''
- !<tag:yaml.org,2002:js/undefined> ''
- 42

I'd prefer a cleaner !js/undefined or !!js/undefined.