There needs to be a way to set the line ending to use when serializing YAML instead of using a hard-coded value.
For my current project I just did an evaluation against js-yaml, and your library won out (primarily because of the comment-preserving capability). However there's one gap: the ability to specify line endings when serializing. Many use cases will want to match the underlying platform default end-of-line sequence for various reasons. For our current data, we can do a global \n replace if necessary on the produced serialization, but that's a post-serialization workaround hack, and more onerous for general YAML processing there are edge cases in which this could corrupt the data.
Objective
Add an option (e.g. eol: '\n' | '\r\n') to ToStringOptions so that stringify() and Document#toString() can produce output using a caller-specified line-ending sequence, rather than always emitting a bare \n.
Background
A tool that writes a YAML file often needs the result to match a specific line-ending convention — the host platform's own convention (\r\n on Windows), a project's existing .gitattributes/core.autocrlf policy, or simply whatever line ending an existing file on disk already uses, so a diff shows only the intended content change. Right now, stringify()/Document#toString() always emit \n, so a caller wanting anything else has no supported option and is left to post-process the resulting string themselves, typically with something like result.replace(/\n/g, '\r\n').
That naive fixup is risky in general, even though it usually happens to work: YAML's own line-break normalization rules mean a compliant parser reading the result back should treat an embedded CR, LF, or CRLF inside scalar content as equivalent, normalizing back to a single semantic line break regardless of which bytes were actually written — so round-tripping through a spec-compliant reader is usually safe. But a caller doing this replace has no reliable way to know that guarantee holds for every consumer of the output (a different tool, a stricter or non-conformant parser, a byte-for-byte diff or hash comparison), and has to independently reason through YAML's block/folded scalar semantics just to convince themselves it's safe at all — reasoning the library itself is in a far better position to get right once, rather than leaving every caller to rediscover it.
Possible approaches
- Add an
eol option to ToStringOptions, threaded through the existing StringifyContext (already passed to every stringify call site), and have the small number of places that currently hardcode '\n' — the final lines.join('\n') in stringifyDocument.ts, the prop/value join in stringify.ts, and block/folded-scalar line-joining in stringifyString.ts — read it from there instead.
- Alternatively, perform the substitution internally as a final step that distinguishes structural line breaks from ones that are part of a scalar's own content, so the library makes that determination once rather than requiring an external, blind string replace.
There needs to be a way to set the line ending to use when serializing YAML instead of using a hard-coded value.
For my current project I just did an evaluation against
js-yaml, and your library won out (primarily because of the comment-preserving capability). However there's one gap: the ability to specify line endings when serializing. Many use cases will want to match the underlying platform default end-of-line sequence for various reasons. For our current data, we can do a global\nreplace if necessary on the produced serialization, but that's a post-serialization workaround hack, and more onerous for general YAML processing there are edge cases in which this could corrupt the data.Objective
Add an option (e.g.
eol: '\n' | '\r\n') toToStringOptionsso thatstringify()andDocument#toString()can produce output using a caller-specified line-ending sequence, rather than always emitting a bare\n.Background
A tool that writes a YAML file often needs the result to match a specific line-ending convention — the host platform's own convention (
\r\non Windows), a project's existing .gitattributes/core.autocrlfpolicy, or simply whatever line ending an existing file on disk already uses, so a diff shows only the intended content change. Right now,stringify()/Document#toString()always emit\n, so a caller wanting anything else has no supported option and is left to post-process the resulting string themselves, typically with something like result.replace(/\n/g, '\r\n').That naive fixup is risky in general, even though it usually happens to work: YAML's own line-break normalization rules mean a compliant parser reading the result back should treat an embedded CR, LF, or CRLF inside scalar content as equivalent, normalizing back to a single semantic line break regardless of which bytes were actually written — so round-tripping through a spec-compliant reader is usually safe. But a caller doing this replace has no reliable way to know that guarantee holds for every consumer of the output (a different tool, a stricter or non-conformant parser, a byte-for-byte diff or hash comparison), and has to independently reason through YAML's block/folded scalar semantics just to convince themselves it's safe at all — reasoning the library itself is in a far better position to get right once, rather than leaving every caller to rediscover it.
Possible approaches
eoloption toToStringOptions, threaded through the existingStringifyContext(already passed to every stringify call site), and have the small number of places that currently hardcode'\n'— the finallines.join('\n')instringifyDocument.ts, the prop/value join instringify.ts, and block/folded-scalar line-joining instringifyString.ts— read it from there instead.