Registry / serialization / yaml-unist-parser

yaml-unist-parser

library3.1.0jsnpmunverified

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.

serialization

npm install yaml-unist-parser

github ↗package ↗

INSTALL

IMPORT

SIG · YAML-UNIST-PARSER

yaml-unist-parser

serializationjavascriptv3.1.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.

parse

✓ import { parse } from 'yaml-unist-parser';

✗ const parse = require('yaml-unist-parser').parse;

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.

YAMLSyntaxError

✓ import { YAMLSyntaxError } from 'yaml-unist-parser';

✗ import { SyntaxError as YAMLSyntaxError } 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.

Node types

✓ import type { Root, Scalar, Pair } from 'yaml-unist-parser/src/types';

✗ import { Root, Scalar, Pair } 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.

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.'); } }

Debug

Known issues

breakingThe `allowDuplicateKeysInMap` option was removed in v3.0.0. Its functionality has been replaced by the `uniqueKeys` option with inverted logic.

fix

Replace `allowDuplicateKeysInMap: true` with `uniqueKeys: false` (to allow duplicates) or simply remove the option if you desire the default unique key behavior (`uniqueKeys: true`).

affects: >=3.0.0

breakingVersion 3.0.0 updated its internal `yaml` dependency to v2. While `yaml-unist-parser` aims to abstract this, it's possible that subtle changes in parsing behavior or edge case handling from the underlying `yaml` library could manifest.

fix

Thoroughly test existing YAML parsing logic when upgrading to v3.0.0 to ensure no unexpected changes in AST output or error conditions, particularly for complex or unconventional YAML structures.

affects: >=3.0.0

gotchaBy default, `yaml-unist-parser` enforces unique keys in maps, meaning duplicate keys will throw a `YAMLSyntaxError`. This strict behavior might not be desired in all use cases.

fix

To allow duplicate keys in maps, pass `{ uniqueKeys: false }` as an option to the `parse` function. Example: `parse(yamlString, { uniqueKeys: false });`

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught SyntaxError [YAMLSyntaxError]: Map keys must be unique

Attempting to parse YAML content that contains duplicate keys within a map, while the `uniqueKeys` option is set to its default value of `true`.

fix

Either ensure all map keys in your YAML are unique, or allow duplicate keys by calling `parse(yamlString, { uniqueKeys: false });`

TypeError: parse is not a function

Incorrect import method used for `parse` function, often seen when trying to use CommonJS `require` syntax or when a default import is attempted for a named export.

fix

Use a named ESM import: `import { parse } from 'yaml-unist-parser';`

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

yamlrequiredCore YAML parsing logic. Updated to v2 in `yaml-unist-parser` v3.0.0.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Bingbot

Resources

githubhttps://github.com/prettier/yaml-unist-parser ↗

packagehttps://www.npmjs.com/package/yaml-unist-parser ↗