@effected/toml 0.14.0 → 0.16.0

package/Toml.js

@@ -6,7 +6,7 @@ import { stringifyValue } from "./internal/stringifyValue.js";
 import { TomlDiagnostic } from "./TomlDiagnostic.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
-//#region src/Toml.ts
+// src/Toml.ts
 /**
 * Options controlling stringify behavior. The only knob is `newline` —
 * omitted, it resolves to `"\n"`.
@@ -58,41 +58,47 @@ var TomlStringifyError = class extends Schema.TaggedError()("TomlStringifyError"
 	}
 };
 /**
-* Run the parser and semantic pass, materializing the engine's raw carriers
-* into the typed error: `RawTomlError` becomes a positioned diagnostic and a
-* `GuardExceeded` depth trip becomes a `NestingDepthExceeded` diagnostic
-* (never an unhandled defect). Anything else is a genuine defect and rethrows
-* — synchronously to a `Result` caller, and as a `Die` through the `Effect`
-* forms, which evaluate this inside the effect.
+* Materialize an engine throw into the typed {@link TomlParseError}:
+* `RawTomlError` becomes a positioned diagnostic and a `GuardExceeded` depth
+* trip becomes a `NestingDepthExceeded` diagnostic (never an unhandled
+* defect). Anything else is a genuine defect and rethrows — synchronously to a
+* `Result` caller, and as a `Die` through the `Effect` forms, which evaluate
+* it inside the effect.
+*
+* The one mapping shared by every parse path — `Toml.parse`/`parseResult`,
+* `TomlDocument.parseResult`/`toValueResult` and `TomlVisitor.visit` — so a
+* given input fails identically through each of them.
+*
+* @internal
 */
-const parseToResult = (text) => {
-	try {
-		return Result.succeed(buildValue(parseExpressions(text)));
-	} catch (defect) {
-		if (isRawTomlError(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] }));
-		if (isGuardExceeded(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
-			code: "NestingDepthExceeded",
-			message: defect.message,
-			offset: defect.offset,
-			length: 0
-		})] }));
-		throw defect;
-	}
+const toTomlParseError = (text, defect) => {
+	if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
+	if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
+		code: "NestingDepthExceeded",
+		message: defect.message,
+		offset: defect.offset,
+		length: 0
+	})] });
+	throw defect;
 };
-const stringifyToResult = (value, options) => {
-	try {
-		return Result.succeed(stringifyValue(value, options?.newline ?? "\n"));
-	} catch (defect) {
-		if (isRawTomlError(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) }));
-		if (isGuardExceeded(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
+/** Run the parser and semantic pass, materializing failures via {@link toTomlParseError}. */
+const parseToResult = (text) => Result.try({
+	try: () => buildValue(parseExpressions(text)),
+	catch: (defect) => toTomlParseError(text, defect)
+});
+const stringifyToResult = (value, options) => Result.try({
+	try: () => stringifyValue(value, options?.newline ?? "\n"),
+	catch: (defect) => {
+		if (isRawTomlError(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) });
+		if (isGuardExceeded(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
 			code: "NestingDepthExceeded",
 			message: defect.message,
 			offset: 0,
 			length: 0
-		}) }));
+		}) });
 		throw defect;
 	}
-};
+});
 /**
 * Static entry points for TOML parsing, stringification and the schema
 * factories. Not instantiable.
@@ -303,5 +309,4 @@ var Toml = class Toml {
 	}
 };
 
-//#endregion
-export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions };
+export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions, toTomlParseError };

package/TomlDateTime.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/TomlDateTime.ts
+// src/TomlDateTime.ts
 /** Zero-pad `value` to `width` digits (never truncates a wider value). */
 function pad(value, width) {
 	return String(value).padStart(width, "0");
@@ -143,5 +143,4 @@ var TomlOffsetDateTime = class extends Schema.Class("TomlOffsetDateTime")(Schema
 	}
 };
 
-//#endregion
 export { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime };

package/TomlDiagnostic.js

@@ -1,7 +1,7 @@
 import { TOML_LEX_ERROR_CODES, TOML_PARSE_ERROR_CODES, TOML_SEMANTIC_ERROR_CODES, TOML_STRINGIFY_ERROR_CODES } from "./internal/diagnostics.js";
 import { Schema } from "effect";
 
