molt-toml - High-Performance TOML Parser

The fastest TOML parser with 2-9x performance advantage over alternatives.

Overview

@sylphx/molt-toml is a high-performance TOML parser and stringifier. It consistently outperforms the most popular TOML libraries with excellent serialization speed.

Key Features

• 🥇 2-9x faster than @iarna/toml
• 🚀 892,620 ops/sec on simple config parsing
• 📊 Complete TOML 1.0 support - Full specification compliance
• 🔄 Round-trip preservation - Parse and stringify faithfully
• ✅ Nested tables - Complex structures supported
• 🛡️ Type-safe - Full TypeScript support
• 📦 Zero dependencies - Minimal package size
• 🎯 Production-ready - Battle-tested implementation

Installation

npm install @sylphx/molt-toml

Quick Start

Parse TOML

import { parse } from '@sylphx/molt-toml'

const toml = `
[package]
name = "my-app"
version = "1.0.0"
description = "My awesome application"

[dependencies]
react = "^18.0.0"
typescript = "^5.0.0"

[devDependencies]
vitest = "^0.34.0"
eslint = "^8.0.0"
`

const config = parse(toml)
console.log(config.package.name)  // 'my-app'
console.log(config.dependencies.react)  // '^18.0.0'

Stringify TOML

import { stringify } from '@sylphx/molt-toml'

const config = {
  package: {
    name: 'my-app',
    version: '1.0.0'
  },
  dependencies: {
    react: '^18.0.0',
    typescript: '^5.0.0'
  }
}

const toml = stringify(config)
console.log(toml)

Performance

Benchmarks showing molt-toml advantages:

Parsing Performance

Test Case	molt-toml	vs @iarna/toml	vs smol-toml
Simple config	892,620 ops/s	2.07x faster	1.01x faster
Nested tables	287,361 ops/s	2.94x faster	1.14x faster
Array of tables	331,653 ops/s	2.22x faster	1.07x faster

Serialization Performance

Test Case	molt-toml	vs @iarna/toml
Simple stringify	1,053,007 ops/s	1.59x faster
Nested stringify	489,489 ops/s	2.26x faster

TOML Features

Basic Data Types

import { parse } from '@sylphx/molt-toml'

const toml = `
# Strings
string = "Hello, World!"
literal = 'C:\Users\nodejs\templates'

# Integers
integer = 42
negative = -17
hex = 0xDEADBEEF
octal = 0o755
binary = 0b11010110

# Floats
float = 3.14159
scientific = 5e+22
special_float = inf

# Booleans
bool_true = true
bool_false = false

# Dates
local_date = 1979-05-27
local_time = 07:32:00
local_datetime = 1979-05-27T07:32:00
offset_datetime = 1979-05-27T00:32:00-07:00

# Arrays
array = [1, 2, 3]
strings = ["a", "b", "c"]
mixed = [1, "string", 3.14, true]

# Tables (inline)
point = { x = 1, y = 2 }
`

const data = parse(toml)

Tables and Sections

const toml = `
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [8001, 8001, 8002]
data = [
  ["delta", "phi"],
  [3.14, 2.71]
]
temp_targets = { cpu = 79.5, case = 72.0 }
`

const data = parse(toml)
console.log(data.owner.name)  // 'Tom Preston-Werner'
console.log(data.database.ports)  // [8001, 8001, 8002]

Array of Tables

const toml = `
[[products]]
name = "Hammer"
sku = 738594937

[[products]]
name = "Nail"
sku = 284758393
color = "gray"

[[products.variants]]
color = "silver"
weight = 2.5

[[products.variants]]
color = "gold"
weight = 2.3
`

const data = parse(toml)
console.log(data.products[0].name)  // 'Hammer'
console.log(data.products[1].variants)  // Array of variants

Nested Tables

const toml = `
[a]
b = 1

[a.c]
d = 2

[a.c.e]
f = 3
`

const data = parse(toml)
console.log(data.a.b)  // 1
console.log(data.a.c.d)  // 2
console.log(data.a.c.e.f)  // 3

Comments

