smol-toml

library1.6.1jsnpmunverified

smol-toml is a JavaScript and TypeScript library designed for parsing and serializing TOML (Tom's Obvious, Minimal Language) documents. Currently at version 1.6.1, it offers a small, fast, and highly compliant implementation of the TOML specification, supporting the latest TOML 1.1.0 standard since version 1.6.0. It maintains a regular release cadence with recent updates addressing security vulnerabilities and feature enhancements. Differentiating itself from other often outdated or unmaintained TOML parsers in the JavaScript ecosystem, smol-toml is noted as the most downloaded TOML parser on npm, actively used in production systems. While generally robust, it explicitly notes some non-compliance with the `toml-test` suite for performance reasons, such as not rejecting invalid UTF-8 or certain invalid dates. It also provides options for handling integers as BigInts to prevent precision loss, a feature introduced in v1.4.0.

serialization

npm install smol-toml

github ↗package ↗

INSTALL

IMPORT

SIG · SMOL-TOML

smol-toml

serializationjavascriptv1.6.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'smol-toml'

✗ const parse = require('smol-toml').parse

smol-toml is primarily designed for ESM usage. CommonJS requires named exports via .parse or destructuring.

stringify

✓ import { stringify } from 'smol-toml'

✗ const stringify = require('smol-toml').stringify

smol-toml is primarily designed for ESM usage. CommonJS requires named exports via .stringify or destructuring.

TOML (default export)

✓ import TOML from 'smol-toml'

✗ import { TOML } from 'smol-toml'

The default export `TOML` is an object containing `parse` and `stringify` methods, similar to the global JSON object.

Demonstrates parsing a TOML string into a JavaScript object and then stringifying the object back into a TOML string, including options for BigInt parsing.

import { parse, stringify } from 'smol-toml'; const tomlDoc = ` [database] driver = "postgresql" server.host = "127.0.0.1" server.port = 3307 float_val = 1.0 int_val = 9223372036854775807 `; console.log('--- Original TOML Document ---'); console.log(tomlDoc); // Parse the TOML document const parsedConfig = parse(tomlDoc, { parseBigInt: true }); // parseBigInt for large integers console.log('\n--- Parsed JavaScript Object ---'); console.log(JSON.stringify(parsedConfig, null, 2)); // Stringify the JavaScript object back to TOML const stringifiedToml = stringify(parsedConfig); console.log('\n--- Stringified TOML Document ---'); console.log(stringifiedToml); // Example with default export import TOML from 'smol-toml'; const parsedWithDefault = TOML.parse(tomlDoc); console.log('\n--- Parsed with default export ---'); console.log(JSON.stringify(parsedWithDefault.database, null, 2));

Debug

Known issues

breakingThe stringify function's output format was significantly improved in v1.5.0 to be more compact by removing unnecessary table headers and empty lines between successive table headers. This change might affect tests or tools that rely on the exact previous output structure.

fix

Review any snapshot tests or external integrations that parse or compare `smol-toml` stringify output. Adjust expectations for the more compact TOML format.

affects: >=1.5.0

breakingsmol-toml v1.6.1 addresses a security vulnerability (GHSA-v3rj-xjv7-4jmq) where specially crafted TOML documents with thousands of successive commented lines could cause an unrestricted recursion leading to a stack overflow error. All users should update immediately.

fix

Upgrade to smol-toml version 1.6.1 or later (`npm install smol-toml@latest`).

affects: >=1.0.0 <1.6.1

gotchaBy default, both integers and floats are parsed into standard JavaScript `number` types. This means that integers larger than 53 bits (Number.MAX_SAFE_INTEGER) will lose precision. To preserve full type information and handle large integers, you must enable the `parseBigInt` option.

fix

When parsing, use `parse(tomlString, { parseBigInt: true })` to interpret all integers as BigInts. This feature was introduced in v1.4.0.

affects: >=1.0.0

gotchaWhen stringifying objects to TOML, `undefined` and `null` values within arrays are explicitly rejected and will cause an error. `undefined` and `null` values as standalone object properties are ignored (do not produce a key/value pair).

fix

Ensure that arrays intended for serialization with `stringify` do not contain `undefined` or `null` elements. Filter these values out before passing the object to `stringify`.

affects: >=1.0.0

gotchaThe `stringify` function explicitly rejects non-serializable JavaScript types such as functions, classes, and symbols. Attempting to stringify an object containing these types will result in an error.

fix

Before stringifying, ensure that the object only contains primitive types, arrays, and plain objects. Remove or transform any functions, classes, or symbols that might be present.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot stringify value: undefined

Attempting to stringify a JavaScript array that contains `undefined` or `null` elements.

fix

Filter `undefined` or `null` values from arrays before passing the object to `smol-toml`'s `stringify` function. Example: `stringify({ my_array: [1, null, 3].filter(item => item !== null) })`.

JavaScript number precision limits exceeded for large integer.

A TOML document contains an integer larger than `Number.MAX_SAFE_INTEGER` (2^53 - 1) which is parsed into a standard JavaScript `number` by default, leading to data corruption.

fix

When parsing TOML, enable BigInt support by calling `parse(tomlString, { parseBigInt: true })`. This will parse large integers as JavaScript `BigInt` types, preserving their full precision.

Error: Cannot stringify value: [Function: myFunction]

An object passed to `stringify` contains a JavaScript `Function`, `Class`, or `Symbol` type, which `smol-toml` does not support for serialization.

fix

Before calling `stringify`, ensure that the object only contains serializable primitive types, arrays, and plain objects. Remove or transform any `Function`, `Class`, or `Symbol` properties.

Upgrade

Version history

1.6.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/squirrelchat/smol-toml ↗

packagehttps://www.npmjs.com/package/smol-toml ↗