yawn-yaml

library3.0.0jsnpmunverified

YAWN YAML is a JavaScript/TypeScript library designed to parse and manipulate YAML documents while meticulously preserving comments, original formatting, and scalar styles. The current stable version is 3.0.0, which represents a complete rewrite, moving from a custom parsing engine to leveraging the modern `yaml` package's Concrete Syntax Tree (CST) model. This fundamental shift significantly enhances robustness in comment preservation and scalar style retention, making it ideal for configuration file management or scenarios where semantic and stylistic integrity of YAML is paramount. Key differentiators include its ability to treat comments as first-class citizens in the AST, ensuring they are not lost during updates, and a substantially reduced bundle size from approximately 300KB to 32KB since version 3.0.0. While no explicit release cadence is stated, major version increments, like v3, indicate significant API changes and architectural overhauls. It offers new API methods for fine-grained control over comments, such as `getCommentBefore()` and `setCommentAfter()`.

serialization

npm install yawn-yaml

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · YAWN-YAML

yawn-yaml

serializationjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YAWN

✓ import YAWN from 'yawn-yaml';

✗ const YAWN = require('yawn-yaml');

Since v3.0.0, yawn-yaml is primarily an ESM module. CommonJS `require` may lead to incorrect imports or compatibility issues, especially with TypeScript or bundlers.

YAWN (type)

✓ import type YAWN from 'yawn-yaml';

For type-only imports in TypeScript, using `import type` is recommended to prevent bundling the value and ensuring tree-shaking effectiveness.

YAWN (dynamic import)

✓ const YAWN = await import('yawn-yaml');

✗ const YAWN = require('yawn-yaml').default;

For dynamic imports in CommonJS environments that need to use the ESM module, `await import()` is the correct pattern. Access the default export directly from the resolved module.

Demonstrates initializing YAWN with a YAML string, accessing and modifying its JSON representation, and then retrieving the updated YAML with original comments and styling preserved.

import YAWN from 'yawn-yaml'; let str = ` # My important configuration port: 3000 # Server port host: localhost # Additional settings enabled: true `; let yawn = new YAWN(str); // Access the parsed JSON representation console.log('Original JSON:', yawn.json); // Update a value via the JSON property yawn.json = { ...yawn.json, port: 8080 }; // Add a new property const updatedJson = yawn.json; updatedJson.database = { type: 'mongodb', uri: 'mongodb://localhost:27017/my_app' // Database connection URI }; yawn.json = updatedJson; // Log the YAML with comments and styling preserved console.log('Updated YAML:\n', yawn.yaml);

Debug

Known issues

breakingVersion 3.0.0 is a complete rewrite, changing the internal architecture to use the `yaml` package's CST model. This introduces significant breaking changes to the API and internal behavior compared to v2.x.

fix

Review the v3.0.0 documentation or migration guides if upgrading from an earlier major version. Existing code will likely require refactoring to adapt to the new API surface and methods.

affects: >=3.0.0

gotchaWhen modifying the `json` property, ensure you assign a *new* object or a deeply cloned one if you modify nested structures. Direct mutation of `yawn.json.someProp = value` will not trigger updates to the underlying YAML structure; you must reassign `yawn.json = { ...yawn.json, someProp: value }`.

fix

Always reassign the `json` property (`yawn.json = newJsonValue;`) after making modifications to ensure changes are propagated and the YAML string is updated correctly.

affects: >=3.0.0

gotchaWhile comments are robustly preserved, inserting new comments or repositioning existing ones may require using the new `getCommentBefore()` and `setCommentAfter()` API methods. Direct string manipulation of the YAML output is generally discouraged.

fix

Utilize the dedicated comment manipulation methods provided by the YAWN API for precise control over comment placement and content, rather than attempting to inject comments by modifying the `json` property or the raw YAML string.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: YAWN is not a constructor

Attempting to use `require('yawn-yaml')` in a CommonJS context when the package is primarily ESM, resulting in the default export not being directly available.

fix

For CommonJS, if ESM is unavoidable, use dynamic import: `const YAWN = await import('yawn-yaml'); const yawnInstance = new YAWN.default(yamlString);`. For ESM, ensure `import YAWN from 'yawn-yaml';` is used.

Property 'someOldMethod' does not exist on type 'YAWN'.

Attempting to call a method that existed in `yawn-yaml` v2.x but was removed or renamed in the v3.0.0 rewrite.

fix

Consult the `yawn-yaml` v3.0.0 documentation for the updated API. Many methods were refactored or replaced due to the internal architecture change.

YAMLException: bad indentation of a mapping entry

The input YAML string is syntactically invalid, usually due to incorrect spacing, missing colons, or other formatting errors.

fix

Validate the YAML string against a linter or an online YAML validator. Ensure consistent indentation (spaces, not tabs) and correct YAML syntax.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

yamlrequiredCore parsing engine, v3 uses its Concrete Syntax Tree (CST) model internally.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mohsen1/yawn-yaml ↗

packagehttps://www.npmjs.com/package/yawn-yaml ↗

homepagehttps://snyk.io/blog/yawn-yaml-v3/ ↗