@decimalturn/toml-patch 2.1.0 → 3.0.1
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 +52 -1
- package/README.md +89 -0
- package/dist/toml-patch.d.ts +338 -306
- package/dist/toml-patch.js +38 -2
- package/package.json +6 -10
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.1] - 2026-08-03
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- Parsing: reject surrogates in `\UXXXXXXXX` escapes. ([#261])
|
|
15
|
+
- Stringify/Patching: reject unpaired surrogates in string values and keys instead of emitting invalid UTF-8. ([#261])
|
|
16
|
+
- Patching: indent a new first element of a multi-line array to match its sibling rows instead of the opening bracket. ([#263])
|
|
17
|
+
- Patching: give each element its own row when inserting more than one into the same multi-line array in a single patch. ([#264])
|
|
18
|
+
- Patching: drop an array element's comment with it when the array is the value of a multi-line inline table key. ([#264])
|
|
19
|
+
- Patching: reclaim a removed section's blank separator, so deleting sections no longer accumulates blank lines. ([#265])
|
|
20
|
+
- Patching: stop reading the removal of a key whose value matches an untouched sibling as a rename onto that sibling, which emitted the key twice and produced invalid TOML. ([#262])
|
|
21
|
+
- Patching: remove an array-of-tables key entirely when it is deleted, instead of bringing it back as `key = []`. ([#266])
|
|
22
|
+
- Patching: re-materialise an emptied nested array-of-tables as `a.b = []` rather than a root key quoted `"a.b"`. ([#266])
|
|
23
|
+
|
|
24
|
+
## [3.0.0] - 2026-07-29
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
|
|
28
|
+
- **BREAKING**: Raise minimum supported Node.js version from `>=14` to `>=16`.
|
|
29
|
+
- 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])
|
|
30
|
+
- Improve stringification performance ([0e66e68])
|
|
31
|
+
|
|
32
|
+
### Added
|
|
33
|
+
|
|
34
|
+
- TomlDocument: New `parseDocument` function that parses a TOML string into a `TomlDocument`
|
|
35
|
+
- 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])
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- Patching: Ensure all elements of nested tables are preserved when using `inlineTableStart` is 2 or higher. ([#253])
|
|
40
|
+
- Patching: prevent whitespace errors when swaping keys between tables.
|
|
41
|
+
- Patching: handle BigInt values in documents without throwing. ([#255])
|
|
42
|
+
- Patching: handle commented multiline arrays correctly when adding keys or emptying them. ([#255])
|
|
43
|
+
- Patching: fix wrong section nesting when replacing a table with a scalar value. ([#255])
|
|
44
|
+
- Patching: preserve key with inline empty array when emptying an array-of-tables. ([#255])
|
|
45
|
+
- Patching: fix `Node not found` errors on structural type replacements like nested table-to-scalar and AOT-to-scalar. ([#255])
|
|
46
|
+
- 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.
|
|
47
|
+
- Patching: preserve `+nan` / `-nan` sign through parse and round-trip. ([#255])
|
|
48
|
+
- 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])
|
|
49
|
+
|
|
10
50
|
## [2.1.0] - 2026-07-21
|
|
11
51
|
|
|
12
52
|
### Added
|
|
@@ -296,4 +336,15 @@ This first forked version from [timhall/toml-patch](https://github.com/timhall/t
|
|
|
296
336
|
[#176]: https://github.com/DecimalTurn/toml-patch/pull/176
|
|
297
337
|
[#187]: https://github.com/DecimalTurn/toml-patch/pull/187
|
|
298
338
|
[#189]: https://github.com/DecimalTurn/toml-patch/pull/189
|
|
299
|
-
[#198]: https://github.com/DecimalTurn/toml-patch/pull/198
|
|
339
|
+
[#198]: https://github.com/DecimalTurn/toml-patch/pull/198
|
|
340
|
+
[#255]: https://github.com/DecimalTurn/toml-patch/pull/255
|
|
341
|
+
[#253]: https://github.com/DecimalTurn/toml-patch/pull/253
|
|
342
|
+
[#259]: https://github.com/DecimalTurn/toml-patch/pull/259
|
|
343
|
+
[#260]: https://github.com/DecimalTurn/toml-patch/pull/260
|
|
344
|
+
[#261]: https://github.com/DecimalTurn/toml-patch/pull/261
|
|
345
|
+
[#262]: https://github.com/DecimalTurn/toml-patch/issues/262
|
|
346
|
+
[#263]: https://github.com/DecimalTurn/toml-patch/pull/263
|
|
347
|
+
[#264]: https://github.com/DecimalTurn/toml-patch/pull/264
|
|
348
|
+
[#265]: https://github.com/DecimalTurn/toml-patch/pull/265
|
|
349
|
+
[#266]: https://github.com/DecimalTurn/toml-patch/pull/266
|
|
350
|
+
[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.
|