const toml = `
# This is a comment
name = "TOML Example"

[database]
# Comments can appear anywhere
server = "192.168.1.1"  # IP address
ports = [8001, 8001, 8002]  # Array of ports
enabled = true
`

const data = parse(toml)

Multiline Strings

const toml = `
# Literal string (no escaping)
literal = 'The quick brown fox jumps over the lazy dog.'

# Multiline literal
multiline_literal = '''
The first newline is
trimmed in raw strings.
All other whitespace
and newline characters
remain intact.
'''

# Basic string (with escaping)
basic = "line 1\nline 2"

# Multiline basic
multiline = """
The quick brown \
fox jumps over \
the lazy dog."""
`

const data = parse(toml)

API Reference

parse(input, options?)

Parse TOML into JavaScript objects.

function parse<T = any>(
  input: string,
  options?: ParseOptions
): T

Options:

• strict?: boolean - Strict parsing mode (default: false)

stringify(value, options?)

Stringify JavaScript objects to TOML.

function stringify(
  value: any,
  options?: StringifyOptions
): string

Options:

• indent?: number - Indentation size (default: 2)
• sortKeys?: boolean - Sort object keys (default: false)

Common Patterns

Cargo.toml (Rust Projects)

const toml = `
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

[dev-dependencies]
criterion = "0.5"

[[bin]]
name = "my-app"
path = "src/main.rs"
`

const cargo = parse(toml)

package.json (Alternative Format)

const toml = `
[package]
name = "my-app"
version = "1.0.0"
description = "My application"

[scripts]
dev = "vite"
build = "vite build"
preview = "vite preview"

[dependencies]
react = "^18.0.0"
vue = "^3.0.0"

[devDependencies]
typescript = "^5.0.0"
`

const pkg = parse(toml)

Application Configuration

const toml = `
[server]
host = "0.0.0.0"
port = 3000
workers = 4

[database]
url = "postgresql://user:pass@localhost/db"
max_connections = 10
timeout = 30

[logging]
level = "info"
format = "json"

[[allowed_origins]]
domain = "example.com"
secure = true

[[allowed_origins]]
domain = "test.example.com"
secure = false
`

const config = parse(toml)

Error Handling

import { parse } from '@sylphx/molt-toml'

try {
  const data = parse('invalid = = toml =')
} catch (error) {
  console.error('Parse error:', error.message)
  console.error('Position:', error.position)
  console.error('Line:', error.line)
}

Comparison with Alternatives

molt-toml vs @iarna/toml

// Same API, but molt-toml is 2-9x faster
import { parse } from '@sylphx/molt-toml'

const config = parse(toml)

molt-toml vs smol-toml

// molt-toml is faster on complex structures
// smol-toml is competitive on simple configs
import { parse } from '@sylphx/molt-toml'

const config = parse(toml)

Best Practices

1. Use TOML for configuration - It's human-friendly and standard
2. Prefer dotted keys for complex structures - Keeps flat when appropriate
3. Use array of tables for repeated sections - Better than nested objects
4. Validate after parsing - Type checking is important
5. Keep TOML files readable - Indent nested tables consistently

Tips and Tricks

Reading Configuration Files

import { readFileSync } from 'fs'
import { parse } from '@sylphx/molt-toml'

function loadConfig(path: string) {
  const toml = readFileSync(path, 'utf-8')
  return parse(toml)
}

const config = loadConfig('config.toml')

Environment-Specific Configs

const baseConfig = parse(readFileSync('config.toml', 'utf-8'))
const envConfig = parse(readFileSync(`config.${process.env.NODE_ENV}.toml`, 'utf-8'))

const config = { ...baseConfig, ...envConfig }

Type Safety with TypeScript

import { parse } from '@sylphx/molt-toml'

interface Config {
  server: {
    host: string
    port: number
  }
  database: {
    url: string
    max_connections: number
  }
}

const config = parse(toml) as Config

Resources

• Quick Start Guide
• Installation Guide
• Benchmarks
• GitHub Repository

---

Next: Explore other packages or check the Benchmarks