A small, fast, and correct TOML parser and serializer. smol-toml is fully spec-compliant with TOML v1.1.0, passing
all1 tests from the official toml-test suite.
[!IMPORTANT]
By default, the behaviour regarding integers doesn't preserve type information, nor does it allow deserializing
integers larger than 53 bits. See Integers.
Reject potentially dangerous keys such as __proto__ or constructor. See .
Key safety
Internally, smol-toml is protected against prototype pollution and will correctly assign a plain property named e.g.
__proto__ on the object, similar to what JavaScript-native JSON.parse does.
However, careless use of the object returned by the parser in your application code may lead to prototype pollution.
This is for instance the case in this example taken from Fastify's secure-json-parse helper which exists to address
this caveat.
import { parse } from 'smol-toml'const a = parse('__proto__.b = 5')console.log(a.b) // ~> undefinedconst b = Object.assign({}, a)console.log(b.b) // ~> 5
Similarly to secure-json-parse, the library offers 3 modes to deal with these keys:
keep (default): preserve potentially unsafe properties and return the object as-is.
drop: silently drop potentially unsafe properties, returning the object as if the properties were not there.
throw: reject documents with potentially unsafe properties and throw a TomlError.
Stringify options
Option
Type
Default
Description
Introduced in
numbersAsFloat
boolean
false
Always render plain numbers as floating point values. See Type preservation.
When parsing, both integers and floats are parsed as plain JavaScript numbers by default, which are double-precision
floating point numbers. That means that the library does not preserve type information between e.g. 1.0 and 1, and
that it is not able to parse integers beyond 53 bits.
While this is sufficient for the vast majority of use-cases, if support of larger integers is needed, it is possible
to enable BigInt support.
When serializing, numbers without a decimal part are serialized as integers (except if they're outside of the safe
range; i.e. they cannot be represented as a signed 53-bit integer). This is generally a good enough heuristic for most
usages, but it is possible to leverage BigInts for full type preservation.
Enabling BigInt
To parse integers beyond 53 bits, it's possible to tell the parser to return all integers as BigInt. This will
therefore preserve the type information at the cost of using a more expensive container (approx. 5% slowdown).
If you want to only use BigInt for numbers that cannot safely be represented as plain JavaScript numbers, you can pass
"asNeeded" instead.
Type preservation
To get end-to-end type preservation, you can tell the serializer to always treat numbers as floating point numbers.
Then, only BigInts will be serialized as integers and numbers without a decimal part will still be serialized as float.
smol-toml can emit time-related types in 2 ways: the modern Temporal API, or the legacy (but currently default)
Date object, using a custom TomlDate object.
[!NOTE]
While TomlDate is 2-3x faster than Temporal in microbenchmarks, the performance difference in practice on parse
time is insignificant (or even slower2) for smol-toml. See the benchmarks.
TomlDate is limited to millisecond precision and has a more lax behaviour. It gracefully accepts certain invalid
inputs, such as "the 30th of February", converting it to the 2nd (or 1st) of March. The Temporal implementation is
stricter and properly rejects these invalid dates.
The next major version of the library will use Temporal by default.
The different TOML types and Temporal types are mapped as described below.
There is an ongoing feature request and an active proposal. Note that the current draft does not allow multi-part values (e.g. 1min 20sec), making it likely that Duration will not always be convertible to a TOML value.
IANA timezones and calendars
ZonedDateTime objects may have 2 different types of timezone identifier attached to them: either an offset such as
+02:00, or an IANA Time Zone Identifier such as Europe/Paris. The latter carries
information about the currently observed offset in that region, daylight savings policies, and other timekeeping quirks
such as leap seconds. It is a much more precise information than the offset alone. Additionally, ZonedDateTime allows
keeping track of a specific calendar to use, such as for example the Japanese imperial era.
TOML can only represent offsets, not precise timezones nor a calendar3. As such, when serializing a
ZonedDateTime, this information is lost and only the offset is preserved; effectively treating the ZonedDateTime
as if it were an Instant. To prevent silent loss of timezone information, the strictTemporal option can be
enabled to throw an error instead. Timezones that aren't simple offsets, or objects using a calendar that isn't
the default ISO 8601 will be rejected.
TomlDate object
[!NOTE]
This object is not formally deprecated yet, but it is a legacy API. It will be deprecated in v2 and removed in v3.
The object directly inherits the JavaScript Date object, with a handful of extra APIs for distinguishing between
different types of time components.
TomlDate preserves the offset, whereas the native Date object usually normalises everything to UTC.
[!CAUTION]
Unlike the Temporal API which supports nanosecond precision, Date is limited to millisecond precision.
import { TomlDate } from 'smol-toml'// Offset Date Timeconst date = new TomlDate('1979-05-27T07:32:00.000-08:00')console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, falseconsole.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000-08:00// Local Date Timeconst date = new TomlDate('1979-05-27T07:32:00.000')console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, trueconsole.log(date.toISOString
You can also wrap a native Date object and specify using different methods depending on the type of date you wish
to represent:
By default, certain invalid datetimes (e.g. 2020-02-30) are gracefully accepted. Due to
JavaScript's lax handling of Unicode, some invalid byte sequences are accepted. Requires using the integersAsBigInt
option for full type preservation. Use the run-toml-test.bash script to run the tests. ↩
The Temporal implementation dispatches more instructions to the CPU; however, it is much
more friendly to the branch predictor. At the microarchitecture level, this allows the CPU
to reach a higher number of instructions per clock, which results in a net positive
performance impact. The CPU has to do more, but it can do it faster. ↩