Parsing YAML

Package: @lanexio/parser-grammar-yaml Stable Layer: 2 (Grammar). Depends only on @lanexio/parser-core. Runtime: Universal (browser, server, edge worker).

Overview

parseYaml implements an iterative YAML 1.2.2 parser with an explicit indentation/container stack. It handles block mappings and sequences, flow collections ({…} and […]), scalars, anchors, aliases, tags, comments, directives, and multi-document streams.

Input is always a Uint8Array. Output is always a LexTree. Malformed input produces YamlKind.Error nodes — parseYaml never throws.

Parse YAML produces structured trees: flow sequences emit FlowSequence → SequenceItem and flow mappings emit FlowMapping → MappingPair → (Key, Value). Block structures mirror the YAML indentation hierarchy.

Import

import {
  parseYaml,
  YamlKind,
  YAML_KIND_NAMES_BY_ID,
  yamlGrammar,
  type ParseYamlOptions,
  type YamlKindValue,
} from '@lanexio/parser-grammar-yaml';

Parse a document

import { parseYaml } from '@lanexio/parser-grammar-yaml';

const encoder = new TextEncoder();
const tree = parseYaml(encoder.encode('key: value\nlist:\n  - one\n  - two'));

console.log(tree.nodeCount);   // total nodes
console.log(tree.root.kind);   // Stream root kind id (0x0a00)

parseYaml accepts a Uint8Array. Always use TextEncoder when converting a string to bytes.

Flow collections

Flow mappings and sequences produce structured subtrees, not flat leaf nodes:

import { parseYaml, YamlKind } from '@lanexio/parser-grammar-yaml';

const encoder = new TextEncoder();
const tree = parseYaml(encoder.encode('{ x: 1, y: [2, 3] }'));

// Walk: Stream → Document → FlowMapping → MappingPair → (Key, Value)
//                                            MappingPair → Key("y"), Value(FlowSequence → ...)

Multi-document streams

const tree = parseYaml(encoder.encode('---\nfirst: doc\n---\nsecond: doc\n...'));
// Stream contains two Document nodes, each with its own BlockMapping root

ParseYamlOptions

Field	Type	Default	Description
`strictMode`	`boolean`	`undefined`	Reserved for future use. Currently has no effect.

Detect LexError nodes

import { parseYaml, YamlKind } from '@lanexio/parser-grammar-yaml';

const encoder = new TextEncoder();
const tree = parseYaml(encoder.encode('key:\n\t-inconsistent indent'));

for (const node of tree.root.children()) {
  if (node.kind === YamlKind.Error) {
    console.log('parse error at', node.range);
  }
}

parseYaml never throws. Malformed input produces YamlKind.Error nodes. The parser always recovers and continues.

YamlKind constants

import { YamlKind } from '@lanexio/parser-grammar-yaml';

// YamlKind is a const object. Use 'as const' pattern, never enum.
const kind: YamlKindValue = YamlKind.BlockMapping;

// Example: walk only scalar nodes
const cursor = tree.cursor();
do {
  if (cursor.current.kind === YamlKind.Scalar) {
    console.log('scalar at', cursor.current.range);
  }
} while (cursor.gotoFirstChild() || cursor.gotoNextSibling() || cursor.gotoParent());

YamlKind values are stable across versions. Never use raw numbers — always reference YamlKind.<name>.

Full exports

Export	Type	Description
`parseYaml`	`(bytes: Uint8Array, options?: ParseYamlOptions) => LexTree`	Parse YAML 1.2.2. Never throws.
`ParseYamlOptions`	`{ readonly strictMode?: boolean }`	Options for `parseYaml`.
`YamlKind`	`const` object	Numeric kind IDs for all YAML node types (0x0A00 block).
`YamlKindValue`	`type` union	Union of all `YamlKind` values.
`YAML_KIND_NAMES_BY_ID`	`ReadonlyMap<number, string>`	Kind-name lookup by numeric ID.
`yamlGrammar`	`Lanexio ParserPureGrammar`	Grammar descriptor for `parser-pure`.

Conformance

Metric	Value
yaml-test-suite structural	266 / 266 (100%)
yaml-test-suite error	82 / 82 (100%)
Internal conformance	194 / 194
verify:no-throw	67 entry points
Fuzz soak (300s)	10.7M rounds / 0 crashes
Per-tag categories	35 / 35 (100%)

Companion packages

@lanexio/parser-core — shared buffer protocol, LexTree, LexNode, LexCursor.
@lanexio/parser-pure — pure-TypeScript multi-grammar bridge; pass yamlGrammar to createParser.
@lanexio/parser — unified entry point; imports parseYaml as an optional peer dependency.