@atomist/yaml-updater

@atomist/yaml-updater

Node TypeScript module @atomist/yaml-updater for creating clean changes to YAML files producing reasonable diffs from the original. This module was originally developed for use with Atomist code transforms.

Using

Add this package to your package's dependencies.

$ npm install @atomist/yaml-updater

This module defines and exports several functions for formatting and updating YAML. The published module contains the TypeScript type definitions. To use from TypeScript, import the functions you want to use. For example:

import { updateYamlDocument } from "@atomist/yaml-updater";

Each function is documented using TypeDoc, which are published at https://atomist.github.io/yaml-updater/. The tests are pretty complete and a great source of examples for what functions are available and how to use them.

In general, updating a property value adds property and value if it does not exist. If the property does exist in the original YAML, its value will be updated. If its current value is an object, the value will be recursively updated, resulting in nested properties being add/updated without affecting elements of the original YAML that do not appear in the updates. If the updated value is null or undefined, the key and value will be removed from the YAML if it exists. If it does not exist, there will be no change.

Most functions take an optional last options parameter that is an object. Currently the only options object parameter used all the update functions is "keepArrayIndent". If the value of that property is true, the resulting YAML will have arrays indented compared to their parent object. If the value is false, the indentation of the array will be at the same level as its parent object. For example, if keepArrayIndent: true, you will get

parent:
  - first array item
  - second array item

while if keepArrayIndent: false, you will get

parent:
- first array item
- second array item

Both are valid YAML and equivalent representation of the same data structure. Note that only arrays that are updated in some way will be modified, so we recommend you base the value for this option on the format of the original YAML document you are updating.

The updateYamlDocuments function also uses the "updateAll" options property. If true, the updates provided to updateYamlDocuments will be applied to all YAML documents. If false, the updates will only be applied to YAML documents with keys that match those in the updates object. For example, given the following YAML:

---
first: element
second: element
---
first: thing
second: thing
third: thing

calling

const updated = updateYamlDocuments({ third: "item" }, docs, { updateAll: false });

with docs being the above YAML documents, would result in:

---
first: element
second: element
---
first: thing
second: thing
third: item

while calling

const updated = updateYamlDocuments({ third: "item" }, docs, { updateAll: true });

would result in:

---
first: element
second: element
third: item
---
first: thing
second: thing
third: item

Support

General support questions should be discussed in the #help channel in the Atomist community Slack workspace.

If you find a problem, please create an issue.

Development

You will need to install Node.js to build and test this project.

Build and test

Install dependencies.

$ npm install

Use the build package script to compile, test, lint, and build the documentation.

$ npm run build

Release

Releases are handled via the Atomist SDM. Just press the 'Approve' button in the Atomist dashboard or Slack.

---

Created by Atomist. Need Help? Join our Slack workspace.