README.md

YAML is a great format, similar to JSON. It allows comments and flexibility in objects and arrays with regards to the elements. They can be inlined ([ ... ] and { ... }) or line-by-line.

YAML isn't however as easy to work with programmatically as JSON.

This package offers an API and standalone executables to allow for modifying a YAML as JSON, and then applying that JSON diff as a patch on the YAML, preserving whitespace, comments and overall structure. This also makes the final YAML diff minimal.

API

This package exports three functions: yamlPatch, yamlDiffPatch and yamlOverwrite.

yamlPatch

function yamlPatch( yaml: string, rfc6902: Array< Operation > ): string;

This function applies <rfc6902> "JSON Patch" operations on a <yaml> while trying to preserve whitespace, comments and structure for a minimal change.

Returns the patched YAML.

You can use the rfc6902 package do create the patch object, or use yamlDiffPatch below.

If the differences are too big, patching may fail (just like regular source code diff/patch operations). It's therefore recommended to - rather than re-using a JSON Patch for multiple different YAMLs - create the JSON Patch from each source YAML, transforming it as necessary and then apply that patch, whenever possible. That should never fail.

yamlDiffPatch

function yamlDiffPatch( yaml: string, oldJson: any, newJson: any ): string;

Uses two JSON's (<oldJson> and <newJson>) and makes a diff between them, then applies this as a patch to the <yaml>.

Returns the patched YAML.

This is the same as yamlPatch( yaml, makeJsonPatch( oldJson, newJson ) ); where makeJsonPatch would create an RFC6902 patch object.

yamlOverwrite

function yamlOverwrite( yaml: string, newJson: any ): string;

Uses the source <yaml> as the source object and diffs that against <newJson>, then applies this diff as a patch to the <yaml>. This will overwrite the fields that are different, while maintaining the structure of the source YAML.

Returns the patched YAML.

This is the same as yamlDiffPatch( yaml, yamlToJson( yaml ), newJson ); where yamlToJson would parse YAML into JSON.

Executables

yaml-patch

❯ yaml-patch

   Usage: yaml-patch source.yaml patch.json

   Patches <source.yaml> with the RFC6902 in <patch.json>

   Options:

   -h, --help           Print (this) help screen
   -o, --output <file>  Output filename to write to, or "-" for stdout (default: -)

yaml-diff-patch

❯ yaml-diff-patch

   Usage: yaml-diff-patch source.yaml old.json new.json

   Patches <source.yaml> with the diff between <old.json> and <new.json>

   Options:

   -h, --help           Print (this) help screen
   -o, --output <file>  Output filename to write to, or "-" for stdout (default: -)

yaml-overwrite

❯ yaml-overwrite

   Usage: yaml-overwrite source.yaml source.json

   Patches <source.yaml> with the diff between <source.yaml> and <source.json>

   Options:

   -h, --help           Print (this) help screen
   -o, --output <file>  Output filename to write to, or "-" for stdout (default: -)