@effected/yaml 0.12.0 → 0.14.0

package/YamlFormat.js

@@ -238,8 +238,56 @@ function formatStream(text, documents, streamErrors, options) {
 	}
 	return parts.join("");
 }
-/** Convert a plain JS scalar value into a synthetic `YamlScalar` (offset/length are irrelevant — immediately re-stringified). */
-function jsValueToNode(value) {
+/**
+* Lower a plain JavaScript value into synthetic AST nodes (offset/length are
+* irrelevant — the result is immediately re-stringified).
+*
+* Recursive by design: an array becomes a block {@link YamlSeq} and any other
+* non-null object a block {@link YamlMap} over its own enumerable string keys,
+* matching what `Yaml.stringify` does with the same value on the value path.
+* 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 (#642).
+*
+* 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
+* the ancestors of the value being lowered, so a value repeated across
+* siblings (a shared, acyclic sub-object) is lowered twice rather than
+* rejected.
+*/
+function jsValueToNode(value, seen, depth) {
+	if (depth > 256) throw new ModifyFailure("NestingDepthExceeded", `Replacement value nests deeper than the maximum of ${256}`, 0, 0);
+	if (typeof value === "object" && value !== null) {
+		if (seen.has(value)) throw new ModifyFailure("CircularReference", "Replacement value contains a circular reference", 0, 0);
+		seen.add(value);
+		try {
+			if (Array.isArray(value)) return YamlSeq.make({
+				items: value.map((item) => jsValueToNode(item, seen, depth + 1)),
+				style: "block",
+				offset: 0,
+				length: 0
+			});
+			const record = value;
+			return YamlMap.make({
+				items: Object.keys(record).map((key) => YamlPair.make({
+					key: YamlScalar.make({
+						value: key,
+						style: "plain",
+						offset: 0,
+						length: 0
+					}),
+					value: jsValueToNode(record[key], seen, depth + 1)
+				})),
+				style: "block",
+				offset: 0,
+				length: 0
+			});
+		} finally {
+			seen.delete(value);
+		}
+	}
 	return YamlScalar.make({
 		value,
 		style: "plain",
@@ -247,8 +295,12 @@ function jsValueToNode(value) {
 		length: 0
 	});
 }
+/** Entry point for {@link jsValueToNode}: one `seen` set per lowering. */
+function lowerValue(value) {
+	return jsValueToNode(value, /* @__PURE__ */ new Set(), 0);
+}
 function modifyDocument(doc, path, value) {
-	if (path.length === 0) return value === void 0 ? null : jsValueToNode(value);
+	if (path.length === 0) return value === void 0 ? null : lowerValue(value);
 	if (doc.contents === null) throw new ModifyFailure("EmptyDocument", "Cannot navigate path in empty document", 0, 0);
 	return modifyNode(doc.contents, path, 0, value);
 }
@@ -264,7 +316,7 @@ function modifyNode(node, path, depth, value) {
 				newItems.splice(pairIndex, 1);
 				return rebuildMap(node, newItems);
 			}
-			const newValueNode = jsValueToNode(value);
+			const newValueNode = lowerValue(value);
 			if (pairIndex >= 0) {
 				const newItems = [...node.items];
 				const oldPair = newItems[pairIndex];
@@ -304,8 +356,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] = jsValueToNode(value);
-			else newItems.push(jsValueToNode(value));
+			} else if (idx < newItems.length) newItems[idx] = lowerValue(value);
+			else newItems.push(lowerValue(value));
 			return rebuildSeq(node, newItems);
 		}
 		if (idx >= node.items.length) throw new ModifyFailure("InvalidIndex", `Index ${idx} out of bounds`, node.offset, node.length);
@@ -456,12 +508,27 @@ var YamlFormat = class YamlFormat {
 	/**
 	* Compute the edits that insert, replace, or remove a value at `path`.
 	* Passing `value === undefined` removes the target key/element; a missing
-	* insertion target appends after the last pair/element. Only
-	* scalar-compatible values are supported (matching v3 — arbitrary object
-	* graphs are not recursively lowered into AST nodes). Fails with
+	* insertion target appends after the last pair/element. Fails with
 	* {@link YamlModificationError} on a fatal parse error or a structural
 	* navigation mismatch.
 	*
+	* **`value` may be a whole object graph.** An array is written as a block
+	* 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. (Before
+	* 0.14.0 only scalars were lowered and a mapping or sequence value was
+	* coerced through `String(value)`, writing the literal text
+	* `[object Object]` into the document — see #642.) Only the surrounding
+	* document is preserved byte-for-byte; the replacement subtree is
+	* synthesized, so it carries no comments and takes 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`).
+	*
 	* **Single-document contract.** A `path` carries no document index, so on
 	* a multi-document stream there is no rule for which document it names —
 	* `modify` fails with {@link YamlModificationError} carrying a

package/index.d.ts

@@ -5,77 +5,77 @@ import { Data, Effect, Option, Result, Schema, Stream } from "effect";
  *
  * @public
  */
-declare const YamlLexErrorCode: Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>;
+export declare const YamlLexErrorCode: Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>;
 /**
  * The union of all lexer-stage error code string literals.
  *
  * @public
  */
-type YamlLexErrorCode = typeof YamlLexErrorCode.Type;
+export type YamlLexErrorCode = typeof YamlLexErrorCode.Type;
 /**
  * Error codes emitted by the CST-parser stage.
  *
  * @public
  */
-declare const YamlParseErrorCode: Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>;
+export declare const YamlParseErrorCode: Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>;
 /**
  * The union of all parser-stage error code string literals.
  *
  * @public
  */
-type YamlParseErrorCode = typeof YamlParseErrorCode.Type;
+export type YamlParseErrorCode = typeof YamlParseErrorCode.Type;
 /**
  * Error codes emitted by the composer stage.
  *
  * @public
  */
-declare const YamlComposerErrorCode: Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>;
+export declare const YamlComposerErrorCode: Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>;
 /**
  * The union of all composer-stage error code string literals.
  *
  * @public
  */
-type YamlComposerErrorCode = typeof YamlComposerErrorCode.Type;
+export type YamlComposerErrorCode = typeof YamlComposerErrorCode.Type;
 /**
  * Error codes emitted by the stringifier (the circular-reference guard).
  *
  * @public
  */
-declare const YamlStringifyErrorCode: Schema.Literals<readonly ["CircularReference"]>;
+export declare const YamlStringifyErrorCode: Schema.Literals<readonly ["CircularReference"]>;
 /**
  * The union of all stringifier-stage error code string literals.
  *
  * @public
  */
-type YamlStringifyErrorCode = typeof YamlStringifyErrorCode.Type;
+export type YamlStringifyErrorCode = typeof YamlStringifyErrorCode.Type;
 /**
  * Error codes emitted by `YamlFormat.modify`'s path navigation against an
  * already-composed AST — not raised by the parser/composer/stringifier.
  *
  * @public
  */
-declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument"]>;
+export declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument", "CircularReference", "NestingDepthExceeded"]>;
 /**
  * The union of all modify-stage error code string literals.
  *
  * @public
  */
-type YamlModifyErrorCode = typeof YamlModifyErrorCode.Type;
+export type YamlModifyErrorCode = typeof YamlModifyErrorCode.Type;
 /**
  * Union of all YAML error codes across all pipeline stages. Stage
  * discrimination lives here (in the code), not in separate error classes.
  *
  * @public
  */
-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"]>]>;
+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"]>]>;
 /**
  * The union of all YAML error code string literals.
  *
  * @public
  */
-type YamlErrorCode = typeof YamlErrorCode.Type;
+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"]>]>;
+  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 message: Schema.String;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -95,7 +95,7 @@ declare const YamlDiagnostic_base: Schema.Class<YamlDiagnostic, Schema.Struct<{
  *
  * @public
  */
-declare class YamlDiagnostic extends YamlDiagnostic_base {
+export declare class YamlDiagnostic extends YamlDiagnostic_base {
   /**
    * The single fatal-code predicate: whether diagnostics with this code
    * abort a parse (vs. being recoverable warnings-as-data). Declared once,
@@ -142,7 +142,7 @@ declare const YamlParseOptions_base: Schema.Class<YamlParseOptions, Schema.Struc
  *
  * @public
  */
-declare class YamlParseOptions extends YamlParseOptions_base {}
+export declare class YamlParseOptions extends YamlParseOptions_base {}
 declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Schema.Struct<{
   readonly indent: Schema.optionalKey<Schema.Number>;
   /**
@@ -257,7 +257,7 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  *
  * @public
  */
-declare class YamlStringifyOptions extends YamlStringifyOptions_base {}
+export declare class YamlStringifyOptions extends YamlStringifyOptions_base {}
 declare const YamlParseError_base: Schema.Class<YamlParseError, Schema.TaggedStruct<"YamlParseError", {
   readonly diagnostics: Schema.$Array<typeof YamlDiagnostic>;
   readonly input: Schema.String;
@@ -272,7 +272,7 @@ declare const YamlParseError_base: Schema.Class<YamlParseError, Schema.TaggedStr
  *
  * @public
  */
-declare class YamlParseError extends YamlParseError_base {
+export declare class YamlParseError extends YamlParseError_base {
   get message(): string;
 }
 declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.TaggedStruct<"YamlStringifyError", {
@@ -288,7 +288,7 @@ declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.T
  *
  * @public
  */
-declare class YamlStringifyError extends YamlStringifyError_base {
+export declare class YamlStringifyError extends YamlStringifyError_base {
   get message(): string;
 }
 /**
@@ -331,7 +331,7 @@ interface YamlBoundCodec<T, RD = never, RE = never> {
  *
  * @public
  */
-declare class Yaml {
+export declare class Yaml {
   private constructor();
   /**
    * Parse a single YAML document into a plain JavaScript value, resolving
@@ -601,7 +601,7 @@ declare const YamlRange_base: Schema.Class<YamlRange, Schema.Struct<{
  *
  * @public
  */
-declare class YamlRange extends YamlRange_base {}
+export declare class YamlRange extends YamlRange_base {}
 declare const YamlEdit_base: Schema.Class<YamlEdit, Schema.Struct<{
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -618,7 +618,7 @@ declare const YamlEdit_base: Schema.Class<YamlEdit, Schema.Struct<{
  *
  * @public
  */
-declare class YamlEdit extends YamlEdit_base {
+export declare class YamlEdit extends YamlEdit_base {
   /**
    * Apply `edits` to `text`, producing a new string. Edits are applied in
    * reverse-offset order so earlier offsets stay valid; the input `edits`
@@ -634,25 +634,25 @@ declare class YamlEdit extends YamlEdit_base {
  *
  * @public
  */
-declare const ScalarStyle: Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
+export declare const ScalarStyle: Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
 /**
  * The union of all scalar style string literals.
  *
  * @public
  */
-type ScalarStyle = typeof ScalarStyle.Type;
+export type ScalarStyle = typeof ScalarStyle.Type;
 /**
  * YAML collection presentation styles.
  *
  * @public
  */
-declare const CollectionStyle: Schema.Literals<readonly ["block", "flow"]>;
+export declare const CollectionStyle: Schema.Literals<readonly ["block", "flow"]>;
 /**
  * The union of all collection style string literals.
  *
  * @public
  */
-type CollectionStyle = typeof CollectionStyle.Type;
+export type CollectionStyle = typeof CollectionStyle.Type;
 /**
  * Quote characters available to the stringifier's plain-scalar fallback: the
  * style a `plain`-styled scalar is rendered in when it turns out to require
@@ -662,13 +662,13 @@ type CollectionStyle = typeof CollectionStyle.Type;
  *
  * @public
  */
-declare const QuoteStyle: Schema.Literals<readonly ["single", "double"]>;
+export declare const QuoteStyle: Schema.Literals<readonly ["single", "double"]>;
 /**
  * The union of all fallback quote style string literals.
  *
  * @public
  */
-type QuoteStyle = typeof QuoteStyle.Type;
+export type QuoteStyle = typeof QuoteStyle.Type;
 /**
  * Foreign resolution dialects the stringifier's plain-scalar fallback can
  * defend against: setting the `quoteCompat` field of `YamlStringifyOptions`
@@ -683,26 +683,26 @@ type QuoteStyle = typeof QuoteStyle.Type;
  *
  * @public
  */
-declare const QuoteCompat: Schema.Literals<readonly ["yaml-1.1"]>;
+export declare const QuoteCompat: Schema.Literals<readonly ["yaml-1.1"]>;
 /**
  * The union of all quote-compat dialect string literals.
  *
  * @public
  */
-type QuoteCompat = typeof QuoteCompat.Type;
+export type QuoteCompat = typeof QuoteCompat.Type;
 /**
  * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
  * Referenced by the {@link YamlScalar} `chomp` field schema.
  *
  * @public
  */
-declare const ScalarChomp: Schema.Literals<readonly ["strip", "clip", "keep"]>;
+export declare const ScalarChomp: Schema.Literals<readonly ["strip", "clip", "keep"]>;
 /**
  * The union of all block-scalar chomping indicator string literals.
  *
  * @public
  */
-type ScalarChomp = typeof ScalarChomp.Type;
+export type ScalarChomp = typeof ScalarChomp.Type;
 declare const YamlScalar_base: Schema.Class<YamlScalar, Schema.TaggedStruct<"YamlScalar", {
   readonly value: Schema.Unknown;
   readonly tag: Schema.optionalKey<Schema.String>;
@@ -746,7 +746,7 @@ declare const YamlScalar_base: Schema.Class<YamlScalar, Schema.TaggedStruct<"Yam
  *
  * @public
  */
-declare class YamlScalar extends YamlScalar_base {
+export declare class YamlScalar extends YamlScalar_base {
   /**
    * Navigate to a descendant by path (string segments for mapping keys,
    * numbers for sequence indices). `Option.none()` when any segment cannot
@@ -790,7 +790,7 @@ declare const YamlAlias_base: Schema.Class<YamlAlias, Schema.TaggedStruct<"YamlA
  *
  * @public
  */
-declare class YamlAlias extends YamlAlias_base {
+export declare class YamlAlias extends YamlAlias_base {
   /** See `YamlScalar.find`. Pure. */
   find(path: YamlPath): Option.Option<YamlNode>;
   /** See `YamlScalar.findAtOffset`. Pure. */
@@ -843,13 +843,13 @@ interface YamlAliasEncoded extends Schema.Codec.Encoded<typeof YamlAlias> {}
  *
  * @public
  */
-declare const YamlNode: Schema.Codec<YamlScalar | YamlMap | YamlSeq | YamlAlias, YamlScalarEncoded | YamlMapEncoded | YamlSeqEncoded | YamlAliasEncoded>;
+export declare const YamlNode: Schema.Codec<YamlScalar | YamlMap | YamlSeq | YamlAlias, YamlScalarEncoded | YamlMapEncoded | YamlSeqEncoded | YamlAliasEncoded>;
 /**
  * The union of all YAML AST value node types.
  *
  * @public
  */
-type YamlNode = YamlScalar | YamlMap | YamlSeq | YamlAlias;
+export type YamlNode = YamlScalar | YamlMap | YamlSeq | YamlAlias;
 declare const YamlPair_base: Schema.Class<YamlPair, Schema.TaggedStruct<"YamlPair", {
   readonly key: Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>;
   readonly value: Schema.NullOr<Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>>;
@@ -867,7 +867,7 @@ declare const YamlPair_base: Schema.Class<YamlPair, Schema.TaggedStruct<"YamlPai
  *
  * @public
  */
-declare class YamlPair extends YamlPair_base {}
+export declare class YamlPair extends YamlPair_base {}
 declare const YamlMap_base: Schema.Class<YamlMap, Schema.TaggedStruct<"YamlMap", {
   readonly items: Schema.$Array<Schema.suspend<typeof YamlPair>>;
   readonly tag: Schema.optionalKey<Schema.String>;
@@ -895,7 +895,7 @@ declare const YamlMap_base: Schema.Class<YamlMap, Schema.TaggedStruct<"YamlMap",
  *
  * @public
  */
-declare class YamlMap extends YamlMap_base {
+export declare class YamlMap extends YamlMap_base {
   /** See `YamlScalar.find`. Pure. */
   find(path: YamlPath): Option.Option<YamlNode>;
   /** See `YamlScalar.findAtOffset`. Pure. */
@@ -929,7 +929,7 @@ declare const YamlSeq_base: Schema.Class<YamlSeq, Schema.TaggedStruct<"YamlSeq",
  *
  * @public
  */
-declare class YamlSeq extends YamlSeq_base {
+export declare class YamlSeq extends YamlSeq_base {
   /** See `YamlScalar.find`. Pure. */
   find(path: YamlPath): Option.Option<YamlNode>;
   /** See `YamlScalar.findAtOffset`. Pure. */
@@ -953,7 +953,7 @@ declare const YamlDirective_base: Schema.Class<YamlDirective, Schema.Struct<{
  *
  * @public
  */
-declare class YamlDirective extends YamlDirective_base {}
+export declare class YamlDirective extends YamlDirective_base {}
 declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
   readonly contents: Schema.NullOr<Schema.suspend<Schema.Schema<YamlNode>>>;
   readonly errors: Schema.$Array<typeof YamlDiagnostic>;
@@ -982,7 +982,7 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
  *
  * @public
  */
-declare class YamlDocument extends YamlDocument_base {
+export declare class YamlDocument extends YamlDocument_base {
   /**
    * Parse a single YAML document, keeping the full AST, directives and
    * recovered diagnostics. Fails with the aggregate {@link YamlParseError}
@@ -1102,7 +1102,7 @@ declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Sc
  *
  * @public
  */
-declare class YamlFormattingOptions extends YamlFormattingOptions_base {}
+export declare class YamlFormattingOptions extends YamlFormattingOptions_base {}
 declare const YamlModificationError_base: Schema.Class<YamlModificationError, Schema.TaggedStruct<"YamlModificationError", {
   readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
   readonly diagnostics: Schema.$Array<typeof YamlDiagnostic>;
@@ -1122,7 +1122,7 @@ declare const YamlModificationError_base: Schema.Class<YamlModificationError, Sc
  *
  * @public
  */
-declare class YamlModificationError extends YamlModificationError_base {
+export declare class YamlModificationError extends YamlModificationError_base {
   get message(): string;
 }
 /**
@@ -1157,7 +1157,7 @@ declare class YamlModificationError extends YamlModificationError_base {
  *
  * @public
  */
-declare class YamlFormat {
+export declare class YamlFormat {
   private constructor();
   /**
    * Compute formatting edits for a YAML document. Non-mutating — apply the
@@ -1219,12 +1219,27 @@ declare class YamlFormat {
   /**
    * Compute the edits that insert, replace, or remove a value at `path`.
    * Passing `value === undefined` removes the target key/element; a missing
-   * insertion target appends after the last pair/element. Only
-   * scalar-compatible values are supported (matching v3 — arbitrary object
-   * graphs are not recursively lowered into AST nodes). Fails with
+   * insertion target appends after the last pair/element. Fails with
    * {@link YamlModificationError} on a fatal parse error or a structural
    * navigation mismatch.
    *
+   * **`value` may be a whole object graph.** An array is written as a block
+   * 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. (Before
+   * 0.14.0 only scalars were lowered and a mapping or sequence value was
+   * coerced through `String(value)`, writing the literal text
+   * `[object Object]` into the document — see #642.) Only the surrounding
+   * document is preserved byte-for-byte; the replacement subtree is
+   * synthesized, so it carries no comments and takes 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`).
+   *
    * **Single-document contract.** A `path` carries no document index, so on
    * a multi-document stream there is no rule for which document it names —
    * `modify` fails with {@link YamlModificationError} carrying a
@@ -1264,13 +1279,13 @@ declare class YamlFormat {
  *
  * @public
  */
-declare const YamlTokenKind: Schema.Literals<readonly ["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;
+export declare const YamlTokenKind: Schema.Literals<readonly ["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;
 /**
  * The union of all lexical token kind string literals.
  *
  * @public
  */
-type YamlTokenKind = typeof YamlTokenKind.Type;
+export type YamlTokenKind = typeof YamlTokenKind.Type;
 declare const YamlToken_base: Schema.Class<YamlToken, Schema.Struct<{
   readonly kind: Schema.Literals<readonly ["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;
   readonly text: Schema.String;
@@ -1291,13 +1306,13 @@ declare const YamlToken_base: Schema.Class<YamlToken, Schema.Struct<{
  *
  * @public
  */
-declare class YamlToken extends YamlToken_base {}
+export declare class YamlToken extends YamlToken_base {}
 /**
  * Tokenizer statics. Not instantiable.
  *
  * @public
  */
-declare class YamlTokens {
+export declare class YamlTokens {
   private constructor();
   /**
    * Tokenize YAML text into the full positioned token array — the sync
@@ -1346,13 +1361,13 @@ declare class YamlTokens {
  *
  * @public
  */
-declare const YamlLintSeverity: Schema.Literals<readonly ["error", "warning"]>;
+export declare const YamlLintSeverity: Schema.Literals<readonly ["error", "warning"]>;
 /**
  * The union of lint severity string literals.
  *
  * @public
  */
-type YamlLintSeverity = typeof YamlLintSeverity.Type;
+export type YamlLintSeverity = typeof YamlLintSeverity.Type;
 declare const YamlLintDiagnostic_base: Schema.Class<YamlLintDiagnostic, Schema.Struct<{
   readonly rule: Schema.String;
   readonly severity: Schema.Literals<readonly ["error", "warning"]>;
@@ -1375,7 +1390,7 @@ declare const YamlLintDiagnostic_base: Schema.Class<YamlLintDiagnostic, Schema.S
  *
  * @public
  */
-declare class YamlLintDiagnostic extends YamlLintDiagnostic_base {}
+export declare class YamlLintDiagnostic extends YamlLintDiagnostic_base {}
 /**
  * One source line of the linted document: its text (without the line
  * terminator — the `\n`, and for CRLF input the `\r\n` pair), the offset of
@@ -1438,7 +1453,7 @@ declare const StyleVote_base: Schema.Class<StyleVote, Schema.TaggedStruct<"Style
  *
  * @public
  */
-declare class StyleVote extends StyleVote_base {}
+export declare class StyleVote extends StyleVote_base {}
 declare const StyleFloor_base: Schema.Class<StyleFloor, Schema.TaggedStruct<"StyleFloor", {
   readonly dimension: Schema.String;
   readonly value: Schema.Number;
@@ -1456,7 +1471,7 @@ declare const StyleFloor_base: Schema.Class<StyleFloor, Schema.TaggedStruct<"Sty
  *
  * @public
  */
-declare class StyleFloor extends StyleFloor_base {}
+export declare class StyleFloor extends StyleFloor_base {}
 /**
  * What a rule's `infer` hook yields per occurrence: a categorical
  * {@link StyleVote} or a measured {@link StyleFloor}.
@@ -1497,13 +1512,13 @@ interface YamlRule {
  *
  * @public
  */
-declare const YamlLintRuleSetting: Schema.Union<readonly [Schema.Literals<readonly ["error", "warning", "off"]>, Schema.$Record<Schema.String, Schema.Unknown>]>;
+export declare const YamlLintRuleSetting: Schema.Union<readonly [Schema.Literals<readonly ["error", "warning", "off"]>, Schema.$Record<Schema.String, Schema.Unknown>]>;
 /**
  * The union type of one `rules`-map entry.
  *
  * @public
  */
-type YamlLintRuleSetting = typeof YamlLintRuleSetting.Type;
+export type YamlLintRuleSetting = typeof YamlLintRuleSetting.Type;
 declare const YamlLintConfig_base: Schema.Class<YamlLintConfig, Schema.Struct<{
   readonly rules: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Literals<readonly ["error", "warning", "off"]>, Schema.$Record<Schema.String, Schema.Unknown>]>>;
 }>, {}>;
@@ -1524,7 +1539,7 @@ declare const YamlLintConfig_base: Schema.Class<YamlLintConfig, Schema.Struct<{
  *
  * @public
  */
-declare class YamlLintConfig extends YamlLintConfig_base {
+export declare class YamlLintConfig extends YamlLintConfig_base {
   /**
    * The default preset. Rule entries accrete as built-ins land; the
    * `quoted-strings` rule defaults to DOUBLE quotes here (the one taste
@@ -1552,7 +1567,7 @@ declare const StyleVoteTally_base: Schema.Class<StyleVoteTally, Schema.Struct<{
  *
  * @public
  */
-declare class StyleVoteTally extends StyleVoteTally_base {}
+export declare class StyleVoteTally extends StyleVoteTally_base {}
 declare const StyleFloorTally_base: Schema.Class<StyleFloorTally, Schema.Struct<{
   readonly rule: Schema.String;
   readonly dimension: Schema.String;
@@ -1566,7 +1581,7 @@ declare const StyleFloorTally_base: Schema.Class<StyleFloorTally, Schema.Struct<
  *
  * @public
  */
-declare class StyleFloorTally extends StyleFloorTally_base {}
+export declare class StyleFloorTally extends StyleFloorTally_base {}
 declare const StyleEvidence_base: Schema.Class<StyleEvidence, Schema.Struct<{
   readonly votes: Schema.$Array<typeof StyleVoteTally>;
   readonly floors: Schema.$Array<typeof StyleFloorTally>;
@@ -1587,7 +1602,7 @@ declare const StyleEvidence_base: Schema.Class<StyleEvidence, Schema.Struct<{
  *
  * @public
  */
-declare class StyleEvidence extends StyleEvidence_base {
+export declare class StyleEvidence extends StyleEvidence_base {
   /** The monoid identity: no observations. */
   static readonly empty: StyleEvidence;
   /**
@@ -1618,7 +1633,7 @@ declare const StyleConflict_base: Schema.Class<StyleConflict, Schema.Struct<{
  *
  * @public
  */
-declare class StyleConflict extends StyleConflict_base {}
+export declare class StyleConflict extends StyleConflict_base {}
 declare const YamlStyleConflictError_base: Schema.Class<YamlStyleConflictError, Schema.TaggedStruct<"YamlStyleConflictError", {
   readonly conflicts: Schema.$Array<typeof StyleConflict>;
 }>, import("effect/Cause").YieldableError>;
@@ -1632,7 +1647,7 @@ declare const YamlStyleConflictError_base: Schema.Class<YamlStyleConflictError,
  *
  * @public
  */
-declare class YamlStyleConflictError extends YamlStyleConflictError_base {
+export declare class YamlStyleConflictError extends YamlStyleConflictError_base {
   get message(): string;
 }
 /**
@@ -1656,7 +1671,7 @@ interface YamlLintInference {
  *
  * @public
  */
-declare class YamlLint {
+export declare class YamlLint {
   private constructor();
   /**
    * The built-in rule catalog. Custom usage is array concatenation:
@@ -1752,7 +1767,7 @@ declare class YamlLint {
  *
  * @public
  */
-type YamlVisitorEvent = Data.TaggedEnum<{
+export type YamlVisitorEvent = Data.TaggedEnum<{
   DocumentStart: {
     readonly path: YamlPath;
     readonly depth: number;
@@ -1832,7 +1847,7 @@ type YamlVisitorEvent = Data.TaggedEnum<{
  *
  * @public
  */
-declare const YamlVisitorEvent: {
+export declare const YamlVisitorEvent: {
   readonly $is: <Tag extends "Alias" | "Comment" | "Directive" | "DocumentEnd" | "DocumentStart" | "Error" | "MapEnd" | "MapStart" | "Pair" | "Scalar" | "SeqEnd" | "SeqStart">(tag: Tag) => (u: unknown) => u is Extract<{
     readonly _tag: "Alias";
     readonly path: YamlPath;
@@ -2326,7 +2341,7 @@ declare const YamlVisitorEvent: {
  *
  * @public
  */
-declare class YamlVisitor {
+export declare class YamlVisitor {
   private constructor();
   /**
    * Create a lazy `Stream` of `YamlVisitorEvent` from YAML text, in document
@@ -2344,5 +2359,5 @@ declare class YamlVisitor {
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }
 //#endregion
-export { CollectionStyle, type LintContext, type LintLine, QuoteCompat, QuoteStyle, ScalarChomp, ScalarStyle, StyleConflict, StyleEvidence, StyleFloor, StyleFloorTally, type StyleObservation, StyleVote, StyleVoteTally, Yaml, YamlAlias, type YamlAliasEncoded, type YamlBoundCodec, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlLint, YamlLintConfig, YamlLintDiagnostic, type YamlLintInference, YamlLintRuleSetting, YamlLintSeverity, YamlMap, type YamlMapEncoded, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, type YamlRule, YamlScalar, type YamlScalarEncoded, type YamlSegment, YamlSeq, type YamlSeqEncoded, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlStyleConflictError, YamlToken, YamlTokenKind, YamlTokens, YamlVisitor, YamlVisitorEvent };
+export type { LintContext, LintLine, StyleObservation, YamlAliasEncoded, YamlBoundCodec, YamlLintInference, YamlMapEncoded, YamlPath, YamlRangeLike, YamlRule, YamlScalarEncoded, YamlSegment, YamlSeqEncoded };
 //# sourceMappingURL=index.d.ts.map

package/internal/composer/block.js

@@ -40,7 +40,7 @@ function composeBlockMapInner(blockMapCst, state, externalFirstKey, meta) {
 	if (state.options.uniqueKeys) checkDuplicateKeys(pairs, state);
 	checkMultilineImplicitKeys(pairs, state);
 	const offset = externalFirstKey ? "offset" in externalFirstKey ? externalFirstKey.offset : blockMapCst.offset : blockMapCst.offset;
-	const length = blockMapCst.offset + blockMapCst.length - offset;
+	const length = trimDisownedTrailingComments(state.text, offset, blockMapCst.offset + blockMapCst.length, state.escapedComments) - offset;
 	const mapComment = meta?.comment !== void 0 ? trailingComment !== void 0 ? `${meta.comment}\n${trailingComment}` : meta.comment : trailingComment;
 	const map = new YamlMap({
 		items: pairs,
@@ -54,6 +54,49 @@ function composeBlockMapInner(blockMapCst, state, externalFirstKey, meta) {
 	if (meta?.anchor) registerAnchor(map, meta.anchor, state, offset);
 	return map;
 }
+/**
+* Narrow a block collection's raw CST span so it stops before any trailing
+* comment line the collection's own comment model has already DISOWNED.
+*
+* The CST length of a block map/seq runs to the end of the last physical line
+* the parser consumed, which includes a floating comment sitting at a column
+* shallower than the collection's content. The comment model deliberately
+* does not give that comment to the collection — `buildPairs` and the block-seq
+* terminal partition push it onto `state.escapedComments`, where the enclosing
+* scope re-attributes it (see `EscapedComment` in `comments.ts`: "it belongs to
+* an outer scope"). The span was the one place that disagreed, reporting an
+* `offset`/`length` whose end lay past a comment the node does not own — so a
+* caller splicing text at the end of the collection inserted AFTER the comment
+* (#642's sibling, #643).
+*
+* The disowned set is the input rather than a re-derived column test, so the
+* span and the comment model cannot drift apart: whatever the partition threw
+* out, the span excludes.
+*
+* Blank lines immediately above a trimmed run go with the run, not with the
+* last entry — but only when something was trimmed, so a collection whose span
+* merely ends in blank lines keeps the end it has always reported.
+*
+* Composition is bottom-up, so a nested collection's own span has already been
+* trimmed by the time its parent's items are read.
+*/
+function trimDisownedTrailingComments(text, offset, end, disowned) {
+	let cut = end;
+	for (const ec of disowned) {
+		if (ec.offset < offset || ec.offset >= cut) continue;
+		const lineStart = text.lastIndexOf("\n", ec.offset - 1) + 1;
+		if (lineStart <= offset || lineStart >= cut) continue;
+		cut = lineStart;
+	}
+	if (cut === end) return end;
+	while (cut > offset && text[cut - 1] === "\n") {
+		const prevLineStart = text.lastIndexOf("\n", cut - 2) + 1;
+		if (prevLineStart <= offset) break;
+		if (text.slice(prevLineStart, cut - 1).trim() !== "") break;
+		cut = prevLineStart;
+	}
+	return cut;
+}
 function flattenBlockMapChildren(children, state, externalKeyColumn, externalKeyOffset) {
 	const items = [];
 	let pendingMeta = {};
@@ -1344,11 +1387,12 @@ function composeBlockSeqInner(cst, state, meta) {
 		} else seqTrailing = withLeadingBlank(pending);
 	}
 	const seqComment = meta?.comment !== void 0 ? seqTrailing !== void 0 ? `${meta.comment}\n${seqTrailing}` : meta.comment : seqTrailing;
+	const seqEnd = trimDisownedTrailingComments(state.text, cst.offset, cst.offset + cst.length, state.escapedComments);
 	const seq = new YamlSeq({
 		items: rawItems,
 		style: "block",
 		offset: cst.offset,
-		length: cst.length,
+		length: seqEnd - cst.offset,
 		...meta?.tag !== void 0 ? { tag: meta.tag } : {},
 		...meta?.anchor !== void 0 ? { anchor: meta.anchor } : {},
 		...seqComment !== void 0 ? { comment: seqComment } : {}
@@ -1371,7 +1415,7 @@ function composeFlatBlockMap(children, startIdx, parentCst, state, externalFirst
 	if (state.options.uniqueKeys) checkDuplicateKeys(pairs, state);
 	checkMultilineImplicitKeys(pairs, state);
 	const offset = "offset" in externalFirstKey ? externalFirstKey.offset : parentCst.offset;
-	const end = parentCst.offset + parentCst.length;
+	const end = trimDisownedTrailingComments(state.text, offset, parentCst.offset + parentCst.length, state.escapedComments);
 	const mapComment = meta?.comment !== void 0 ? trailingComment !== void 0 ? `${meta.comment}\n${trailingComment}` : meta.comment : trailingComment;
 	const map = new YamlMap({
 		items: pairs,

package/internal/diagnostics.js

@@ -52,6 +52,13 @@ const YAML_STRINGIFY_ERROR_CODES = ["CircularReference"];
 * not re-emit `%YAML`/`%TAG` directive lines, and re-emitting a document
 * 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
+* deliberately the ones the stringify and compose stages already use for the
+* same conditions, so `YamlErrorCode` gains no member.
 */
 const YAML_MODIFY_ERROR_CODES = [
 	"EmptyDocument",
@@ -59,7 +66,9 @@ const YAML_MODIFY_ERROR_CODES = [
 	"InvalidIndex",
 	"NotNavigable",
 	"MultiDocumentStream",
-	"DirectiveCarryingDocument"
+	"DirectiveCarryingDocument",
+	"CircularReference",
+	"NestingDepthExceeded"
 ];
 /**
 * The single source of truth for which diagnostic codes are fatal to a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.12.0",
+	"version": "0.14.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [
@@ -41,7 +41,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.109"
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"