Small and Fast TOML Parser

Common errors

• Error: Cannot stringify value: undefined

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

  cause 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]

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

Warnings

• breaking The 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.
• breaking smol-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`).
• gotcha By 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.
• gotcha When 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`.
• gotcha The `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.

Install

• npm install smol-toml npm
• yarn add smol-toml yarn
• pnpm add smol-toml pnpm

Imports

• parse
  wrong:

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

  correct:

  import { parse } from 'smol-toml'

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

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

  correct:

  import { stringify } from 'smol-toml'

  smol-toml is primarily designed for ESM usage. CommonJS requires named exports via .stringify or destructuring.
• TOML (default export)
  wrong:

  import { TOML } from 'smol-toml'

  correct:

  import TOML from 'smol-toml'

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

Quickstart

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