@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 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.