yaml-unist-parser is a JavaScript library designed to parse YAML strings and produce an Abstract Syntax Tree (AST) that is compatible with the unist specification. This makes it a suitable tool for applications that process YAML content using a unified syntax tree, such as linters, formatters, and compilers within the unist ecosystem. The current stable version is 3.1.0, with a recent major release (v3.0.0) indicating active development, though a precise release cadence isn't published. Key differentiators include its focus on generating a unist-compatible AST, enhanced node positioning within the AST, and improved comment attaching, which are crucial for tools like Prettier that rely on precise AST details for formatting.
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The library primarily uses ES modules. While CommonJS might work with transpilation, direct ESM import is preferred. `parse` is the main function for converting YAML strings to a unist AST.
import { parse } from 'yaml-unist-parser';
Introduced in v3.1.0, this custom error class allows for specific error handling when parsing invalid YAML. It's a named export.
import { YAMLSyntaxError } from 'yaml-unist-parser';
For TypeScript users, specific AST node types (like `Root`, `Scalar`, `Pair`, `YAMLMapping`, `YAMLSequence`) can be imported directly from the `src/types` path for stricter type checking and AST manipulation.
import type { Root, Scalar, Pair } from 'yaml-unist-parser/src/types';
This quickstart demonstrates how to parse a complex YAML string into a unist AST, handling potential errors.
import { parse } from 'yaml-unist-parser';
// Example YAML content including various structures and comments
const yamlContent = `
# This is a simple YAML document
metadata:
name: my-app
version: 1.0.0
tags: [backend, service]
environment: production
# A list of features
features:
- login
- dashboard
- reports: { enabled: true, level: 'admin' }
server:
port: 8080
host: 0.0.0.0
`;
try {
// Parse the YAML content into a unist-compatible AST
const ast = parse(yamlContent, { uniqueKeys: true });
console.log('Successfully parsed YAML. Root node type:', ast.type);
console.log('AST Structure (first few nodes):', JSON.stringify(ast, null, 2).substring(0, 500) + '...');
// You can traverse the AST using unist-utils or other AST manipulation libraries
// For example, to find all scalar nodes:
// visit(ast, 'scalar', (node) => { console.log('Scalar value:', node.value); });
} catch (error) {
if (error instanceof Error) {
console.error('YAML Parsing Error:', error.message);
} else {
console.error('An unexpected error occurred during parsing.');
}
}
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.