@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/dist/toml-patch.d.ts
CHANGED
|
@@ -1,255 +1,294 @@
|
|
|
1
|
-
|
|
1
|
+
|
|
2
|
+
//#region src/toml-format.d.ts
|
|
2
3
|
declare class TomlFormat {
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
4
|
+
/**
|
|
5
|
+
* The line ending character(s) to use in the output TOML.
|
|
6
|
+
* This option affects only the stringification process, not the internal representation (CST).
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* - '\n' for Unix/Linux line endings
|
|
10
|
+
* - '\r\n' for Windows line endings
|
|
11
|
+
*/
|
|
12
|
+
newLine: string;
|
|
13
|
+
/**
|
|
14
|
+
* The number of trailing newlines to add at the end of the TOML document.
|
|
15
|
+
* This option affects only the stringification process, not the internal representation (CST).
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* - 0: No trailing newline
|
|
19
|
+
* - 1: One trailing newline (standard)
|
|
20
|
+
* - 2: Two trailing newlines (adds extra spacing)
|
|
21
|
+
*/
|
|
22
|
+
trailingNewline: number;
|
|
23
|
+
/**
|
|
24
|
+
* Whether to add trailing commas after the last element in arrays and inline tables.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* - true: [1, 2, 3,] and { x = 1, y = 2, }
|
|
28
|
+
* - false: [1, 2, 3] and { x = 1, y = 2 }
|
|
29
|
+
*/
|
|
30
|
+
trailingComma: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Whether to add spaces after opening brackets/braces and before closing brackets/braces
|
|
33
|
+
* in arrays and inline tables.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* - true: [ 1, 2, 3 ] and { x = 1, y = 2 }
|
|
37
|
+
* - false: [1, 2, 3] and {x = 1, y = 2}
|
|
38
|
+
*/
|
|
39
|
+
bracketSpacing: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Whether the output should include a leading UTF-8 BOM marker (U+FEFF).
|
|
42
|
+
*
|
|
43
|
+
* This is auto-detected from the source TOML and preserved during patching.
|
|
44
|
+
*/
|
|
45
|
+
leadingBom: boolean;
|
|
46
|
+
/**
|
|
47
|
+
* The nesting depth at which new tables should start being formatted as inline tables.
|
|
48
|
+
* When adding new tables during patching or stringifying objects:
|
|
49
|
+
* - Tables at depth >= inlineTableStart will be formatted as inline tables
|
|
50
|
+
* - Tables at depth < inlineTableStart will be formatted as separate table sections
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* - 0: All tables are inline tables including top-level tables (root level)
|
|
54
|
+
* - 1: Top-level tables as sections, nested tables as inline (default)
|
|
55
|
+
* - 2: Two levels as sections, deeper nesting as inline
|
|
56
|
+
*/
|
|
57
|
+
inlineTableStart?: number;
|
|
58
|
+
/**
|
|
59
|
+
* Whether to truncate time components in UTC date fields when they are zero.
|
|
60
|
+
* This setting affects only the stringification process.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* - true: Date('2024-01-15T00:00:00.000Z') serializes as 2024-01-15
|
|
64
|
+
* - false: Date('2024-01-15T00:00:00.000Z') serializes as 2024-01-15T00:00:00.000Z
|
|
65
|
+
*
|
|
66
|
+
*/
|
|
67
|
+
truncateZeroTimeInDates?: boolean;
|
|
68
|
+
/**
|
|
69
|
+
* Whether to use tabs instead of spaces for indentation/padding.
|
|
70
|
+
* When enabled, lines that need to be indented will use tabs.
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* - true: Uses tabs for indentation
|
|
74
|
+
* - false: Uses spaces for indentation (default)
|
|
75
|
+
*
|
|
76
|
+
*/
|
|
77
|
+
useTabsForIndentation?: boolean;
|
|
78
|
+
/**
|
|
79
|
+
* The minimum number of decimal places to use when serializing JS numbers as TOML floats.
|
|
80
|
+
* When greater than 0, plain JS integer values are serialized as TOML floats padded with
|
|
81
|
+
* zeros to reach the specified decimal count. BigInt values are always serialized as integers
|
|
82
|
+
* regardless of this setting.
|
|
83
|
+
*
|
|
84
|
+
* @example
|
|
85
|
+
* - 0: stringify({ x: 1, y: 1.5 }) → x = 1 / y = 1.5 (default)
|
|
86
|
+
* - 1: stringify({ x: 1, y: 1.5 }) → x = 1.0 / y = 1.5
|
|
87
|
+
* - 2: stringify({ x: 1, y: 1.5 }) → x = 1.00 / y = 1.50
|
|
88
|
+
*/
|
|
89
|
+
minimumDecimals?: number;
|
|
90
|
+
/**
|
|
91
|
+
* Whether `patch()` should reorder root key-values, `[table]`/`[[array]]` section blocks,
|
|
92
|
+
* and rows inside table bodies to match the key order of the JS object passed to `patch()`,
|
|
93
|
+
* carrying each entry's owned comments along with it (see docs/CommentOwnership.md).
|
|
94
|
+
*
|
|
95
|
+
* Off by default: with the option unset or `false`, `patch()` only ever changes values that
|
|
96
|
+
* actually differ between the existing document and the updated object, preserving the
|
|
97
|
+
* existing document's order even when the JS object's key order differs.
|
|
98
|
+
*
|
|
99
|
+
* Not auto-detectable — the existing document's order says nothing about the caller's
|
|
100
|
+
* intent, so `autoDetectFormatWithCst` always resolves this to `false`.
|
|
101
|
+
*
|
|
102
|
+
* See docs/PLAN-Update-Order.md for the full behavior and current scope limitations.
|
|
103
|
+
*/
|
|
104
|
+
updateOrder?: boolean;
|
|
105
|
+
constructor(newLine?: string, trailingNewline?: number, trailingComma?: boolean, bracketSpacing?: boolean, inlineTableStart?: number, truncateZeroTimeInDates?: boolean, useTabsForIndentation?: boolean, minimumDecimals?: number, leadingBom?: boolean, updateOrder?: boolean);
|
|
106
|
+
/**
|
|
107
|
+
* Creates a new TomlFormat instance with default formatting preferences.
|
|
108
|
+
*
|
|
109
|
+
* @returns A new TomlFormat instance with default values:
|
|
110
|
+
* - newLine: '\n'
|
|
111
|
+
* - trailingNewline: 1
|
|
112
|
+
* - trailingComma: false
|
|
113
|
+
* - bracketSpacing: true
|
|
114
|
+
* - leadingBom: false
|
|
115
|
+
* - inlineTableStart: 1
|
|
116
|
+
* - truncateZeroTimeInDates: false
|
|
117
|
+
* - useTabsForIndentation: false
|
|
118
|
+
* - minimumDecimals: 0
|
|
119
|
+
*/
|
|
120
|
+
static default(): TomlFormat;
|
|
121
|
+
/**
|
|
122
|
+
* Auto-detects formatting preferences from an existing TOML string.
|
|
123
|
+
*
|
|
124
|
+
* This method analyzes the provided TOML string to determine formatting
|
|
125
|
+
* preferences such as line endings, trailing newlines, and comma usage.
|
|
126
|
+
*
|
|
127
|
+
* @param tomlString - The TOML string to analyze for formatting patterns
|
|
128
|
+
* @returns A new TomlFormat instance with detected formatting preferences
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```typescript
|
|
132
|
+
* const toml = 'array = ["a", "b", "c",]\ntable = { x = 1, y = 2, }';
|
|
133
|
+
* const format = TomlFormat.autoDetectFormat(toml);
|
|
134
|
+
* // format.trailingComma will be true
|
|
135
|
+
* // format.newLine will be '\n'
|
|
136
|
+
* // format.trailingNewline will be 0 (no trailing newline)
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
139
|
+
static autoDetectFormat(tomlString: string): TomlFormat;
|
|
140
|
+
/**
|
|
141
|
+
* Internal method: Auto-detects formatting preferences from a TOML string with optional pre-parsed CST.
|
|
142
|
+
*
|
|
143
|
+
* This is used internally to avoid redundant parsing when the CST is already available.
|
|
144
|
+
* External callers should use `autoDetectFormat(tomlString)` instead.
|
|
145
|
+
*
|
|
146
|
+
* @internal
|
|
147
|
+
* @param tomlString - The TOML string to analyze for formatting patterns
|
|
148
|
+
* @param syntaxTree - Optional pre-parsed CST to avoid redundant parsing
|
|
149
|
+
* @returns A new TomlFormat instance with detected formatting preferences
|
|
150
|
+
*/
|
|
151
|
+
static autoDetectFormatWithCst(tomlString: string, syntaxTree?: Iterable<any>): TomlFormat;
|
|
152
|
+
/** @deprecated Use autoDetectFormatWithCst instead. */
|
|
153
|
+
static autoDetectFormatWithAst(tomlString: string, syntaxTree?: Iterable<any>): TomlFormat;
|
|
138
154
|
}
|
|
139
|
-
|
|
155
|
+
//#endregion
|
|
156
|
+
//#region src/parse-options.d.ts
|
|
140
157
|
type IntegersAsBigInt = boolean | 'asNeeded';
|
|
141
158
|
interface ParseOptions {
|
|
142
|
-
|
|
159
|
+
/**
|
|
160
|
+
* Controls how TOML integers are returned in the parsed JavaScript object.
|
|
161
|
+
* - `true`: All integers are returned as `bigint`.
|
|
162
|
+
* - `false`: All integers are returned as `number` (may lose precision for large integers).
|
|
163
|
+
* - `'asNeeded'` (default): Integers that fit within the JavaScript safe-integer range are returned as `number`; larger integers are returned as `bigint`.
|
|
164
|
+
*/
|
|
165
|
+
integersAsBigInt?: IntegersAsBigInt;
|
|
166
|
+
/**
|
|
167
|
+
* When true, TOML date/time values are parsed into Temporal objects
|
|
168
|
+
* (Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainDateTime,
|
|
169
|
+
* Temporal.ZonedDateTime) instead of custom Date subclasses.
|
|
170
|
+
*
|
|
171
|
+
* The Temporal API must be available in the runtime.
|
|
172
|
+
* - Node.js >= v26: full native support.
|
|
173
|
+
* - Node.js < v26: enable with the `--harmony-temporal` flag.
|
|
174
|
+
* - Modern browsers: native support.
|
|
175
|
+
* - Other runtimes: use @js-temporal/polyfill.
|
|
176
|
+
*
|
|
177
|
+
* Default: false (returns custom Date subclasses for backward compatibility).
|
|
178
|
+
*/
|
|
179
|
+
temporal?: boolean;
|
|
143
180
|
}
|
|
144
|
-
|
|
181
|
+
//#endregion
|
|
182
|
+
//#region src/location.d.ts
|
|
145
183
|
interface Location {
|
|
146
|
-
|
|
147
|
-
|
|
184
|
+
start: Position;
|
|
185
|
+
end: Position;
|
|
148
186
|
}
|
|
149
187
|
interface Position {
|
|
150
|
-
|
|
151
|
-
|
|
188
|
+
line: number;
|
|
189
|
+
column: number;
|
|
152
190
|
}
|
|
153
|
-
|
|
191
|
+
//#endregion
|
|
192
|
+
//#region src/cst.d.ts
|
|
154
193
|
declare enum NodeType {
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
194
|
+
Document = "Document",
|
|
195
|
+
Table = "Table",
|
|
196
|
+
TableKey = "TableKey",
|
|
197
|
+
/**
|
|
198
|
+
* Array of Tables node
|
|
199
|
+
* More info: https://toml.io/en/latest#array-of-tables
|
|
200
|
+
*/
|
|
201
|
+
TableArray = "TableArray",
|
|
202
|
+
TableArrayKey = "TableArrayKey",
|
|
203
|
+
KeyValue = "KeyValue",
|
|
204
|
+
Key = "Key",
|
|
205
|
+
String = "String",
|
|
206
|
+
Integer = "Integer",
|
|
207
|
+
Float = "Float",
|
|
208
|
+
Boolean = "Boolean",
|
|
209
|
+
DateTime = "DateTime",
|
|
210
|
+
InlineArray = "InlineArray",
|
|
211
|
+
InlineItem = "InlineItem",
|
|
212
|
+
InlineTable = "InlineTable",
|
|
213
|
+
/**
|
|
214
|
+
* Comment node
|
|
215
|
+
* More info: https://toml.io/en/latest#comment
|
|
216
|
+
*/
|
|
217
|
+
Comment = "Comment"
|
|
179
218
|
}
|
|
180
219
|
interface Table extends TreeNode {
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
220
|
+
type: NodeType.Table;
|
|
221
|
+
key: TableKey;
|
|
222
|
+
items: RowItem[];
|
|
184
223
|
}
|
|
185
224
|
interface TableKey extends TreeNode {
|
|
186
|
-
|
|
187
|
-
|
|
225
|
+
type: NodeType.TableKey;
|
|
226
|
+
item: Key;
|
|
188
227
|
}
|
|
189
228
|
interface TableArray extends TreeNode {
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
229
|
+
type: NodeType.TableArray;
|
|
230
|
+
key: TableArrayKey;
|
|
231
|
+
items: RowItem[];
|
|
193
232
|
}
|
|
194
233
|
interface TableArrayKey extends TreeNode {
|
|
195
|
-
|
|
196
|
-
|
|
234
|
+
type: NodeType.TableArrayKey;
|
|
235
|
+
item: Key;
|
|
197
236
|
}
|
|
198
237
|
interface KeyValue extends TreeNode {
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
238
|
+
type: NodeType.KeyValue;
|
|
239
|
+
key: Key;
|
|
240
|
+
value: Value;
|
|
241
|
+
equals: number;
|
|
203
242
|
}
|
|
204
243
|
interface Key extends TreeNode {
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
244
|
+
type: NodeType.Key;
|
|
245
|
+
raw: string;
|
|
246
|
+
value: string[];
|
|
208
247
|
}
|
|
209
248
|
interface String extends TreeNode {
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
249
|
+
type: NodeType.String;
|
|
250
|
+
raw: string;
|
|
251
|
+
value: string;
|
|
213
252
|
}
|
|
214
253
|
interface Integer extends TreeNode {
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
254
|
+
type: NodeType.Integer;
|
|
255
|
+
raw: string;
|
|
256
|
+
value: number | bigint;
|
|
218
257
|
}
|
|
219
258
|
interface Float extends TreeNode {
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
259
|
+
type: NodeType.Float;
|
|
260
|
+
raw: string;
|
|
261
|
+
value: number;
|
|
262
|
+
/** Sign prefix for NaN values: '+' for +nan, '-' for -nan, undefined for nan */
|
|
263
|
+
nanSign?: '+' | '-';
|
|
223
264
|
}
|
|
224
265
|
interface Boolean extends TreeNode {
|
|
225
|
-
|
|
226
|
-
|
|
266
|
+
type: NodeType.Boolean;
|
|
267
|
+
value: boolean;
|
|
227
268
|
}
|
|
228
269
|
interface DateTime extends TreeNode {
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
270
|
+
type: NodeType.DateTime;
|
|
271
|
+
raw: string;
|
|
272
|
+
value: Date;
|
|
232
273
|
}
|
|
233
274
|
interface InlineArray<TItem = TreeNode> extends TreeNode {
|
|
234
|
-
|
|
235
|
-
|
|
275
|
+
type: NodeType.InlineArray;
|
|
276
|
+
items: InlineArrayItem<TItem>[];
|
|
236
277
|
}
|
|
237
278
|
interface InlineItem<TItem = TreeNode> extends TreeNode {
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
}
|
|
242
|
-
interface InlineArrayItem<TItem = TreeNode> extends InlineItem<TItem> {
|
|
279
|
+
type: NodeType.InlineItem;
|
|
280
|
+
item: TItem;
|
|
281
|
+
comma: boolean;
|
|
243
282
|
}
|
|
283
|
+
interface InlineArrayItem<TItem = TreeNode> extends InlineItem<TItem> {}
|
|
244
284
|
interface InlineTable extends TreeNode {
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
}
|
|
248
|
-
interface InlineTableItem extends InlineItem<KeyValue> {
|
|
285
|
+
type: NodeType.InlineTable;
|
|
286
|
+
items: InlineTableItem[];
|
|
249
287
|
}
|
|
288
|
+
interface InlineTableItem extends InlineItem<KeyValue> {}
|
|
250
289
|
interface Comment extends TreeNode {
|
|
251
|
-
|
|
252
|
-
|
|
290
|
+
type: NodeType.Comment;
|
|
291
|
+
raw: string;
|
|
253
292
|
}
|
|
254
293
|
/**
|
|
255
294
|
* RowItem represents items that can appear inside Table and TableArray sections.
|
|
@@ -302,10 +341,64 @@ type RowItem = KeyValue | Comment;
|
|
|
302
341
|
type Block = KeyValue | Table | TableArray | Comment;
|
|
303
342
|
type Value<TInlineArrayItem = TreeNode> = String | Integer | Float | Boolean | DateTime | InlineArray<TInlineArrayItem> | InlineTable;
|
|
304
343
|
interface TreeNode {
|
|
305
|
-
|
|
306
|
-
|
|
344
|
+
type: NodeType;
|
|
345
|
+
loc: Location;
|
|
307
346
|
}
|
|
308
|
-
|
|
347
|
+
//#endregion
|
|
348
|
+
//#region src/toml-document.d.ts
|
|
349
|
+
/**
|
|
350
|
+
* TomlDocument encapsulates a TOML CST and provides methods to interact with it.
|
|
351
|
+
*/
|
|
352
|
+
declare class TomlDocument {
|
|
353
|
+
private _cst;
|
|
354
|
+
private _currentTomlString;
|
|
355
|
+
private _format;
|
|
356
|
+
private _integersAsBigInt;
|
|
357
|
+
private _temporal;
|
|
358
|
+
/**
|
|
359
|
+
* Initializes the TomlDocument with TOML source, parsing it into a CST.
|
|
360
|
+
*
|
|
361
|
+
* When bytes are provided, they are decoded as UTF-8 in fatal mode.
|
|
362
|
+
* This rejects invalid UTF-8 sequences before parsing.
|
|
363
|
+
*
|
|
364
|
+
* @param tomlSource - The TOML source to parse (string or raw UTF-8 bytes)
|
|
365
|
+
* @param options - Optional parse options
|
|
366
|
+
* @param options.integersAsBigInt - Controls bigint vs number for TOML integers
|
|
367
|
+
* @param options.temporal - When true, returns Temporal objects for date/time values
|
|
368
|
+
*/
|
|
369
|
+
constructor(tomlSource: string | Uint8Array, options?: ParseOptions);
|
|
370
|
+
get toTomlString(): string;
|
|
371
|
+
/**
|
|
372
|
+
* Returns the JavaScript object representation of the TOML document.
|
|
373
|
+
*/
|
|
374
|
+
get toJsObject(): any;
|
|
375
|
+
/**
|
|
376
|
+
* Returns the internal CST (for testing purposes).
|
|
377
|
+
* @internal
|
|
378
|
+
*/
|
|
379
|
+
get cst(): Block[];
|
|
380
|
+
/**
|
|
381
|
+
* Applies a patch to the current CST using a modified JS object.
|
|
382
|
+
* Updates the internal CST. Use toTomlString getter to retrieve the updated TOML string.
|
|
383
|
+
* @param updatedObject - The modified JS object to patch with
|
|
384
|
+
* @param format - Optional formatting options
|
|
385
|
+
*/
|
|
386
|
+
patch(updatedObject: any, format?: Partial<TomlFormat> | TomlFormat): void;
|
|
387
|
+
/**
|
|
388
|
+
* Updates the internal document by supplying a modified tomlString.
|
|
389
|
+
* Use toJsObject getter to retrieve the updated JS object representation.
|
|
390
|
+
* @param tomlString - The modified TOML string to update with
|
|
391
|
+
*/
|
|
392
|
+
update(tomlString: string): void;
|
|
393
|
+
/**
|
|
394
|
+
* Overwrites the internal syntax tree by fully re-parsing the supplied tomlString.
|
|
395
|
+
* This is simpler but slower than update() which uses incremental parsing.
|
|
396
|
+
* @param tomlString - The TOML string to overwrite with
|
|
397
|
+
*/
|
|
398
|
+
overwrite(tomlString: string): void;
|
|
399
|
+
}
|
|
400
|
+
//#endregion
|
|
401
|
+
//#region src/patch.d.ts
|
|
309
402
|
/**
|
|
310
403
|
* Applies modifications to a TOML document by comparing an existing TOML string with updated JavaScript data.
|
|
311
404
|
*
|
|
@@ -320,96 +413,48 @@ interface TreeNode {
|
|
|
320
413
|
* @returns A new TOML string with the changes applied
|
|
321
414
|
*/
|
|
322
415
|
declare function patch(existing: string, updated: any, format?: Partial<TomlFormat> | TomlFormat): string;
|
|
323
|
-
|
|
416
|
+
//#endregion
|
|
417
|
+
//#region src/date-format.d.ts
|
|
324
418
|
/**
|
|
325
419
|
* Custom Date class for local dates (date-only).
|
|
326
420
|
* Format: 1979-05-27
|
|
327
421
|
*/
|
|
328
422
|
declare class LocalDate extends Date {
|
|
329
|
-
|
|
330
|
-
|
|
423
|
+
constructor(value: string);
|
|
424
|
+
toISOString(): string;
|
|
331
425
|
}
|
|
332
426
|
/**
|
|
333
427
|
* Custom Date class for local times (time-only)
|
|
334
428
|
* Format: 07:32:00 or 07:32:00.999
|
|
335
429
|
*/
|
|
336
430
|
declare class LocalTime extends Date {
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
431
|
+
originalFormat: string;
|
|
432
|
+
constructor(value: string, originalFormat: string);
|
|
433
|
+
toISOString(): string;
|
|
340
434
|
}
|
|
341
435
|
/**
|
|
342
436
|
* Custom Date class for local datetime (no timezone)
|
|
343
437
|
* Format: 1979-05-27T07:32:00 or 1979-05-27 07:32:00
|
|
344
438
|
*/
|
|
345
439
|
declare class LocalDateTime extends Date {
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
440
|
+
useSpaceSeparator: boolean;
|
|
441
|
+
originalFormat: string;
|
|
442
|
+
constructor(value: string, useSpaceSeparator?: boolean, originalFormat?: string);
|
|
443
|
+
toISOString(): string;
|
|
350
444
|
}
|
|
351
445
|
/**
|
|
352
446
|
* Custom Date class for offset datetime that preserves space separator
|
|
353
447
|
* Format: 1979-05-27T07:32:00Z or 1979-05-27 07:32:00-07:00
|
|
354
448
|
*/
|
|
355
449
|
declare class OffsetDateTime extends Date {
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
}
|
|
362
|
-
|
|
363
|
-
/**
|
|
364
|
-
* TomlDocument encapsulates a TOML CST and provides methods to interact with it.
|
|
365
|
-
*/
|
|
366
|
-
declare class TomlDocument {
|
|
367
|
-
private _cst;
|
|
368
|
-
private _currentTomlString;
|
|
369
|
-
private _format;
|
|
370
|
-
private _integersAsBigInt;
|
|
371
|
-
/**
|
|
372
|
-
* Initializes the TomlDocument with TOML source, parsing it into a CST.
|
|
373
|
-
*
|
|
374
|
-
* When bytes are provided, they are decoded as UTF-8 in fatal mode.
|
|
375
|
-
* This rejects invalid UTF-8 sequences before parsing.
|
|
376
|
-
*
|
|
377
|
-
* @param tomlSource - The TOML source to parse (string or raw UTF-8 bytes)
|
|
378
|
-
* @param options - Optional parse options
|
|
379
|
-
* @param options.integersAsBigInt - Controls bigint vs number for TOML integers
|
|
380
|
-
*/
|
|
381
|
-
constructor(tomlSource: string | Uint8Array, options?: ParseOptions);
|
|
382
|
-
get toTomlString(): string;
|
|
383
|
-
/**
|
|
384
|
-
* Returns the JavaScript object representation of the TOML document.
|
|
385
|
-
*/
|
|
386
|
-
get toJsObject(): any;
|
|
387
|
-
/**
|
|
388
|
-
* Returns the internal CST (for testing purposes).
|
|
389
|
-
* @internal
|
|
390
|
-
*/
|
|
391
|
-
get cst(): Block[];
|
|
392
|
-
/**
|
|
393
|
-
* Applies a patch to the current CST using a modified JS object.
|
|
394
|
-
* Updates the internal CST. Use toTomlString getter to retrieve the updated TOML string.
|
|
395
|
-
* @param updatedObject - The modified JS object to patch with
|
|
396
|
-
* @param format - Optional formatting options
|
|
397
|
-
*/
|
|
398
|
-
patch(updatedObject: any, format?: Partial<TomlFormat> | TomlFormat): void;
|
|
399
|
-
/**
|
|
400
|
-
* Updates the internal document by supplying a modified tomlString.
|
|
401
|
-
* Use toJsObject getter to retrieve the updated JS object representation.
|
|
402
|
-
* @param tomlString - The modified TOML string to update with
|
|
403
|
-
*/
|
|
404
|
-
update(tomlString: string): void;
|
|
405
|
-
/**
|
|
406
|
-
* Overwrites the internal syntax tree by fully re-parsing the supplied tomlString.
|
|
407
|
-
* This is simpler but slower than update() which uses incremental parsing.
|
|
408
|
-
* @param tomlString - The TOML string to overwrite with
|
|
409
|
-
*/
|
|
410
|
-
overwrite(tomlString: string): void;
|
|
450
|
+
useSpaceSeparator: boolean;
|
|
451
|
+
originalOffset?: string;
|
|
452
|
+
originalFormat: string;
|
|
453
|
+
constructor(value: string, useSpaceSeparator?: boolean);
|
|
454
|
+
toISOString(): string;
|
|
411
455
|
}
|
|
412
|
-
|
|
456
|
+
//#endregion
|
|
457
|
+
//#region src/index.d.ts
|
|
413
458
|
/**
|
|
414
459
|
* Parses a TOML string or raw UTF-8 bytes into a JavaScript object.
|
|
415
460
|
*
|
|
@@ -431,10 +476,18 @@ declare class TomlDocument {
|
|
|
431
476
|
* your code serializes the result to JSON or performs arithmetic mixing `number`
|
|
432
477
|
* and `bigint`, set `integersAsBigInt: false` to restore the previous behavior.
|
|
433
478
|
*
|
|
479
|
+
* By default (`options.temporal` unset or `false`), TOML date/time values are
|
|
480
|
+
* returned as custom Date subclasses (LocalDate, LocalTime, LocalDateTime,
|
|
481
|
+
* OffsetDateTime). Set `options.temporal` to `true` to return Temporal API
|
|
482
|
+
* objects instead (Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainDateTime,
|
|
483
|
+
* Temporal.ZonedDateTime). The Temporal API must be available in the runtime.
|
|
484
|
+
*
|
|
434
485
|
* @param value - TOML source as a string or raw UTF-8 bytes
|
|
435
486
|
* @param options - Optional parse options
|
|
436
487
|
* @param options.integersAsBigInt - Controls `bigint` vs `number` for integers.
|
|
437
488
|
* `'asNeeded'` (default) | `true` | `false`
|
|
489
|
+
* @param options.temporal - When true, returns Temporal objects for date/time values.
|
|
490
|
+
* Default: false.
|
|
438
491
|
* @returns The parsed JavaScript object
|
|
439
492
|
*/
|
|
440
493
|
declare function parse(value: string | Uint8Array, options?: ParseOptions): any;
|
|
@@ -446,6 +499,15 @@ declare function parse(value: string | Uint8Array, options?: ParseOptions): any;
|
|
|
446
499
|
* @returns The stringified TOML representation
|
|
447
500
|
*/
|
|
448
501
|
declare function stringify(value: any, format?: Partial<TomlFormat> | TomlFormat): string;
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
502
|
+
/**
|
|
503
|
+
* Parses a TOML string or raw UTF-8 bytes into a {@link TomlDocument}.
|
|
504
|
+
*
|
|
505
|
+
* This is a convenience alternative to `new TomlDocument(value, options)`.
|
|
506
|
+
*
|
|
507
|
+
* @param value - TOML source as a string or raw UTF-8 bytes
|
|
508
|
+
* @param options - Optional parse options
|
|
509
|
+
* @returns A {@link TomlDocument} representing the parsed TOML
|
|
510
|
+
*/
|
|
511
|
+
declare function parseDocument(value: string | Uint8Array, options?: ParseOptions): TomlDocument;
|
|
512
|
+
//#endregion
|
|
513
|
+
export { type IntegersAsBigInt, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, type ParseOptions, TomlDocument, TomlFormat, parse, parseDocument, patch, stringify };
|