@decimalturn/toml-patch 0.3.7 → 0.4.0

package/dist/toml-patch.d.ts

@@ -1,10 +1,248 @@
-//! @decimalturn/toml-patch v0.3.7 - https://github.com/DecimalTurn/toml-patch - @license: MIT
-interface Format {
-    printWidth?: number;
-    tabWidth?: number;
-    useTabs?: boolean;
-    trailingComma?: boolean;
-    bracketSpacing?: boolean;
+//! @decimalturn/toml-patch v0.4.0 - https://github.com/DecimalTurn/toml-patch - @license: MIT
+interface Location {
+    start: Position;
+    end: Position;
+}
+interface Position {
+    line: number;
+    column: number;
+}
+
+declare enum NodeType {
+    Document = "Document",
+    Table = "Table",
+    TableKey = "TableKey",
+    /**
+     * Array of Tables node
+     * More info: https://toml.io/en/latest#array-of-tables
+     */
+    TableArray = "TableArray",
+    TableArrayKey = "TableArrayKey",
+    KeyValue = "KeyValue",
+    Key = "Key",
+    String = "String",
+    Integer = "Integer",
+    Float = "Float",
+    Boolean = "Boolean",
+    DateTime = "DateTime",
+    InlineArray = "InlineArray",
+    InlineItem = "InlineItem",
+    InlineTable = "InlineTable",
+    /**
+     * Comment node
+     * More info: https://toml.io/en/latest#comment
+     */
+    Comment = "Comment"
+}
+interface Table extends TreeNode {
+    type: NodeType.Table;
+    key: TableKey;
+    items: RowItem[];
+}
+interface TableKey extends TreeNode {
+    type: NodeType.TableKey;
+    item: Key;
+}
+interface TableArray extends TreeNode {
+    type: NodeType.TableArray;
+    key: TableArrayKey;
+    items: RowItem[];
+}
+interface TableArrayKey extends TreeNode {
+    type: NodeType.TableArrayKey;
+    item: Key;
+}
+interface KeyValue extends TreeNode {
+    type: NodeType.KeyValue;
+    key: Key;
+    value: Value;
+    equals: number;
+}
+interface Key extends TreeNode {
+    type: NodeType.Key;
+    raw: string;
+    value: string[];
+}
+interface String extends TreeNode {
+    type: NodeType.String;
+    raw: string;
+    value: string;
+}
+interface Integer extends TreeNode {
+    type: NodeType.Integer;
+    raw: string;
+    value: number;
+}
+interface Float extends TreeNode {
+    type: NodeType.Float;
+    raw: string;
+    value: number;
+}
+interface Boolean extends TreeNode {
+    type: NodeType.Boolean;
+    value: boolean;
+}
+interface DateTime extends TreeNode {
+    type: NodeType.DateTime;
+    raw: string;
+    value: Date;
+}
+interface InlineArray<TItem = TreeNode> extends TreeNode {
+    type: NodeType.InlineArray;
+    items: InlineArrayItem<TItem>[];
+}
+interface InlineItem<TItem = TreeNode> extends TreeNode {
+    type: NodeType.InlineItem;
+    item: TItem;
+    comma: boolean;
+}
+interface InlineArrayItem<TItem = TreeNode> extends InlineItem<TItem> {
+}
+interface InlineTable extends TreeNode {
+    type: NodeType.InlineTable;
+    items: InlineTableItem[];
+}
+interface InlineTableItem extends InlineItem<KeyValue> {
+}
+interface Comment extends TreeNode {
+    type: NodeType.Comment;
+    raw: string;
+}
+/**
+ * RowItem represents items that can appear inside Table and TableArray sections.
+ * These are the items that form the "rows" of content within table structures.
+ *
+ * Unlike Block items (which include Table and TableArray), RowItems can only be
+ * KeyValue pairs and Comments - you cannot have nested tables within a table section.
+ */
+type RowItem = KeyValue | Comment;
+/**
+ * Block represents items that can appear at the root level (Document level) in TOML.
+ *
+ * Context and Usage:
+ * - Block items are the fundamental top-level constructs in a TOML document
+ * - They appear directly in Document containers and regular Table sections
+ * - This is in contrast to InlineItems, which appear within inline containers
+ *
+ * Important Distinction:
+ * - Table and TableArray can ONLY exist as Block items (they cannot appear inside inline containers)
+ * - KeyValue and Comment can exist as BOTH Block items AND as InlineItems:
+ *   * As Block: When they appear at root level or inside regular Table sections
+ *   * As InlineItem: When they appear inside InlineTable or InlineArray containers
+ *
+ * Examples:
+ * ```toml
+ * # These are Block items at root level:
+ * name = "value"        # KeyValue as Block
+ * # This is a comment   # Comment as Block
+ * [table]               # Table as Block
+ * [[array]]             # TableArray as Block
+ *
+ * # These are Block items inside a Table:
+ * [config]
+ * setting = "value"     # KeyValue as Block (inside Table)
+ * # comment here        # Comment as Block (inside Table)
+ *
+ * # These are InlineItems (NOT Block items):
+ * array = [ "a", "b" ]          # "a", "b" are InlineItems
+ * table = { key = "value" }     # key="value" is InlineItem
+ * ```
+ *
+ * Type Safety:
+ * This distinction is crucial for the AST structure because:
+ * - Document.items: Block[]
+ * - Table.items: RowItem[] (KeyValue | Comment)
+ * - TableArray.items: RowItem[] (KeyValue | Comment)
+ * - InlineArray.items: InlineArrayItem[] (which extends InlineItem)
+ * - InlineTable.items: InlineTableItem[] (which extends InlineItem)
+ */
+type Block = KeyValue | Table | TableArray | Comment;
+type Value<TInlineArrayItem = TreeNode> = String | Integer | Float | Boolean | DateTime | InlineArray<TInlineArrayItem> | InlineTable;
+interface TreeNode {
+    type: NodeType;
+    loc: Location;
+}
+
+declare class TomlFormat {
+    /**
+     * The line ending character(s) to use in the output TOML.
+     * This option affects only the stringification process, not the internal representation (AST).
+     *
+     * @example
+     * - '\n' for Unix/Linux line endings
+     * - '\r\n' for Windows line endings
+     */
+    newLine: string;
+    /**
+     * The number of trailing newlines to add at the end of the TOML document.
+     * This option affects only the stringification process, not the internal representation (AST).
+     *
+     * @example
+     * - 0: No trailing newline
+     * - 1: One trailing newline (standard)
+     * - 2: Two trailing newlines (adds extra spacing)
+     */
+    trailingNewline: number;
+    /**
+     * Whether to add trailing commas after the last element in arrays and inline tables.
+     *
+     * @example
+     * - true:  [1, 2, 3,] and { x = 1, y = 2, }
+     * - false: [1, 2, 3] and { x = 1, y = 2 }
+     */
+    trailingComma: boolean;
+    /**
+     * Whether to add spaces after opening brackets/braces and before closing brackets/braces
+     * in arrays and inline tables.
+     *
+     * @example
+     * - true:  [ 1, 2, 3 ] and { x = 1, y = 2 }
+     * - false: [1, 2, 3] and {x = 1, y = 2}
+     */
+    bracketSpacing: boolean;
+    /**
+     * The nesting depth at which new tables should start being formatted as inline tables.
+     * When adding new tables during patching or stringifying objects:
+     * - Tables at depth >= inlineTableStart will be formatted as inline tables
+     * - Tables at depth < inlineTableStart will be formatted as separate table sections
+     *
+     * @example
+     * - 0: All tables are inline tables including top-level tables (root level)
+     * - 1: Top-level tables as sections, nested tables as inline (default)
+     * - 2: Two levels as sections, deeper nesting as inline
+     */
+    inlineTableStart?: number;
+    constructor(newLine?: string, trailingNewline?: number, trailingComma?: boolean, bracketSpacing?: boolean, inlineTableStart?: number);
+    /**
+     * Creates a new TomlFormat instance with default formatting preferences.
+     *
+     * @returns A new TomlFormat instance with default values:
+     *   - newLine: '\n'
+     *   - trailingNewline: 1
+     *   - trailingComma: false
+     *   - bracketSpacing: true
+     *   - inlineTableStart: 1
+     */
+    static default(): TomlFormat;
+    /**
+     * Auto-detects formatting preferences from an existing TOML string.
+     *
+     * This method analyzes the provided TOML string to determine formatting
+     * preferences such as line endings, trailing newlines, and comma usage.
+     *
+     * @param tomlString - The TOML string to analyze for formatting patterns
+     * @returns A new TomlFormat instance with detected formatting preferences
+     *
+     * @example
+     * ```typescript
+     * const toml = 'array = ["a", "b", "c",]\ntable = { x = 1, y = 2, }';
+     * const format = TomlFormat.autoDetectFormat(toml);
+     * // format.trailingComma will be true
+     * // format.newLine will be '\n'
+     * // format.trailingNewline will be 0 (no trailing newline)
+     * ```
+     */
+    static autoDetectFormat(tomlString: string): TomlFormat;
 }
 
 /**
@@ -20,11 +258,54 @@ interface Format {
  * @param format - Optional formatting options to apply to new or modified sections
  * @returns A new TOML string with the changes applied
  */
-declare function patch(existing: string, updated: any, format?: Format): string;
+declare function patch(existing: string, updated: any, format?: Partial<TomlFormat> | TomlFormat): string;
+
+/**
+ * TomlDocument encapsulates a TOML AST and provides methods to interact with it.
+ */
+declare class TomlDocument {
+    #private;
+    /**
+     * Initializes the TomlDocument with a TOML string, parsing it into an AST.
+     * @param tomlString - The TOML string to parse
+     */
+    constructor(tomlString: string);
+    get toTomlString(): string;
+    /**
+     * Returns the JavaScript object representation of the TOML document.
+     */
+    get toJsObject(): any;
+    /**
+     * Returns the internal AST (for testing purposes).
+     * @internal
+     */
+    get ast(): Block[];
+    /**
+     * Applies a patch to the current AST using a modified JS object.
+     * Updates the internal AST. Use toTomlString getter to retrieve the updated TOML string.
+     * @param updatedObject - The modified JS object to patch with
+     * @param format - Optional formatting options
+     */
+    patch(updatedObject: any, format?: Partial<TomlFormat> | TomlFormat): void;
+    /**
+     * Updates the internal document by supplying a modified tomlString.
+     * Use toJsObject getter to retrieve the updated JS object representation.
+     * @param tomlString - The modified TOML string to update with
+     */
+    update(tomlString: string): void;
+    /**
+     * Overwrites the internal AST by fully re-parsing the supplied tomlString.
+     * This is simpler but slower than update() which uses incremental parsing.
+     * @param tomlString - The TOML string to overwrite with
+     */
+    overwrite(tomlString: string): void;
+}
 
 /**
  * Parses a TOML string into a JavaScript object.
  * The function converts TOML syntax to its JavaScript equivalent.
+ * This proceeds in two steps: first, it parses the TOML string into an AST,
+ * and then it converts the AST into a JavaScript object.
  *
  * @param value - The TOML string to parse
  * @returns The parsed JavaScript object
@@ -37,6 +318,6 @@ declare function parse(value: string): any;
  * @param format - Optional formatting options for the resulting TOML
  * @returns The stringified TOML representation
  */
-declare function stringify(value: any, format?: Format): string;
+declare function stringify(value: any, format?: Partial<TomlFormat> | TomlFormat): string;
 
-export { parse, patch, stringify };
+export { TomlDocument, TomlFormat, parse, patch, stringify };