@effected/yaml 0.23.0 → 0.24.0

package/Yaml.js

@@ -224,8 +224,12 @@ const aliasCountExceededError = (message, text) => new YamlParseError({
 /**
 * Map an internal stringifier throw to its typed {@link YamlStringifyError},
 * or return `undefined` for any other defect (which the caller re-throws).
-* Shared by the Effect and synchronous stringify paths so both surface the
-* hardening guards (circular reference, nesting-depth cap) identically.
+* Shared by every stringify path — `Yaml.stringify`/`stringifyResult`, the
+* schema encoders, `YamlDocument#stringifyResult` and `YamlFormat.modify`'s
+* backstop — so all of them surface the hardening guards (circular
+* reference, nesting-depth cap) identically.
+*
+* @internal
 */
 const stringifyDefectToError = (defect, value) => {
 	if (defect instanceof StringifyFailure) return new YamlStringifyError({
@@ -266,12 +270,13 @@ const parseResultImpl = (text, options) => {
 		input: text
 	}));
 	const anchors = /* @__PURE__ */ new Map();
-	try {
-		return Result.succeed(nodeToJsValue(doc.contents, anchors, options?.maxAliasCount ?? 100));
-	} catch (defect) {
-		if (defect instanceof AliasExpansionBudgetExceeded) return Result.fail(aliasCountExceededError(defect.message, text));
-		throw defect;
-	}
+	return Result.try({
+		try: () => nodeToJsValue(doc.contents, anchors, options?.maxAliasCount ?? 100),
+		catch: (defect) => {
+			if (defect instanceof AliasExpansionBudgetExceeded) return aliasCountExceededError(defect.message, text);
+			throw defect;
+		}
+	});
 };
 /**
 * Synchronous multi-document parse returning a `Result`. Mirrors
@@ -308,15 +313,14 @@ const parseAllResultImpl = (text, options) => {
 * recursion budget yields a `Failure` carrying a typed {@link YamlStringifyError},
 * never a thrown defect.
 */
-const stringifyResultImpl = (value, options) => {
-	try {
-		return Result.succeed(stringifyValue(value, toStringifyInput(options)));
-	} catch (defect) {
+const stringifyResultImpl = (value, options) => Result.try({
+	try: () => stringifyValue(value, toStringifyInput(options)),
+	catch: (defect) => {
 		const error = stringifyDefectToError(defect, value);
-		if (error !== void 0) return Result.fail(error);
+		if (error !== void 0) return error;
 		throw defect;
 	}
-};
+});
 /**
 * Collect the raw diagnostics that make a composed document a parse failure:
 * every fatal-code error, plus DuplicateKey warnings promoted to errors when
@@ -328,14 +332,6 @@ const failureRecords = (doc, uniqueKeys) => {
 	if (fatal.length > 0) return fatal;
 	return uniqueKeys ? doc.warnings.filter((w) => w.code === "DuplicateKey") : [];
 };
-const stringifyOrFail = (value, options) => Effect.try({
-	try: () => stringifyValue(value, toStringifyInput(options)),
-	catch: (defect) => {
-		const error = stringifyDefectToError(defect, value);
-		if (error !== void 0) return error;
-		throw defect;
-	}
-});
 /**
 * Static entry points for YAML parsing, stringification, comment stripping,
 * semantic equality and the schema factories. Not instantiable.
@@ -425,9 +421,7 @@ var Yaml = class Yaml {
 	* @returns An `Effect` that succeeds with the YAML text, or fails with
 	*   {@link YamlStringifyError}.
 	*/
-	static stringify = Effect.fn("Yaml.stringify")(function* (value, options) {
-		return yield* stringifyOrFail(value, options);
-	});
+	static stringify = Effect.fn("Yaml.stringify")((value, options) => Effect.fromResult(stringifyResultImpl(value, options)));
 	/**
 	* Synchronous single-document parse, returning a `Result` instead of
 	* an `Effect`. A pure escape hatch for config-time callers that cannot
@@ -631,7 +625,7 @@ var Yaml = class Yaml {
 	static fromString(options) {
 		return Schema.String.pipe(Schema.decodeTo(Schema.Unknown, SchemaTransformation.transformEffect({
 			decode: (input) => Yaml.parse(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, input))),
-			encode: (value) => stringifyOrFail(value).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, value)))
+			encode: (value) => Effect.fromResult(stringifyResultImpl(value)).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, value)))
 		})));
 	}
 	/**
@@ -655,7 +649,7 @@ var Yaml = class Yaml {
 				if (values.length === 0) return "";
 				const parts = [];
 				for (let index = 0; index < values.length; index++) {
-					const yaml = yield* stringifyOrFail(values[index]).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, values)));
+					const yaml = yield* Effect.fromResult(stringifyResultImpl(values[index])).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, values)));
 					parts.push(index > 0 ? `---\n${yaml}` : yaml);
 				}
 				return parts.join("");
@@ -774,4 +768,4 @@ function deepEqualValues(a, b) {
 	return false;
 }
 
-export { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions };
+export { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions, stringifyDefectToError };

package/YamlDocument.js

@@ -1,10 +1,10 @@
 import { YamlNode } from "./YamlNode.js";
 import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
 import { isFatalCode } from "./internal/diagnostics.js";
-import { StringifyDepthExceeded, StringifyFailure, stringifyDocument } from "./internal/stringifier.js";
+import { stringifyDocument } from "./internal/stringifier.js";
 import { YamlDiagnostic } from "./YamlDiagnostic.js";
-import { YamlParseError, YamlStringifyError } from "./Yaml.js";
-import { Effect, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { YamlParseError, stringifyDefectToError } from "./Yaml.js";
+import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 // src/YamlDocument.ts
 /**
@@ -58,11 +58,47 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	hasDocumentEnd: Schema.optionalKey(Schema.Boolean),
 	hasDocumentStartTab: Schema.optionalKey(Schema.Boolean)
 }) {
+	/**
+	* Synchronous single-document parse, returning a `Result` instead of an
+	* `Effect`. This is the primitive {@link YamlDocument.parse} is defined in
+	* terms of — a synchronous host can call it without an Effect runtime.
+	* Keeps the full AST, directives and recovered diagnostics; fails with the
+	* aggregate {@link YamlParseError} when any fatal-code diagnostic is
+	* present, and non-fatal diagnostics are data on the returned document.
+	*
+	* @example
+	* ```ts
+	* import { YamlDocument } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = YamlDocument.parseResult("name: Alice\n");
+	* if (Result.isSuccess(result)) {
+	*   console.log(result.success.toValue()); // => { name: "Alice" }
+	* }
+	* ```
+	*
+	* @param text - The YAML source to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns A `Result` succeeding with the {@link YamlDocument}, or failing
+	*   with {@link YamlParseError}.
+	*/
+	static parseResult(text, options) {
+		const raw = composeFirstDocument(text, toParseInput(options));
+		const fatal = raw.errors.filter((e) => isFatalCode(e.code));
+		if (fatal.length > 0) return Result.fail(new YamlParseError({
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
+			input: text
+		}));
+		return Result.succeed(fromRawDocument(raw, text));
+	}
 	/**
 	* Parse a single YAML document, keeping the full AST, directives and
 	* recovered diagnostics. Fails with the aggregate {@link YamlParseError}
 	* when any fatal-code diagnostic is present; non-fatal diagnostics are
-	* data on the returned document.
+	* data on the returned document. Defined in terms of
+	* {@link YamlDocument.parseResult} — synchronous callers can use that
+	* variant directly.
 	*
 	* @param text - The YAML source to parse.
 	* @param options - Optional {@link YamlParseOptions}; defaults apply for
@@ -70,19 +106,46 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* @returns An `Effect` that succeeds with the {@link YamlDocument}, or fails
 	*   with {@link YamlParseError}.
 	*/
-	static parse = Effect.fn("YamlDocument.parse")(function* (text, options) {
-		const raw = composeFirstDocument(text, toParseInput(options));
-		const fatal = raw.errors.filter((e) => isFatalCode(e.code));
-		if (fatal.length > 0) return yield* new YamlParseError({
+	static parse = Effect.fn("YamlDocument.parse")((text, options) => Effect.fromResult(YamlDocument.parseResult(text, options)));
+	/**
+	* Synchronous multi-document parse, returning a `Result` instead of an
+	* `Effect` — the primitive {@link YamlDocument.parseAll} is defined in
+	* terms of. Any fatal diagnostic in any document — or a stream-level
+	* directive-placement error — fails the whole parse with one aggregate
+	* {@link YamlParseError}.
+	*
+	* @example
+	* ```ts
+	* import { YamlDocument } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = YamlDocument.parseAllResult("a: 1\n---\nb: 2\n");
+	* if (Result.isSuccess(result)) {
+	*   console.log(result.success.length); // => 2
+	* }
+	* ```
+	*
+	* @param text - The YAML stream to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns A `Result` succeeding with one {@link YamlDocument} per
+	*   document, or failing with {@link YamlParseError}.
+	*/
+	static parseAllResult(text, options) {
+		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
+		const fatal = [...streamErrors.filter((e) => e.code === "InvalidDirective"), ...documents.flatMap((d) => d.errors.filter((e) => isFatalCode(e.code)))];
+		if (fatal.length > 0) return Result.fail(new YamlParseError({
 			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
 			input: text
-		});
-		return fromRawDocument(raw, text);
-	});
+		}));
+		return Result.succeed(documents.map((raw) => fromRawDocument(raw, text)));
+	}
 	/**
 	* Parse a multi-document YAML stream into one {@link YamlDocument} per
 	* document. Any fatal diagnostic in any document — or a stream-level
-	* directive-placement error — fails the whole Effect.
+	* directive-placement error — fails the whole Effect. Defined in terms of
+	* {@link YamlDocument.parseAllResult} — synchronous callers can use that
+	* variant directly.
 	*
 	* @param text - The YAML stream to parse.
 	* @param options - Optional {@link YamlParseOptions}; defaults apply for
@@ -90,15 +153,7 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* @returns An `Effect` that succeeds with one {@link YamlDocument} per
 	*   document, or fails with {@link YamlParseError}.
 	*/
-	static parseAll = Effect.fn("YamlDocument.parseAll")(function* (text, options) {
-		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
-		const fatal = [...streamErrors.filter((e) => e.code === "InvalidDirective"), ...documents.flatMap((d) => d.errors.filter((e) => isFatalCode(e.code)))];
-		if (fatal.length > 0) return yield* new YamlParseError({
-			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
-			input: text
-		});
-		return documents.map((raw) => fromRawDocument(raw, text));
-	});
+	static parseAll = Effect.fn("YamlDocument.parseAll")((text, options) => Effect.fromResult(YamlDocument.parseAllResult(text, options)));
 	/**
 	* A `Schema<YamlDocument, string>` decoding YAML text into a full
 	* document (AST, directives, diagnostics) and encoding a document back to
@@ -119,11 +174,16 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	}
 	/**
 	* Stringify this document (contents, directives and framing) as YAML.
-	* Fails with {@link YamlStringifyError} on circular references introduced
-	* into a synthetic AST (`CircularReference`) or on a synthetic AST nested
-	* deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
-	* — both surface through the typed error channel rather than as an
-	* unhandled stack-overflow defect.
+	* Fails with {@link YamlStringifyError} (`NestingDepthExceeded`) on a
+	* synthetic AST nested deeper than the stringifier's recursion budget. A
+	* cycle introduced into a synthetic AST fails the same way: the node path
+	* keeps no ancestor set, so the cycle is caught by the depth cap rather
+	* than reported as `CircularReference`. Either way the failure surfaces
+	* through the typed error channel, never as an unhandled stack-overflow
+	* defect.
+	* Defined in terms of {@link YamlDocument.stringifyResult} behind a
+	* `YamlDocument.stringify` span — synchronous callers can use that variant
+	* directly.
 	*
 	* @remarks
 	* `YamlStringifyOptions.lineWidth` is not honored here: column-based
@@ -142,31 +202,46 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	*   {@link YamlStringifyError}.
 	*/
 	stringify(options) {
-		return Effect.try({
+		return Effect.suspend(() => Effect.fromResult(this.stringifyResult(options))).pipe(Effect.withSpan("YamlDocument.stringify"));
+	}
+	/**
+	* Synchronous stringify, returning a `Result` instead of an `Effect` — the
+	* primitive {@link YamlDocument.stringify} is defined in terms of, so a
+	* synchronous host can round-trip a document parsed with
+	* {@link YamlDocument.parseResult} without an Effect runtime. Fails with
+	* {@link YamlStringifyError} exactly where `stringify` does: a synthetic
+	* AST nested deeper than the stringifier's recursion budget, or one
+	* containing a cycle, both as `NestingDepthExceeded` (the node path keeps
+	* no ancestor set, so a cycle is caught by the depth cap, not reported as
+	* `CircularReference`).
+	*
+	* @remarks
+	* `YamlStringifyOptions.lineWidth` is not honored here, for the reason
+	* given on {@link YamlDocument.stringify}.
+	*
+	* @example
+	* ```ts
+	* import { YamlDocument } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const parsed = YamlDocument.parseResult("# keep\nname: Alice\n");
+	* if (Result.isSuccess(parsed)) {
+	*   const text = parsed.success.stringifyResult();
+	*   if (Result.isSuccess(text)) console.log(text.success); // => "# keep\nname: Alice\n"
+	* }
+	* ```
+	*
+	* @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+	*   omitted fields.
+	* @returns A `Result` succeeding with the YAML text, or failing with
+	*   {@link YamlStringifyError}.
+	*/
+	stringifyResult(options) {
+		return Result.try({
 			try: () => stringifyDocument(toRawDocument(this), toStringifyInput(options)),
 			catch: (defect) => {
-				if (defect instanceof StringifyFailure) return new YamlStringifyError({
-					diagnostics: [YamlDiagnostic.make({
-						code: "CircularReference",
-						message: defect.reason,
-						offset: 0,
-						length: 0,
-						line: 0,
-						character: 0
-					})],
-					value: this
-				});
-				if (defect instanceof StringifyDepthExceeded) return new YamlStringifyError({
-					diagnostics: [YamlDiagnostic.make({
-						code: "NestingDepthExceeded",
-						message: defect.message,
-						offset: 0,
-						length: 0,
-						line: 0,
-						character: 0
-					})],
-					value: this
-				});
+				const error = stringifyDefectToError(defect, this);
+				if (error !== void 0) return error;
 				throw defect;
 			}
 		});

package/YamlFormat.js

@@ -3,11 +3,11 @@ import { EMPTY_DOCUMENT, composeAllDocuments, composeFirstDocumentCounted } from
 import { isFatalCode } from "./internal/diagnostics.js";
 import { renderDoubleQuoted, renderSingleQuoted, stringifyDocument, stringifyValue, stripNodeComments } from "./internal/stringifier.js";
 import { YamlDiagnostic } from "./YamlDiagnostic.js";
-import { YamlStringifyOptions } from "./Yaml.js";
+import { YamlStringifyOptions, stringifyDefectToError } from "./Yaml.js";
 import { YamlEdit, YamlRange } from "./YamlEdit.js";
 import { computeEdits } from "./internal/diff.js";
 import { requoteScalarText } from "./internal/requote.js";
-import { Effect, Schema } from "effect";
+import { Effect, Result, Schema } from "effect";
 
 // src/YamlFormat.ts
 /**
@@ -263,7 +263,10 @@ function formatStream(text, documents, streamErrors, options) {
 *
 * The two conditions with no finite rendering fail typed rather than hanging
 * or overflowing the stack: a cycle raises `CircularReference` and a graph
-* deeper than `MAX_NESTING_DEPTH` raises `NestingDepthExceeded`. `seen` holds
+* that would sit deeper than `MAX_NESTING_DEPTH` in the output document
+* raises `NestingDepthExceeded`. `depth` is measured in the stringifier's own
+* units — one per node from the document root — so the caller passes the
+* target's depth, not zero. `seen` holds
 * the ancestors of the value being lowered, so a value repeated across
 * siblings (a shared, acyclic sub-object) is lowered twice rather than
 * rejected.
@@ -306,12 +309,17 @@ function jsValueToNode(value, seen, depth) {
 		length: 0
 	});
 }
-/** Entry point for {@link jsValueToNode}: one `seen` set per lowering. */
-function lowerValue(value) {
-	return jsValueToNode(value, /* @__PURE__ */ new Set(), 0);
+/**
+* Entry point for {@link jsValueToNode}: one `seen` set per lowering, counting
+* depth from `targetDepth` — the depth the value will occupy in the output
+* document (the path length: a root replacement sits at 0, a value one key
+* down at 1).
+*/
+function lowerValue(value, targetDepth) {
+	return jsValueToNode(value, /* @__PURE__ */ new Set(), targetDepth);
 }
 function modifyDocument(doc, path, value) {
-	if (path.length === 0) return value === void 0 ? null : lowerValue(value);
+	if (path.length === 0) return value === void 0 ? null : lowerValue(value, 0);
 	if (doc.contents === null) throw new ModifyFailure("EmptyDocument", "Cannot navigate path in empty document", 0, 0);
 	return modifyNode(doc.contents, path, 0, value);
 }
@@ -327,7 +335,7 @@ function modifyNode(node, path, depth, value) {
 				newItems.splice(pairIndex, 1);
 				return rebuildMap(node, newItems);
 			}
-			const newValueNode = lowerValue(value);
+			const newValueNode = lowerValue(value, depth + 1);
 			if (pairIndex >= 0) {
 				const newItems = [...node.items];
 				const oldPair = newItems[pairIndex];
@@ -367,8 +375,8 @@ function modifyNode(node, path, depth, value) {
 			const newItems = [...node.items];
 			if (value === void 0) {
 				if (idx < newItems.length) newItems.splice(idx, 1);
-			} else if (idx < newItems.length) newItems[idx] = lowerValue(value);
-			else newItems.push(lowerValue(value));
+			} else if (idx < newItems.length) newItems[idx] = lowerValue(value, depth + 1);
+			else newItems.push(lowerValue(value, depth + 1));
 			return rebuildSeq(node, newItems);
 		}
 		if (idx >= node.items.length) throw new ModifyFailure("InvalidIndex", `Index ${idx} out of bounds`, node.offset, node.length);
@@ -678,7 +686,9 @@ var YamlFormat = class YamlFormat {
 		return YamlEdit.applyAll(text, YamlFormat.format(text, range, options));
 	}
 	/**
-	* Compute the edits that insert, replace, or remove a value at `path`.
+	* Compute the edits that insert, replace, or remove a value at `path`,
+	* synchronously — the primitive {@link YamlFormat.modify} is defined in
+	* terms of, so a synchronous host can call it without an Effect runtime.
 	* Passing `value === undefined` removes the target key/element; a missing
 	* insertion target appends after the last pair/element. Fails with
 	* {@link YamlModificationError} on a fatal parse error or a structural
@@ -714,8 +724,10 @@ var YamlFormat = class YamlFormat {
 	*
 	* Two replacement values have no finite rendering and fail typed rather
 	* than hanging or overflowing the stack: one containing a circular
-	* reference (`CircularReference`) and one nesting deeper than 256 levels
-	* (`NestingDepthExceeded`).
+	* reference (`CircularReference`) and one that would sit deeper than 256
+	* levels in the output document (`NestingDepthExceeded`). The depth is
+	* counted from the document root, so the same value can fit at `[]` and
+	* fail a few keys down.
 	*
 	* **Single-document contract.** A `path` carries no document index, so on
 	* a multi-document stream there is no rule for which document it names —
@@ -740,63 +752,109 @@ var YamlFormat = class YamlFormat {
 	*   target instead.
 	* @param options - Optional {@link YamlStringifyOptions} for the
 	*   re-stringify step.
-	* @returns An `Effect` that succeeds with the edits to apply (via
-	*   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+	* @returns A `Result` succeeding with the edits to apply (via
+	*   `YamlEdit.applyAll`), or failing with {@link YamlModificationError}.
 	*
 	* @remarks
 	* `options` is a bare {@link YamlStringifyOptions} — it controls only the
 	* internal re-stringify step, not a range (there is no range to restrict
 	* for a path-targeted modification).
 	*/
-	static modify = Effect.fn("YamlFormat.modify")(function* (text, path, value, options) {
-		const { document: doc, documentCount } = composeFirstDocumentCounted(text, {});
-		if (documentCount > 1) return yield* new YamlModificationError({
+	static modifyResult(text, path, value, options) {
+		const fail = (diagnostics) => Result.fail(new YamlModificationError({
 			path,
-			diagnostics: [YamlDiagnostic.fromRaw({
-				code: "MultiDocumentStream",
-				message: `Cannot modify a multi-document stream (${documentCount} documents): modify re-emits exactly one document`,
-				offset: 0,
-				length: 0
-			}, text)]
-		});
+			diagnostics
+		}));
+		const { document: doc, documentCount } = composeFirstDocumentCounted(text, {});
+		if (documentCount > 1) return fail([YamlDiagnostic.fromRaw({
+			code: "MultiDocumentStream",
+			message: `Cannot modify a multi-document stream (${documentCount} documents): modify re-emits exactly one document`,
+			offset: 0,
+			length: 0
+		}, text)]);
 		const fatal = doc.errors.filter((e) => isFatalCode(e.code));
-		if (fatal.length > 0) return yield* new YamlModificationError({
-			path,
-			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text))
-		});
-		if (doc.directives.length > 0) return yield* new YamlModificationError({
-			path,
-			diagnostics: [YamlDiagnostic.fromRaw({
-				code: "DirectiveCarryingDocument",
-				message: "Cannot modify a document carrying %YAML/%TAG directives: modify does not re-emit directive lines, and dropping a %TAG orphans the shorthand tags that depend on it",
-				offset: 0,
-				length: 0
-			}, text)]
-		});
+		if (fatal.length > 0) return fail(fatal.map((e) => YamlDiagnostic.fromRaw(e, text)));
+		if (doc.directives.length > 0) return fail([YamlDiagnostic.fromRaw({
+			code: "DirectiveCarryingDocument",
+			message: "Cannot modify a document carrying %YAML/%TAG directives: modify does not re-emit directive lines, and dropping a %TAG orphans the shorthand tags that depend on it",
+			offset: 0,
+			length: 0
+		}, text)]);
 		const regional = tryRegionalScalarEdit(text, doc, path, value, options);
-		if (regional !== void 0) return regional.map((e) => YamlEdit.make(e));
+		if (regional !== void 0) return Result.succeed(regional.map((e) => YamlEdit.make(e)));
 		let newContents;
 		try {
 			newContents = modifyDocument(doc, path, value);
 		} catch (err) {
 			if (!(err instanceof ModifyFailure)) throw err;
-			return yield* new YamlModificationError({
-				path,
-				diagnostics: [YamlDiagnostic.fromRaw({
-					code: err.code,
-					message: err.message,
-					offset: err.offset,
-					length: err.length
-				}, text)]
-			});
+			return fail([YamlDiagnostic.fromRaw({
+				code: err.code,
+				message: err.message,
+				offset: err.offset,
+				length: err.length
+			}, text)]);
 		}
 		const outputDoc = {
 			...doc,
 			contents: newContents
 		};
-		const formatted = stringifyDocument(outputDoc, toStringifyInput(options));
-		return computeEdits(text, withSourceBom(text, formatted)).map((e) => YamlEdit.make(e));
-	});
+		let formatted;
+		try {
+			formatted = stringifyDocument(outputDoc, toStringifyInput(options));
+		} catch (defect) {
+			const error = stringifyDefectToError(defect, value);
+			if (error === void 0) throw defect;
+			return fail(error.diagnostics);
+		}
+		return Result.succeed(computeEdits(text, withSourceBom(text, formatted)).map((e) => YamlEdit.make(e)));
+	}
+	/**
+	* Compute the edits that insert, replace, or remove a value at `path`.
+	* Defined in terms of {@link YamlFormat.modifyResult}, which carries the
+	* full contract — value lowering, region-confined scalar replacement, the
+	* single-document contract and the directive refusal — behind a
+	* `YamlFormat.modify` span; synchronous callers can use that variant
+	* directly.
+	*
+	* @param text - The YAML source to modify.
+	* @param path - The location to insert, replace or remove.
+	* @param value - The JavaScript value to write; `undefined` removes the
+	*   target instead.
+	* @param options - Optional {@link YamlStringifyOptions} for the
+	*   re-stringify step.
+	* @returns An `Effect` that succeeds with the edits to apply (via
+	*   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+	*/
+	static modify = Effect.fn("YamlFormat.modify")((text, path, value, options) => Effect.fromResult(YamlFormat.modifyResult(text, path, value, options)));
+	/**
+	* Synchronous {@link YamlFormat.modifyToString}: modify `text` and apply the
+	* resulting edits in one step (`YamlEdit.applyAll ∘ modifyResult`),
+	* returning a `Result`. Inherits the {@link YamlFormat.modifyResult} error
+	* channel.
+	*
+	* @example
+	* ```ts
+	* import { YamlFormat } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = YamlFormat.modifyToStringResult("port: 3000 # dev\n", ["port"], 8080);
+	* if (Result.isSuccess(result)) {
+	*   console.log(result.success); // => "port: 8080 # dev\n"
+	* }
+	* ```
+	*
+	* @param text - The YAML source to modify.
+	* @param path - The location to insert, replace or remove.
+	* @param value - The JavaScript value to write; `undefined` removes the
+	*   target instead.
+	* @param options - Optional {@link YamlStringifyOptions} for the
+	*   re-stringify step.
+	* @returns A `Result` succeeding with the modified text, or failing with
+	*   {@link YamlModificationError}.
+	*/
+	static modifyToStringResult(text, path, value, options) {
+		return Result.map(YamlFormat.modifyResult(text, path, value, options), (edits) => YamlEdit.applyAll(text, edits));
+	}
 	/**
 	* Modify `text` and apply the resulting edits in one step
 	* (`YamlEdit.applyAll ∘ modify`). Inherits the {@link YamlFormat.modify}
@@ -812,11 +870,12 @@ var YamlFormat = class YamlFormat {
 	*   re-stringify step.
 	* @returns An `Effect` that succeeds with the modified text, or fails with
 	*   {@link YamlModificationError}.
+	*
+	* @remarks
+	* Defined in terms of {@link YamlFormat.modifyToStringResult}; it opens its
+	* own span, with no nested `YamlFormat.modify` child span.
 	*/
-	static modifyToString = Effect.fn("YamlFormat.modifyToString")(function* (text, path, value, options) {
-		const edits = yield* YamlFormat.modify(text, path, value, options);
-		return YamlEdit.applyAll(text, edits);
-	});
+	static modifyToString = Effect.fn("YamlFormat.modifyToString")((text, path, value, options) => Effect.fromResult(YamlFormat.modifyToStringResult(text, path, value, options)));
 };
 
 export { YamlFormat, YamlFormattingOptions, YamlModificationError };

package/index.d.ts

@@ -1036,11 +1036,39 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
  * @public
  */
 export declare class YamlDocument extends YamlDocument_base {
+  /**
+   * Synchronous single-document parse, returning a `Result` instead of an
+   * `Effect`. This is the primitive {@link YamlDocument.parse} is defined in
+   * terms of — a synchronous host can call it without an Effect runtime.
+   * Keeps the full AST, directives and recovered diagnostics; fails with the
+   * aggregate {@link YamlParseError} when any fatal-code diagnostic is
+   * present, and non-fatal diagnostics are data on the returned document.
+   *
+   * @example
+   * ```ts
+   * import { YamlDocument } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const result = YamlDocument.parseResult("name: Alice\n");
+   * if (Result.isSuccess(result)) {
+   *   console.log(result.success.toValue()); // => { name: "Alice" }
+   * }
+   * ```
+   *
+   * @param text - The YAML source to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns A `Result` succeeding with the {@link YamlDocument}, or failing
+   *   with {@link YamlParseError}.
+   */
+  static parseResult(text: string, options?: YamlParseOptions): Result.Result<YamlDocument, YamlParseError>;
   /**
    * Parse a single YAML document, keeping the full AST, directives and
    * recovered diagnostics. Fails with the aggregate {@link YamlParseError}
    * when any fatal-code diagnostic is present; non-fatal diagnostics are
-   * data on the returned document.
+   * data on the returned document. Defined in terms of
+   * {@link YamlDocument.parseResult} — synchronous callers can use that
+   * variant directly.
    *
    * @param text - The YAML source to parse.
    * @param options - Optional {@link YamlParseOptions}; defaults apply for
@@ -1049,10 +1077,37 @@ export declare class YamlDocument extends YamlDocument_base {
    *   with {@link YamlParseError}.
    */
   static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<YamlDocument, YamlParseError, never>;
+  /**
+   * Synchronous multi-document parse, returning a `Result` instead of an
+   * `Effect` — the primitive {@link YamlDocument.parseAll} is defined in
+   * terms of. Any fatal diagnostic in any document — or a stream-level
+   * directive-placement error — fails the whole parse with one aggregate
+   * {@link YamlParseError}.
+   *
+   * @example
+   * ```ts
+   * import { YamlDocument } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const result = YamlDocument.parseAllResult("a: 1\n---\nb: 2\n");
+   * if (Result.isSuccess(result)) {
+   *   console.log(result.success.length); // => 2
+   * }
+   * ```
+   *
+   * @param text - The YAML stream to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns A `Result` succeeding with one {@link YamlDocument} per
+   *   document, or failing with {@link YamlParseError}.
+   */
+  static parseAllResult(text: string, options?: YamlParseOptions): Result.Result<ReadonlyArray<YamlDocument>, YamlParseError>;
   /**
    * Parse a multi-document YAML stream into one {@link YamlDocument} per
    * document. Any fatal diagnostic in any document — or a stream-level
-   * directive-placement error — fails the whole Effect.
+   * directive-placement error — fails the whole Effect. Defined in terms of
+   * {@link YamlDocument.parseAllResult} — synchronous callers can use that
+   * variant directly.
    *
    * @param text - The YAML stream to parse.
    * @param options - Optional {@link YamlParseOptions}; defaults apply for
@@ -1076,11 +1131,16 @@ export declare class YamlDocument extends YamlDocument_base {
   static schema(options?: YamlParseOptions): Schema.Codec<YamlDocument, string>;
   /**
    * Stringify this document (contents, directives and framing) as YAML.
-   * Fails with {@link YamlStringifyError} on circular references introduced
-   * into a synthetic AST (`CircularReference`) or on a synthetic AST nested
-   * deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
-   * — both surface through the typed error channel rather than as an
-   * unhandled stack-overflow defect.
+   * Fails with {@link YamlStringifyError} (`NestingDepthExceeded`) on a
+   * synthetic AST nested deeper than the stringifier's recursion budget. A
+   * cycle introduced into a synthetic AST fails the same way: the node path
+   * keeps no ancestor set, so the cycle is caught by the depth cap rather
+   * than reported as `CircularReference`. Either way the failure surfaces
+   * through the typed error channel, never as an unhandled stack-overflow
+   * defect.
+   * Defined in terms of {@link YamlDocument.stringifyResult} behind a
+   * `YamlDocument.stringify` span — synchronous callers can use that variant
+   * directly.
    *
    * @remarks
    * `YamlStringifyOptions.lineWidth` is not honored here: column-based
@@ -1099,6 +1159,39 @@ export declare class YamlDocument extends YamlDocument_base {
    *   {@link YamlStringifyError}.
    */
   stringify(options?: YamlStringifyOptions): Effect.Effect<string, YamlStringifyError>;
+  /**
+   * Synchronous stringify, returning a `Result` instead of an `Effect` — the
+   * primitive {@link YamlDocument.stringify} is defined in terms of, so a
+   * synchronous host can round-trip a document parsed with
+   * {@link YamlDocument.parseResult} without an Effect runtime. Fails with
+   * {@link YamlStringifyError} exactly where `stringify` does: a synthetic
+   * AST nested deeper than the stringifier's recursion budget, or one
+   * containing a cycle, both as `NestingDepthExceeded` (the node path keeps
+   * no ancestor set, so a cycle is caught by the depth cap, not reported as
+   * `CircularReference`).
+   *
+   * @remarks
+   * `YamlStringifyOptions.lineWidth` is not honored here, for the reason
+   * given on {@link YamlDocument.stringify}.
+   *
+   * @example
+   * ```ts
+   * import { YamlDocument } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const parsed = YamlDocument.parseResult("# keep\nname: Alice\n");
+   * if (Result.isSuccess(parsed)) {
+   *   const text = parsed.success.stringifyResult();
+   *   if (Result.isSuccess(text)) console.log(text.success); // => "# keep\nname: Alice\n"
+   * }
+   * ```
+   *
+   * @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+   *   omitted fields.
+   * @returns A `Result` succeeding with the YAML text, or failing with
+   *   {@link YamlStringifyError}.
+   */
+  stringifyResult(options?: YamlStringifyOptions): Result.Result<string, YamlStringifyError>;
   /**
    * Reconstruct the plain JavaScript value of this document's contents,
    * resolving anchors and aliases. `null` for an empty document. Pure and
@@ -1315,7 +1408,9 @@ export declare class YamlFormat {
    */
   static formatToString(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): string;
   /**
-   * Compute the edits that insert, replace, or remove a value at `path`.
+   * Compute the edits that insert, replace, or remove a value at `path`,
+   * synchronously — the primitive {@link YamlFormat.modify} is defined in
+   * terms of, so a synchronous host can call it without an Effect runtime.
    * Passing `value === undefined` removes the target key/element; a missing
    * insertion target appends after the last pair/element. Fails with
    * {@link YamlModificationError} on a fatal parse error or a structural
@@ -1351,8 +1446,10 @@ export declare class YamlFormat {
    *
    * Two replacement values have no finite rendering and fail typed rather
    * than hanging or overflowing the stack: one containing a circular
-   * reference (`CircularReference`) and one nesting deeper than 256 levels
-   * (`NestingDepthExceeded`).
+   * reference (`CircularReference`) and one that would sit deeper than 256
+   * levels in the output document (`NestingDepthExceeded`). The depth is
+   * counted from the document root, so the same value can fit at `[]` and
+   * fail a few keys down.
    *
    * **Single-document contract.** A `path` carries no document index, so on
    * a multi-document stream there is no rule for which document it names —
@@ -1377,15 +1474,60 @@ export declare class YamlFormat {
    *   target instead.
    * @param options - Optional {@link YamlStringifyOptions} for the
    *   re-stringify step.
-   * @returns An `Effect` that succeeds with the edits to apply (via
-   *   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+   * @returns A `Result` succeeding with the edits to apply (via
+   *   `YamlEdit.applyAll`), or failing with {@link YamlModificationError}.
    *
    * @remarks
    * `options` is a bare {@link YamlStringifyOptions} — it controls only the
    * internal re-stringify step, not a range (there is no range to restrict
    * for a path-targeted modification).
    */
+  static modifyResult(text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions): Result.Result<ReadonlyArray<YamlEdit>, YamlModificationError>;
+  /**
+   * Compute the edits that insert, replace, or remove a value at `path`.
+   * Defined in terms of {@link YamlFormat.modifyResult}, which carries the
+   * full contract — value lowering, region-confined scalar replacement, the
+   * single-document contract and the directive refusal — behind a
+   * `YamlFormat.modify` span; synchronous callers can use that variant
+   * directly.
+   *
+   * @param text - The YAML source to modify.
+   * @param path - The location to insert, replace or remove.
+   * @param value - The JavaScript value to write; `undefined` removes the
+   *   target instead.
+   * @param options - Optional {@link YamlStringifyOptions} for the
+   *   re-stringify step.
+   * @returns An `Effect` that succeeds with the edits to apply (via
+   *   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+   */
   static readonly modify: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<readonly YamlEdit[], YamlModificationError, never>;
+  /**
+   * Synchronous {@link YamlFormat.modifyToString}: modify `text` and apply the
+   * resulting edits in one step (`YamlEdit.applyAll ∘ modifyResult`),
+   * returning a `Result`. Inherits the {@link YamlFormat.modifyResult} error
+   * channel.
+   *
+   * @example
+   * ```ts
+   * import { YamlFormat } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const result = YamlFormat.modifyToStringResult("port: 3000 # dev\n", ["port"], 8080);
+   * if (Result.isSuccess(result)) {
+   *   console.log(result.success); // => "port: 8080 # dev\n"
+   * }
+   * ```
+   *
+   * @param text - The YAML source to modify.
+   * @param path - The location to insert, replace or remove.
+   * @param value - The JavaScript value to write; `undefined` removes the
+   *   target instead.
+   * @param options - Optional {@link YamlStringifyOptions} for the
+   *   re-stringify step.
+   * @returns A `Result` succeeding with the modified text, or failing with
+   *   {@link YamlModificationError}.
+   */
+  static modifyToStringResult(text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions): Result.Result<string, YamlModificationError>;
   /**
    * Modify `text` and apply the resulting edits in one step
    * (`YamlEdit.applyAll ∘ modify`). Inherits the {@link YamlFormat.modify}
@@ -1401,6 +1543,10 @@ export declare class YamlFormat {
    *   re-stringify step.
    * @returns An `Effect` that succeeds with the modified text, or fails with
    *   {@link YamlModificationError}.
+   *
+   * @remarks
+   * Defined in terms of {@link YamlFormat.modifyToStringResult}; it opens its
+   * own span, with no nested `YamlFormat.modify` child span.
    */
   static readonly modifyToString: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlModificationError, never>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.23.0",
+	"version": "0.24.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [