smol-toml

smol-toml is a compact TOML v1.1.0 parser and serializer built to fix a gap in the JavaScript ecosystem, where most existing TOML libraries were outdated, unmaintained, or non-compliant with the spec. It exposes just two core functions — parse() and stringify() — plus a TomlDate helper class that correctly represents all four TOML date/time variants (offset date-time, local date-time, local date, local time) using an extended native Date object.

Despite its small surface area, smol-toml passes the vast majority of the official toml-test conformance suite and benchmarks faster than nearly every competing JS TOML parser on both small and multi-megabyte documents, while offering opt-in BigInt support for integers beyond the 53-bit safe range that plain JavaScript numbers can represent.

What You Get

• A parse() function converting TOML text into plain JavaScript objects, passing nearly all of the official toml-test conformance suite
• A stringify() function that serializes JS objects back to TOML, correctly round-tripping integers vs floats where possible
• A TomlDate class distinguishing Offset Date-Time, Local Date-Time, Local Date, and Local Time, each queryable via isDateTime()/isDate()/isTime()/isLocal()
• Opt-in BigInt integer parsing (integersAsBigInt: true or "asNeeded") for values beyond JavaScript’s 53-bit safe integer range
• A numbersAsFloat stringify option for end-to-end type preservation between BigInt integers and floating-point numbers
• Best-in-class benchmarked performance among JS TOML parsers on both spec-example and multi-megabyte documents

Common Use Cases

• Parsing pyproject.toml-style or Cargo-style configuration files inside JavaScript/TypeScript tooling
• Reading and writing TOML-based config for CLIs, build tools, and language-server implementations written in JS
• Round-tripping TOML documents where integer-vs-float type distinctions and TOML date semantics must be preserved
• Replacing an unmaintained or non-conformant legacy TOML parser in an existing Node.js codebase
• High-throughput parsing of large TOML documents where parser performance is a meaningful bottleneck

Under The Hood

Architecture: The library is deliberately small and flat — src/parse.ts drives a hand-written recursive-descent-style tokenizer/parser that delegates primitive value parsing to src/primitive.ts (strings, numbers, booleans) and src/date.ts (the four TOML date/time forms), while src/struct.ts assembles parsed key/value pairs into nested objects and arrays-of-tables; src/stringify.ts performs the inverse walk, and src/extract.ts plus src/util.ts hold small shared helpers, with src/error.ts defining a dedicated parse-error type carrying line/column context. Tech Stack: Pure TypeScript with zero runtime dependencies, built and tested via a pnpm workspace (pnpm-workspace.yaml) with a Justfile/mise.toml for task running, and benchmarked against seven competing parsers using the mitata benchmarking library. Code Quality: Correctness is validated against the official toml-lang/toml-test conformance suite via run-toml-test.bash, with explicitly documented, deliberate exceptions (e.g. invalid UTF-8 and some invalid dates are accepted for performance reasons) rather than silent gaps, plus a dedicated test/ directory of unit tests alongside the conformance harness. API Design: The public surface is intentionally minimal — parse(), stringify(), and TomlDate — mirroring the ergonomics of the built-in JSON global (import TOML from 'smol-toml'; TOML.stringify(...)), which keeps the learning curve near zero for anyone already familiar with JSON.parse/JSON.stringify.