@decimalturn/toml-patch 3.3.3-dev → 3.3.3
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/LICENSE +22 -0
- package/README.md +174 -0
- package/dist/toml-patch.js +84 -0
- package/package.json +104 -16
- package/dist/dev/comment-alignment.js +0 -371
- package/dist/dev/comment-alignment.js.map +0 -1
- package/dist/dev/comment-ownership.js +0 -672
- package/dist/dev/comment-ownership.js.map +0 -1
- package/dist/dev/cst-source.js +0 -117
- package/dist/dev/cst-source.js.map +0 -1
- package/dist/dev/cst.js +0 -67
- package/dist/dev/cst.js.map +0 -1
- package/dist/dev/cursor.js +0 -65
- package/dist/dev/cursor.js.map +0 -1
- package/dist/dev/date-format.js +0 -286
- package/dist/dev/date-format.js.map +0 -1
- package/dist/dev/decode-utf8.js +0 -26
- package/dist/dev/decode-utf8.js.map +0 -1
- package/dist/dev/diff-lite.js +0 -107
- package/dist/dev/diff-lite.js.map +0 -1
- package/dist/dev/diff.js +0 -264
- package/dist/dev/diff.js.map +0 -1
- package/dist/dev/encode-lite.js +0 -209
- package/dist/dev/encode-lite.js.map +0 -1
- package/dist/dev/escape-preference.js +0 -165
- package/dist/dev/escape-preference.js.map +0 -1
- package/dist/dev/find-by-path.js +0 -114
- package/dist/dev/find-by-path.js.map +0 -1
- package/dist/dev/formatter.js +0 -297
- package/dist/dev/formatter.js.map +0 -1
- package/dist/dev/generate.js +0 -479
- package/dist/dev/generate.js.map +0 -1
- package/dist/dev/inline-comma-space.js +0 -12
- package/dist/dev/inline-comma-space.js.map +0 -1
- package/dist/dev/inline-format.js +0 -105
- package/dist/dev/inline-format.js.map +0 -1
- package/dist/dev/inline-layout.js +0 -106
- package/dist/dev/inline-layout.js.map +0 -1
- package/dist/dev/line-ending-backslash.js +0 -319
- package/dist/dev/line-ending-backslash.js.map +0 -1
- package/dist/dev/literal-string.js +0 -45
- package/dist/dev/literal-string.js.map +0 -1
- package/dist/dev/location.js +0 -103
- package/dist/dev/location.js.map +0 -1
- package/dist/dev/parse-error.js +0 -26
- package/dist/dev/parse-error.js.map +0 -1
- package/dist/dev/parse-js.js +0 -149
- package/dist/dev/parse-js.js.map +0 -1
- package/dist/dev/parse-string.js +0 -119
- package/dist/dev/parse-string.js.map +0 -1
- package/dist/dev/parse-toml.js +0 -713
- package/dist/dev/parse-toml.js.map +0 -1
- package/dist/dev/patch-lite.js +0 -4
- package/dist/dev/patch-lite2.js +0 -96
- package/dist/dev/patch-lite2.js.map +0 -1
- package/dist/dev/patch.js +0 -3143
- package/dist/dev/patch.js.map +0 -1
- package/dist/dev/smol-toml-date.js +0 -60
- package/dist/dev/smol-toml-date.js.map +0 -1
- package/dist/dev/to-js.js +0 -307
- package/dist/dev/to-js.js.map +0 -1
- package/dist/dev/to-toml.js +0 -873
- package/dist/dev/to-toml.js.map +0 -1
- package/dist/dev/tokenizer.js +0 -224
- package/dist/dev/tokenizer.js.map +0 -1
- package/dist/dev/toml-document.js +0 -220
- package/dist/dev/toml-document.js.map +0 -1
- package/dist/dev/toml-format.js +0 -548
- package/dist/dev/toml-format.js.map +0 -1
- package/dist/dev/toml-patch.js +0 -93
- package/dist/dev/toml-patch.js.map +0 -1
- package/dist/dev/traverse.js +0 -60
- package/dist/dev/traverse.js.map +0 -1
- package/dist/dev/truncate.js +0 -63
- package/dist/dev/truncate.js.map +0 -1
- package/dist/dev/update-order.js +0 -234
- package/dist/dev/update-order.js.map +0 -1
- package/dist/dev/utils.js +0 -295
- package/dist/dev/utils.js.map +0 -1
- package/dist/dev/writer.js +0 -757
- package/dist/dev/writer.js.map +0 -1
- package/dist/patch-lite.d.ts +0 -16
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2019–2025 Tim Hall
|
|
4
|
+
Copyright (c) 2025 Martin Leduc
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
<img src="assets/toml-patch-logo.png" alt="toml-patch logo" width="120"/>
|
|
2
|
+
|
|
3
|
+
# toml-patch
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@decimalturn/toml-patch)
|
|
6
|
+
[](https://jsr.io/@decimalturn/toml-patch)
|
|
7
|
+
[](https://github.com/DecimalTurn/toml-patch/actions/workflows/test-and-build.yml)
|
|
8
|
+
|
|
9
|
+
Patch, parse, and stringify [TOML](https://toml.io/en/) (v1.1.0) while preserving comments, whitespace and formatting.
|
|
10
|
+
|
|
11
|
+
This project started as a fork of the [original toml-patch](https://github.com/timhall/toml-patch) but has since evolved into a standalone project with significant improvements in reliability and features. We've added TOML v1.1 support, introduced new APIs like `TomlDocument` and `TomlFormat` classes, fixed numerous bugs through increase in testing namely with [toml-test](https://github.com/toml-lang/toml-test).
|
|
12
|
+
|
|
13
|
+
We hope that these improvements can be incorporated upstream one day if the original author returns, but until then, this project is the actively maintained version.
|
|
14
|
+
|
|
15
|
+
## Documentation
|
|
16
|
+
|
|
17
|
+
- [Installation](#installation)
|
|
18
|
+
- [API](#api)
|
|
19
|
+
- [Patch-lite](#patch-lite)
|
|
20
|
+
- [Comment ownership](#comment-ownership)
|
|
21
|
+
- [Date/time handling and Temporal](#datetime-handling--temporal)
|
|
22
|
+
- [Formatting](#formatting)
|
|
23
|
+
- [Changelog](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/CHANGELOG.md)
|
|
24
|
+
- [Contributing](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/CONTRIBUTING.md)
|
|
25
|
+
- [MIT License](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/LICENSE)
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
toml-patch is dependency-free and can be installed via your favorite package manager.
|
|
30
|
+
|
|
31
|
+
*Example with NPM*
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
$ npm install --save @decimalturn/toml-patch
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For the standalone lite distribution, install the `lite` npm dist-tag:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
$ npm install --save @decimalturn/toml-patch@lite
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
For browser usage, you can use unpkg:
|
|
44
|
+
|
|
45
|
+
```html
|
|
46
|
+
<script type="module">
|
|
47
|
+
import * as TOML from 'https://unpkg.com/@decimalturn/toml-patch@v3.3.3/dist/toml-patch.js';
|
|
48
|
+
</script>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## API
|
|
52
|
+
|
|
53
|
+
`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.
|
|
54
|
+
|
|
55
|
+
See the [API reference](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/API.md) for `patch`, `parse`, `stringify` and the `TomlDocument` class.
|
|
56
|
+
|
|
57
|
+
For a quick start, patch an existing TOML string like this:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { patch } from '@decimalturn/toml-patch';
|
|
61
|
+
|
|
62
|
+
const existing = 'title = "TOML example"\nowner.name = "Bob"\n';
|
|
63
|
+
const updated = patch(existing, {
|
|
64
|
+
title: 'TOML example',
|
|
65
|
+
owner: { name: 'Tim' }
|
|
66
|
+
});
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Comment Ownership
|
|
70
|
+
|
|
71
|
+
When `patch()` removes or reorders an entry, any comment describing it (a same-line trailing
|
|
72
|
+
comment, or a line-comment directly above with no blank line in between) travels along with
|
|
73
|
+
it, instead of being left behind to describe whatever ends up in that spot. This applies to root
|
|
74
|
+
keys, `[table]`/`[[array-of-tables]]` blocks, and elements inside multi-line arrays and inline
|
|
75
|
+
tables.
|
|
76
|
+
|
|
77
|
+
```js
|
|
78
|
+
import * as TOML from '@decimalturn/toml-patch';
|
|
79
|
+
import { strict as assert } from 'assert';
|
|
80
|
+
|
|
81
|
+
const existing = `
|
|
82
|
+
x = 1 # a note about x
|
|
83
|
+
y = 2
|
|
84
|
+
`;
|
|
85
|
+
|
|
86
|
+
const patched = TOML.patch(existing, { y: 2 });
|
|
87
|
+
|
|
88
|
+
assert.strictEqual(patched, `
|
|
89
|
+
y = 2
|
|
90
|
+
`);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
See the [comment ownership guide](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/Comment-Ownership.md) for the full behavior, including how a blank line opts a comment out of ownership and current scope limitations.
|
|
94
|
+
|
|
95
|
+
Note that `patch()` does not reorder entries by default.
|
|
96
|
+
To have it match the key order of the object you pass in, enable `updateOrder` in the [formatting options](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/Formatting.md#updateorder).
|
|
97
|
+
|
|
98
|
+
## Date/Time Handling & Temporal
|
|
99
|
+
|
|
100
|
+
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. Fractional seconds keep the source precision, sub-millisecond digits included.
|
|
101
|
+
|
|
102
|
+
### Enabling Temporal
|
|
103
|
+
|
|
104
|
+
The `temporal: true` option requires `Temporal` to be available in the runtime:
|
|
105
|
+
|
|
106
|
+
| Runtime | How to enable |
|
|
107
|
+
|---|---|
|
|
108
|
+
| **Node.js 26+** | Built-in (no config needed) |
|
|
109
|
+
| **Node.js 20–24** | `node --harmony-temporal` flag |
|
|
110
|
+
| **Node.js 14–26** | [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill) |
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
import * as TOML from '@decimalturn/toml-patch';
|
|
114
|
+
|
|
115
|
+
// Node 26+ (native) or Node 20–24 with --harmony-temporal:
|
|
116
|
+
const obj = TOML.parse('d = 2024-01-15\n', { temporal: true });
|
|
117
|
+
// obj.d → Temporal.PlainDate
|
|
118
|
+
|
|
119
|
+
// All Node versions with the polyfill:
|
|
120
|
+
import { Temporal } from '@js-temporal/polyfill';
|
|
121
|
+
globalThis.Temporal = Temporal;
|
|
122
|
+
const obj2 = TOML.parse('d = 2024-01-15\n', { temporal: true });
|
|
123
|
+
// obj2.d → PlainDate (polyfill)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
> **Note:** Only offset-based timezones (`+05:30`, `Z`) are supported in TOML. IANA timezone annotations (e.g., `[Asia/Kolkata]`) will throw an error.
|
|
127
|
+
|
|
128
|
+
See the [date/time guide](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/Dates.md) for details and examples.
|
|
129
|
+
|
|
130
|
+
## Patch-lite
|
|
131
|
+
|
|
132
|
+
`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.
|
|
133
|
+
|
|
134
|
+
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:
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
npm install --save @decimalturn/toml-patch@lite
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import { patch } from '@decimalturn/toml-patch';
|
|
142
|
+
|
|
143
|
+
const existing = 'version = "1.0.0"\n';
|
|
144
|
+
const updated = patch(existing, { version: '1.0.1' });
|
|
145
|
+
// updated === 'version = "1.0.1"\n'
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
For more info, check out the [Patch-lite guide](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/Patch-Lite.md)
|
|
149
|
+
|
|
150
|
+
## Formatting
|
|
151
|
+
|
|
152
|
+
The `TomlFormat` class controls how TOML documents are formatted during stringification and patching operations.
|
|
153
|
+
|
|
154
|
+
The recommended approach is to start with `TomlFormat.default()` and override the options you need. e.g.:
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
import { stringify, TomlFormat } from '@decimalturn/toml-patch';
|
|
158
|
+
|
|
159
|
+
const format = TomlFormat.default();
|
|
160
|
+
format.newLine = '\r\n';
|
|
161
|
+
format.trailingNewline = 0;
|
|
162
|
+
format.trailingComma = true;
|
|
163
|
+
format.bracketSpacing = false;
|
|
164
|
+
format.indentWidth = 4;
|
|
165
|
+
format.multilineTable = 'parent';
|
|
166
|
+
|
|
167
|
+
const toml = stringify({
|
|
168
|
+
title: 'My App',
|
|
169
|
+
tags: ['dev', 'config'],
|
|
170
|
+
database: { host: 'localhost', port: 5432 }
|
|
171
|
+
}, format);
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
See the [formatting reference](https://github.com/DecimalTurn/toml-patch/blob/v3.3.3/docs/Formatting.md) for the complete list of options, auto-detection behavior, `updateOrder` and more examples.
|