@lanexio/parser-grammar-yaml

This page documents @lanexio/parser-grammar-yaml, the YAML grammar package implementing an iterative YAML 1.2.2 parser with explicit indentation and container stack.

• Version: Stable
• Module name: parser-grammar-yaml
• Package: @lanexio/parser-grammar-yaml
• Import path: @lanexio/parser-grammar-yaml
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse YAML 1.2.2 documents into a flat AST.

Layer contract

Layer 2 dependency rules

This package depends only on Layer 1 core packages. It does not import from query, bridge, devtools, or entry packages. Grammar packs never depend on other grammar packs.

When to use this module

• You need to parse YAML 1.2.2 documents (block and flow) into a traversable AST.
• You need structured flow collections (flow mappings and sequences produce structured subtrees).
• You need multi-document stream support.

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseYamlOptions
Outputs	LexTree (flat AST rooted at YamlKind.Stream)
Side effects	None
Determinism	Yes (same bytes + same options produce identical tree)
External dependencies	@lanexio/parser-core
Never-throw guarantee	Yes
Security surface	None (parse only, no output generation)

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-yaml

   npm

   npm install @lanexio/parser-grammar-yaml

   yarn

   yarn add @lanexio/parser-grammar-yaml

2. Import the named export.

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

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

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

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

const tree = parseYaml(bytes);

console.log(tree.nodeCount);
console.log(tree.root.kind);   // YamlKind.Stream

Flow collections

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)

Exports

Export	Type	Description
parseYaml	(bytes: Uint8Array, options?: ParseYamlOptions) => LexTree	Parse YAML 1.2.2. Never throws.
YamlKind	const object	Numeric kind IDs for all YAML node types.
YAML_KIND_NAMES_BY_ID	ReadonlyMap<number, string>	Kind-name lookup by numeric ID.
yamlGrammar	LanexioParserPureGrammar	Grammar descriptor for use with parser-pure.
yamlRegistration	GrammarRegistration	Registration for the unified grammar registry.
yamlToValue	(target: LexTree | LexNode, options?: ToValueOptions) => LexValueResult	Project a YAML tree or node subtree into a host value (core-schema scalars, anchors/aliases, merge keys, multi-doc streams). Never throws.
yamlValueExtractor	LexValueExtractor	The YAML value extractor (registered under yaml and yml).

Value extraction

yamlToValue() projects a YAML stream into an object, array, or scalar. Plain scalars resolve by the YAML 1.2.2 core schema (null, bool, decimal/octal/hex int, float, .inf/.nan, else string); quoted and block scalars unquote. Anchors and aliases resolve with cycle detection (circular_alias), unknown anchors report missing_anchor, << merge keys copy anchored mappings with explicit keys winning, and multi-document streams project to an array of values.

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

const { value } = yamlToValue(parseYaml(new TextEncoder().encode('name: Tom\nage: 30\n')));
console.log(value); // { name: 'Tom', age: 30 }

See the value-extraction reference for the full contract.

Options

ParseYamlOptions

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

Return shape

Property	Type	Description
root	LexNode	Root node (YamlKind.Stream).
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes.

Exported types

Type	Purpose	Notes
ParseYamlOptions	Options for parseYaml	{ readonly strictMode?: boolean }
YamlKindValue	Union of all YamlKind values	Type-safe kind reference

Configuration and Extension

No configuration extension points. The parser is fully self-contained. ParseYamlOptions is reserved for future extension.

Accessibility

Accessibility requirements

• No direct accessibility surface. The YAML parser produces flat AST data structures. Consuming code is responsible for rendering output with appropriate semantics.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (data format)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• parseYaml never throws on any byte sequence.
• YAML has unique security risks (anchors, aliases, tags). Lanexio Parser produces a LexTree and does not resolve YAML tags into application-level types.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce YamlKind.Error AST nodes	Implemented
YAML anchor/alias injection	Parser produces AST but does not resolve anchors or execute tag handlers	Documented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser	Consumes	6	Unified entry point

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

Parsing YAML Guide: parse YAML documents with options and kind constants.

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.