@effected/toml 0.15.0 → 0.17.0

package/Toml.js

@@ -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,4 +309,4 @@ var Toml = class Toml {
 	}
 };
 
-export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions };
+export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions, toTomlParseError };

package/TomlDiagnostic.js

@@ -1,5 +1,6 @@
 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";
+import { LineIndex } from "@effected/source";
 
 // src/TomlDiagnostic.ts
 /**
@@ -49,6 +50,15 @@ const TomlErrorCode = Schema.Union([
 * and `@effected/yaml`'s `YamlDiagnostic`; `message` is this package's
 * additive extra.
 *
+* With `message` it satisfies `@effected/source`'s `SourceDiagnostic`
+* structurally, so a consumer written over that interface (an LSP server, a
+* CLI printing annotations) reads it directly. `line` and `character` come
+* from `@effected/source`'s `LineIndex` under its default `"lsp"` rule: a line
+* ends at `\n`, `\r\n` or a bare `\r`, as an LSP client counts. TOML's own
+* newline is `\n` or `\r\n` only, so a bare `\r` is invalid TOML; it is
+* counted as a line break only so a diagnostic about it positions LSP-style.
+* An offset at the `\n` of a `\r\n` reads as the end of its line.
+*
 * @public
 */
 var TomlDiagnostic = class TomlDiagnostic extends Schema.Class("TomlDiagnostic")({
@@ -69,7 +79,7 @@ var TomlDiagnostic = class TomlDiagnostic extends Schema.Class("TomlDiagnostic")
 	* @returns The diagnostic with `line` and `character` filled in.
 	*/
 	static fromRaw(source, raw) {
-		const { line, character } = lineChar(source, raw.offset);
+		const { line, character } = LineIndex.make(source).positionAt(raw.offset);
 		return TomlDiagnostic.make({
 			code: raw.code,
 			message: raw.message,
@@ -80,30 +90,5 @@ var TomlDiagnostic = class TomlDiagnostic extends Schema.Class("TomlDiagnostic")
 		});
 	}
 };
-/**
-* Compute the zero-based line/character position of `offset` within `text`.
-* Recognizes `\n`, `\r` and `\r\n` as line breaks (TOML's newline grammar);
-* a CRLF pair counts as a single newline.
-*/
-function lineChar(text, offset) {
-	let line = 0;
-	let lineStart = 0;
-	const limit = Math.min(offset, text.length);
-	for (let i = 0; i < limit; i++) {
-		const ch = text.charCodeAt(i);
-		if (ch === 10) {
-			line++;
-			lineStart = i + 1;
-		} else if (ch === 13) {
-			if (i + 1 < text.length && text.charCodeAt(i + 1) === 10) i++;
-			line++;
-			lineStart = i + 1;
-		}
-	}
-	return {
-		line,
-		character: offset - lineStart
-	};
-}
 
 export { TomlDiagnostic, TomlErrorCode, TomlLexErrorCode, TomlParseErrorCode, TomlSemanticErrorCode, TomlStringifyErrorCode };

package/TomlDocument.js

@@ -1,30 +1,13 @@
 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";
 
 // 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;
-};
-/**
 * 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
@@ -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)
 		});
 	}
 	/**

package/TomlFormat.js

@@ -7,7 +7,7 @@ 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";
 
 // src/TomlFormat.ts
 /**
@@ -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,10 +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)));
 };
 
 export { TomlFormat, TomlFormattingOptions, TomlModificationError };

package/TomlVisitor.js

@@ -1,12 +1,9 @@
-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";
 
 // src/TomlVisitor.ts
 /**
@@ -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.

package/index.d.ts

@@ -79,6 +79,15 @@ declare const TomlDiagnostic_base: Schema.Class<TomlDiagnostic, Schema.Struct<{
  * and `@effected/yaml`'s `YamlDiagnostic`; `message` is this package's
  * additive extra.
  *
+ * With `message` it satisfies `@effected/source`'s `SourceDiagnostic`
+ * structurally, so a consumer written over that interface (an LSP server, a
+ * CLI printing annotations) reads it directly. `line` and `character` come
+ * from `@effected/source`'s `LineIndex` under its default `"lsp"` rule: a line
+ * ends at `\n`, `\r\n` or a bare `\r`, as an LSP client counts. TOML's own
+ * newline is `\n` or `\r\n` only, so a bare `\r` is invalid TOML; it is
+ * counted as a line break only so a diagnostic about it positions LSP-style.
+ * An offset at the `\n` of a `\r\n` reads as the end of its line.
+ *
  * @public
  */
 export declare class TomlDiagnostic extends TomlDiagnostic_base {
@@ -678,13 +687,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
@@ -706,9 +742,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
@@ -874,7 +938,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
@@ -891,15 +957,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.
@@ -947,125 +1064,22 @@ export type TomlVisitorEvent = Data.TaggedEnum<{
  *
  * @public
  */
-export 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">;
-};
+export declare const TomlVisitorEvent: Data.TaggedEnum.Constructor<{
+  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>;
+}>;
 /**
  * Walks TOML text as a `Stream` of table, array-table, key-value and comment
  * events in document order, without building a value. Not instantiable.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/toml",
-	"version": "0.15.0",
+	"version": "0.17.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": [
@@ -37,6 +37,9 @@
 		},
 		"./package.json": "./package.json"
 	},
+	"dependencies": {
+		"@effected/source": "^0.1.0"
+	},
 	"peerDependencies": {
 		"effect": "^4.0.0"
 	},

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }