//#region src/toml-format.d.ts
type MultilineContainerMode = boolean | number | 'auto' | 'parent';
export 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 (CST).
   *
   * @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 (CST).
   *
   * @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;
  /**
   * Whether the output should include a leading UTF-8 BOM marker (U+FEFF).
   *
   * This is auto-detected from the source TOML and preserved during patching.
   */
  leadingBom: 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;
  /**
   * Whether to truncate time components in UTC date fields when they are zero.
   * This setting affects only the stringification process.
   *
   * @example
   * - true:  Date('2024-01-15T00:00:00.000Z') serializes as 2024-01-15
   * - false: Date('2024-01-15T00:00:00.000Z') serializes as 2024-01-15T00:00:00.000Z
   *
   */
  truncateZeroTimeInDates?: boolean;
  /**
   * Whether to use tabs instead of spaces for indentation/padding.
   * When enabled, lines that need to be indented will use tabs.
   *
   * @example
   * - true:  Uses tabs for indentation
   * - false: Uses spaces for indentation (default)
   *
   */
  useTabsForIndentation?: boolean;
  /**
   * The number of columns used for one indentation level in generated multiline values.
   * This is auto-detected when patching and defaults to two columns.
   */
  indentWidth: number;
  /**
   * The minimum number of decimal places to use when serializing JS numbers as TOML floats.
   * When greater than 0, plain JS integer values are serialized as TOML floats padded with
   * zeros to reach the specified decimal count. BigInt values are always serialized as integers
   * regardless of this setting.
   *
   * @example
   * - 0: stringify({ x: 1, y: 1.5 })  →  x = 1 / y = 1.5   (default)
   * - 1: stringify({ x: 1, y: 1.5 })  →  x = 1.0 / y = 1.5
   * - 2: stringify({ x: 1, y: 1.5 })  →  x = 1.00 / y = 1.50
   */
  minimumDecimals?: number;
  /**
   * Whether `patch()` should reorder root key-values, `[table]`/`[[array]]` section blocks,
   * and rows inside table bodies to match the key order of the JS object passed to `patch()`,
   * carrying each entry's owned comments along with it (see docs/CommentOwnership.md).
   *
   * Off by default: with the option unset or `false`, `patch()` only ever changes values that
   * actually differ between the existing document and the updated object, preserving the
   * existing document's order even when the JS object's key order differs.
   *
   * Not auto-detectable — the existing document's order says nothing about the caller's
   * intent, so `autoDetectFormatWithCst` always resolves this to `false`.
   *
   * See docs/PLAN-Update-Order.md for the full behavior and current scope limitations.
   */
  updateOrder?: boolean;
  /**
   * Whether newly generated inline tables should use multiline layout.
   *
   * `true` and `false` select a layout directly. A non-negative integer selects
   * multiline layout at that structural container depth or deeper. `'auto'`
   * keeps new containers compact and `'parent'` follows the immediate parent.
   */
  multilineTable: MultilineContainerMode;
  /**
   * Whether newly generated inline arrays should use multiline layout.
   *
   * `true` and `false` select a layout directly. A non-negative integer selects
   * multiline layout at that structural container depth or deeper. `'auto'`
   * keeps new containers compact and `'parent'` follows the immediate parent.
   */
  multilineArray: MultilineContainerMode;
  constructor(newLine?: string, trailingNewline?: number, trailingComma?: boolean, bracketSpacing?: boolean, inlineTableStart?: number, truncateZeroTimeInDates?: boolean, useTabsForIndentation?: boolean, minimumDecimals?: number, leadingBom?: boolean, updateOrder?: boolean, indentWidth?: number, multilineTable?: MultilineContainerMode | null, multilineArray?: MultilineContainerMode | null);
  /**
   * 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
   *   - leadingBom: false
   *   - inlineTableStart: 1
   *   - truncateZeroTimeInDates: false
   *   - useTabsForIndentation: false
   *   - minimumDecimals: 0
   *   - updateOrder: false
   */
  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;
  /**
   * Internal method: Auto-detects formatting preferences from a TOML string with optional pre-parsed CST.
   *
   * This is used internally to avoid redundant parsing when the CST is already available.
   * External callers should use `autoDetectFormat(tomlString)` instead.
   *
   * @internal
   * @param tomlString - The TOML string to analyze for formatting patterns
   * @param syntaxTree - Optional pre-parsed CST to avoid redundant parsing
   * @returns A new TomlFormat instance with detected formatting preferences
   */
  static autoDetectFormatWithCst(tomlString: string, syntaxTree?: Iterable<any>): TomlFormat;
  /** @deprecated Use autoDetectFormatWithCst instead. */
  static autoDetectFormatWithAst(tomlString: string, syntaxTree?: Iterable<any>): TomlFormat;
}
//#endregion
//#region src/parse-options.d.ts
type IntegersAsBigInt = boolean | 'asNeeded';
interface ParseOptions {
  /**
   * Controls how TOML integers are returned in the parsed JavaScript object.
   * - `true`: All integers are returned as `bigint`.
   * - `false`: All integers are returned as `number` (may lose precision for large integers).
   * - `'asNeeded'` (default): Integers that fit within the JavaScript safe-integer range are returned as `number`; larger integers are returned as `bigint`.
   */
  integersAsBigInt?: IntegersAsBigInt;
  /**
   * When true, TOML date/time values are parsed into Temporal objects
   * (Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainDateTime,
   * Temporal.ZonedDateTime) instead of custom Date subclasses.
   *
   * The Temporal API must be available in the runtime.
   * - Node.js >= v26: full native support.
   * - Node.js < v26: enable with the `--harmony-temporal` flag.
   * - Modern browsers: native support.
   * - Other runtimes: use @js-temporal/polyfill.
   *
   * Default: false (returns custom Date subclasses for backward compatibility).
   */
  temporal?: boolean;
}
//#endregion
//#region src/location.d.ts
interface Location {
  start: Position;
  end: Position;
}
interface Position {
  line: number;
  column: number;
}
//#endregion
//#region src/cst.d.ts
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 | bigint;
}
interface Float extends TreeNode {
  type: NodeType.Float;
  raw: string;
  value: number;
  /** Sign prefix for NaN values: '+' for +nan, '-' for -nan, undefined for nan */
  nanSign?: '+' | '-';
}
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 CST 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;
  /** Absolute UTF-16 offsets into the source that produced this node. */
  readonly range?: readonly [number, number];
  /** Set on generated or mutated nodes and propagated to their ancestors. */
  dirty?: boolean;
}
//#endregion
//#region src/toml-document.d.ts
/**
 * TomlDocument encapsulates a TOML CST and provides methods to interact with it.
 */
