#typescript/src/toml

#typescript/src/toml

TOML parsing and comment-preserving single-key editing for the config subsystem, gating input on TOML 1.0 and splicing edits byte-exactly at one key.

Parsing strategy (the TOML 1.0 acceptance gate): smol-toml is the value parser but accepts TOML 1.1, while the siblings' parsers (go-toml-edit, Python tomllib) are TOML-1.0-native. Every parse therefore first validates the raw text with toml-eslint-parser in "1.0" mode -- a full spec-compliant TOML 1.0 parser -- which reliably rejects the six 1.1-only constructs pinned in docs/history/_ts-port-spec.md (backslash-e / backslash-x escapes in basic strings, newlines and trailing commas in inline tables, times and datetimes without seconds). When the 1.0 parse fails but a 1.1 parse succeeds, the failure is classified into the specific gate error; otherwise the document is genuinely malformed and the 1.0 parser's own message (with position) is reported. Only after the gate passes does smol-toml produce the value tree (with { integersAsBigInt: true }, so TOML integers are bigint end-to-end).

Editing strategy (the single-key splicer): config set must preserve comments, key order, whitespace, and line endings byte-exactly for everything except the target key -- the tomlkit behavior Python relies on, and the go-toml-edit round-trip behavior Go relies on. The splicer locates the target value's byte range via the toml-eslint-parser AST and performs string surgery: replace the value token in place, append new keys at the end of the owning table's key block, or create a new [table] header at the end of the document (both siblings append missing tables at document end). Every splice is verified by re-parsing both versions and asserting that only the target key changed -- a mismatch is a hard internal error.

#TomlLoadFailure

export class TomlLoadFailure extends Error

A TOML document failed to parse (or failed the 1.0 gate). line/column are 1-based when known; config.ts formats them into the sibling-shaped "config file : (line X, column Y)" surface.

#parseTomlConfig

export function parseTomlConfig(text: string): Record<string, unknown>

Parses a TOML config document: TOML 1.0 gate first, then smol-toml with integersAsBigInt (ints are bigint, floats are number). Throws TomlLoadFailure with 1-based position info on any failure.

#renderTomlValue

export function renderTomlValue(value: unknown): string

Renders a value as a TOML value token, mirroring Python's _toml_format_scalar: bools lowercase, ints (bigint) decimal, floats in SCF, strings basic-quoted. Beyond Python's backslash/quote escaping, control characters are escaped too (Python would emit invalid TOML for them; the splicer's re-parse verification demands valid output). Arrays render as "[a, b]"; Maps and plain objects render as inline tables with sorted keys (the TS dict display rule; semantically identical to tomlkit's section tables, and splice-verified).

#renderTomlKeyPart

export function renderTomlKeyPart(part: string): string

Renders one key segment: bare when possible, basic-quoted otherwise.

#deepEqualTrees

export function deepEqualTrees(a: unknown, b: unknown): boolean

Deep equality over config value trees: bigint/number/string/boolean scalars, arrays, Maps, and plain objects (Maps and objects compare interchangeably by entries). Non-plain objects (e.g. TomlDate) compare by String() form.

#tomlSetKey

export function tomlSetKey(

Sets dottedKey = value in the TOML document text, preserving all other bytes exactly. Resolution order: replace an existing value token in place (including inside inline tables); append key = value at the end of the owning table's key block; append a dotted key when the parent exists only implicitly via dotted keys; otherwise create a new [parent] header at the end of the document (both siblings append missing tables at document end). The result is verified by re-parsing both versions.

#tomlDeleteKey

export function tomlDeleteKey(text: string, dottedKey: string): string

Deletes dottedKey from the TOML document text, removing the key's whole line (with any trailing comment, matching tomlkit) and pruning a [table] header left with no keys. Entries inside inline tables are removed with their separating comma; an inline table left empty is deleted with its own key. Throws when the key is not present (callers check the parsed data first). The result is verified by re-parsing both versions.