Skip to content

About

Patch, parse and stringify TOML while preserving comments, whitespace and formatting.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

2,677 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

toml-patch

toml-patch logo

NPM Version JSR Version GitHub branch status


toml-patch edits TOML 1.1 documents without rewriting lines you did not change. Comments, tabs, trailing whitespace, and line endings on those lines stay as they were.

The published package is @decimalturn/toml-patch. It exports patch, parse, and stringify, plus TomlDocument for repeated work on one file and TomlFormat for stringify and patch options. There are no runtime dependencies. This tree is Rethunk-AI's fork of DecimalTurn/toml-patch, which started as a fork of timhall/toml-patch.

Quick start

pnpm add @decimalturn/toml-patch

Install options, the lite dist-tag, browser usage, and how to verify a clone are in HUMANS.md.

Highlights

  • Parse, patch, and stringify TOML 1.1
  • Untouched lines stay byte-identical after a patch
  • TomlDocument for multi-step edits and TomlFormat for output options
  • patch-lite dist-tag for edit-only installs
  • Optional Temporal date/time values
  • Comments travel with the entry they describe when patch() removes or reorders it

Documentation

Document Contents
HUMANS.md Install, verify, uninstall
AGENTS.md Layout, gate, invariants
CONTRIBUTING.md Development workflow
API patch, parse, stringify, TomlDocument
Comment ownership Which comments move with an entry
Date/time Date subclasses and Temporal
Formatting TomlFormat options
Patch-lite Edit-only distribution
Changelog Release notes
License MIT

API

toml-patch provides a functional API for one-time operations and a document-oriented API for workflows that need multiple operations on the same TOML document.

See the API reference for patch, parse, stringify and the TomlDocument class.

For a quick start, patch an existing TOML string like this:

import { patch } from '@decimalturn/toml-patch';

const existing = 'title = "TOML example"\nowner.name = "Bob"\n';
const updated = patch(existing, {
  title: 'TOML example',
  owner: { name: 'Tim' }
});

Comment Ownership

When patch() removes or reorders an entry, any comment describing it (a same-line trailing comment, or a line-comment directly above with no blank line in between) travels along with it, instead of being left behind to describe whatever ends up in that spot. This applies to root keys, [table]/[[array-of-tables]] blocks, and elements inside multi-line arrays and inline tables.

import * as TOML from '@decimalturn/toml-patch';
import { strict as assert } from 'assert';

const existing = `
x = 1 # a note about x
y = 2
`;

const patched = TOML.patch(existing, { y: 2 });

assert.strictEqual(patched, `
y = 2
`);

See the comment ownership guide for the full behavior, including how a blank line opts a comment out of ownership and current scope limitations.

Note that patch() does not reorder entries by default. To have it match the key order of the object you pass in, enable updateOrder in the formatting options.

Date/Time Handling & Temporal

TOML date/time values are parsed into custom Date subclasses (LocalDate, LocalTime, LocalDateTime, OffsetDateTime) by default. Set temporal: true to receive Temporal objects instead. stringify() and patch() auto-detect Temporal objects and serialize them correctly. Fractional seconds keep the source precision, sub-millisecond digits included.

Enabling Temporal

The temporal: true option requires Temporal to be available in the runtime:

Runtime How to enable
Node.js 26+ Built-in (no config needed)
Node.js 20–24 node --harmony-temporal flag
Node.js 14–26 @js-temporal/polyfill
import * as TOML from '@decimalturn/toml-patch';

// Node 26+ (native) or Node 20–24 with --harmony-temporal:
const obj = TOML.parse('d = 2024-01-15\n', { temporal: true });
// obj.d → Temporal.PlainDate

// All Node versions with the polyfill:
import { Temporal } from '@js-temporal/polyfill';
globalThis.Temporal = Temporal;
const obj2 = TOML.parse('d = 2024-01-15\n', { temporal: true });
// obj2.d → PlainDate (polyfill)

Note: Only offset-based timezones (+05:30, Z) are supported in TOML. IANA timezone annotations (e.g., [Asia/Kolkata]) will throw an error.

See the date/time guide for details and examples.

Patch-lite

patch-lite is a smaller, edit-only distribution for applications that only need to update existing TOML values, such as bumping a package version. It exposes the same patch name with a two-argument (existing, updated) signature.

It is not part of the main package: the main package ships the full API only. Install the lite build from the lite npm dist-tag, then import it with the same specifier:

npm install --save @decimalturn/toml-patch@lite
import { patch } from '@decimalturn/toml-patch';

const existing = 'version = "1.0.0"\n';
const updated = patch(existing, { version: '1.0.1' });
// updated === 'version = "1.0.1"\n'

For more info, check out the Patch-lite guide

Formatting

The TomlFormat class controls how TOML documents are formatted during stringification and patching operations.

The recommended approach is to start with TomlFormat.default() and override the options you need. e.g.:

import { stringify, TomlFormat } from '@decimalturn/toml-patch';

const format = TomlFormat.default();
format.newLine = '\r\n';
format.trailingNewline = 0;
format.trailingComma = true;
format.bracketSpacing = false;
format.indentWidth = 4;
format.multilineTable = 'parent';

const toml = stringify({
  title: 'My App',
  tags: ['dev', 'config'],
  database: { host: 'localhost', port: 5432 }
}, format);

See the formatting reference for the complete list of options, auto-detection behavior, updateOrder and more examples.

License

MIT. See LICENSE.

Copyright (c) 2019–2025 Tim Hall Copyright (c) 2025 Martin Leduc

About

Patch, parse and stringify TOML while preserving comments, whitespace and formatting.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages