@lanexio/parser-grammar-toml

This page documents @lanexio/parser-grammar-toml, the TOML grammar package supporting both TOML v1.0.0 and v1.1.0 with version selection.

• Version: Stable
• Module name: parser-grammar-toml
• Package: @lanexio/parser-grammar-toml
• Import path: @lanexio/parser-grammar-toml
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse TOML configuration files 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 TOML configuration files (v1.0.0 or v1.1.0) into a traversable AST.
• You need strict adherence to a specific TOML version.
• You need incremental reuse for repeated parsing.

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseTomlOptions
Outputs	LexTree (flat AST)
Side effects	None
Determinism	Yes
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-toml

   npm

   npm install @lanexio/parser-grammar-toml

   yarn

   yarn add @lanexio/parser-grammar-toml

2. Import the named export.

   import { parseToml } from '@lanexio/parser-grammar-toml';

Peer dependencies

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

Basic Usage

import { parseToml } from '@lanexio/parser-grammar-toml';

const encoder = new TextEncoder();
const bytes = encoder.encode('[server]\nhost = "localhost"\nport = 8080');

const tree = parseToml(bytes);

console.log(tree.nodeCount);

Strict TOML 1.0.0

import { parseToml10 } from '@lanexio/parser-grammar-toml';

const encoder = new TextEncoder();
const tree = parseToml10(encoder.encode('key = "value"'));

Explicit TOML 1.1.0

import { parseToml } from '@lanexio/parser-grammar-toml';

const encoder = new TextEncoder();
const tree = parseToml(encoder.encode('key = "value"'), { version: '1.1' });

Exports

Export	Type	Description
parseToml	(bytes: Uint8Array, options?: ParseTomlOptions) => LexTree	Parse TOML (defaults to v1.1.0). Never throws.
parseToml10	(bytes: Uint8Array) => LexTree	Parse TOML v1.0.0 (strict).
parseToml11	(bytes: Uint8Array) => LexTree	Parse TOML v1.1.0.
TomlKind	const object	Numeric kind IDs for all TOML node types.
TomlField	const object	Numeric field IDs for TOML value slots.
TOML_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
TOML_KIND_NAMES_BY_ID	readonly Record<number, string>	Kind-name lookup by numeric ID.
tomlGrammar	LanexioParserPureGrammar	Grammar descriptor for use with parser-pure.
tomlRegistration	GrammarRegistration	Registration for the unified grammar registry.
tomlReuseOracle	ReuseOracle	Incremental reuse oracle.
tomlToValue	(target: LexTree | LexNode, options?: ToValueOptions) => LexValueResult	Project a TOML tree or node subtree into a host value. Never throws.
tomlValueExtractor	LexValueExtractor	The TOML value extractor (registered under toml).

Value extraction

tomlToValue() reconstructs the TOML document object graph by path: dotted keys create nested objects, [table] headers create nested tables (with implicit tables on the way), [[array-of-tables]] headers append elements, and a nested [a.b] after [[a]] attaches to the most recent element. Basic and literal strings unescape, integers honor 0x/0o/0b and underscores (unsafe_integer past Number.MAX_SAFE_INTEGER), floats support inf/nan, booleans project, and date-times stay raw RFC 3339 text strings.

import { parseToml, tomlToValue } from '@lanexio/parser-grammar-toml';

const { value } = tomlToValue(parseToml(new TextEncoder().encode('[server]\nport = 8080\n')));
console.log(value); // { server: { port: 8080 } }

See the value-extraction reference for the full contract.

Options

ParseTomlOptions

Field	Type	Required	Default	Description
version	TomlVersion	No	'1.1'	TOML version dialect: '1.0' or '1.1'. Canonical key; wins over spec when both are given.
spec	TomlVersion	No	undefined	Documented alias for version (ADR 0048), matching the unified strict convention’s “spec” vocabulary. An explicit version wins; spec wins over the strict-mode default.
mode	ParseMode	No	'lenient'	Parse mode. Strict mode defaults the version to '1.0' when neither version nor spec is given.
strict	boolean	No	undefined	Convenience alias for mode: 'strict' (ADR 0044). true picks strict, false is the explicit lenient spelling; an explicit mode wins.

parseToml with no options defaults to TOML v1.1.0. Version precedence (highest to lowest): an explicit version wins over spec, and either wins over the strict-mode default. parseToml10 and parseToml11 are unaffected.

Conformance corpus

Strict mode is mechanically enforced against the official toml-test reference suite (ADR 0034): every .toml file under corpus/toml-test/invalid/ (511 files across its 16 category subdirectories) must carry hasError: true under strict: true with zero false accepts. See TOML conformance for the ledger.

Return shape

Property	Type	Description
root	LexNode	Root node of the document.
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes.

Exported types

Type	Purpose	Notes
ParseTomlOptions	Options for parseToml	{ version?, spec?, mode?, strict? }
TomlVersion	TOML version string	'1.0' | '1.1'
TomlKindType	Union of all TomlKind values	Type-safe kind reference
TomlFieldType	Union of all TomlField values	Type-safe field reference

Configuration and Extension

Version selection

parseToml defaults to TOML 1.1.0. Use parseToml10(bytes) for strict TOML 1.0.0. Use parseToml(bytes, { version: '1.0' }) or its spec alias parseToml(bytes, { spec: '1.0' }) for explicit version selection; an explicit version wins over spec, and either wins over the strict-mode default.

Accessibility

Accessibility requirements

• No direct accessibility surface. The TOML parser produces flat AST data structures.

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

• parseToml never throws on any byte sequence.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce LexError AST nodes	Implemented

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

Flat AST How the 16-byte node layout works.

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