@effected/toml 0.1.0

package/index.d.ts

@@ -0,0 +1,897 @@
+import { Data, Effect, Schema, Stream } from "effect";
+//#region src/TomlDiagnostic.d.ts
+/**
+ * Error codes emitted by the lexer stage.
+ *
+ * @public
+ */
+declare const TomlLexErrorCode: Schema.Literals<readonly ["InvalidUtf8", "UnterminatedString", "InvalidEscape", "InvalidUnicodeEscape", "ControlCharacterInString", "ControlCharacterInComment", "InvalidCharacter", "BareCarriageReturn"]>;
+/**
+ * The union of all lexer-stage error code string literals.
+ *
+ * @public
+ */
+type TomlLexErrorCode = typeof TomlLexErrorCode.Type;
+/**
+ * Error codes emitted by the parser stage.
+ *
+ * @public
+ */
+declare const TomlParseErrorCode: Schema.Literals<readonly ["ExpectedKey", "ExpectedEquals", "ExpectedValue", "ExpectedNewline", "ExpectedTableHeaderClose", "UnterminatedArray", "UnterminatedInlineTable", "TrailingCommaInInlineTable", "NewlineInInlineTable", "InvalidValue", "InvalidNumber", "IntegerOutOfRange", "InvalidDateTime", "NestingDepthExceeded"]>;
+/**
+ * The union of all parser-stage error code string literals.
+ *
+ * @public
+ */
+type TomlParseErrorCode = typeof TomlParseErrorCode.Type;
+/**
+ * Error codes emitted by the semantic (table/key conflict) stage.
+ *
+ * @public
+ */
+declare const TomlSemanticErrorCode: Schema.Literals<readonly ["DuplicateKey", "TableRedefined", "ArrayOfTablesConflict", "DottedKeyConflict", "InlineTableExtended"]>;
+/**
+ * The union of all semantic-stage error code string literals.
+ *
+ * @public
+ */
+type TomlSemanticErrorCode = typeof TomlSemanticErrorCode.Type;
+/**
+ * Error codes emitted by the stringifier stage.
+ *
+ * @public
+ */
+declare const TomlStringifyErrorCode: Schema.Literals<readonly ["CircularReference", "UnsupportedValue", "IntegerOutOfRange", "NestingDepthExceeded"]>;
+/**
+ * The union of all stringifier-stage error code string literals.
+ *
+ * @public
+ */
+type TomlStringifyErrorCode = typeof TomlStringifyErrorCode.Type;
+/**
+ * Union of all TOML error codes across all pipeline stages. Stage
+ * discrimination lives here (in the code), not in separate error classes.
+ *
+ * @public
+ */
+declare const TomlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["InvalidUtf8", "UnterminatedString", "InvalidEscape", "InvalidUnicodeEscape", "ControlCharacterInString", "ControlCharacterInComment", "InvalidCharacter", "BareCarriageReturn"]>, Schema.Literals<readonly ["ExpectedKey", "ExpectedEquals", "ExpectedValue", "ExpectedNewline", "ExpectedTableHeaderClose", "UnterminatedArray", "UnterminatedInlineTable", "TrailingCommaInInlineTable", "NewlineInInlineTable", "InvalidValue", "InvalidNumber", "IntegerOutOfRange", "InvalidDateTime", "NestingDepthExceeded"]>, Schema.Literals<readonly ["DuplicateKey", "TableRedefined", "ArrayOfTablesConflict", "DottedKeyConflict", "InlineTableExtended"]>, Schema.Literals<readonly ["CircularReference", "UnsupportedValue", "IntegerOutOfRange", "NestingDepthExceeded"]>]>;
+/**
+ * The union of all TOML error code string literals.
+ *
+ * @public
+ */
+type TomlErrorCode = typeof TomlErrorCode.Type;
+declare const TomlDiagnostic_base: Schema.Class<TomlDiagnostic, Schema.Struct<{
+  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["InvalidUtf8", "UnterminatedString", "InvalidEscape", "InvalidUnicodeEscape", "ControlCharacterInString", "ControlCharacterInComment", "InvalidCharacter", "BareCarriageReturn"]>, Schema.Literals<readonly ["ExpectedKey", "ExpectedEquals", "ExpectedValue", "ExpectedNewline", "ExpectedTableHeaderClose", "UnterminatedArray", "UnterminatedInlineTable", "TrailingCommaInInlineTable", "NewlineInInlineTable", "InvalidValue", "InvalidNumber", "IntegerOutOfRange", "InvalidDateTime", "NestingDepthExceeded"]>, Schema.Literals<readonly ["DuplicateKey", "TableRedefined", "ArrayOfTablesConflict", "DottedKeyConflict", "InlineTableExtended"]>, Schema.Literals<readonly ["CircularReference", "UnsupportedValue", "IntegerOutOfRange", "NestingDepthExceeded"]>]>;
+  readonly message: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+}>, {}>;
+/**
+ * One structured diagnostic: its {@link (TomlErrorCode:type)}, a
+ * human-readable `message`, and its exact position (`offset`/`length`, plus
+ * zero-based `line`/`character`).
+ *
+ * @remarks
+ * The five-field positional core (`code`/`offset`/`length`/`line`/`character`)
+ * is structurally identical to `@effected/jsonc`'s parse-error detail shape
+ * and `@effected/yaml`'s `YamlDiagnostic`; `message` is this package's
+ * additive extra.
+ *
+ * @public
+ */
+declare class TomlDiagnostic extends TomlDiagnostic_base {
+  /**
+   * Materialize an engine record, deriving `line`/`character` (0-based)
+   * from `offset` against the source `text`. Advanced — the parse/stringify
+   * entry points call this for you.
+   */
+  static fromRaw(source: string, raw: {
+    readonly code: TomlErrorCode;
+    readonly message: string;
+    readonly offset: number;
+    readonly length: number;
+  }): TomlDiagnostic;
+}
+//#endregion
+//#region src/Toml.d.ts
+declare const TomlStringifyOptions_base: Schema.Class<TomlStringifyOptions, Schema.Struct<{
+  readonly newline: Schema.optionalKey<Schema.Literals<readonly ["\n", "\r\n"]>>;
+}>, {}>;
+/**
+ * Options controlling stringify behavior. The only knob is `newline` —
+ * omitted, it resolves to `"\n"`.
+ *
+ * @public
+ */
+declare class TomlStringifyOptions extends TomlStringifyOptions_base {}
+declare const TomlParseError_base: Schema.Class<TomlParseError, Schema.TaggedStruct<"TomlParseError", {
+  readonly diagnostics: Schema.$Array<typeof TomlDiagnostic>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Parse failure: the {@link TomlDiagnostic} entries describing why the
+ * document was rejected (first violation wins, so there is one today; the
+ * array shape matches `@effected/yaml`'s aggregate contract). Raised by
+ * {@link Toml.parse} and the decode direction of the schema factories.
+ *
+ * @public
+ */
+declare class TomlParseError extends TomlParseError_base {
+  get message(): string;
+}
+declare const TomlStringifyError_base: Schema.Class<TomlStringifyError, Schema.TaggedStruct<"TomlStringifyError", {
+  readonly diagnostic: typeof TomlDiagnostic;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Stringification failure: an unsupported value, an out-of-range integer, a
+ * circular reference or a tripped depth guard, as one structured
+ * {@link TomlDiagnostic} (offset `0` — there is no source text). Raised by
+ * {@link Toml.stringify} and the encode direction of the schema factories.
+ *
+ * @public
+ */
+declare class TomlStringifyError extends TomlStringifyError_base {
+  get message(): string;
+}
+/**
+ * Static entry points for TOML parsing, stringification and the schema
+ * factories. Not instantiable.
+ *
+ * @remarks
+ * `parse`, `stringify` and the schema factories carry real typed error
+ * channels — including the hardening guards (nesting-depth caps on both
+ * sides, circular-reference detection on encode) that keep malformed or
+ * adversarial input on the typed channel instead of surfacing as an
+ * unhandled defect. `parse` takes no options: TOML 1.0.0 parsing has no
+ * knobs.
+ *
+ * @example
+ * ```ts
+ * import { Toml } from "@effected/toml";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const value = yield* Toml.parse('name = "Alice"\nage = 30');
+ *   return value; // { name: "Alice", age: 30 }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Toml {
+  private constructor();
+  /**
+   * Parse a TOML 1.0.0 document into a plain JavaScript value: tables and
+   * inline tables become plain objects (`__proto__` lands as an own data
+   * property), arrays become plain arrays, integers become `number` (or
+   * `bigint` past 2^53) and date-times become the four `TomlDateTime`
+   * classes. Fails with {@link TomlParseError} at the first violation;
+   * returns `unknown`, never `any`.
+   *
+   * A nesting-depth bomb (arrays or inline tables past the engine cap) also
+   * fails through {@link TomlParseError} with a `NestingDepthExceeded`
+   * diagnostic, never as an unhandled defect.
+   */
+  static readonly parse: (text: string) => Effect.Effect<unknown, TomlParseError, never>;
+  /**
+   * Stringify a plain JavaScript value as a canonical TOML document: within
+   * a table, non-table pairs first, then sub-tables as `[dotted.header]`
+   * sections depth-first, then arrays of tables as `[[dotted.header]]`
+   * sections, a blank line before every header except at document start.
+   * Fails with {@link TomlStringifyError} on unsupported values (TOML has no
+   * null), out-of-int64-range `bigint`s, circular references and
+   * depth-guard trips — all on the typed channel.
+   */
+  static readonly stringify: (value: unknown, options?: TomlStringifyOptions | undefined) => Effect.Effect<string, TomlStringifyError, never>;
+  /**
+   * A `Schema<unknown, string>` decoding a TOML document and encoding values
+   * back to canonical TOML text.
+   *
+   * Schema-producing: each call returns a fresh schema whose derivation
+   * caches are not shared across calls. Bind the result to a `const` on hot
+   * paths; the pre-bound {@link Toml.TomlFromString} covers the common case.
+   */
+  static fromString(): Schema.Codec<unknown, string>;
+  /**
+   * The zero-config `Schema<unknown, string>` — `Toml.fromString()`
+   * pre-bound so the common case needs no memoization discipline.
+   */
+  static readonly TomlFromString: Schema.Codec<unknown, string>;
+  /**
+   * Compose {@link Toml.fromString} with a target schema, yielding a
+   * `Schema<A, string>` that decodes TOML straight into a validated domain
+   * value. The target's decoding/encoding service requirements flow through.
+   *
+   * Schema-producing: bind the result to a `const` on hot paths (see
+   * {@link Toml.fromString}).
+   */
+  static schema<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>): Schema.Codec<T, string, RD, RE>;
+}
+//#endregion
+//#region src/TomlDateTime.d.ts
+declare const TomlLocalDate_base: Schema.Class<TomlLocalDate, Schema.Struct<{
+  year: Schema.Int;
+  month: Schema.Int;
+  day: Schema.Int;
+}>, {}>;
+/**
+ * A TOML local date: `year`-`month`-`day` with no time-of-day or offset,
+ * validated against the real Gregorian calendar.
+ *
+ * @public
+ */
+declare class TomlLocalDate extends TomlLocalDate_base {
+  toString(): string;
+}
+declare const TomlLocalTime_base: Schema.Class<TomlLocalTime, Schema.Struct<{
+  hour: Schema.Int;
+  minute: Schema.Int;
+  second: Schema.Int;
+  nanosecond: Schema.Int;
+}>, {}>;
+/**
+ * A TOML local time: `hour`:`minute`:`second`[.`nanosecond`] with no date or
+ * offset. `second` tolerates the RFC 3339 leap second (0-60).
+ *
+ * @public
+ */
+declare class TomlLocalTime extends TomlLocalTime_base {
+  toString(): string;
+}
+declare const TomlLocalDateTime_base: Schema.Class<TomlLocalDateTime, Schema.Struct<{
+  readonly year: Schema.Int;
+  readonly month: Schema.Int;
+  readonly day: Schema.Int;
+  readonly hour: Schema.Int;
+  readonly minute: Schema.Int;
+  readonly second: Schema.Int;
+  readonly nanosecond: Schema.Int;
+}>, {}>;
+/**
+ * A TOML local date-time: a {@link TomlLocalDate} and a {@link TomlLocalTime}
+ * combined, with no offset.
+ *
+ * @public
+ */
+declare class TomlLocalDateTime extends TomlLocalDateTime_base {
+  toString(): string;
+}
+declare const TomlOffsetDateTime_base: Schema.Class<TomlOffsetDateTime, Schema.Struct<{
+  readonly year: Schema.Int;
+  readonly month: Schema.Int;
+  readonly day: Schema.Int;
+  readonly hour: Schema.Int;
+  readonly minute: Schema.Int;
+  readonly second: Schema.Int;
+  readonly nanosecond: Schema.Int;
+  readonly offsetMinutes: Schema.Int;
+}>, {}>;
+/**
+ * A TOML offset date-time: a {@link TomlLocalDateTime} plus `offsetMinutes`
+ * (-1439-1439). Parsing enforces `hh <= 23` / `mm <= 59` before construction;
+ * this class only bounds the combined minute count.
+ *
+ * @public
+ */
+declare class TomlOffsetDateTime extends TomlOffsetDateTime_base {
+  toString(): string;
+}
+//#endregion
+//#region src/TomlNode.d.ts
+/**
+ * The three simple-key spellings: `bare`, `basic` (`"..."`) and `literal`
+ * (`'...'`).
+ *
+ * @public
+ */
+declare const TomlKeyKind: Schema.Literals<readonly ["bare", "basic", "literal"]>;
+/**
+ * The union of all key-kind string literals.
+ *
+ * @public
+ */
+type TomlKeyKind = typeof TomlKeyKind.Type;
+declare const TomlKey_base: Schema.Class<TomlKey, Schema.TaggedStruct<"TomlKey", {
+  readonly value: Schema.String;
+  readonly kind: Schema.Literals<readonly ["bare", "basic", "literal"]>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * One simple key within a (possibly dotted) key path.
+ *
+ * - `value` — the decoded key text (escapes resolved, quotes stripped).
+ * - `kind` — how the key was spelled in the source.
+ * - `offset` / `length` — the key's span in the source, quotes included.
+ *
+ * @public
+ */
+declare class TomlKey extends TomlKey_base {}
+/**
+ * The four TOML string forms.
+ *
+ * @public
+ */
+declare const TomlStringStyle: Schema.Literals<readonly ["basic", "literal", "multiline-basic", "multiline-literal"]>;
+/**
+ * The union of all string-style literals.
+ *
+ * @public
+ */
+type TomlStringStyle = typeof TomlStringStyle.Type;
+declare const TomlString_base: Schema.Class<TomlString, Schema.TaggedStruct<"TomlString", {
+  readonly value: Schema.String;
+  readonly style: Schema.Literals<readonly ["basic", "literal", "multiline-basic", "multiline-literal"]>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A string value node. `value` is the decoded text; the raw spelling lives in
+ * the source span.
+ *
+ * @public
+ */
+declare class TomlString extends TomlString_base {}
+declare const TomlInteger_base: Schema.Class<TomlInteger, Schema.TaggedStruct<"TomlInteger", {
+  readonly value: Schema.Union<readonly [Schema.Number, Schema.BigInt]>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * An integer value node. Decodes to `number` when the magnitude fits in
+ * 2^53 - 1, else `bigint` (TOML integers span the full signed 64-bit range).
+ *
+ * @public
+ */
+declare class TomlInteger extends TomlInteger_base {}
+declare const TomlFloat_base: Schema.Class<TomlFloat, Schema.TaggedStruct<"TomlFloat", {
+  readonly value: Schema.Number;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A float value node, including the special spellings (`inf`, `nan`).
+ *
+ * @public
+ */
+declare class TomlFloat extends TomlFloat_base {}
+declare const TomlBoolean_base: Schema.Class<TomlBoolean, Schema.TaggedStruct<"TomlBoolean", {
+  readonly value: Schema.Boolean;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A boolean value node.
+ *
+ * @public
+ */
+declare class TomlBoolean extends TomlBoolean_base {}
+declare const TomlDateTimeLiteral_base: Schema.Class<TomlDateTimeLiteral, Schema.TaggedStruct<"TomlDateTimeLiteral", {
+  readonly value: Schema.Union<readonly [typeof TomlOffsetDateTime, typeof TomlLocalDateTime, typeof TomlLocalDate, typeof TomlLocalTime]>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A date-time value node wrapping one of the four TOML date-time classes.
+ *
+ * @public
+ */
+declare class TomlDateTimeLiteral extends TomlDateTimeLiteral_base {}
+declare const TomlArray_base: Schema.Class<TomlArray, Schema.TaggedStruct<"TomlArray", {
+  readonly items: Schema.$Array<Schema.suspend<Schema.Codec<TomlValueNode, TomlValueNode, never, never>>>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * An array value node. Heterogeneous per TOML 1.0.0; may span multiple lines
+ * (the span covers brackets, inner newlines and inner comments).
+ *
+ * @public
+ */
+declare class TomlArray extends TomlArray_base {}
+declare const TomlInlineEntry_base: Schema.Class<TomlInlineEntry, Schema.TaggedStruct<"TomlInlineEntry", {
+  readonly keyPath: Schema.$Array<typeof TomlKey>;
+  readonly value: Schema.suspend<Schema.Codec<TomlValueNode, TomlValueNode, never, never>>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * One `key = value` entry inside an inline table. `keyPath` has more than one
+ * element for dotted keys (`{a.b = 1}`).
+ *
+ * @public
+ */
+declare class TomlInlineEntry extends TomlInlineEntry_base {}
+declare const TomlInlineTable_base: Schema.Class<TomlInlineTable, Schema.TaggedStruct<"TomlInlineTable", {
+  readonly entries: Schema.$Array<typeof TomlInlineEntry>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * An inline table value node (`{ k = v, ... }`). Single-line by grammar.
+ *
+ * @public
+ */
+declare class TomlInlineTable extends TomlInlineTable_base {}
+/**
+ * A discriminated-union schema covering all seven TOML value node types.
+ * Defined lazily via `Schema.suspend` to break the recursive reference chain
+ * `TomlValueNode → TomlArray/TomlInlineTable → TomlValueNode`.
+ *
+ * @public
+ */
+declare const TomlValueNode: Schema.Codec<TomlString | TomlInteger | TomlFloat | TomlBoolean | TomlDateTimeLiteral | TomlArray | TomlInlineTable>;
+/**
+ * The union of all TOML value node types.
+ *
+ * @public
+ */
+type TomlValueNode = TomlString | TomlInteger | TomlFloat | TomlBoolean | TomlDateTimeLiteral | TomlArray | TomlInlineTable;
+declare const TomlKeyValue_base: Schema.Class<TomlKeyValue, Schema.TaggedStruct<"TomlKeyValue", {
+  readonly keyPath: Schema.$Array<typeof TomlKey>;
+  readonly value: Schema.suspend<Schema.Codec<TomlValueNode, TomlValueNode, never, never>>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A `key = value` expression. The span starts at the first character of the
+ * line's leading whitespace and ends after the terminating newline (or at
+ * EOF); multi-line values extend it. `comment` holds the decoded trailing
+ * comment (without `#`, one leading space stripped) when present.
+ *
+ * @public
+ */
+declare class TomlKeyValue extends TomlKeyValue_base {}
+declare const TomlTableHeader_base: Schema.Class<TomlTableHeader, Schema.TaggedStruct<"TomlTableHeader", {
+  readonly keyPath: Schema.$Array<typeof TomlKey>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A `[table]` header expression. Span contract as in {@link TomlKeyValue}.
+ *
+ * @public
+ */
+declare class TomlTableHeader extends TomlTableHeader_base {}
+declare const TomlArrayTableHeader_base: Schema.Class<TomlArrayTableHeader, Schema.TaggedStruct<"TomlArrayTableHeader", {
+  readonly keyPath: Schema.$Array<typeof TomlKey>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A `[[array-of-tables]]` header expression. Span contract as in
+ * {@link TomlKeyValue}.
+ *
+ * @public
+ */
+declare class TomlArrayTableHeader extends TomlArrayTableHeader_base {}
+declare const TomlTrivia_base: Schema.Class<TomlTrivia, Schema.TaggedStruct<"TomlTrivia", {
+  readonly text: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A run of consecutive blank and comment-only lines, coalesced into one
+ * expression. `text` is the raw source slice, newlines included.
+ *
+ * @public
+ */
+declare class TomlTrivia extends TomlTrivia_base {}
+/**
+ * The union schema of the four expression types making up a document's
+ * linear CST.
+ *
+ * @public
+ */
+declare const TomlExpression: Schema.Union<readonly [typeof TomlKeyValue, typeof TomlTableHeader, typeof TomlArrayTableHeader, typeof TomlTrivia]>;
+/**
+ * The union of all expression node types.
+ *
+ * @public
+ */
+type TomlExpression = typeof TomlExpression.Type;
+//#endregion
+//#region src/TomlDocument.d.ts
+declare const TomlDocument_base: Schema.Class<TomlDocument, Schema.Struct<{
+  readonly source: Schema.String;
+  readonly expressions: Schema.$Array<Schema.Union<readonly [typeof TomlKeyValue, typeof TomlTableHeader, typeof TomlArrayTableHeader, typeof TomlTrivia]>>;
+  readonly diagnostics: Schema.$Array<typeof TomlDiagnostic>;
+}>, {}>;
+/**
+ * A parsed TOML document that never loses a byte: the `source` text, the
+ * linear {@link (TomlExpression:type)} CST whose spans tile the source
+ * exactly, and
+ * any semantic violations as {@link TomlDiagnostic} data.
+ *
+ * @remarks
+ * `parse` fails typed only on lex/parse errors; a syntactically valid but
+ * semantically illegal document (say, a duplicate key) still parses with the
+ * violation recorded in `diagnostics`, so the text stays inspectable and
+ * editable. `stringify` reconstructs the source by concatenating expression
+ * spans — that the result equals `source` is the span-bookkeeping proof, held
+ * byte-exact across the full toml-test corpus. `toValue` refuses on a
+ * non-empty `diagnostics`.
+ *
+ * Construct via {@link TomlDocument.parse}; `TomlDocument.make` is for
+ * synthetic documents.
+ *
+ * @example
+ * ```ts
+ * import { TomlDocument } from "@effected/toml";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const doc = yield* TomlDocument.parse('name = "Alice"\n');
+ *   doc.stringify(); // 'name = "Alice"\n' — byte-exact
+ *   return yield* doc.toValue(); // { name: "Alice" }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class TomlDocument extends TomlDocument_base {
+  /**
+   * Parse TOML text into a lossless document. Fails with
+   * {@link TomlParseError} only on lex/parse errors — including a
+   * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
+   * diagnostic, never an unhandled defect. Semantic violations do not fail:
+   * they land in `diagnostics` as data (first violation wins, so there is at
+   * most one today; the array shape is the contract).
+   */
+  static readonly parse: (text: string) => Effect.Effect<TomlDocument, TomlParseError, never>;
+  /**
+   * A `Schema<TomlDocument, string>` decoding TOML text into a full document
+   * (source, expressions, diagnostics) and encoding a document back to its
+   * byte-exact text.
+   *
+   * Schema-producing: each call returns a fresh schema whose derivation
+   * caches are not shared across calls; bind the result to a `const` on hot
+   * paths.
+   */
+  static schema(): Schema.Codec<TomlDocument, string>;
+  /**
+   * Materialize the document's plain JavaScript value. Fails with
+   * {@link TomlParseError} carrying the stored `diagnostics` when the parse
+   * recorded semantic violations; otherwise builds the value from the
+   * expression list (already validated, so the defensive materialization
+   * wrapper is belt-and-suspenders).
+   */
+  toValue(): Effect.Effect<unknown, TomlParseError>;
+  /**
+   * Reconstruct the document text by concatenating each expression's source
+   * span in order. The expression spans tile the source exactly, so the
+   * result equals `source` byte-for-byte — the round-trip contract this
+   * class exists to prove. Pure and total.
+   */
+  stringify(): string;
+}
+//#endregion
+//#region src/TomlEdit.d.ts
+/**
+ * A single path segment: a `string` for table keys or a `number` for array
+ * and array-of-tables indices.
+ *
+ * @public
+ */
+type TomlSegment = string | number;
+/**
+ * An ordered sequence of {@link TomlSegment} values describing a location
+ * within a TOML document's semantic tree.
+ *
+ * @public
+ */
+type TomlPath = ReadonlyArray<TomlSegment>;
+declare const TomlRange_base: Schema.Class<TomlRange, Schema.Struct<{
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A range within a TOML document, expressed as a zero-based character
+ * `offset` and a `length` in UTF-16 code units. Pass to `TomlFormat.format`
+ * to restrict formatting to the expressions intersecting a region.
+ *
+ * @public
+ */
+declare class TomlRange extends TomlRange_base {}
+declare const TomlEdit_base: Schema.Class<TomlEdit, Schema.Struct<{
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly content: Schema.String;
+}>, {}>;
+/**
+ * A non-mutating text edit: replace the span `[offset, offset + length)` with
+ * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
+ *
+ * @remarks
+ * Structurally identical to `@effected/jsonc`'s and `@effected/yaml`'s edit
+ * shapes (same field names, types and semantics) per the jsonc/yaml parity
+ * convention, so consumer code can be written once over "a document codec's
+ * Edit/Range/Path".
+ *
+ * @public
+ */
+declare class TomlEdit extends TomlEdit_base {
+  /**
+   * Apply `edits` to `text`, producing a new string. Edits are applied in
+   * reverse-offset order so earlier offsets stay valid; the input `edits`
+   * array is not mutated. Overlapping edits are a programmer error and throw
+   * as a defect — `TomlFormat` never produces them.
+   */
+  static applyAll(text: string, edits: ReadonlyArray<TomlEdit>): string;
+}
+//#endregion
+//#region src/TomlFormat.d.ts
+/**
+ * A range accepted at the `format`/`formatToString` call sites: either a
+ * {@link TomlRange} instance or a plain `{ offset, length }` literal (the two
+ * are structurally interchangeable — only `offset`/`length` are read).
+ *
+ * @public
+ */
+type TomlRangeLike = TomlRange | {
+  readonly offset: number;
+  readonly length: number;
+};
+declare const TomlFormattingOptions_base: Schema.Class<TomlFormattingOptions, Schema.Struct<{
+  readonly newline: Schema.optionalKey<Schema.Literals<readonly ["\n", "\r\n"]>>;
+}>, {}>;
+/**
+ * Options controlling formatting and modification behavior. The only knob is
+ * `newline`: for `format` it normalizes every newline outside multi-line
+ * strings; for `modify` it overrides the dominant newline inherited by
+ * inserted lines.
+ *
+ * @public
+ */
+declare class TomlFormattingOptions extends TomlFormattingOptions_base {}
+declare const TomlModificationError_base: Schema.Class<TomlModificationError, Schema.TaggedStruct<"TomlModificationError", {
+  readonly diagnostic: typeof TomlDiagnostic;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when `TomlFormat.modify` cannot resolve the requested path against
+ * the document's semantic view, when the insertion target refuses (an inline
+ * table or an implicitly created table), or when the replacement value
+ * cannot render as TOML. Carries one structured {@link TomlDiagnostic} —
+ * never a collapsed `reason` string.
+ *
+ * @public
+ */
+declare class TomlModificationError extends TomlModificationError_base {
+  get message(): string;
+}
+/**
+ * Formatting and modification statics. Not instantiable.
+ *
+ * @remarks
+ * `format`/`formatToString` are pure and total: malformed input yields no
+ * edits rather than corrupting the document, and every edit derives from an
+ * expression or value span, so bytes inside multi-line strings are
+ * untouchable by construction. `modify`/`modifyToString` carry a real error
+ * channel — {@link TomlParseError} when the source does not parse and
+ * {@link TomlModificationError} for path-resolution and insertion-target
+ * failures — and every document they produce reparses cleanly.
+ *
+ * @public
+ */
+declare class TomlFormat {
+  private constructor();
+  /**
+   * Compute conservative formatting edits: one space around `=`, leading
+   * indentation stripped, trailing whitespace stripped with one space before
+   * a trailing `#`, one space after a non-empty `#` (unless it starts with
+   * space, tab or `!`), a single final newline, and — when
+   * `options.newline` is set — every newline normalized outside multi-line
+   * strings. Nothing else: no reordering, no blank-line collapsing, no value
+   * rewriting. `range` restricts edits to the expressions intersecting it.
+   * Non-mutating — apply with `TomlEdit.applyAll` (or use
+   * {@link TomlFormat.formatToString}).
+   */
+  static format(text: string, range?: TomlRangeLike, options?: TomlFormattingOptions): ReadonlyArray<TomlEdit>;
+  /**
+   * Format `text` and apply the resulting edits in one step
+   * (`TomlEdit.applyAll ∘ format`). Pure and total.
+   */
+  static formatToString(text: string, range?: TomlRangeLike, options?: TomlFormattingOptions): string;
+  /**
+   * Compute the edits that replace, delete, or insert a value at `path`,
+   * resolved through the document's semantic view. Every segment but the
+   * last must resolve — intermediate tables are never auto-created. A
+   * `value` of `undefined` deletes: a key-value's whole line, an inline
+   * entry, or an array item, splicing separators. A new key inserts per the
+   * pinned placement rules: root keys land after the last root expression
+   * (before the first header), section keys after the section's last
+   * expression, dotted-table keys as dotted keys appended to the defining
+   * section; inline and implicitly created tables refuse. Inserted lines
+   * inherit the document's dominant newline unless `options.newline`
+   * overrides it. Every modified document reparses cleanly.
+   */
+  static readonly modify: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<readonly TomlEdit[], TomlModificationError | TomlParseError, never>;
+  /**
+   * Modify `text` and apply the resulting edits in one step
+   * (`TomlEdit.applyAll ∘ modify`).
+   */
+  static readonly modifyToString: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<string, TomlModificationError | TomlParseError, never>;
+}
+//#endregion
+//#region src/TomlVisitor.d.ts
+/**
+ * The discriminated union of TOML visitor events, in document order.
+ * `TableStart` fires once for the root with `path: []` before any other
+ * event, then again for every `[table]` header. `ArrayTableStart` fires for
+ * every `[[array]]` header with the 0-based element `index`. `KeyValue.path`
+ * includes the final key. `Comment` covers both standalone (trivia) and
+ * trailing comments — see the module remarks for `offset`'s exact meaning.
+ *
+ * @public
+ */
+type TomlVisitorEvent = Data.TaggedEnum<{
+  TableStart: {
+    readonly path: ReadonlyArray<string>;
+  };
+  ArrayTableStart: {
+    readonly path: ReadonlyArray<string>;
+    readonly index: number;
+  };
+  KeyValue: {
+    readonly path: ReadonlyArray<string>;
+    readonly node: TomlKeyValue;
+  };
+  Comment: {
+    readonly text: string;
+    readonly offset: number;
+  };
+}>;
+/**
+ * Constructors and matchers for the `TomlVisitorEvent` union (e.g.
+ * `TomlVisitorEvent.KeyValue({ path, node })`, `TomlVisitorEvent.$is("Comment")`).
+ *
+ * @public
+ */
+declare const TomlVisitorEvent: {
+  readonly $is: <Tag extends "ArrayTableStart" | "Comment" | "KeyValue" | "TableStart">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "ArrayTableStart";
+    readonly path: ReadonlyArray<string>;
+    readonly index: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Comment";
+    readonly text: string;
+    readonly offset: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "KeyValue";
+    readonly path: ReadonlyArray<string>;
+    readonly node: TomlKeyValue;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "TableStart";
+    readonly path: ReadonlyArray<string>;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly ArrayTableStart: (args: {
+        readonly _tag: "ArrayTableStart";
+        readonly path: ReadonlyArray<string>;
+        readonly index: number;
+      }) => any;
+      readonly Comment: (args: {
+        readonly _tag: "Comment";
+        readonly text: string;
+        readonly offset: number;
+      }) => any;
+      readonly KeyValue: (args: {
+        readonly _tag: "KeyValue";
+        readonly path: ReadonlyArray<string>;
+        readonly node: TomlKeyValue;
+      }) => any;
+      readonly TableStart: (args: {
+        readonly _tag: "TableStart";
+        readonly path: ReadonlyArray<string>;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "ArrayTableStart";
+      readonly path: ReadonlyArray<string>;
+      readonly index: number;
+    } | {
+      readonly _tag: "Comment";
+      readonly text: string;
+      readonly offset: number;
+    } | {
+      readonly _tag: "KeyValue";
+      readonly path: ReadonlyArray<string>;
+      readonly node: TomlKeyValue;
+    } | {
+      readonly _tag: "TableStart";
+      readonly path: ReadonlyArray<string>;
+    }) => import("effect/Unify").Unify<ReturnType<Cases["ArrayTableStart" | "Comment" | "KeyValue" | "TableStart"]>>;
+    <Cases extends {
+      readonly ArrayTableStart: (args: {
+        readonly _tag: "ArrayTableStart";
+        readonly path: ReadonlyArray<string>;
+        readonly index: number;
+      }) => any;
+      readonly Comment: (args: {
+        readonly _tag: "Comment";
+        readonly text: string;
+        readonly offset: number;
+      }) => any;
+      readonly KeyValue: (args: {
+        readonly _tag: "KeyValue";
+        readonly path: ReadonlyArray<string>;
+        readonly node: TomlKeyValue;
+      }) => any;
+      readonly TableStart: (args: {
+        readonly _tag: "TableStart";
+        readonly path: ReadonlyArray<string>;
+      }) => any;
+    }>(value: {
+      readonly _tag: "ArrayTableStart";
+      readonly path: ReadonlyArray<string>;
+      readonly index: number;
+    } | {
+      readonly _tag: "Comment";
+      readonly text: string;
+      readonly offset: number;
+    } | {
+      readonly _tag: "KeyValue";
+      readonly path: ReadonlyArray<string>;
+      readonly node: TomlKeyValue;
+    } | {
+      readonly _tag: "TableStart";
+      readonly path: ReadonlyArray<string>;
+    }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["ArrayTableStart" | "Comment" | "KeyValue" | "TableStart"]>>;
+  };
+  readonly ArrayTableStart: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "ArrayTableStart";
+    readonly path: ReadonlyArray<string>;
+    readonly index: number;
+  }, "_tag">;
+  readonly Comment: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Comment";
+    readonly text: string;
+    readonly offset: number;
+  }, "_tag">;
+  readonly KeyValue: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "KeyValue";
+    readonly path: ReadonlyArray<string>;
+    readonly node: TomlKeyValue;
+  }, "_tag">;
+  readonly TableStart: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "TableStart";
+    readonly path: ReadonlyArray<string>;
+  }, "_tag">;
+};
+/**
+ * SAX-style TOML visitor statics. Not instantiable.
+ *
+ * @public
+ */
+declare class TomlVisitor {
+  private constructor();
+  /**
+   * Create a `Stream` of `TomlVisitorEvent` from TOML text, in document
+   * order. Fails the stream with {@link TomlParseError} on the first
+   * lex/parse or semantic violation — never as an unhandled defect.
+   *
+   * @remarks
+   * Construction is eager, not on-demand: the full text is parsed, walked by
+   * `analyze` and sorted into document order up front, inside the `Effect`
+   * `Stream.unwrap` runs to build the stream. Only enumeration of the
+   * already-built event array is streamed — `Stream.take` still short-circuits
+   * consumption, but it does not avoid the initial parse/analyze/sort pass.
+   */
+  static visit(text: string): Stream.Stream<TomlVisitorEvent, TomlParseError>;
+}
+//#endregion
+export { Toml, TomlArray, TomlArrayTableHeader, TomlBoolean, TomlDateTimeLiteral, TomlDiagnostic, TomlDocument, TomlEdit, TomlErrorCode, TomlExpression, TomlFloat, TomlFormat, TomlFormattingOptions, TomlInlineEntry, TomlInlineTable, TomlInteger, TomlKey, TomlKeyKind, TomlKeyValue, TomlLexErrorCode, TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlModificationError, TomlOffsetDateTime, TomlParseError, TomlParseErrorCode, type TomlPath, TomlRange, type TomlRangeLike, type TomlSegment, TomlSemanticErrorCode, TomlString, TomlStringStyle, TomlStringifyError, TomlStringifyErrorCode, TomlStringifyOptions, TomlTableHeader, TomlTrivia, TomlValueNode, TomlVisitor, TomlVisitorEvent };
+//# sourceMappingURL=index.d.ts.map