{"id":15828,"library":"smol-toml","title":"Small and Fast TOML Parser","description":"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.","status":"active","version":"1.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/squirrelchat/smol-toml","tags":["javascript","toml","parser","serializer","typescript"],"install":[{"cmd":"npm install smol-toml","lang":"bash","label":"npm"},{"cmd":"yarn add smol-toml","lang":"bash","label":"yarn"},{"cmd":"pnpm add smol-toml","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"smol-toml is primarily designed for ESM usage. CommonJS requires named exports via .parse or destructuring.","wrong":"const parse = require('smol-toml').parse","symbol":"parse","correct":"import { parse } from 'smol-toml'"},{"note":"smol-toml is primarily designed for ESM usage. CommonJS requires named exports via .stringify or destructuring.","wrong":"const stringify = require('smol-toml').stringify","symbol":"stringify","correct":"import { stringify } from 'smol-toml'"},{"note":"The default export `TOML` is an object containing `parse` and `stringify` methods, similar to the global JSON object.","wrong":"import { TOML } from 'smol-toml'","symbol":"TOML (default export)","correct":"import TOML from 'smol-toml'"}],"quickstart":{"code":"import { parse, stringify } from 'smol-toml';\n\nconst tomlDoc = `\n[database]\ndriver = \"postgresql\"\nserver.host = \"127.0.0.1\"\nserver.port = 3307\nfloat_val = 1.0\nint_val = 9223372036854775807\n`;\n\nconsole.log('--- Original TOML Document ---');\nconsole.log(tomlDoc);\n\n// Parse the TOML document\nconst parsedConfig = parse(tomlDoc, { parseBigInt: true }); // parseBigInt for large integers\nconsole.log('\\n--- Parsed JavaScript Object ---');\nconsole.log(JSON.stringify(parsedConfig, null, 2));\n\n// Stringify the JavaScript object back to TOML\nconst stringifiedToml = stringify(parsedConfig);\nconsole.log('\\n--- Stringified TOML Document ---');\nconsole.log(stringifiedToml);\n\n// Example with default export\nimport TOML from 'smol-toml';\nconst parsedWithDefault = TOML.parse(tomlDoc);\nconsole.log('\\n--- Parsed with default export ---');\nconsole.log(JSON.stringify(parsedWithDefault.database, null, 2));\n","lang":"typescript","description":"Demonstrates parsing a TOML string into a JavaScript object and then stringifying the object back into a TOML string, including options for BigInt parsing."},"warnings":[{"fix":"Review any snapshot tests or external integrations that parse or compare `smol-toml` stringify output. Adjust expectations for the more compact TOML format.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Upgrade to smol-toml version 1.6.1 or later (`npm install smol-toml@latest`).","message":"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.","severity":"breaking","affected_versions":">=1.0.0 <1.6.1"},{"fix":"When parsing, use `parse(tomlString, { parseBigInt: true })` to interpret all integers as BigInts. This feature was introduced in v1.4.0.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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) })`.","cause":"Attempting to stringify a JavaScript array that contains `undefined` or `null` elements.","error":"Error: Cannot stringify value: undefined"},{"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.","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.","error":"JavaScript number precision limits exceeded for large integer."},{"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.","cause":"An object passed to `stringify` contains a JavaScript `Function`, `Class`, or `Symbol` type, which `smol-toml` does not support for serialization.","error":"Error: Cannot stringify value: [Function: myFunction]"}],"ecosystem":"npm"}