export declare class TomlDocument {
  private _cst;
  private _currentTomlString;
  private _format;
  private _integersAsBigInt;
  private _temporal;
  /**
   * Initializes the TomlDocument with TOML source, parsing it into a CST.
   *
   * When bytes are provided, they are decoded as UTF-8 in fatal mode.
   * This rejects invalid UTF-8 sequences before parsing.
   *
   * @param tomlSource - The TOML source to parse (string or raw UTF-8 bytes)
   * @param options - Optional parse options
   * @param options.integersAsBigInt - Controls bigint vs number for TOML integers
   * @param options.temporal - When true, returns Temporal objects for date/time values
   */
  constructor(tomlSource: string | Uint8Array, options?: ParseOptions);
  get toTomlString(): string;
  /**
   * Returns the JavaScript object representation of the TOML document.
   */
  get toJsObject(): any;
  /**
   * Returns the internal CST (for testing purposes).
   * @internal
   */
  get cst(): Block[];
  /**
   * Applies a patch to the current CST using a modified JS object.
   * Updates the internal CST. 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 syntax tree 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;
}
//#endregion
//#region src/patch.d.ts
/**
 * Applies modifications to a TOML document by comparing an existing TOML string with updated JavaScript data.
 *
 * This function preserves formatting and comments from the existing TOML document while
 * applying changes from the updated data structure. It performs a diff between the existing
 * and updated data, then strategically applies only the necessary changes to maintain the
 * original document structure as much as possible.
 *
 * @param existing - The original TOML document as a string
 * @param updated - The updated JavaScript object with desired changes
 * @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?: Partial<TomlFormat> | TomlFormat): string;
//#endregion
//#region src/date-format.d.ts
/**
 * Custom Date class for local dates (date-only).
 * Format: 1979-05-27
 */
export declare class LocalDate extends Date {
  constructor(value: string);
  toISOString(): string;
}
/**
 * Custom Date class for local times (time-only)
 * Format: 07:32:00 or 07:32:00.999
 */
export declare class LocalTime extends Date {
  originalFormat: string;
  constructor(value: string, originalFormat: string);
  toISOString(): string;
}
/**
 * Custom Date class for local datetime (no timezone)
 * Format: 1979-05-27T07:32:00 or 1979-05-27 07:32:00
 */
export declare class LocalDateTime extends Date {
  useSpaceSeparator: boolean;
  originalFormat: string;
  constructor(value: string, useSpaceSeparator?: boolean, originalFormat?: string);
  toISOString(): string;
}
/**
 * Custom Date class for offset datetime that preserves space separator
 * Format: 1979-05-27T07:32:00Z or 1979-05-27 07:32:00-07:00
 */
export declare class OffsetDateTime extends Date {
  useSpaceSeparator: boolean;
  originalOffset?: string;
  originalFormat: string;
  constructor(value: string, useSpaceSeparator?: boolean);
  toISOString(): string;
}
//#endregion
//#region src/index.d.ts
/**
 * Parses a TOML string or raw UTF-8 bytes into a JavaScript object.
 *
 * When raw bytes (Uint8Array / Buffer) are provided, they are decoded with
 * the WHATWG TextDecoder in fatal mode, which rejects any invalid UTF-8
 * byte sequences before parsing begins. This matches the TOML spec requirement
 * that "A TOML file must be a valid UTF-8 encoded Unicode document."
 *
 * The string path has zero overhead — the bytes path incurs one TextDecoder
 * decode (which also produces the string needed for parsing).
 *
 * By default (`options.integersAsBigInt` unset or `'asNeeded'`), integers that
 * fit within the JavaScript safe-integer range are returned as `number`; integers
 * outside that range are returned as `bigint` to preserve precision. Set
 * `options.integersAsBigInt` to `true` to always return `bigint` for all integers,
 * or `false` to always return `number` (large integers will lose precision).
 *
 * Note: the `'asNeeded'` default is a behavioral change from prior versions (<=1.0.7). If
 * your code serializes the result to JSON or performs arithmetic mixing `number`
 * and `bigint`, set `integersAsBigInt: false` to restore the previous behavior.
 *
 * By default (`options.temporal` unset or `false`), TOML date/time values are
 * returned as custom Date subclasses (LocalDate, LocalTime, LocalDateTime,
 * OffsetDateTime). Set `options.temporal` to `true` to return Temporal API
 * objects instead (Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainDateTime,
 * Temporal.ZonedDateTime). The Temporal API must be available in the runtime.
 *
 * @param value - TOML source as a string or raw UTF-8 bytes
 * @param options - Optional parse options
 * @param options.integersAsBigInt - Controls `bigint` vs `number` for integers.
 *   `'asNeeded'` (default) | `true` | `false`
 * @param options.temporal - When true, returns Temporal objects for date/time values.
 *   Default: false.
 * @returns The parsed JavaScript object
 */
export declare function parse(value: string | Uint8Array, options?: ParseOptions): any;
/**
 * Converts a JavaScript object to a TOML string.
 *
 * @param value - The JavaScript object to stringify
 * @param format - Optional formatting options for the resulting TOML
 * @returns The stringified TOML representation
 */
export declare function stringify(value: any, format?: Partial<TomlFormat> | TomlFormat): string;
/**
 * Parses a TOML string or raw UTF-8 bytes into a {@link TomlDocument}.
 *
 * This is a convenience alternative to `new TomlDocument(value, options)`.
 *
 * @param value - TOML source as a string or raw UTF-8 bytes
 * @param options - Optional parse options
 * @returns A {@link TomlDocument} representing the parsed TOML
 */
export declare function parseDocument(value: string | Uint8Array, options?: ParseOptions): TomlDocument;
//#endregion
export { type IntegersAsBigInt, type MultilineContainerMode, type ParseOptions, patch };