A small, fast, and correct TOML parser and serializer. smol-toml is fully(ish) spec-compliant with TOML v1.1.0.
Why yet another TOML parser? Well, the ecosystem of TOML parsers in JavaScript is quite underwhelming, most likely due to a lack of interest. With most parsers being outdated, unmaintained, non-compliant, or a combination of these, a new parser didn't feel too out of place.
[insert xkcd 927]
Nowadays, smol-toml is the most downloaded TOML parser on npm thanks to its quality. From frameworks to tooling, it has been battle-tested and is actively used in production systems.
smol-toml passes most of the tests from the toml-test suite; use the
run-toml-test.bash script to run the tests. Due to the nature of JavaScript and the limits of the language,
it doesn't pass certain tests, namely:
- Invalid UTF-8 strings (and comments) are not rejected
- Certain invalid dates are not rejected
- For instance,
2023-02-30would be accepted and parsed as2023-03-02. While additional checks could be performed to reject these, they've not been added for performance reasons.
- For instance,
Please also note that by default, the behavior regarding integers doesn't preserve type information, nor does it allow deserializing integers larger than 53 bits. See Integers.
You can see a list of all tests smol-toml fails (and the reason why it fails these) in the list of skipped tests in
run-toml-test.bash. Note that some failures are not specification violations per-se. For instance, the TOML spec
does not require 64-bit integer range support or sub-millisecond time precision, but are included in the toml-test
suite. See toml-lang/toml-test#154 and toml-lang/toml-test#155
[pnpm | yarn | npm] i smol-toml
import { parse, stringify } from 'smol-toml'
const doc = '...'
const parsed = parse(doc)
console.log(parsed)
const toml = stringify(parsed)
console.log(toml)Alternatively, if you prefer something similar to the JSON global, you can import the library as follows
import TOML from 'smol-toml'
TOML.stringify({ ... })A few notes on the stringify function:
undefinedandnullvalues on objects are ignored (does not produce a key/value).undefinedandnullvalues in arrays are rejected.- Functions, classes and symbols are rejected.
- By default, floats will be serialized as integers if they don't have a decimal part. See Integers
stringify(parse('a = 1.0')) === 'a = 1'
- JS
Datewill be serialized as Offset Date Time- Use the
TomlDateobject for representing other types.
- Use the
When parsing, both integers and floats are read as plain JavaScript numbers, which essentially are floats. This means loss of type information, and makes it impossible to safely represent integers beyond 53 bits.
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 allows in most cases to preserve
whether a number is an integer or not, but fails to preserve type information for numbers like 1.0.
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 slightly more expensive container.
import { parse } from 'smol-toml'
const doc = '...'
const parsed = parse(doc, { integersAsBigInt: true })If you want to keep numbers for integers that can safely be represented as a JavaScript number, you can pass
"asNeeded" instead.
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.
import { stringify } from 'smol-toml'
const obj = { ... }
const toml = stringify(obj, { numbersAsFloat: true })smol-toml uses an extended Date object to represent all types of TOML Dates. In the future, smol-toml will use
objects from the Temporal proposal, but for now we're stuck with the legacy Date object.
import { TomlDate } from 'smol-toml'
// Offset Date Time
const date = new TomlDate('1979-05-27T07:32:00.000-08:00')
console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, false
console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000-08:00
// Local Date Time
const date = new TomlDate('1979-05-27T07:32:00.000')
console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, true
console.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000
// Local Date
const date = new TomlDate('1979-05-27')
console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, true, false, true
console.log(date.toISOString()) // ~> 1979-05-27
// Local Time
const date = new TomlDate('07:32:00')
console.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, false, true, true
console.log(date.toISOString()) // ~> 07:32:00.000You can also wrap a native Date object and specify using different methods depending on the type of date you wish
to represent:
import { TomlDate } from 'smol-toml'
const jsDate = new Date()
const offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate)
const localDateTime = TomlDate.wrapAsLocalDateTime(jsDate)
const localDate = TomlDate.wrapAsLocalDate(jsDate)
const localTime = TomlDate.wrapAsLocalTime(jsDate)The benchmark is ran using mitata.
Parsers and serializers are tested in 2 scenarios: using the example from TOML's homepage and specification, and using a ~5MB randomly generated1 file.
While fast-toml is included as it's a challenging candidate, it takes a lot of shortcuts that makes it very fast,
but at the expense of correctness (it has significant defects and does not pass the TOML test suite). smol-toml is
almost as fast, without sacrificing correctness. 😎
| Parse | smol-toml@1.7.0 | @iarna/toml@3.0.0 | @ltd/j-toml@1.38.0 | fast-toml@0.5.4 | @std/toml@1.0.11 | toml@4.1.1 | js-toml@1.1.2 | @decimalturn/toml-patch@2.0.0 |
|---|---|---|---|---|---|---|---|---|
| Spec example | 4.90 µs/iter | 12.36 µs/iter | 33.17 µs/iter | 4.80 µs/iter | 22.94 µs/iter | 29.86 µs/iter | 23.67 µs/iter | 17.81 µs/iter |
| ~5MB test file | 116.74 ms/iter | DNF | 198.57 ms/iter | 93.51 ms/iter | 429.91 ms/iter | 415.92 ms/iter | 361.89 ms/iter | 176.94 ms/iter |
| Stringify | smol-toml@1.7.0 | @iarna/toml@3.0.0 | @ltd/j-toml@1.38.0 | fast-toml@0.5.4 | @std/toml@1.0.11 | toml@4.1.1 | js-toml@1.1.2 | @decimalturn/toml-patch@2.0.0 |
|---|---|---|---|---|---|---|---|---|
| Spec example | 2.24 µs/iter | 8.68 µs/iter | 89.89 µs/iter | N/A | 3.86 µs/iter | N/A | 3.53 µs/iter | N/A2 |
| ~5MB test file | 42.34 ms/iter | 132.74 ms/iter | 921.98 ms/iter | N/A | 68.37 ms/iter | N/A | 106.14 ms/iter | N/A2 |
Detailed benchmark data
node --expose-gc bench/parse.bench.ts
clk: ~5.47 GHz
cpu: AMD Ryzen 9 9950X3D 16-Core Processor
runtime: node 26.3.1 (x64-linux)
benchmark avg (min … max) p75 / p99 (min … top 1%)
------------------------------------------- -------------------------------
• spec document
------------------------------------------- -------------------------------
smol-toml 4.90 µs/iter 4.85 µs █
(4.72 µs … 96.03 µs) 6.13 µs █▅
( 2.09 kb … 325.14 kb) 12.96 kb ▁██▄▃▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
4.01 ipc ( 99.63% cache) 21.59 branch misses
27.50k cycles 110.19k instructions 4.09k c-refs 15.27 c-misses
@iarna/toml 12.36 µs/iter 12.19 µs █
(11.86 µs … 131.24 µs) 16.53 µs █
(176.00 b … 360.27 kb) 24.00 kb ▅█▅▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
3.97 ipc ( 99.71% cache) 60.52 branch misses
68.38k cycles 271.17k instructions 12.01k c-refs 35.06 c-misses
@ltd/j-toml 33.17 µs/iter 32.50 µs ▇█
(31.03 µs … 1.10 ms) 36.36 µs ███▆
( 40.00 b … 537.94 kb) 27.61 kb ▁▃▇████▆▂▁▁▂▂▁▁▁▁▁▁▁▁
3.15 ipc ( 99.50% cache) 305.47 branch misses
183.96k cycles 579.46k instructions 32.33k c-refs 160.93 c-misses
fast-toml 4.80 µs/iter 4.77 µs █
(4.61 µs … 96.44 µs) 5.58 µs █▃
(256.00 b … 329.85 kb) 12.55 kb ▁▆██▅▄▃▂▂▁▁▁▁▁▁▁▁▁▁▁▁
4.61 ipc ( 99.61% cache) 18.02 branch misses
26.90k cycles 123.90k instructions 3.73k c-refs 14.45 c-misses
deno's @std/toml 22.94 µs/iter 22.84 µs █
(21.43 µs … 183.90 µs) 27.22 µs ██
(800.00 b … 619.62 kb) 64.88 kb ▁▄▄▆██▅▂▁▁▁▁▁▁▁▁▁▁▁▁▁
3.73 ipc ( 99.67% cache) 106.77 branch misses
126.43k cycles 472.03k instructions 23.79k c-refs 79.52 c-misses
node-toml 29.86 µs/iter 29.51 µs █
(28.17 µs … 200.95 µs) 42.50 µs █▇
(976.00 b … 785.96 kb) 104.23 kb ▄██▂▂▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
4.01 ipc ( 99.36% cache) 146.79 branch misses
163.80k cycles 657.50k instructions 27.26k c-refs 174.37 c-misses
js-toml 23.67 µs/iter 23.31 µs █▃
(22.10 µs … 196.26 µs) 34.04 µs ██
( 2.55 kb … 678.23 kb) 96.06 kb ▃██▄▂▂▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁
4.14 ipc ( 98.56% cache) 141.38 branch misses
129.53k cycles 536.67k instructions 18.52k c-refs 266.18 c-misses
@decimalturn/toml-patch 17.81 µs/iter 17.68 µs █▇
(16.82 µs … 159.63 µs) 23.01 µs ██▅
(264.00 b … 651.59 kb) 56.03 kb ▃███▄▂▂▂▂▂▁▁▁▁▁▁▁▁▁▁▁
3.60 ipc ( 99.55% cache) 73.51 branch misses
98.49k cycles 354.88k instructions 20.21k c-refs 90.93 c-misses
summary
fast-toml
1.02x faster than smol-toml
2.57x faster than @iarna/toml
3.71x faster than @decimalturn/toml-patch
4.77x faster than deno's @std/toml
4.93x faster than js-toml
6.22x faster than node-toml
6.9x faster than @ltd/j-toml (nice)
• 5MB document
------------------------------------------- -------------------------------
smol-toml 116.74 ms/iter 118.39 ms █ █
(110.52 ms … 127.54 ms) 123.91 ms █ ▅ ▅ █ ▅ ▅▅ ▅ ▅
( 32.98 mb … 49.20 mb) 42.93 mb █▁█▁█▁▁█▁█▁██▁▁█▁▁▁▁█
2.48 ipc ( 98.45% cache) 3.17M branch misses
629.10M cycles 1.56G instructions 101.49M c-refs 1.58M c-misses
@iarna/toml error: Unexpected character in datetime, expected period (.), minus (-), plus (+) or Z at row 5, col 45, pos 569:
4: NfF6LuAerfn5mDPI7Cp 2qsrB4vGmJTyb5jNubOIBYYWrWlAsrw PX93S57gjb5GEhR8qOU5blDQmwfVJTA YvmJ9cE3cUZU NAJQgAbIdpZLhc4lOs4ZhMEWehhZqXCsVD1YP1vN2GEoM2WX''', 1986-05-27T18:36:13Z, -5460, "2ZAV3fYlb23hf7r7QoftVlicWE2iuwp", 4790.2253 ]
5> SzeC4Me8T = [ 5928.9340, 1991-04-28 19:24:24, 7807, -782.4516, 0b1000011111, "YvXRZKBGle9d51sqE90t8hP" ]
^
6: SLMvBirT.pmpX1D.9PivpfFBo = 2010-09-29
@ltd/j-toml 198.57 ms/iter 196.77 ms █
(181.11 ms … 291.66 ms) 209.47 ms ██
( 8.55 mb … 55.95 mb) 35.95 mb ████▁▁▁▁▁█▁█▁▁▁█▁▁▁▁█
2.32 ipc ( 97.82% cache) 3.98M branch misses
1.08G cycles 2.50G instructions 166.94M c-refs 3.63M c-misses
fast-toml 93.51 ms/iter 95.06 ms █
(89.98 ms … 96.83 ms) 95.74 ms ▅ ▅ ▅ █▅ ▅▅ ▅▅▅
( 13.30 mb … 34.88 mb) 24.04 mb █▁▁▁█▁█▁██▁▁▁▁▁██▁███
2.83 ipc ( 98.14% cache) 2.36M branch misses
507.32M cycles 1.44G instructions 66.44M c-refs 1.23M c-misses
deno's @std/toml 429.91 ms/iter 436.58 ms █
(419.32 ms … 441.05 ms) 437.63 ms ▅ ▅▅▅ ▅ ▅ ▅ ▅ ▅█
(180.32 mb … 204.05 mb) 191.51 mb █▁███▁▁█▁█▁▁▁▁▁█▁█▁██
3.15 ipc ( 97.05% cache) 6.63M branch misses
2.36G cycles 7.45G instructions 255.14M c-refs 7.54M c-misses
node-toml 415.92 ms/iter 413.57 ms ██
(404.84 ms … 448.96 ms) 438.33 ms ██ █
( 45.80 mb … 78.18 mb) 50.13 mb ████▁█▁▁▁▁▁▁▁▁▁▁▁▁▁▁█
4.26 ipc ( 97.29% cache) 6.53M branch misses
2.25G cycles 9.59G instructions 194.56M c-refs 5.27M c-misses
js-toml 361.89 ms/iter 369.39 ms █
(346.05 ms … 406.77 ms) 394.74 ms ▅█ ▅
(249.62 mb … 282.33 mb) 265.65 mb ██▁█▁▁▁▁▁▁▇▁▁▁▇▁▁▁▁▁▇
2.55 ipc ( 94.91% cache) 5.64M branch misses
1.73G cycles 4.43G instructions 112.66M c-refs 5.74M c-misses
@decimalturn/toml-patch 176.94 ms/iter 174.86 ms █
(172.74 ms … 197.94 ms) 182.08 ms █ ██
( 27.14 mb … 38.55 mb) 28.81 mb █▁████▁▁▁▁▁█▁▁▁▁▁▁▁▁█
3.18 ipc ( 97.69% cache) 3.58M branch misses
947.48M cycles 3.02G instructions 130.37M c-refs 3.01M c-misses
summary
fast-toml
1.25x faster than smol-toml
1.89x faster than @decimalturn/toml-patch
2.12x faster than @ltd/j-toml
3.87x faster than js-toml
4.45x faster than node-toml
4.6x faster than deno's @std/toml
node --expose-gc bench/stringify.bench.ts
clk: ~5.48 GHz
cpu: AMD Ryzen 9 9950X3D 16-Core Processor
runtime: node 26.3.1 (x64-linux)
benchmark avg (min … max) p75 / p99 (min … top 1%)
------------------------------------------- -------------------------------
• spec document
------------------------------------------- -------------------------------
smol-toml 2.24 µs/iter 2.24 µs ▄ █
(2.22 µs … 2.27 µs) 2.27 µs █▃ ▅▆ █▃
( 4.60 kb … 4.71 kb) 4.61 kb ▅███▃██████▃▇▃▃▅▃▁▁▃▅
4.62 ipc ( 99.64% cache) 5.08 branch misses
12.21k cycles 56.44k instructions 1.12k c-refs 4.08 c-misses
@iarna/toml 8.68 µs/iter 8.67 µs █
(8.65 µs … 8.89 µs) 8.73 µs ▅█▅ ▅
(654.88 b … 1.53 kb) 720.60 b ▇███▇▁█▁▁▁▁▁▇▇▁▁▁▁▁▁▇
4.00 ipc ( 99.49% cache) 23.53 branch misses
47.95k cycles 191.80k instructions 7.11k c-refs 36.09 c-misses
@ltd/j-toml 89.89 µs/iter 90.21 µs █
(69.82 µs … 209.14 µs) 95.93 µs █
( 4.04 kb … 389.75 kb) 37.49 kb ▁▁▁▁▁▁▁▂▁▁▁▁▁▁▁█▄▄▃▂▂
4.20 ipc ( 99.76% cache) 544.09 branch misses
490.58k cycles 2.06M instructions 35.22k c-refs 82.84 c-misses
deno's @std/toml 3.86 µs/iter 3.86 µs █
(3.83 µs … 4.24 µs) 3.88 µs ▅ ▅ █▅▅██▅
(836.05 b … 4.28 kb) 0.98 kb █▁██▅█▅████████▁▁▁▁▁▅
4.00 ipc ( 99.60% cache) 6.22 branch misses
21.36k cycles 85.36k instructions 3.32k c-refs 13.27 c-misses
js-toml 3.53 µs/iter 3.54 µs █▂▄
(3.52 µs … 3.58 µs) 3.58 µs ▆███
( 5.76 kb … 7.29 kb) 6.98 kb ▃▇████▃▅▁▃▁▃▁▁▁▁▁▁▁▁▃
4.37 ipc ( 99.11% cache) 10.24 branch misses
19.45k cycles 84.99k instructions 2.10k c-refs 18.67 c-misses
@decimalturn/toml-patch 81.54 µs/iter 81.22 µs █
(78.63 µs … 341.24 µs) 103.14 µs █▂
(872.00 b … 831.95 kb) 113.00 kb ▃██▅▃▂▁▂▁▁▁▁▁▁▁▁▁▁▁▁▁
4.56 ipc ( 99.28% cache) 567.51 branch misses
443.97k cycles 2.02M instructions 52.63k c-refs 381.28 c-misses
summary
smol-toml
1.58x faster than js-toml
1.73x faster than deno's @std/toml
3.88x faster than @iarna/toml
36.44x faster than @decimalturn/toml-patch
40.18x faster than @ltd/j-toml
• 5MB document
------------------------------------------- -------------------------------
smol-toml 42.34 ms/iter 43.06 ms █ █
(40.50 ms … 45.33 ms) 43.51 ms █ ▅▅▅▅ ▅ ▅▅▅ █
( 9.46 mb … 35.74 mb) 12.91 mb █▁▁▁▁████▁▁▁█▁▁███▁▁█
2.12 ipc ( 95.19% cache) 1.59M branch misses
217.80M cycles 462.56M instructions 14.99M c-refs 720.67k c-misses
@iarna/toml 132.74 ms/iter 134.02 ms █
(125.91 ms … 138.18 ms) 137.02 ms █ █
( 27.35 mb … 54.08 mb) 41.53 mb █▁▁█▁▁▁▁█▁▁█▁███▁▁▁▁█
2.56 ipc ( 97.08% cache) 4.44M branch misses
704.85M cycles 1.80G instructions 85.83M c-refs 2.50M c-misses
@ltd/j-toml 921.98 ms/iter 927.58 ms █ ██ █
(889.05 ms … 937.02 ms) 929.09 ms ▅ █ ▅██▅█
( 4.20 mb … 33.46 mb) 18.59 mb █▁▁▁▁▁▁▁▁▁▁▁▁▁█▁█████
4.06 ipc ( 99.42% cache) 6.75M branch misses
5.04G cycles 20.45G instructions 243.67M c-refs 1.41M c-misses
deno's @std/toml 68.37 ms/iter 69.68 ms █ █
(61.79 ms … 78.19 ms) 77.23 ms ▅ ▅█▅ ▅ ▅█ ▅ ▅
( 29.04 mb … 62.29 mb) 33.86 mb █▁███▁▁█▁██▁█▁▁▁▁▁▁▁█
2.21 ipc ( 95.21% cache) 1.74M branch misses
332.33M cycles 732.79M instructions 30.06M c-refs 1.44M c-misses
js-toml 106.14 ms/iter 107.44 ms █
(102.35 ms … 117.91 ms) 108.69 ms ▅█ ▅▅ ▅ ▅▅ ▅ ▅▅
( 34.03 mb … 62.21 mb) 44.13 mb ██▁▁██▁▁█▁██▁▁▁▁█▁▁██
2.39 ipc ( 96.23% cache) 3.05M branch misses
570.22M cycles 1.36G instructions 50.24M c-refs 1.90M c-misses
@decimalturn/toml-patch 1.07 s/iter 1.08 s █ █ █
(1.05 s … 1.14 s) 1.09 s █▅ ▅▅ █ █ ▅ ▅
(116.61 mb … 147.62 mb) 121.20 mb ██▁██▁▁▁█▁▁▁▁▁█▁▁█▁▁█
3.67 ipc ( 93.69% cache) 12.18M branch misses
5.77G cycles 21.17G instructions 780.26M c-refs 49.26M c-misses
summary
smol-toml
1.61x faster than deno's @std/toml
2.51x faster than js-toml
3.13x faster than @iarna/toml
21.77x faster than @ltd/j-toml
25.29x faster than @decimalturn/toml-patch
