@effected/yaml 0.24.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
 */
@@ -227,14 +230,14 @@ const aliasCountExceededError = (message, text) => new YamlParseError({
 * Shared by every stringify path — `Yaml.stringify`/`stringifyResult`, the
 * schema encoders, `YamlDocument#stringifyResult` and `YamlFormat.modify`'s
 * backstop — so all of them surface the hardening guards (circular
-* reference, nesting-depth cap) identically.
+* 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,
@@ -309,9 +312,9 @@ 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) => Result.try({
 	try: () => stringifyValue(value, toStringifyInput(options)),
@@ -401,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
@@ -504,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

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

@@ -174,13 +174,16 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	}
 	/**
 	* Stringify this document (contents, directives and framing) as YAML.
-	* Fails with {@link YamlStringifyError} (`NestingDepthExceeded`) on a
-	* synthetic AST nested deeper than the stringifier's recursion budget. A
-	* cycle introduced into a synthetic AST fails the same way: the node path
-	* keeps no ancestor set, so the cycle is caught by the depth cap rather
-	* than reported as `CircularReference`. Either way the failure surfaces
-	* through the typed error channel, never as an unhandled stack-overflow
-	* defect.
+	* 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.
@@ -209,11 +212,10 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* primitive {@link YamlDocument.stringify} is defined in terms of, so a
 	* synchronous host can round-trip a document parsed with
 	* {@link YamlDocument.parseResult} without an Effect runtime. Fails with
-	* {@link YamlStringifyError} exactly where `stringify` does: a synthetic
-	* AST nested deeper than the stringifier's recursion budget, or one
-	* containing a cycle, both as `NestingDepthExceeded` (the node path keeps
-	* no ancestor set, so a cycle is caught by the depth cap, not reported as
-	* `CircularReference`).
+	* {@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

package/YamlFormat.js

@@ -259,12 +259,16 @@ 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
-* that would sit deeper than `MAX_NESTING_DEPTH` in the output document
-* raises `NestingDepthExceeded`. `depth` is measured in the stringifier's own
+* 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
@@ -302,7 +306,14 @@ 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,
@@ -698,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.
@@ -722,12 +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 that would sit deeper than 256
-	* levels in the output document (`NestingDepthExceeded`). The depth is
-	* counted from the document root, so the same value can fit at `[]` and
-	* fail a few keys down.
+	* 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 —

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
@@ -1131,13 +1142,16 @@ export declare class YamlDocument extends YamlDocument_base {
   static schema(options?: YamlParseOptions): Schema.Codec<YamlDocument, string>;
   /**
    * Stringify this document (contents, directives and framing) as YAML.
-   * Fails with {@link YamlStringifyError} (`NestingDepthExceeded`) on a
-   * synthetic AST nested deeper than the stringifier's recursion budget. A
-   * cycle introduced into a synthetic AST fails the same way: the node path
-   * keeps no ancestor set, so the cycle is caught by the depth cap rather
-   * than reported as `CircularReference`. Either way the failure surfaces
-   * through the typed error channel, never as an unhandled stack-overflow
-   * defect.
+   * 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.
@@ -1164,11 +1178,10 @@ export declare class YamlDocument extends YamlDocument_base {
    * primitive {@link YamlDocument.stringify} is defined in terms of, so a
    * synchronous host can round-trip a document parsed with
    * {@link YamlDocument.parseResult} without an Effect runtime. Fails with
-   * {@link YamlStringifyError} exactly where `stringify` does: a synthetic
-   * AST nested deeper than the stringifier's recursion budget, or one
-   * containing a cycle, both as `NestingDepthExceeded` (the node path keeps
-   * no ancestor set, so a cycle is caught by the depth cap, not reported as
-   * `CircularReference`).
+   * {@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
@@ -1420,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.
@@ -1444,12 +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 that would sit deeper than 256
-   * levels in the output document (`NestingDepthExceeded`). The depth is
-   * counted from the document root, so the same value can fit at `[]` and
-   * fail a few keys down.
+   * 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 —

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.24.0",
+	"version": "0.25.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [