@lanexio/parser-grammar-json

This page documents @lanexio/parser-grammar-json, the JSON grammar package supporting strict JSON (RFC 8259), JSONC (comments and trailing commas), and JSON5 (ES5 relaxations).

• Version: Stable
• Module name: parser-grammar-json
• Package: @lanexio/parser-grammar-json
• Import path: @lanexio/parser-grammar-json
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse JSON, JSONC, and JSON5 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 strict JSON (RFC 8259) into a traversable AST.
• You need to parse JSONC (JSON with Comments) or JSON5 (ES5 syntax relaxations).
• You need structured AST with object members, arrays, and value nodes.

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseJsonDialectOptions
Outputs	LexTree (flat AST rooted at JsonKind.Document)
Side effects	None
Determinism	Yes (same bytes + same dialect 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-json

   npm

   npm install @lanexio/parser-grammar-json

   yarn

   yarn add @lanexio/parser-grammar-json

2. Import the named export.

   import { parseJson } from '@lanexio/parser-grammar-json';

Peer dependencies

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

Basic Usage

import { parseJson } from '@lanexio/parser-grammar-json';

const encoder = new TextEncoder();
const bytes = encoder.encode('{"key": [1, true, null]}');

const tree = parseJson(bytes);

console.log(tree.nodeCount);
console.log(tree.root.kind);   // JsonKind.Document

JSONC (with comments)

import { parseJsonc } from '@lanexio/parser-grammar-json';

const encoder = new TextEncoder();
const tree = parseJsonc(encoder.encode('/* comment */ { "key": 1 }'));

JSON5

import { parseJson5 } from '@lanexio/parser-grammar-json';

const encoder = new TextEncoder();
const tree = parseJson5(encoder.encode('{ key: "value", }'));  // unquoted keys, trailing comma

Exports

Export	Type	Description
parseJson	(bytes: Uint8Array) => LexTree	Parse strict JSON (RFC 8259). Convenience wrapper.
parseJsonc	(bytes: Uint8Array) => LexTree	Parse JSONC (JSON with Comments and trailing commas).
parseJson5	(bytes: Uint8Array) => LexTree	Parse JSON5 (ES5 relaxations).
parseWithDialect	(bytes: Uint8Array, options: ParseJsonDialectOptions) => LexTree	Parse with explicit dialect selection.
STRICT_JSON	JsonDialect	Strict JSON dialect (RFC 8259).
JSONC	JsonDialect	JSONC dialect (comments, trailing commas).
JSON5	JsonDialect	JSON5 dialect (unquoted keys, single quotes, etc.).
JsonKind	const object	Numeric kind IDs for all JSON node types.
JsonField	const object	Numeric field IDs for JSON value slots.
JSON_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
JSON_KIND_NAMES_BY_ID	readonly Record<number, string>	Kind-name lookup by numeric ID.
jsonGrammar	LanexioParserPureGrammar	Grammar descriptor for strict JSON.
jsoncGrammar	LanexioParserPureGrammar	Grammar descriptor for JSONC.
json5Grammar	LanexioParserPureGrammar	Grammar descriptor for JSON5.
jsonRegistration	GrammarRegistration	Registration for the unified grammar registry.
jsoncRegistration	GrammarRegistration	Registration for JSONC.
json5Registration	GrammarRegistration	Registration for JSON5.
jsonReuseOracle	ReuseOracle	Incremental reuse oracle for strict JSON.
jsoncReuseOracle	ReuseOracle	Incremental reuse oracle for JSONC.
json5ReuseOracle	ReuseOracle	Incremental reuse oracle for JSON5.
jsonToValue	(target: LexTree | LexNode, options?: ToValueOptions) => LexValueResult	Project a JSON/JSONC/JSON5 tree or node subtree into a host value. Never throws.
jsonValueExtractor	LexValueExtractor	The JSON value extractor (registered under json, jsonc, and json5).

Value extraction

jsonToValue() projects a JSON tree into the equivalent JavaScript value. Objects and arrays recurse; strings unescape per RFC 8259 section 7 plus the JSON5 escape set; numbers map directly with unsafe_integer past Number.MAX_SAFE_INTEGER and overflow for 1e400-style literals; JSON5 hex, Infinity, and NaN forms project to their numeric values; duplicate keys last-win with a duplicate_key diagnostic.

import { parseJson, jsonToValue } from '@lanexio/parser-grammar-json';

const { value } = jsonToValue(parseJson(new TextEncoder().encode('{"a": [1, true, null]}')));
console.log(value); // { a: [1, true, null] }

See the value-extraction reference for the full contract.

Options

ParseJsonDialectOptions

Field	Type	Required	Default	Description
dialect	JsonDialect	Yes	-	The JSON dialect to use (STRICT_JSON, JSONC, or JSON5).

Return shape

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

Exported types

Type	Purpose	Notes
ParseJsonDialectOptions	Options for parseWithDialect	{ dialect: JsonDialect }
JsonDialect	JSON dialect definition	Defines parsing rules
JsonKindType	Union of all JsonKind values	Type-safe kind reference
JsonFieldType	Union of all JsonField values	Type-safe field reference

Configuration and Extension

Dialect selection

Use parseWithDialect to select the parsing dialect explicitly. The convenience functions parseJson, parseJsonc, and parseJson5 are thin wrappers around parseWithDialect.

Accessibility

Accessibility requirements

• No direct accessibility surface. The JSON 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

• parseJson, parseJsonc, and parseJson5 never throw on any byte sequence.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce JsonKind.Error 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

Parsing JSON Guide: parse JSON with options and kind constants.

Flat AST How the 16-byte node layout works.

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