toml-node

toml is a TOML parser for Node.js that scores 702/708 (99.2%) on the official toml-test compliance suite, covering the full TOML v1.1.0 specification including dotted keys, inline tables, array of tables, and multiline strings. It ships with zero runtime dependencies, requires Node.js 20 or later, and is built on the Peggy parser generator, which compiles a PEG grammar (src/toml.pegjs) into the parser at build time.

Beyond spec compliance, the library is deliberately careful about lossless data representation: integers outside JavaScript’s safe integer range throw by default rather than silently rounding, with an opt-in bigint mode to parse the full 64-bit range exactly, and date/time values can be returned as native Temporal objects instead of Date/strings. Recent releases have also patched a prototype-pollution vulnerability (CVE-2026-63376) and a stack-overflow denial-of-service on deeply nested input, with nesting depth now bounded and configurable via maxDepth.

What You Get

• A single parse(input, options) function that turns TOML text into plain JavaScript objects
• Full TOML v1.1.0 spec support: dotted/quoted keys, inline tables, arrays of tables, multiline strings
• Lossless 64-bit integer handling via an opt-in bigint mode instead of silent rounding
• Optional Temporal output for date/time values, with a polyfill fallback for runtimes without native Temporal
• Bundled TypeScript type definitions (index.d.ts)

Common Use Cases

• Loading .toml configuration files for CLI tools and Node.js applications
• Parsing Cargo.toml, pyproject.toml, or other TOML-based manifests programmatically
• Validating TOML documents against the spec before writing them to disk
• Migrating configuration from JSON/YAML to TOML in a Node.js build pipeline

Under The Hood

Architecture index.js is a thin entry point that delegates to lib/parser.js (generated by Peggy from the src/toml.pegjs grammar) and lib/compiler.js (a hand-written semantic reducer). The parser produces a typed AST (Assign, ObjectPath, ArrayPath, Integer, Array, InlineTable, Date-family nodes), and compiler.js’s compile() walks that AST with closure-scoped state (assignedPaths/valueAssignments/explicitTablePaths Sets plus a WeakSet of “owned” containers) to enforce TOML’s redefinition rules and guard against prototype-pollution-style key traversal, producing a plain object tree rooted in Object.create(null) tables. This two-stage grammar-parse-then-semantic-reduce split cleanly separates syntax from TOML’s table/array redefinition semantics; changes to the core compile reducer would ripple through every value type.

Tech Stack Plain CommonJS JavaScript with no runtime dependencies; devDependencies are limited to peggy (compiles the .pegjs grammar into lib/parser.js at build time via npm run build) and @js-temporal/polyfill (used to exercise Temporal support in tests on runtimes lacking a native Temporal global). Tests run on Node’s built-in node:test/node:assert rather than an external framework, and CI (.github/workflows/ci.yml) runs the unit suite plus the official toml-test spec suite across Node 20/22/24.

Code Quality test/test_toml.js exercises parsing behavior with deepStrictEqual fixture comparisons against real TOML files (test/*.toml) and includes explicit regression tests for the prototype-pollution fix (rejectsWithoutObjectPrototypeMutation). test/spec-test.js runs the external toml-test compliance suite. Errors are never swallowed: both the parser and compiler throw Error instances augmented with line/column via a shared genError helper. The project uses plain JS with a hand-authored .d.ts rather than TypeScript, and a legacy .jshintrc rather than a modern linter/formatter, but CI enforces both build and test on every push across three Node versions.

API Design The public surface is a single function, toml.parse(input, options), with no class instantiation or required configuration for the common case. Advanced behavior (bigint, useTemporal/temporal, maxDepth) is opt-in and orthogonal, and each option is documented in the README with a runnable example. Thrown errors carry line and column properties, making them easy to surface in editor tooling or CLI diagnostics, and TypeScript types ship with the package despite the implementation itself being plain JavaScript.