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