If you haven't heard of TOML, well you're just missing out. Go check it out now. Back? Good.
TOML Spec Support
toml-node supports TOML v1.1.0, scoring 702/708 (99.2%) on the official toml-test compliance suite:
Pass
Total
Rate
Valid tests
218
218
100%
Invalid tests
484
490
98.8%
Total
702
708
99.2%
The 6 remaining failures are inherent JavaScript platform limitations shared by all JS TOML parsers: they cover UTF-8 encoding validation, which Node.js handles at the engine level before the parser sees the data.
Note that integers beyond Number.MAX_SAFE_INTEGER require the bigint option to parse losslessly; without it they throw a parse error rather than silently losing precision.
Requires Node.js 20 or later. Zero runtime dependencies.
Usage
const toml = require('toml');const data = toml.parse(someTomlString);
toml.parse throws an exception on parse errors with line and column properties:
try { toml.parse(someBadToml);} catch (e) { console.error(`Parsing error on line ${e.line}, column ${e.column}: ${e.message}`);}
Nesting Depth Limit
To guard against stack overflow on maliciously deep input, arrays and inline tables may nest at most 500 levels deep by default; input past the limit throws a normal parse error. Adjust the limit with the maxDepth option:
toml.parse(someTomlString, { maxDepth: 100 });
Integer Range and BigInt
TOML requires parsers to handle the full range of 64-bit signed integers, but JavaScript's number type can only represent integers up to Number.MAX_SAFE_INTEGER (2⁵³ − 1) losslessly. By default, toml.parse returns integers as number and throws a parse error when a value falls outside the safe range, rather than silently returning a rounded value:
toml.parse('id = 771752188537605140');// Error: Integer 771752188537605140 cannot be represented losslessly// as a JavaScript number. Use the `bigint` option to parse integers// as BigInt values.
Pass bigint: true to instead parse all integers as BigInt, preserving the full 64-bit range:
Integers outside the 64-bit signed range always throw, in either mode, as required by the spec. Floats are unaffected by all of this: TOML floats are IEEE 754 binary64 values, which is exactly what a JavaScript number is, so every TOML float is represented as faithfully as the spec intends.
Date/Time Values
Offset date-times are returned as JavaScript Date objects. Local date-times, local dates, and local times are returned as strings since they have no timezone information and can't be losslessly represented as Date:
Offset date-times become Temporal.ZonedDateTime values whose time zone is
the original UTC offset (Z maps to the UTC time zone), so the offset
written in the TOML document is preserved — unlike the default Date
representation, which loses it. Fractional seconds beyond nanosecond
precision are truncated, as permitted by the TOML spec.
useTemporal requires a runtime with the Temporal global. On runtimes
that don't provide it yet, pass an implementation such as
@js-temporal/polyfill
via the temporal option: