smol-toml

A small, fast, and correct TOML parser and serializer. smol-toml is fully(ish) spec-compliant with TOML v1.0.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]

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 are not rejected
• Certain invalid UTF-8 codepoints are not rejected
• Certain invalid dates are not rejected
  • For instance, 2023-02-30 would be accepted and parsed as 2023-03-02. While additional checks could be performed to reject these, they've not been added for performance reasons.
• smol-toml doesn't preserve type information between integers and floats (in JS, everything is a float)

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 https://github.com/toml-lang/toml-test/issues/154 and https://github.com/toml-lang/toml-test/issues/155

Installation

[pnpm | yarn | npm] i smol-toml

Usage

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:

• undefined and null values on objects are ignored (does not produce a key/value).
• undefined and null values in arrays are rejected.
• Functions, classes and symbols are rejected.
• floats will be serialized as integers if they don't have a decimal part.
  • stringify(parse('a = 1.0')) === 'a = 1'
• JS Date will be serialized as Offset Date Time
  • Use the TomlDate object for representing other types.

Dates

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.000

You 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)

Performance

A note on these performance numbers: in some highly synthetic tests, other parsers such as fast-toml greatly outperform other parsers, mostly due to their lack of compliance with the spec. For example, to parse a string, fast-toml skips the entire string while smol-toml does validate the string, costing a fair share of performance.

The ~5MB test file used for benchmark here is filled with random data which attempts to be close-ish to reality in terms of structure. The idea is to have a file relatively close to a real-world application, with moderately sized strings etc.

The large TOML generator can be found here