@decimalturn/toml-patch 2.1.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0] - 2026-07-29
11
+
12
+ ### Changed
13
+
14
+ - **BREAKING**: Raise minimum supported Node.js version from `>=14` to `>=16`.
15
+ - Patching: introducing explicit comment ownership. Comments describing a key, table, array-of-tables entry or an element inside a multi-line array or inline table now travel with it when removed or reordered via `patch()`, instead of being left behind to describe whatever ends up in that spot. See [docs/CommentOwnership.md](docs/CommentOwnership.md). ([#259])
16
+ - Improve stringification performance ([0e66e68])
17
+
18
+ ### Added
19
+
20
+ - TomlDocument: New `parseDocument` function that parses a TOML string into a `TomlDocument`
21
+ - Patching: New `updateOrder` option in `TomlFormat`. When `true`, `patch()` reorders root key-values, section blocks and table-body rows to match the JS object's key order, carrying each entry's comments along. Off by default. Shapes not yet reordered are left in place and reported via `console.warn`. ([#260])
22
+
23
+ ### Fixed
24
+
25
+ - Patching: Ensure all elements of nested tables are preserved when using `inlineTableStart` is 2 or higher. ([#253])
26
+ - Patching: prevent whitespace errors when swaping keys between tables.
27
+ - Patching: handle BigInt values in documents without throwing. ([#255])
28
+ - Patching: handle commented multiline arrays correctly when adding keys or emptying them. ([#255])
29
+ - Patching: fix wrong section nesting when replacing a table with a scalar value. ([#255])
30
+ - Patching: preserve key with inline empty array when emptying an array-of-tables. ([#255])
31
+ - Patching: fix `Node not found` errors on structural type replacements like nested table-to-scalar and AOT-to-scalar. ([#255])
32
+ - Patching: fix remaining structural type replacement bugs — offset corruption when removing multiple sibling tables/AOTs, outer key loss when replacing a table/AOT with an inline object, and errors converting an array-of-tables to a plain array.
33
+ - Patching: preserve `+nan` / `-nan` sign through parse and round-trip. ([#255])
34
+ - Patching: keep a regenerated root key at root level when a section header survives alongside it — emptying an array-of-tables appended the key past the header, which silently reparented it into that section. ([#260])
35
+
10
36
  ## [2.1.0] - 2026-07-21
11
37
 
12
38
  ### Added
@@ -296,4 +322,9 @@ This first forked version from [timhall/toml-patch](https://github.com/timhall/t
296
322
  [#176]: https://github.com/DecimalTurn/toml-patch/pull/176
297
323
  [#187]: https://github.com/DecimalTurn/toml-patch/pull/187
298
324
  [#189]: https://github.com/DecimalTurn/toml-patch/pull/189
299
- [#198]: https://github.com/DecimalTurn/toml-patch/pull/198
325
+ [#198]: https://github.com/DecimalTurn/toml-patch/pull/198
326
+ [#255]: https://github.com/DecimalTurn/toml-patch/pull/255
327
+ [#253]: https://github.com/DecimalTurn/toml-patch/pull/253
328
+ [#259]: https://github.com/DecimalTurn/toml-patch/pull/259
329
+ [#260]: https://github.com/DecimalTurn/toml-patch/pull/260
330
+ [0e66e68]: https://github.com/DecimalTurn/toml-patch/commit/0e66e68cbf42a07bc44445e46c3ea7bea97f95c1
package/README.md CHANGED
@@ -32,6 +32,7 @@ We hope that these improvements can be incorporated upstream one day if the orig
32
32
  - [Methods](#methods)
33
33
  - [patch() Example](#patch-example)
34
34
  - [update() Example](#update-example)
35
+ - [Comment Ownership](#comment-ownership)
35
36
  - [Date/Time Handling & Temporal](#datetime-handling--temporal)
36
37
  - [Formatting](#formatting)
37
38
  - [TomlFormat Class](#tomlformat-class)
@@ -245,6 +246,8 @@ new TomlDocument(tomlSource: string | Uint8Array, options?: ParseOptions)
245
246
 
246
247
  Initializes the TomlDocument with TOML source, parsing it into an internal representation (CST). When bytes are provided they are decoded as UTF-8 in fatal mode, rejecting invalid sequences before parsing.
247
248
 
249
+ > **Tip:** `parseDocument(value, options)` is a convenience alternative to `new TomlDocument(value, options)`.
250
+
248
251
  **Parameters:**
249
252
  - `tomlSource: string | Uint8Array` - The TOML source to parse
250
253
  - `options?: ParseOptions` - Optional parse options
@@ -378,6 +381,36 @@ doc.update(updatedToml);
378
381
  console.log(doc.toJsObject.server.port); // 3000
379
382
  ```
380
383
 
384
+ ## Comment Ownership
385
+
386
+ When `patch()` removes or reorders an entry, any comment describing it — a same-line trailing
387
+ comment, or an own-line comment directly above with no blank line in between — travels along with
388
+ it, instead of being left behind to describe whatever ends up in that spot. This applies to root
389
+ keys, `[table]`/`[[array-of-tables]]` blocks, and elements inside multi-line arrays and inline
390
+ tables.
391
+
392
+ ```js
393
+ import * as TOML from '@decimalturn/toml-patch';
394
+ import { strict as assert } from 'assert';
395
+
396
+ const existing = `
397
+ x = 1 # a note about x
398
+ y = 2
399
+ `;
400
+
401
+ const patched = TOML.patch(existing, { y: 2 });
402
+
403
+ assert.strictEqual(patched, `
404
+ y = 2
405
+ `);
406
+ ```
407
+
408
+ See **[docs/CommentOwnership.md](docs/CommentOwnership.md)** for the full behavior, including how a
409
+ blank line opts a comment out of ownership, and current scope limitations.
410
+
411
+ Note that `patch()` does not reorder entries by default.
412
+ To have it match the key order of the object you pass in, enable [`updateOrder`](#formatting-options).
413
+
381
414
  ## Date/Time Handling & Temporal
382
415
 
383
416
  TOML date/time values are parsed into custom `Date` subclasses (`LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetDateTime`) by default. Set `temporal: true` to receive [Temporal](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects instead. `stringify()` and `patch()` auto-detect Temporal objects and serialize them correctly.
@@ -426,6 +459,7 @@ class TomlFormat {
426
459
  truncateZeroTimeInDates: boolean
427
460
  minimumDecimals?: number
428
461
  leadingBom: boolean
462
+ updateOrder?: boolean
429
463
 
430
464
  static default(): TomlFormat
431
465
  static autoDetectFormat(tomlString: string): TomlFormat
@@ -581,6 +615,61 @@ format.minimumDecimals = 1; // { x: 1, y: 1.5 } → { x = 1.0, y = 1.5 }
581
615
  format.minimumDecimals = 2; // { x: 1, y: 1.5 } → { x = 1.00, y = 1.50 }
582
616
  ```
583
617
 
618
+ **updateOrder**
619
+ - **Type:** `boolean` (optional)
620
+ - **Default:** `false`
621
+ - **Description:** Whether `patch()` should reorder entries to match the key order of the JS object you pass in, instead of preserving the existing document's order. Applies to root key-values, `[table]`/`[[array-of-tables]]` section blocks, and rows inside table bodies. Each entry's comments travel with it (see [docs/CommentOwnership.md](docs/CommentOwnership.md)). This option only affects `patch()`, and is never auto-detected — an existing document's order says nothing about what order you want.
622
+
623
+ With the option off (the default), `patch()` only changes values that actually differ, leaving order alone. Given:
624
+
625
+ ```toml
626
+ b = 2
627
+ a = 1
628
+ ```
629
+
630
+ ```js
631
+ patch(existing, { a: 1, b: 2 }); // unchanged: b = 2 then a = 1
632
+ patch(existing, { a: 1, b: 2 }, { updateOrder: true }); // reordered: a = 1 then b = 2
633
+ ```
634
+
635
+ Comments travel with their entry. Given:
636
+
637
+ ```toml
638
+ # the second one
639
+ b = 2
640
+
641
+ # the first one
642
+ a = 1
643
+ ```
644
+
645
+ `patch(existing, { a: 1, b: 2 }, { updateOrder: true })` produces:
646
+
647
+ ```toml
648
+ # the first one
649
+ a = 1
650
+
651
+ # the second one
652
+ b = 2
653
+ ```
654
+
655
+ TOML validity takes precedence over the requested order. A root key-value cannot appear after a section header (it would bind to that section), so root keys and section blocks are reordered independently of each other — a section is never pulled ahead of a root key, regardless of where it sits in the object. Given:
656
+
657
+ ```toml
658
+ [section]
659
+ key = "value"
660
+ ```
661
+
662
+ `patch(existing, { new_root: 42, section: { key: 'value' } }, { updateOrder: true })` produces:
663
+
664
+ ```toml
665
+ new_root = 42
666
+
667
+ [section]
668
+ key = "value"
669
+ ```
670
+
671
+ Some shapes are not reordered yet: the interiors of inline tables (`{ a = 1, b = 2 }`) and of `[[array-of-tables]]` entries, dotted-key implicit tables, and documents where a table's sub-tables are non-contiguous (`[a]`, `[b]`, `[a.c]` — permuting these would silently relocate unrelated sections). In each case the affected entry is left exactly where it was, and `patch()` emits a `console.warn` naming what it couldn't place so the skip isn't silent.
672
+
584
673
  ### Auto-Detection and Patching
585
674
 
586
675
  The `TomlFormat.autoDetectFormat()` method analyzes existing TOML strings to automatically detect and preserve their current formatting. If you don't supply the `format` argument when patching an existing document, this is what will be used to determine the formatting to use when inserting new elements.