@decimalturn/toml-patch 2.0.1 → 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 +39 -1
- package/README.md +124 -0
- package/dist/toml-patch.d.ts +346 -284
- package/dist/toml-patch.js +38 -2
- package/package.json +13 -18
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,39 @@ 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
|
+
|
|
36
|
+
## [2.1.0] - 2026-07-21
|
|
37
|
+
|
|
38
|
+
### Added
|
|
39
|
+
|
|
40
|
+
- Parsing: New `temporal` option in `ParseOptions`. When `true`, TOML date/time values are returned as [Temporal](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects (`Temporal.PlainDate`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, `Temporal.ZonedDateTime`) instead of custom `Date` subclasses.
|
|
41
|
+
- Stringify: Auto-detect Temporal objects in the input JS and serialize them to the correct TOML date/time type. Note that `ZonedDateTime` with IANA timezone annotations will throws an error (TOML only supports numerical offsets).
|
|
42
|
+
|
|
10
43
|
## [2.0.1] - 2026-07-19
|
|
11
44
|
|
|
12
45
|
### Fixed
|
|
@@ -289,4 +322,9 @@ This first forked version from [timhall/toml-patch](https://github.com/timhall/t
|
|
|
289
322
|
[#176]: https://github.com/DecimalTurn/toml-patch/pull/176
|
|
290
323
|
[#187]: https://github.com/DecimalTurn/toml-patch/pull/187
|
|
291
324
|
[#189]: https://github.com/DecimalTurn/toml-patch/pull/189
|
|
292
|
-
[#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,8 @@ 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)
|
|
36
|
+
- [Date/Time Handling & Temporal](#datetime-handling--temporal)
|
|
35
37
|
- [Formatting](#formatting)
|
|
36
38
|
- [TomlFormat Class](#tomlformat-class)
|
|
37
39
|
- [Basic Usage](#basic-usage)
|
|
@@ -162,6 +164,7 @@ Parses a TOML string (or raw UTF-8 bytes) into a JavaScript object.
|
|
|
162
164
|
- `'asNeeded'` *(default)* — integers within the JS safe-integer range are `number`; larger values are `bigint` to preserve precision
|
|
163
165
|
- `true` — all integers are returned as `bigint`
|
|
164
166
|
- `false` — all integers are returned as `number` (large values lose precision)
|
|
167
|
+
- `temporal?: boolean` — When `true`, TOML date/time values are returned as [Temporal](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects instead of custom `Date` subclasses. Default: `false`. Requires Temporal in the runtime (Node 26+ native, Node 20–24 with `--harmony-temporal`, or [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill) on any version). See [Date/Time Handling](#datetime-handling--temporal).
|
|
165
168
|
|
|
166
169
|
**Returns:** `any` - The parsed JavaScript object
|
|
167
170
|
|
|
@@ -243,6 +246,8 @@ new TomlDocument(tomlSource: string | Uint8Array, options?: ParseOptions)
|
|
|
243
246
|
|
|
244
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.
|
|
245
248
|
|
|
249
|
+
> **Tip:** `parseDocument(value, options)` is a convenience alternative to `new TomlDocument(value, options)`.
|
|
250
|
+
|
|
246
251
|
**Parameters:**
|
|
247
252
|
- `tomlSource: string | Uint8Array` - The TOML source to parse
|
|
248
253
|
- `options?: ParseOptions` - Optional parse options
|
|
@@ -250,6 +255,7 @@ Initializes the TomlDocument with TOML source, parsing it into an internal repre
|
|
|
250
255
|
- `'asNeeded'` *(default)* — integers within the JS safe-integer range are `number`; larger values are `bigint` to preserve precision
|
|
251
256
|
- `true` — all integers are returned as `bigint`
|
|
252
257
|
- `false` — all integers are returned as `number` (large values lose precision)
|
|
258
|
+
- `temporal?: boolean` — When `true`, TOML date/time values are returned as [Temporal](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects. Default: `false`. Requires Temporal in the runtime (Node 26+ native, Node 20–24 with `--harmony-temporal`, or [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill) on any version). See [Date/Time Handling](#datetime-handling--temporal).
|
|
253
259
|
|
|
254
260
|
##### Basic Usage Example
|
|
255
261
|
|
|
@@ -375,6 +381,68 @@ doc.update(updatedToml);
|
|
|
375
381
|
console.log(doc.toJsObject.server.port); // 3000
|
|
376
382
|
```
|
|
377
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
|
+
|
|
414
|
+
## Date/Time Handling & Temporal
|
|
415
|
+
|
|
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.
|
|
417
|
+
|
|
418
|
+
### Enabling Temporal
|
|
419
|
+
|
|
420
|
+
The `temporal: true` option requires `Temporal` to be available in the runtime:
|
|
421
|
+
|
|
422
|
+
| Runtime | How to enable |
|
|
423
|
+
|---|---|
|
|
424
|
+
| **Node.js 26+** | Built-in — enable with `temporal: true` |
|
|
425
|
+
| **Node.js 20–24** | `node --harmony-temporal` flag |
|
|
426
|
+
| **Node.js 14–26** | [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill) |
|
|
427
|
+
|
|
428
|
+
```js
|
|
429
|
+
import * as TOML from '@decimalturn/toml-patch';
|
|
430
|
+
|
|
431
|
+
// Node 26+ (native) or Node 20–24 with --harmony-temporal:
|
|
432
|
+
const obj = TOML.parse('d = 2024-01-15\n', { temporal: true });
|
|
433
|
+
// obj.d → Temporal.PlainDate
|
|
434
|
+
|
|
435
|
+
// All Node versions with the polyfill:
|
|
436
|
+
import { Temporal } from '@js-temporal/polyfill';
|
|
437
|
+
globalThis.Temporal = Temporal;
|
|
438
|
+
const obj2 = TOML.parse('d = 2024-01-15\n', { temporal: true });
|
|
439
|
+
// obj2.d → PlainDate (polyfill)
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
> **Note:** Only offset-based timezones (`+05:30`, `Z`) are supported in TOML. IANA timezone annotations (e.g., `[Asia/Kolkata]`) will throw an error.
|
|
443
|
+
|
|
444
|
+
See **[docs/Dates.md](docs/Dates.md)** for details and examples.
|
|
445
|
+
|
|
378
446
|
## Formatting
|
|
379
447
|
|
|
380
448
|
The `TomlFormat` class provides decent control over how TOML documents are formatted during stringification and patching operations. This class encapsulates all formatting preferences, making it easy to maintain consistent styling across your TOML documents.
|
|
@@ -391,6 +459,7 @@ class TomlFormat {
|
|
|
391
459
|
truncateZeroTimeInDates: boolean
|
|
392
460
|
minimumDecimals?: number
|
|
393
461
|
leadingBom: boolean
|
|
462
|
+
updateOrder?: boolean
|
|
394
463
|
|
|
395
464
|
static default(): TomlFormat
|
|
396
465
|
static autoDetectFormat(tomlString: string): TomlFormat
|
|
@@ -546,6 +615,61 @@ format.minimumDecimals = 1; // { x: 1, y: 1.5 } → { x = 1.0, y = 1.5 }
|
|
|
546
615
|
format.minimumDecimals = 2; // { x: 1, y: 1.5 } → { x = 1.00, y = 1.50 }
|
|
547
616
|
```
|
|
548
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
|
+
|
|
549
673
|
### Auto-Detection and Patching
|
|
550
674
|
|
|
551
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.
|