-//#region src/TomlDiagnostic.ts
+// src/TomlDiagnostic.ts
 /**
 * Error codes emitted by the lexer stage.
 *
@@ -106,5 +106,4 @@ function lineChar(text, offset) {
 	};
 }
 
-//#endregion
 export { TomlDiagnostic, TomlErrorCode, TomlLexErrorCode, TomlParseErrorCode, TomlSemanticErrorCode, TomlStringifyErrorCode };

package/TomlDocument.js

@@ -1,29 +1,12 @@
 import { isRawTomlError } from "./internal/diagnostics.js";
-import { isGuardExceeded } from "./internal/limits.js";
 import { TomlExpression } from "./TomlNode.js";
 import { parseExpressions } from "./internal/parser.js";
 import { analyze, buildValue } from "./internal/semantic.js";
 import { TomlDiagnostic } from "./TomlDiagnostic.js";
-import { TomlParseError } from "./Toml.js";
-import { Effect, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { TomlParseError, toTomlParseError } from "./Toml.js";
+import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
-//#region src/TomlDocument.ts
-/**
-* Materialize an engine throw into the typed error: `RawTomlError` becomes a
-* positioned diagnostic and a `GuardExceeded` depth trip becomes a
-* `NestingDepthExceeded` diagnostic. Anything else is a genuine defect and
-* rethrows.
-*/
-const materializeError = (text, defect) => {
-	if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
-	if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
-		code: "NestingDepthExceeded",
-		message: defect.message,
-		offset: defect.offset,
-		length: 0
-	})] });
-	throw defect;
-};
+// src/TomlDocument.ts
 /**
 * A parsed TOML document that never loses a byte: the `source` text, the
 * linear {@link (TomlExpression:type)} CST whose spans tile the source
@@ -61,36 +44,64 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
 	expressions: Schema.Array(TomlExpression),
 	diagnostics: Schema.Array(TomlDiagnostic)
 }) {
+	/**
+	* Synchronous {@link TomlDocument.parse}, returning a `Result` instead of
+	* an `Effect` — the primitive `parse` is defined in terms of, so a
+	* synchronous host can call it without an Effect runtime. Fails with
+	* {@link TomlParseError} only on lex/parse errors — including a
+	* nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
+	* diagnostic, never a throw. 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).
+	*
+	* @example
+	* ```ts
+	* import { TomlDocument } from "@effected/toml";
+	* import { Result } from "effect";
+	*
+	* const result = TomlDocument.parseResult('name = "Alice"\n');
+	* if (Result.isSuccess(result)) {
+	*   console.log(result.success.stringify()); // => 'name = "Alice"\n'
+	* }
+	* ```
+	*
+	* @param text - The TOML source to parse.
+	* @returns A `Result` succeeding with the {@link TomlDocument}, or failing
+	*   with {@link TomlParseError}.
+	*/
+	static parseResult(text) {
+		return Result.map(Result.try({
+			try: () => parseExpressions(text),
+			catch: (defect) => toTomlParseError(text, defect)
+		}), (expressions) => {
+			const diagnostics = [];
+			try {
+				analyze(expressions);
+			} catch (defect) {
+				if (!isRawTomlError(defect)) throw defect;
+				diagnostics.push(TomlDiagnostic.fromRaw(text, defect.diagnostic));
+			}
+			return TomlDocument.make({
+				source: text,
+				expressions,
+				diagnostics
+			});
+		});
+	}
 	/**
 	* 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).
+	* they land in `diagnostics` as data. Defined in terms of
+	* {@link TomlDocument.parseResult} — synchronous callers can use that
+	* variant directly.
 	*
 	* @param text - The TOML source to parse.
 	* @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
 	*   with {@link TomlParseError}.
 	*/
-	static parse = Effect.fn("TomlDocument.parse")(function* (text) {
-		const expressions = yield* Effect.try({
-			try: () => parseExpressions(text),
-			catch: (defect) => materializeError(text, defect)
-		});
-		const diagnostics = [];
-		try {
-			analyze(expressions);
-		} catch (defect) {
-			if (!isRawTomlError(defect)) throw defect;
-			diagnostics.push(TomlDiagnostic.fromRaw(text, defect.diagnostic));
-		}
-		return TomlDocument.make({
-			source: text,
-			expressions,
-			diagnostics
-		});
-	});
+	static parse = Effect.fn("TomlDocument.parse")((text) => Effect.fromResult(TomlDocument.parseResult(text)));
 	/**
 	* A `Schema<TomlDocument, string>` decoding TOML text into a full document
 	* (source, expressions, diagnostics) and encoding a document back to its
@@ -111,13 +122,43 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
 	* {@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).
+	* wrapper is belt-and-suspenders). Defined in terms of
+	* {@link TomlDocument.toValueResult} — synchronous callers can use that
+	* variant directly.
+	*
+	* @returns An `Effect` that succeeds with the plain value, or fails with
+	*   {@link TomlParseError}.
 	*/
 	toValue() {
-		if (this.diagnostics.length > 0) return Effect.fail(new TomlParseError({ diagnostics: this.diagnostics }));
-		return Effect.try({
+		return Effect.suspend(() => Effect.fromResult(this.toValueResult()));
+	}
+	/**
+	* Synchronous {@link TomlDocument.toValue}, returning a `Result` — the
+	* second half of a synchronous document round-trip that starts at
+	* {@link TomlDocument.parseResult}. Fails with {@link TomlParseError}
+	* carrying the stored `diagnostics` when the parse recorded semantic
+	* violations.
+	*
+	* @example
+	* ```ts
+	* import { TomlDocument } from "@effected/toml";
+	* import { Result } from "effect";
+	*
+	* const parsed = TomlDocument.parseResult("a = 1\na = 2\n");
+	* if (Result.isSuccess(parsed)) {
+	*   const value = parsed.success.toValueResult();
+	*   console.log(Result.isFailure(value)); // => true — DuplicateKey
+	* }
+	* ```
+	*
+	* @returns A `Result` succeeding with the plain value, or failing with
+	*   {@link TomlParseError}.
+	*/
+	toValueResult() {
+		if (this.diagnostics.length > 0) return Result.fail(new TomlParseError({ diagnostics: this.diagnostics }));
+		return Result.try({
 			try: () => buildValue(this.expressions),
-			catch: (defect) => materializeError(this.source, defect)
+			catch: (defect) => toTomlParseError(this.source, defect)
 		});
 	}
 	/**
@@ -133,5 +174,4 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
 	}
 };
 
-//#endregion
 export { TomlDocument };

package/TomlEdit.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/TomlEdit.ts
+// src/TomlEdit.ts
 /**
 * 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`
@@ -52,5 +52,4 @@ var TomlEdit = class extends Schema.Class("TomlEdit")({
 	}
 };
 
-//#endregion
 export { TomlEdit, TomlRange };

package/TomlFormat.js

@@ -7,9 +7,9 @@ import { renderInlineValue, renderKey } from "./internal/stringifyValue.js";
 import { TomlDiagnostic } from "./TomlDiagnostic.js";
 import { TomlDocument } from "./TomlDocument.js";
 import { TomlEdit } from "./TomlEdit.js";
-import { Effect, Schema } from "effect";
+import { Effect, Result, Schema } from "effect";
 
-//#region src/TomlFormat.ts
+// src/TomlFormat.ts
 /**
 * Options controlling formatting and modification behavior. The only knob is
 * `newline`: for `format` it normalizes every newline outside multi-line
@@ -579,7 +579,9 @@ var TomlFormat = class TomlFormat {
 	}
 	/**
 	* Compute the edits that replace, delete, or insert a value at `path`,
-	* resolved through the document's semantic view. Every segment but the
+	* synchronously — the primitive {@link TomlFormat.modify} is defined in
+	* terms of, so a synchronous host can call it without an Effect runtime.
+	* Paths resolve 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
@@ -596,22 +598,24 @@ var TomlFormat = class TomlFormat {
 	*   target instead.
 	* @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
 	*   the newline used for inserted lines.
-	* @returns An `Effect` that succeeds with the edits to apply (via
-	*   `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
+	* @returns A `Result` succeeding with the edits to apply (via
+	*   `TomlEdit.applyAll`), or failing with {@link TomlParseError} when the
 	*   source does not parse, or {@link TomlModificationError} when `path`
 	*   cannot be resolved or the insertion target is not allowed.
 	*/
-	static modify = Effect.fn("TomlFormat.modify")(function* (text, path, value, options) {
-		const failWith = (code, message, offset = 0, length = 0) => new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
+	static modifyResult(text, path, value, options) {
+		const failWith = (code, message, offset = 0, length = 0) => Result.fail(new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
 			code,
 			message,
 			offset,
 			length
-		}) });
-		if (path.length === 0) return yield* failWith("DottedKeyConflict", "an empty path does not address a value");
-		if (path.length > 256) return yield* failWith("NestingDepthExceeded", `path depth ${path.length} exceeds the ${256} cap`);
-		const doc = yield* TomlDocument.parse(text);
-		if (doc.diagnostics.length > 0) return yield* new TomlModificationError({ diagnostic: doc.diagnostics[0] });
+		}) }));
+		if (path.length === 0) return failWith("DottedKeyConflict", "an empty path does not address a value");
+		if (path.length > 256) return failWith("NestingDepthExceeded", `path depth ${path.length} exceeds the ${256} cap`);
+		const parsed = TomlDocument.parseResult(text);
+		if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
+		const doc = parsed.success;
+		if (doc.diagnostics.length > 0) return Result.fail(new TomlModificationError({ diagnostic: doc.diagnostics[0] }));
 		const { root, sections } = buildSemanticIndex(doc.expressions);
 		const ctx = {
 			source: text,
@@ -627,20 +631,73 @@ var TomlFormat = class TomlFormat {
 			for (let i = 0; i < path.length - 1; i++) cursor = step(cursor, path[i]);
 			raw = terminal(cursor, path[path.length - 1], value, ctx);
 		} catch (defect) {
-			if (defect instanceof ModifyFailure) return yield* failWith(defect.code, defect.message, defect.offset, defect.len);
-			if (isRawTomlError(defect)) return yield* new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, defect.diagnostic) });
-			if (isGuardExceeded(defect)) return yield* failWith("NestingDepthExceeded", defect.message, defect.offset);
+			if (defect instanceof ModifyFailure) return failWith(defect.code, defect.message, defect.offset, defect.len);
+			if (isRawTomlError(defect)) return Result.fail(new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, defect.diagnostic) }));
+			if (isGuardExceeded(defect)) return failWith("NestingDepthExceeded", defect.message, defect.offset);
 			throw defect;
 		}
