YAML Parser and Stringifier

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., `"type": "module"` in `package.json` or `.mjs` files).
  fix Update imports to use ESM syntax: `import { parse, stringify } from 'yaml'`.

• Property 'parse' does not exist on type 'typeof import("yaml")' or 'yaml.parse is not a function'

  cause Incorrectly importing named exports, often by trying to use a default import or a CommonJS-style property access with ESM.
  fix Ensure you are using named imports: `import { parse, stringify } from 'yaml'`.

• Error: The current Node.js version is <some-version> which does not satisfy the requirement >= 14.6.

  cause Running the library on an unsupported Node.js version.
  fix Update your Node.js environment to a version `>= 14.6` or higher to meet the package's engine requirements.

Warnings

• breaking Version 3.0.0-0 is a prerelease and highly unstable. It's published under the `next` dist-tag and using a non-exact range like `^3.0.0-0` can cause unpredictable breaking changes when new prereleases are published.
  Fix: For v3 prereleases, always install with `npm install --save-exact yaml@next` to pin to a specific unstable version, or avoid using it in production until the final release.
• breaking Node.js engine requirement shifted in `v2.7.0` to `>= 14.18` from `>= 14.6`, then reverted to `>= 14.6` in `v2.8.0`. Ensure your Node.js environment meets the specific requirement for the minor version of `yaml` you are using to avoid runtime errors.
  Fix: Check the `engines.node` field in `package.json` for your specific `yaml` version or update Node.js to a version `>= 14.18` for broader compatibility within the v2 range.
• gotcha The minimum supported TypeScript version for the included typings is 3.9. Using the library with earlier TypeScript versions may result in type errors.
  Fix: Update your TypeScript compiler to version 3.9 or newer, or set `skipLibCheck: true` in your `tsconfig.json` to bypass type checking for declaration files (use with caution).
• gotcha While documented endpoints are semver-major, undocumented library internals may change between minor versions. Relying on internal structures not explicitly part of the public API can lead to unexpected breakages.
  Fix: Adhere strictly to the documented API endpoints and classes. Avoid directly accessing private properties or methods which may be subject to change without a major version bump.

Install

• npm install yaml npm
• yarn add yaml yarn
• pnpm add yaml pnpm

Imports

• parse
  wrong:

  const parse = require('yaml').parse

  correct:

  import { parse } from 'yaml'

  Use named import for parsing YAML strings into JavaScript objects or YAML Documents.
• stringify
  wrong:

  const stringify = require('yaml').stringify

  correct:

  import { stringify } from 'yaml'

  Use named import for converting JavaScript objects or YAML Documents back into YAML strings.
• Document
  wrong:

  const Document = require('yaml').Document

  correct:

  import { Document } from 'yaml'

  The `Document` class represents a single YAML document within a stream, allowing for advanced AST manipulation and meta-data access.
• parseDocument
  wrong:

  const parseDocument = require('yaml').parseDocument

  correct:

  import { parseDocument } from 'yaml'

  For parsing a single YAML document and returning a `Document` instance, which provides richer API access than `parse`.
• YAMLMap, YAMLSeq, Scalar
  wrong:

  const { YAMLMap } = require('yaml')

  correct:

  import { YAMLMap, YAMLSeq, Scalar } from 'yaml'

  These classes represent core YAML AST nodes (mappings, sequences, scalars) and are used for low-level document manipulation.

Quickstart

This quickstart demonstrates parsing multi-document YAML strings, modifying values and adding new items using the Document API, and then stringifying the result. It also shows parsing a single document with `parseDocument` and direct AST manipulation.

import { parse, stringify, Document, YAMLMap, Scalar } from 'yaml';

const yamlString = `
# My shopping list
- item: Apples
  quantity: 2
  notes: Green ones

---
# My second shopping list
- item: Milk
  quantity: 1
  unit: gallon
`;

// Parse a multi-document YAML string, keeping CST nodes for better comment preservation
const documents = parse(yamlString, { keepCstNodes: true }) as Document[];

// Access and modify the first document
const firstDoc = documents[0];
if (firstDoc && firstDoc.contents instanceof Array) { // Assuming a sequence at root
  const appleItem = firstDoc.contents[0];
  if (appleItem instanceof YAMLMap) {
    appleItem.set('quantity', 3); // Change quantity
    appleItem.set('notes', 'Honeycrisp preferred'); // Update notes
  }
}

// Access and modify the second document
const secondDoc = documents[1];
if (secondDoc && secondDoc.contents instanceof Array) {
  secondDoc.contents.push(new YAMLMap());
  const newItem = secondDoc.contents[secondDoc.contents.length - 1] as YAMLMap;
  newItem.set('item', 'Bread');
  newItem.set('quantity', 1);
  newItem.set('type', 'whole wheat');
}

// Stringify the modified documents back to YAML
const modifiedYaml = documents.map(doc => stringify(doc)).join('\n---\n');

console.log('Original YAML:\n', yamlString);
console.log('\nModified YAML:\n', modifiedYaml);

// Example of parsing a single document with parseDocument and accessing AST
const singleDocString = `
user: John Doe
roles:
  - admin
  - editor
active: true
`;

const doc = parseDocument(singleDocString);

if (doc.contents instanceof YAMLMap) {
  const userNode = doc.contents.get('user');
  if (userNode instanceof Scalar) {
    console.log(`\nUser from single document: ${userNode.value}`);
  }
  doc.contents.set('status', 'online');
}

console.log('\nModified Single Document with new status:\n', doc.toString());