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.

Spec

YAML 1.2.2 §§3, 6, 7, 8, 9 Cite: https://yaml.org/spec/1.2.2/

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. The flow-collection state machine also carries a structural forward-progress guard: even a hypothetical dispatch gap degrades to an Error node plus a one-byte advance rather than a hang.

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();
visit: while (true) {
  if (cursor.current.kind === YamlKind.Scalar) {
    console.log('scalar at', cursor.current.range);
  }
  if (cursor.gotoFirstChild()) continue;
  while (!cursor.gotoNextSibling()) {
    if (!cursor.gotoParent()) break visit;
  }
}

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	LanexioParserPureGrammar	Grammar descriptor — pass to createParser from @lanexio/parser.

Conformance

Metric	Value
yaml-test-suite valid	267 / 268 (99.6%)
Internal conformance	171 / 171
verify:no-throw	67 entry points
Fuzz soak (300s)	10.7M rounds / 0 crashes

Known limitations

Exactly one yaml-test-suite case is expected to fail — CT4Q (Spec Example 7.20), the explicit ? key indicator in flow context, which is currently consumed as a plain scalar. It is tracked per-case in the suite’s expectations file with a rationale code. Additionally, multiline flow scalars (block styles inside flow context, YAML 1.2.2 § 7.3) are not yet handled — only single-line plain scalars in flow context. Anchors (&), aliases (*), and tags (!) inside flow collections, including decorator-prefixed implicit mapping keys like [&a key: value], are fully handled.

Companion packages

• @lanexio/parser-core — shared buffer protocol, LexTree, LexNode, LexCursor.
• @lanexio/parser — unified entry point; pass this package’s grammar descriptor to createParser for a string-accepting, never-throwing parser handle.

Security and stability

User-controlled bytes

parseYaml processes untrusted byte sequences. YAML has unique security risks (anchors, aliases, tags). Lanexio Parser produces a LexTree; it does not resolve YAML tags into application-level types. You are responsible for validating the AST before dereferencing aliases or executing tag handlers.

Never-throw guarantee

All Lanexio Parser parse functions, including parseYaml, carry the Never-Throw Integrity guarantee. Malformed input produces YamlKind.Error AST nodes, never exceptions. See Stability Guarantees.