-		return raw.map((edit) => TomlEdit.make({
+		return Result.succeed(raw.map((edit) => TomlEdit.make({
 			offset: edit.offset,
 			length: edit.length,
 			content: edit.newText
-		}));
-	});
+		})));
+	}
+	/**
+	* Compute the edits that replace, delete, or insert a value at `path`.
+	* Defined in terms of {@link TomlFormat.modifyResult}, which carries the
+	* full contract — semantic path resolution, deletion splicing and the
+	* pinned insertion placement rules — behind a `TomlFormat.modify` span;
+	* synchronous callers can use that variant directly.
+	*
+	* @param text - The TOML source to modify.
+	* @param path - The location to set, replace or delete.
+	* @param value - The plain JavaScript value to write; `undefined` deletes the
+	*   target instead.
+	* @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
+	*   the newline used for inserted lines.
+	* @returns An `Effect` that succeeds with the edits to apply (via
+	*   `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
+	*   source does not parse, or {@link TomlModificationError} when `path`
+	*   cannot be resolved or the insertion target is not allowed.
+	*
+	* @remarks
+	* The source is parsed through `TomlDocument.parseResult`, so this span no
+	* longer opens a nested `TomlDocument.parse` child span.
+	*/
+	static modify = Effect.fn("TomlFormat.modify")((text, path, value, options) => Effect.fromResult(TomlFormat.modifyResult(text, path, value, options)));
+	/**
+	* Synchronous {@link TomlFormat.modifyToString}: modify `text` and apply the
+	* resulting edits in one step (`TomlEdit.applyAll ∘ modifyResult`),
+	* returning a `Result`. Inherits the {@link TomlFormat.modifyResult} error
+	* channel.
+	*
+	* @example
+	* ```ts
+	* import { TomlFormat } from "@effected/toml";
+	* import { Result } from "effect";
+	*
+	* const result = TomlFormat.modifyToStringResult("port = 3000 # dev\n", ["port"], 8080);
+	* if (Result.isSuccess(result)) {
+	*   console.log(result.success); // => "port = 8080 # dev\n"
+	* }
+	* ```
+	*
+	* @param text - The TOML source to modify.
+	* @param path - The location to set, replace or delete.
+	* @param value - The plain JavaScript value to write; `undefined` deletes the
+	*   target instead.
+	* @param options - Optional {@link TomlFormattingOptions}.
+	* @returns A `Result` succeeding with the modified text, or failing with
+	*   {@link TomlParseError} or {@link TomlModificationError}.
+	*/
+	static modifyToStringResult(text, path, value, options) {
+		return Result.map(TomlFormat.modifyResult(text, path, value, options), (edits) => TomlEdit.applyAll(text, edits));
+	}
 	/**
 	* Modify `text` and apply the resulting edits in one step
-	* (`TomlEdit.applyAll ∘ modify`).
+	* (`TomlEdit.applyAll ∘ modify`). Defined in terms of
+	* {@link TomlFormat.modifyToStringResult}; it opens its own span and no
+	* longer a nested `TomlFormat.modify` child span.
 	*
 	* @param text - The TOML source to modify.
 	* @param path - The location to set, replace or delete.
@@ -651,11 +708,7 @@ var TomlFormat = class TomlFormat {
 	*   {@link TomlParseError} or {@link TomlModificationError}, as
 	*   {@link TomlFormat.modify} does.
 	*/
