@effected/yaml 0.23.0 → 0.25.0

package/Yaml.js

@@ -171,11 +171,14 @@ var YamlParseError = class extends Schema.TaggedError()("YamlParseError", {
 	}
 };
 /**
-* Stringification failure (the circular-reference guard), carrying structured
-* {@link YamlDiagnostic} entries and the offending value. Raised by
-* {@link Yaml.stringify}, `YamlDocument#stringify` and the encode direction of
-* the schema factories. The error itself has no `code` field: read the code
-* from the diagnostics — `error.diagnostics[0].code` is the primary failure.
+* Stringification failure, carrying structured {@link YamlDiagnostic} entries
+* and the offending value. Raised by {@link Yaml.stringify},
+* `YamlDocument#stringify` and the encode direction of the schema factories
+* on a circular reference (`CircularReference`), a value nested past the
+* stringifier's recursion budget (`NestingDepthExceeded`) or a value with no
+* YAML representation (`UnrepresentableValue` — a function or a symbol). The
+* error itself has no `code` field: read the code from the diagnostics —
+* `error.diagnostics[0].code` is the primary failure.
 *
 * @public
 */
@@ -224,13 +227,17 @@ 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, unrepresentable value, nesting-depth cap) identically.
+*
+* @internal
 */
 const stringifyDefectToError = (defect, value) => {
 	if (defect instanceof StringifyFailure) return new YamlStringifyError({
 		diagnostics: [YamlDiagnostic.make({
-			code: "CircularReference",
+			code: defect.code,
 			message: defect.reason,
 			offset: 0,
 			length: 0,
@@ -266,12 +273,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
@@ -304,19 +312,18 @@ const parseAllResultImpl = (text, options) => {
 };
 /**
 * Synchronous stringify returning a `Result`. Mirrors {@link Yaml.stringify}
-* without the Effect wrapper: a circular reference or a value nested past the
-* recursion budget yields a `Failure` carrying a typed {@link YamlStringifyError},
-* never a thrown defect.
+* without the Effect wrapper: a circular reference, a function or symbol
+* value, or a value nested past the 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 +335,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.
@@ -405,10 +404,14 @@ var Yaml = class Yaml {
 	static parseAll = Effect.fn("Yaml.parseAll")((text, options) => Effect.fromResult(Yaml.parseAllResult(text, options)));
 	/**
 	* Stringify a plain JavaScript value as YAML. Fails with
-	* {@link YamlStringifyError} on circular references (`CircularReference`)
-	* or on a value nested deeper than the stringifier's recursion budget
-	* (`NestingDepthExceeded`) — both surface through the typed error channel
-	* rather than as an unhandled stack-overflow defect.
+	* {@link YamlStringifyError} on circular references (`CircularReference`),
+	* on a value nested deeper than the stringifier's recursion budget
+	* (`NestingDepthExceeded`) and on a function or symbol anywhere in the
+	* value (`UnrepresentableValue`) — all surface through the typed error
+	* channel, never as a stack-overflow defect and never as the function's
+	* source text or `Symbol(s)` written into the document as a string. A
+	* `bigint` is an integer and renders bare, exactly as `YamlFormat.modify`
+	* writes one; `null` and `undefined` both render as `null`.
 	*
 	* @remarks
 	* A `"<<"` object key is emitted **quoted** (`'<<': …`). This is the
@@ -425,9 +428,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
@@ -510,10 +511,11 @@ var Yaml = class Yaml {
 	* The pure counterpart to {@link Yaml.stringify} for config-time callers
 	* that cannot `await`.
 	*
-	* Preserves the package contract — a circular reference (`CircularReference`)
-	* or a value nested past the recursion budget (`NestingDepthExceeded`)
-	* yields a `Failure` carrying a {@link YamlStringifyError} rather than a
-	* thrown stack-overflow defect; the method never throws.
+	* Preserves the package contract — a circular reference (`CircularReference`),
+	* a value nested past the recursion budget (`NestingDepthExceeded`) or a
+	* function or symbol value (`UnrepresentableValue`) yields a `Failure`
+	* carrying a {@link YamlStringifyError} rather than a thrown defect; the
+	* method never throws.
 	*
 	* @example
 	* ```ts
@@ -631,7 +633,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 +657,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 +776,4 @@ function deepEqualValues(a, b) {
 	return false;
 }
 
-export { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions };
+export { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions, stringifyDefectToError };

package/YamlDiagnostic.js

@@ -21,7 +21,10 @@ const YamlParseErrorCode = Schema.Literals(YAML_PARSE_ERROR_CODES);
 */
 const YamlComposerErrorCode = Schema.Literals(YAML_COMPOSE_ERROR_CODES);
 /**
-* Error codes emitted by the stringifier (the circular-reference guard).
+* Error codes emitted by the stringifier: `CircularReference` (the value or
+* synthetic AST points back at itself) and `UnrepresentableValue` (a function
+* or symbol, which has no YAML rendering and is never written as its
+* `String()` form).
 *
 * @public
 */

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,19 @@ 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.
+	* A parsed document always stringifies; the failures belong to hand-built
+	* ASTs and surface as {@link YamlStringifyError} through the typed error
+	* channel, never as an unhandled stack-overflow defect or as corrupted
+	* output: a cycle in the AST fails `CircularReference` on the first
+	* re-entry of an ancestor collection (the node path keeps the same
+	* ancestor set the value path does), a tree nested deeper than the
+	* stringifier's recursion budget fails `NestingDepthExceeded`, and a
+	* scalar node holding anything but `null`, a boolean, a number, a bigint
+	* or a string — a function, a symbol, an object — fails
+	* `UnrepresentableValue` rather than being written as its `String()` form.
+	* 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 +205,45 @@ 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 hand-built
+	* AST containing a cycle (`CircularReference`), one nested deeper than the
+	* stringifier's recursion budget (`NestingDepthExceeded`) or one whose
+	* scalar node holds a value with no YAML form (`UnrepresentableValue`).
+	*
+	* @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
 /**
@@ -259,11 +259,18 @@ function formatStream(text, documents, streamErrors, options) {
 * Before this was recursive, a mapping or sequence value fell through to the
 * node stringifier's `String(value)` fallback and landed in the document as
 * the literal text `[object Object]` — a silent corruption that only surfaced
-* on the next read.
+* on the next read. Every other value becomes a plain {@link YamlScalar} and
+* renders exactly as the value path renders it: a `bigint` bare, `undefined`
+* as `null`.
 *
-* 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
+* Three conditions fail typed rather than hanging, overflowing the stack or
+* corrupting the document: a cycle raises `CircularReference`, a graph that
+* would sit deeper than `MAX_NESTING_DEPTH` in the output document raises
+* `NestingDepthExceeded`, and a function or symbol — which has no YAML
+* rendering, and whose `String()` form the value path refuses to write too —
+* raises `UnrepresentableValue`. `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.
@@ -299,19 +306,31 @@ function jsValueToNode(value, seen, depth) {
 			seen.delete(value);
 		}
 	}
-	return YamlScalar.make({
+	if (typeof value === "function" || typeof value === "symbol") throw new ModifyFailure("UnrepresentableValue", `A ${typeof value} value has no YAML representation`, 0, 0);
+	return value === null || value === void 0 ? YamlScalar.make({
+		value: null,
+		style: "plain",
+		raw: "null",
+		offset: 0,
+		length: 0
+	}) : YamlScalar.make({
 		value,
 		style: "plain",
 		offset: 0,
 		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 +346,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 +386,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 +697,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
@@ -688,7 +709,10 @@ var YamlFormat = class YamlFormat {
 	* sequence and any other non-null object as a block mapping over its own
 	* enumerable string keys, recursively — the same lowering
 	* {@link Yaml.stringify} applies to the same value, so `modify` and
-	* `stringify` agree on what a given JavaScript value means. For a synthesized
+	* `stringify` agree on what a given JavaScript value means: a `bigint`
+	* renders bare (`a: 10`, never `a: "10"`), `null` renders as `null`, and a
+	* function or symbol fails `UnrepresentableValue` on both paths rather
+	* than landing in the document as its `String()` form. For a synthesized
 	* subtree (an object/array value) only the surrounding document is
 	* preserved byte-for-byte; the subtree carries no comments and takes the
 	* stringifier's styles.
@@ -712,10 +736,13 @@ var YamlFormat = class YamlFormat {
 	* whole document, which normalises line endings to LF, applies those
 	* options, and renders the replacement in the stringifier's styles.
 	*
-	* 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`).
+	* Three replacement values have no rendering and fail typed rather than
+	* hanging, overflowing the stack or corrupting the document: one
+	* containing a circular reference (`CircularReference`), one that would
+	* sit deeper than 256 levels in the output document
+	* (`NestingDepthExceeded`) and one containing a function or symbol
+	* (`UnrepresentableValue`). 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 +767,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 +885,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

@@ -36,11 +36,14 @@ export declare const YamlComposerErrorCode: Schema.Literals<readonly ["Undefined
  */
 export type YamlComposerErrorCode = typeof YamlComposerErrorCode.Type;
 /**
- * Error codes emitted by the stringifier (the circular-reference guard).
+ * Error codes emitted by the stringifier: `CircularReference` (the value or
+ * synthetic AST points back at itself) and `UnrepresentableValue` (a function
+ * or symbol, which has no YAML rendering and is never written as its
+ * `String()` form).
  *
  * @public
  */
-export declare const YamlStringifyErrorCode: Schema.Literals<readonly ["CircularReference"]>;
+export declare const YamlStringifyErrorCode: Schema.Literals<readonly ["CircularReference", "UnrepresentableValue"]>;
 /**
  * The union of all stringifier-stage error code string literals.
  *
@@ -53,7 +56,7 @@ export type YamlStringifyErrorCode = typeof YamlStringifyErrorCode.Type;
  *
  * @public
  */
-export declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded"]>;
+export declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded", "UnrepresentableValue"]>;
 /**
  * The union of all modify-stage error code string literals.
  *
@@ -66,7 +69,7 @@ export type YamlModifyErrorCode = typeof YamlModifyErrorCode.Type;
  *
  * @public
  */
-export declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded"]>]>;
+export declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference", "UnrepresentableValue"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded", "UnrepresentableValue"]>]>;
 /**
  * The union of all YAML error code string literals.
  *
@@ -74,7 +77,7 @@ export declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<reado
  */
 export type YamlErrorCode = typeof YamlErrorCode.Type;
 declare const YamlDiagnostic_base: Schema.Class<YamlDiagnostic, Schema.Struct<{
-  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded"]>]>;
+  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference", "UnrepresentableValue"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded", "UnrepresentableValue"]>]>;
   readonly message: Schema.String;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -288,11 +291,14 @@ declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.T
   readonly value: Schema.Unknown;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Stringification failure (the circular-reference guard), carrying structured
- * {@link YamlDiagnostic} entries and the offending value. Raised by
- * {@link Yaml.stringify}, `YamlDocument#stringify` and the encode direction of
- * the schema factories. The error itself has no `code` field: read the code
- * from the diagnostics — `error.diagnostics[0].code` is the primary failure.
+ * Stringification failure, carrying structured {@link YamlDiagnostic} entries
+ * and the offending value. Raised by {@link Yaml.stringify},
+ * `YamlDocument#stringify` and the encode direction of the schema factories
+ * on a circular reference (`CircularReference`), a value nested past the
+ * stringifier's recursion budget (`NestingDepthExceeded`) or a value with no
+ * YAML representation (`UnrepresentableValue` — a function or a symbol). The
+ * error itself has no `code` field: read the code from the diagnostics —
+ * `error.diagnostics[0].code` is the primary failure.
  *
  * @public
  */
@@ -384,10 +390,14 @@ export declare class Yaml {
   static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly unknown[], YamlParseError, never>;
   /**
    * Stringify a plain JavaScript value as YAML. Fails with
-   * {@link YamlStringifyError} on circular references (`CircularReference`)
-   * or on a value nested deeper than the stringifier's recursion budget
-   * (`NestingDepthExceeded`) — both surface through the typed error channel
-   * rather than as an unhandled stack-overflow defect.
+   * {@link YamlStringifyError} on circular references (`CircularReference`),
+   * on a value nested deeper than the stringifier's recursion budget
+   * (`NestingDepthExceeded`) and on a function or symbol anywhere in the
+   * value (`UnrepresentableValue`) — all surface through the typed error
+   * channel, never as a stack-overflow defect and never as the function's
+   * source text or `Symbol(s)` written into the document as a string. A
+   * `bigint` is an integer and renders bare, exactly as `YamlFormat.modify`
+   * writes one; `null` and `undefined` both render as `null`.
    *
    * @remarks
    * A `"<<"` object key is emitted **quoted** (`'<<': …`). This is the
@@ -483,10 +493,11 @@ export declare class Yaml {
    * The pure counterpart to {@link Yaml.stringify} for config-time callers
    * that cannot `await`.
    *
-   * Preserves the package contract — a circular reference (`CircularReference`)
-   * or a value nested past the recursion budget (`NestingDepthExceeded`)
-   * yields a `Failure` carrying a {@link YamlStringifyError} rather than a
-   * thrown stack-overflow defect; the method never throws.
+   * Preserves the package contract — a circular reference (`CircularReference`),
+   * a value nested past the recursion budget (`NestingDepthExceeded`) or a
+   * function or symbol value (`UnrepresentableValue`) yields a `Failure`
+   * carrying a {@link YamlStringifyError} rather than a thrown defect; the
+   * method never throws.
    *
    * @example
    * ```ts
@@ -1036,11 +1047,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 +1088,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 +1142,19 @@ 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.
+   * A parsed document always stringifies; the failures belong to hand-built
+   * ASTs and surface as {@link YamlStringifyError} through the typed error
+   * channel, never as an unhandled stack-overflow defect or as corrupted
+   * output: a cycle in the AST fails `CircularReference` on the first
+   * re-entry of an ancestor collection (the node path keeps the same
+   * ancestor set the value path does), a tree nested deeper than the
+   * stringifier's recursion budget fails `NestingDepthExceeded`, and a
+   * scalar node holding anything but `null`, a boolean, a number, a bigint
+   * or a string — a function, a symbol, an object — fails
+   * `UnrepresentableValue` rather than being written as its `String()` form.
+   * 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 +1173,38 @@ 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 hand-built
+   * AST containing a cycle (`CircularReference`), one nested deeper than the
+   * stringifier's recursion budget (`NestingDepthExceeded`) or one whose
+   * scalar node holds a value with no YAML form (`UnrepresentableValue`).
+   *
+   * @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 +1421,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
@@ -1325,7 +1433,10 @@ export declare class YamlFormat {
    * sequence and any other non-null object as a block mapping over its own
    * enumerable string keys, recursively — the same lowering
    * {@link Yaml.stringify} applies to the same value, so `modify` and
-   * `stringify` agree on what a given JavaScript value means. For a synthesized
+   * `stringify` agree on what a given JavaScript value means: a `bigint`
+   * renders bare (`a: 10`, never `a: "10"`), `null` renders as `null`, and a
+   * function or symbol fails `UnrepresentableValue` on both paths rather
+   * than landing in the document as its `String()` form. For a synthesized
    * subtree (an object/array value) only the surrounding document is
    * preserved byte-for-byte; the subtree carries no comments and takes the
    * stringifier's styles.
@@ -1349,10 +1460,13 @@ export declare class YamlFormat {
    * whole document, which normalises line endings to LF, applies those
    * options, and renders the replacement in the stringifier's styles.
    *
-   * 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`).
+   * Three replacement values have no rendering and fail typed rather than
+   * hanging, overflowing the stack or corrupting the document: one
+   * containing a circular reference (`CircularReference`), one that would
+   * sit deeper than 256 levels in the output document
+   * (`NestingDepthExceeded`) and one containing a function or symbol
+   * (`UnrepresentableValue`). 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 +1491,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 +1560,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/internal/composer/scalars.js

@@ -927,6 +927,7 @@ function shouldPreserveRaw(rawValue, value) {
 		if (Number.isNaN(value) || !Number.isFinite(value)) return false;
 		return rawValue !== String(value);
 	}
+	if (typeof value === "bigint") return rawValue !== value.toString();
 	return false;
 }
 

package/internal/diagnostics.js

@@ -35,13 +35,18 @@ const YAML_COMPOSE_ERROR_CODES = [
 	"InvalidDirective"
 ];
 /**
-* Error codes for the stringifier stage. The engine's only deliberate
-* stringify failure is the circular-reference guard (thrown as
-* `StringifyFailure`); the facade materializes it under this code so
-* `YamlStringifyError` carries structured diagnostics rather than a
-* `reason` string.
+* Error codes for the stringifier stage. The engine's deliberate stringify
+* failures are the circular-reference guard and the unrepresentable-value
+* guard (a function or symbol on the value path, or a synthetic scalar node
+* holding anything but `null`, a boolean, a number, a bigint or a string),
+* both thrown as `StringifyFailure` carrying one of these codes; the facade
+* materializes them so `YamlStringifyError` carries structured diagnostics
+* rather than a `reason` string. `UnrepresentableValue` exists because the
+* alternative — writing `String(value)` into the document — turned a function's
+* source text or `Symbol(s)` into a quoted string that only surfaced on the
+* next read.
 */
-const YAML_STRINGIFY_ERROR_CODES = ["CircularReference"];
+const YAML_STRINGIFY_ERROR_CODES = ["CircularReference", "UnrepresentableValue"];
 /**
 * Error codes for the modify stage (`YamlFormat.modify`'s guards and path
 * navigation against an already-composed AST). Not raised by the
@@ -53,10 +58,11 @@ const YAML_STRINGIFY_ERROR_CODES = ["CircularReference"];
 * without its `%TAG` orphans every shorthand tag that depends on it — the
 * output would be unparseable — so modify fails typed rather than corrupting.
 *
-* `CircularReference` and `NestingDepthExceeded` are the two limits on the
-* replacement value itself: `modify` lowers a plain JavaScript value into
-* AST nodes, and an object graph that points back at itself or nests deeper
-* than `MAX_NESTING_DEPTH` has no finite YAML rendering. Both names are
+* `CircularReference`, `NestingDepthExceeded` and `UnrepresentableValue` are
+* the three limits on the replacement value itself: `modify` lowers a plain
+* JavaScript value into AST nodes, and an object graph that points back at
+* itself or nests deeper than `MAX_NESTING_DEPTH` has no finite YAML
+* rendering, while a function or symbol has none at all. All three names are
 * deliberately the ones the stringify and compose stages already use for the
 * same conditions, so `YamlErrorCode` gains no member.
 */
@@ -68,7 +74,8 @@ const YAML_MODIFY_ERROR_CODES = [
 	"MultiDocumentStream",
 	"DirectiveCarryingDocument",
 	"CircularReference",
-	"NestingDepthExceeded"
+	"NestingDepthExceeded",
+	"UnrepresentableValue"
 ];
 /**
 * The single source of truth for which diagnostic codes are fatal to a

package/internal/stringifier.js

@@ -3,18 +3,32 @@ import { foldRenderedScalar, hasInteriorTrailingWhitespace, hasNewlineSpacesTab,
 
 // src/internal/stringifier.ts
 /**
-* Thrown by the stringifier on its failure paths (circular references). The
-* facade catches this and materializes the public stringify error.
+* Thrown by the stringifier on its two deliberate failure paths: a circular
+* reference (`CircularReference`) and a value with no YAML representation
+* (`UnrepresentableValue` — a function or symbol on the value path, or a
+* synthetic scalar node holding anything but `null`, a boolean, a number, a
+* bigint or a string). The facade catches this and materializes the public
+* stringify error under `code`.
 */
 var StringifyFailure = class extends Error {
+	code;
 	reason;
-	constructor(reason) {
+	constructor(code, reason) {
 		super(reason);
 		this.name = "StringifyFailure";
+		this.code = code;
 		this.reason = reason;
 	}
 };
 /**
+* Build the unrepresentable-value failure for a value of `kind` (its
+* `typeof`). Shared by the value path and the node path so the two report
+* the same condition in the same words.
+*/
+function unrepresentable(kind) {
+	return new StringifyFailure("UnrepresentableValue", `A ${kind} value has no YAML representation`);
+}
+/**
 * Thrown by the value-stringifier trio when its mutual recursion exceeds
 * {@link MAX_NESTING_DEPTH}. A deeply-nested acyclic value (e.g. a 50 000-deep
 * array) would otherwise overflow the call stack as an unhandled `RangeError`
@@ -305,7 +319,7 @@ function renderNumber(n) {
 */
 function detectCircular(value, seen) {
 	if (value !== null && typeof value === "object") {
-		if (seen.has(value)) throw new StringifyFailure("Circular reference detected");
+		if (seen.has(value)) throw new StringifyFailure("CircularReference", "Circular reference detected");
 	}
 }
 /** Resolves optional stringify options into a fully-defaulted context. */
@@ -360,7 +374,7 @@ function stringifyLines(value, ctx, depth, allowFold = true) {
 			ctx.seen.delete(value);
 		}
 	}
-	return [renderDoubleQuoted(String(value))];
+	throw unrepresentable(typeof value);
 }
 /**
 * Stringifies a JavaScript array into YAML sequence lines (no leading indent).
@@ -603,8 +617,15 @@ function stripNodeComments(node) {
 function stringifyNodeLines(node, ctx, depth) {
 	if (depth > 256) throw new StringifyDepthExceeded();
 	if (node instanceof YamlScalar) return stringifyScalarNodeLines(node, ctx);
-	if (node instanceof YamlMap) return stringifyMapNodeLines(node, ctx, depth);
-	if (node instanceof YamlSeq) return stringifySeqNodeLines(node, ctx, depth);
+	if (node instanceof YamlMap || node instanceof YamlSeq) {
+		if (ctx.seen.has(node)) throw new StringifyFailure("CircularReference", "Circular reference detected in the document AST");
+		ctx.seen.add(node);
+		try {
+			return node instanceof YamlMap ? stringifyMapNodeLines(node, ctx, depth) : stringifySeqNodeLines(node, ctx, depth);
+		} finally {
+			ctx.seen.delete(node);
+		}
+	}
 	if (node instanceof YamlAlias) return [`*${node.name}`];
 	return ["null"];
 }
@@ -623,12 +644,13 @@ function stringifyScalarNodeLines(node, ctx) {
 	}
 	let lines;
 	if (val === null || val === void 0) {
-		if (isEmpty) lines = [""];
+		if (isEmpty && node.raw === void 0) lines = [""];
 		else lines = ["null"];
 	} else if (typeof val === "boolean") lines = [val ? "true" : "false"];
 	else if (typeof val === "number") lines = [node.raw !== void 0 ? node.raw : renderNumber(val)];
 	else if (typeof val === "string") lines = renderString(val, style, " ".repeat(ctx.indent), !!node.tag, ctx.forceDefaultStyles, node.chomp, ctx.parentPosition, ctx.quoteStyle, node.blockIndent, ctx.quoteCompat, ctx.inFlow).split("\n");
-	else lines = [renderDoubleQuoted(String(val))];
+	else if (typeof val === "bigint") lines = [node.raw !== void 0 ? node.raw : val.toString()];
+	else throw unrepresentable(typeof val);
 	if (node.tag) lines[0] = `${node.tag} ${lines[0]}`;
 	if (node.anchor) lines[0] = `&${node.anchor} ${lines[0]}`;
 	return lines;

package/package.json

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