-	static modifyToString = Effect.fn("TomlFormat.modifyToString")(function* (text, path, value, options) {
-		const edits = yield* TomlFormat.modify(text, path, value, options);
-		return TomlEdit.applyAll(text, edits);
-	});
+	static modifyToString = Effect.fn("TomlFormat.modifyToString")((text, path, value, options) => Effect.fromResult(TomlFormat.modifyToStringResult(text, path, value, options)));
 };
 
-//#endregion
 export { TomlFormat, TomlFormattingOptions, TomlModificationError };

package/TomlNode.js

@@ -1,7 +1,7 @@
 import { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime } from "./TomlDateTime.js";
 import { Schema } from "effect";
 
-//#region src/TomlNode.ts
+// src/TomlNode.ts
 /**
 * The three simple-key spellings: `bare`, `basic` (`"..."`) and `literal`
 * (`'...'`).
@@ -209,5 +209,4 @@ const TomlExpression = Schema.Union([
 	TomlTrivia
 ]);
 
-//#endregion
 export { TomlArray, TomlArrayTableHeader, TomlBoolean, TomlDateTimeLiteral, TomlExpression, TomlFloat, TomlInlineEntry, TomlInlineTable, TomlInteger, TomlKey, TomlKeyKind, TomlKeyValue, TomlString, TomlStringStyle, TomlTableHeader, TomlTrivia, TomlValueNode };

package/TomlVisitor.js

@@ -1,14 +1,11 @@
-import { isRawTomlError } from "./internal/diagnostics.js";
-import { isGuardExceeded } from "./internal/limits.js";
 import { TomlKeyValue, TomlTrivia } from "./TomlNode.js";
 import { scanComment, scanNewline, scanWhitespace } from "./internal/scanner.js";
 import { parseExpressions } from "./internal/parser.js";
 import { analyze } from "./internal/semantic.js";
-import { TomlDiagnostic } from "./TomlDiagnostic.js";
-import { TomlParseError } from "./Toml.js";
-import { Data, Effect, Stream } from "effect";
+import { toTomlParseError } from "./Toml.js";
+import { Data, Effect, Result, Stream } from "effect";
 
-//#region src/TomlVisitor.ts
+// src/TomlVisitor.ts
 /**
 * Constructors and matchers for the `TomlVisitorEvent` union (e.g.
 * `TomlVisitorEvent.KeyValue({ path, node })`, `TomlVisitorEvent.$is("Comment")`).
@@ -108,22 +105,14 @@ const collectEvents = (text) => {
 };
 /**
 * Run `collectEvents`, materializing the engine's raw carriers into
-* {@link TomlParseError} exactly like `Toml.parse` — a lex/parse error and a
-* semantic-pass error (e.g. `DuplicateKey`) both fail the same way.
+* {@link TomlParseError} through the same `toTomlParseError` mapping
+* `Toml.parse` uses — a lex/parse error and a semantic-pass error (e.g.
+* `DuplicateKey`) both fail the same way.
 */
-const collectEventsOrFail = (text) => Effect.try({
+const collectEventsOrFail = (text) => Effect.suspend(() => Effect.fromResult(Result.try({
 	try: () => collectEvents(text),
-	catch: (defect) => {
-		if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
-		if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
-			code: "NestingDepthExceeded",
-			message: defect.message,
-			offset: defect.offset,
-			length: 0
-		})] });
-		throw defect;
-	}
-});
+	catch: (defect) => toTomlParseError(text, defect)
+})));
 /**
 * Walks TOML text as a `Stream` of table, array-table, key-value and comment
 * events in document order, without building a value. Not instantiable.
@@ -162,5 +151,4 @@ var TomlVisitor = class {
 	}
 };
 
-//#endregion
 export { TomlVisitor, TomlVisitorEvent };

package/index.d.ts

@@ -1,5 +1,4 @@
 import { Data, Effect, Result, Schema, Stream } from "effect";
-//#region src/TomlDiagnostic.d.ts
 /**
  * Error codes emitted by the lexer stage.
  *
@@ -99,8 +98,6 @@ export declare class TomlDiagnostic extends TomlDiagnostic_base {
     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"]>>;
 }>, {}>;
@@ -360,8 +357,6 @@ export declare class Toml {
    */
   static bind<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>): TomlBoundCodec<T, RD, RE>;
 }
-//#endregion
-//#region src/TomlDateTime.d.ts
 declare const TomlLocalDate_base: Schema.Class<TomlLocalDate, Schema.Struct<{
   year: Schema.Int;
   month: Schema.Int;
@@ -429,8 +424,6 @@ declare const TomlOffsetDateTime_base: Schema.Class<TomlOffsetDateTime, Schema.S
 export declare class TomlOffsetDateTime extends TomlOffsetDateTime_base {
   toString(): string;
 }
-//#endregion
-//#region src/TomlNode.d.ts
 /**
  * The three simple-key spellings: `bare`, `basic` (`"..."`) and `literal`
  * (`'...'`).
@@ -647,8 +640,6 @@ export declare const TomlExpression: Schema.Union<readonly [typeof TomlKeyValue,
  * @public
  */
 export 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]>>;
@@ -687,13 +678,40 @@ declare const TomlDocument_base: Schema.Class<TomlDocument, Schema.Struct<{
  * @public
  */
 export declare class TomlDocument extends TomlDocument_base {
+  /**
+   * Synchronous {@link TomlDocument.parse}, returning a `Result` instead of
+   * an `Effect` — the primitive `parse` is defined in terms of, so a
+   * synchronous host can call it without an Effect runtime. Fails with
+   * {@link TomlParseError} only on lex/parse errors — including a
+   * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
+   * diagnostic, never a throw. 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).
+   *
+   * @example
+   * ```ts
+   * import { TomlDocument } from "@effected/toml";
+   * import { Result } from "effect";
+   *
+   * const result = TomlDocument.parseResult('name = "Alice"\n');
+   * if (Result.isSuccess(result)) {
+   *   console.log(result.success.stringify()); // => 'name = "Alice"\n'
+   * }
+   * ```
+   *
+   * @param text - The TOML source to parse.
+   * @returns A `Result` succeeding with the {@link TomlDocument}, or failing
+   *   with {@link TomlParseError}.
+   */
+  static parseResult(text: string): Result.Result<TomlDocument, TomlParseError>;
   /**
    * 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).
+   * they land in `diagnostics` as data. Defined in terms of
+   * {@link TomlDocument.parseResult} — synchronous callers can use that
+   * variant directly.
    *
    * @param text - The TOML source to parse.
    * @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
@@ -715,9 +733,37 @@ export declare class TomlDocument extends TomlDocument_base {
    * {@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).
+   * wrapper is belt-and-suspenders). Defined in terms of
+   * {@link TomlDocument.toValueResult} — synchronous callers can use that
+   * variant directly.
+   *
+   * @returns An `Effect` that succeeds with the plain value, or fails with
+   *   {@link TomlParseError}.
    */
   toValue(): Effect.Effect<unknown, TomlParseError>;
+  /**
+   * Synchronous {@link TomlDocument.toValue}, returning a `Result` — the
+   * second half of a synchronous document round-trip that starts at
+   * {@link TomlDocument.parseResult}. Fails with {@link TomlParseError}
+   * carrying the stored `diagnostics` when the parse recorded semantic
+   * violations.
+   *
+   * @example
+   * ```ts
+   * import { TomlDocument } from "@effected/toml";
+   * import { Result } from "effect";
+   *
+   * const parsed = TomlDocument.parseResult("a = 1\na = 2\n");
+   * if (Result.isSuccess(parsed)) {
+   *   const value = parsed.success.toValueResult();
+   *   console.log(Result.isFailure(value)); // => true — DuplicateKey
+   * }
+   * ```
+   *
+   * @returns A `Result` succeeding with the plain value, or failing with
+   *   {@link TomlParseError}.
+   */
+  toValueResult(): Result.Result<unknown, TomlParseError>;
   /**
    * Reconstruct the document text by concatenating each expression's source
    * span in order. The expression spans tile the source exactly, so the
@@ -726,8 +772,6 @@ export declare class TomlDocument extends TomlDocument_base {
    */
   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.
@@ -784,8 +828,6 @@ export declare class TomlEdit extends TomlEdit_base {
    */
   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
@@ -887,7 +929,9 @@ export declare class TomlFormat {
   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
+   * synchronously — the primitive {@link TomlFormat.modify} is defined in
+   * terms of, so a synchronous host can call it without an Effect runtime.
+   * Paths resolve 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
@@ -904,15 +948,66 @@ export declare class TomlFormat {
    *   target instead.
    * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
    *   the newline used for inserted lines.
+   * @returns A `Result` succeeding with the edits to apply (via
+   *   `TomlEdit.applyAll`), or failing with {@link TomlParseError} when the
+   *   source does not parse, or {@link TomlModificationError} when `path`
+   *   cannot be resolved or the insertion target is not allowed.
+   */
+  static modifyResult(text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions): Result.Result<ReadonlyArray<TomlEdit>, TomlParseError | TomlModificationError>;
+  /**
+   * Compute the edits that replace, delete, or insert a value at `path`.
+   * Defined in terms of {@link TomlFormat.modifyResult}, which carries the
+   * full contract — semantic path resolution, deletion splicing and the
+   * pinned insertion placement rules — behind a `TomlFormat.modify` span;
+   * synchronous callers can use that variant directly.
+   *
+   * @param text - The TOML source to modify.
+   * @param path - The location to set, replace or delete.
+   * @param value - The plain JavaScript value to write; `undefined` deletes the
+   *   target instead.
+   * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
+   *   the newline used for inserted lines.
    * @returns An `Effect` that succeeds with the edits to apply (via
    *   `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
    *   source does not parse, or {@link TomlModificationError} when `path`
    *   cannot be resolved or the insertion target is not allowed.
+   *
+   * @remarks
+   * The source is parsed through `TomlDocument.parseResult`, so this span no
+   * longer opens a nested `TomlDocument.parse` child span.
    */
   static readonly modify: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<readonly TomlEdit[], TomlModificationError | TomlParseError, never>;
+  /**
+   * Synchronous {@link TomlFormat.modifyToString}: modify `text` and apply the
+   * resulting edits in one step (`TomlEdit.applyAll ∘ modifyResult`),
+   * returning a `Result`. Inherits the {@link TomlFormat.modifyResult} error
+   * channel.
+   *
+   * @example
+   * ```ts
+   * import { TomlFormat } from "@effected/toml";
+   * import { Result } from "effect";
+   *
+   * const result = TomlFormat.modifyToStringResult("port = 3000 # dev\n", ["port"], 8080);
+   * if (Result.isSuccess(result)) {
+   *   console.log(result.success); // => "port = 8080 # dev\n"
+   * }
+   * ```
+   *
+   * @param text - The TOML source to modify.
+   * @param path - The location to set, replace or delete.
+   * @param value - The plain JavaScript value to write; `undefined` deletes the
+   *   target instead.
+   * @param options - Optional {@link TomlFormattingOptions}.
+   * @returns A `Result` succeeding with the modified text, or failing with
+   *   {@link TomlParseError} or {@link TomlModificationError}.
+   */
+  static modifyToStringResult(text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions): Result.Result<string, TomlParseError | TomlModificationError>;
   /**
    * Modify `text` and apply the resulting edits in one step
-   * (`TomlEdit.applyAll ∘ modify`).
+   * (`TomlEdit.applyAll ∘ modify`). Defined in terms of
+   * {@link TomlFormat.modifyToStringResult}; it opens its own span and no
+   * longer a nested `TomlFormat.modify` child span.
    *
    * @param text - The TOML source to modify.
    * @param path - The location to set, replace or delete.
@@ -925,8 +1020,6 @@ export declare class TomlFormat {
    */
   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
@@ -1116,6 +1209,5 @@ export declare class TomlVisitor {
    */
   static visit(text: string): Stream.Stream<TomlVisitorEvent, TomlParseError>;
 }
-//#endregion
 export type { TomlBoundCodec, TomlPath, TomlRangeLike, TomlSegment };
 //# sourceMappingURL=index.d.ts.map

package/internal/diagnostics.js

@@ -1,4 +1,4 @@
-//#region src/internal/diagnostics.ts
+// src/internal/diagnostics.ts
 const TOML_LEX_ERROR_CODES = [
 	"InvalidUtf8",
 	"UnterminatedString",
@@ -47,5 +47,4 @@ var RawTomlError = class extends Error {
 };
 const isRawTomlError = (u) => u instanceof RawTomlError;
 
-//#endregion
 export { RawTomlError, TOML_LEX_ERROR_CODES, TOML_PARSE_ERROR_CODES, TOML_SEMANTIC_ERROR_CODES, TOML_STRINGIFY_ERROR_CODES, isRawTomlError };

package/internal/limits.js

@@ -1,4 +1,4 @@
-//#region src/internal/limits.ts
+// src/internal/limits.ts
 /**
 * Raw guard-trip signal. The engine throws it; ONLY the public modules catch
 * it and materialize the typed error. It must never escape a public entry
@@ -20,5 +20,4 @@ var GuardExceeded = class extends Error {
 };
 const isGuardExceeded = (u) => u instanceof GuardExceeded;
 
-//#endregion
 export { GuardExceeded, isGuardExceeded };

package/internal/parser.js

@@ -4,7 +4,7 @@ import { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime } f
 import { TomlArray, TomlArrayTableHeader, TomlBoolean, TomlDateTimeLiteral, TomlFloat, TomlInlineEntry, TomlInlineTable, TomlInteger, TomlKey, TomlKeyValue, TomlString, TomlTableHeader, TomlTrivia } from "../TomlNode.js";
 import { assertValidUnicode, classifyValueToken, scanBareKey, scanBasicString, scanComment, scanLiteralString, scanMultilineBasicString, scanMultilineLiteralString, scanNewline, scanValueToken, scanWhitespace, skipBom } from "./scanner.js";
 
-//#region src/internal/parser.ts
+// src/internal/parser.ts
 const LF = 10;
 const CR = 13;
 const QUOTE = 34;
@@ -400,5 +400,4 @@ const parseExpressions = (source) => {
 	return expressions;
 };
 
-//#endregion
 export { parseExpressions };

package/internal/scanner.js

@@ -1,7 +1,7 @@
 import { RawTomlError } from "./diagnostics.js";
 import { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime } from "../TomlDateTime.js";
 
-//#region src/internal/scanner.ts
+// src/internal/scanner.ts
 const NUL = 0;
 const TAB = 9;
 const LF = 10;
@@ -503,5 +503,4 @@ const classifyValueToken = (token, offset) => {
 	return raise("InvalidValue", `${token} is not a valid TOML value`, offset, length);
 };
 
-//#endregion
 export { assertValidUnicode, classifyValueToken, isBareKeyChar, scanBareKey, scanBasicString, scanComment, scanLiteralString, scanMultilineBasicString, scanMultilineLiteralString, scanNewline, scanValueToken, scanWhitespace, skipBom };

package/internal/semantic.js

@@ -1,7 +1,7 @@
 import { RawTomlError } from "./diagnostics.js";
 import { TomlArray, TomlArrayTableHeader, TomlInlineTable, TomlTableHeader, TomlTrivia } from "../TomlNode.js";
 
-//#region src/internal/semantic.ts
+// src/internal/semantic.ts
 const makeNode = (kind, sectionId = 0) => ({
 	kind,
 	table: /* @__PURE__ */ new Map(),
@@ -249,5 +249,4 @@ const buildValue = (expressions) => {
 	return result;
 };
 
-//#endregion
 export { analyze, buildValue };

package/internal/stringifyValue.js

@@ -2,7 +2,7 @@ import { RawTomlError } from "./diagnostics.js";
 import { GuardExceeded } from "./limits.js";
 import { TomlLocalDate, TomlLocalDateTime, TomlLocalTime, TomlOffsetDateTime } from "../TomlDateTime.js";
 
-//#region src/internal/stringifyValue.ts
+// src/internal/stringifyValue.ts
 const INT64_MIN = -(2n ** 63n);
 const INT64_MAX = 2n ** 63n - 1n;
 const INT64_FLOAT_BOUND = 2 ** 63;
@@ -187,5 +187,4 @@ const stringifyValue = (value, newline) => {
 	return lines.length === 0 ? "" : `${lines.join(newline)}${newline}`;
 };
 
-//#endregion
 export { renderInlineValue, renderKey, stringifyValue };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/toml",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"private": false,
 	"description": "TOML 1.1.0 parsing, editing and formatting as Effect schemas: typed diagnostics, a lossless CST and first-class date-time values.",
 	"keywords": [