@effected/yaml 0.3.0 → 0.3.1

package/Yaml.js

@@ -44,7 +44,9 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * no-fold behavior; a positive value folds long plain, double-quoted and
 * block-folded (`>`) scalars at approximately that column, inserting only
 * semantically transparent line breaks. Block-literal (`|`) content is never
-* folded — literal blocks preserve their bytes by definition.
+* folded — literal blocks preserve their bytes by definition. Folding is a
+* value-path feature only: `YamlDocument#stringify` and the `YamlFormat`
+* helpers accept these options but do not fold (see `lineWidth`).
 *
 * `indentSequences` controls the presentation of block sequences nested under
 * a mapping key: `false` (the default) emits them at the key's column — the
@@ -75,6 +77,15 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	* Column at which to fold long scalars. Default `0` (and any value `<= 0`)
 	* never wraps; a positive value folds plain, double-quoted and block-folded
 	* (`>`) scalars at approximately that column, never block-literal (`|`).
+	*
+	* Takes effect only through {@link Yaml.stringify} and
+	* {@link Yaml.stringifySync} — the two entry points that accept these
+	* options on the value path. The schema factories ({@link Yaml.fromString},
+	* {@link Yaml.schema}, {@link Yaml.YamlFromString}) encode with default
+	* stringify options (`lineWidth` `0`), so their output never folds. The
+	* document/node path — `YamlDocument#stringify` and the `YamlFormat`
+	* helpers built on it — threads the field into its render context but
+	* never reads it, so it is inert there.
 	*/
 	lineWidth: Schema.optionalKey(Schema.Number),
 	defaultScalarStyle: Schema.optionalKey(ScalarStyle),
@@ -181,7 +192,7 @@ const stringifyDefectToError = (defect, value) => {
 	});
 };
 /**
-* Synchronous single-document parse returning a {@link Result}. The pure
+* Synchronous single-document parse returning a `Result`. The pure
 * engine bypasses the Effect runtime entirely: the composer, the failure
 * collection and the alias-expansion budget all run inline, and every failure
 * mode (fatal diagnostics, duplicate keys, a "billion laughs" blow-up) yields
@@ -203,7 +214,7 @@ const parseSyncImpl = (text, options) => {
 	}
 };
 /**
-* Synchronous stringify returning a {@link Result}. Mirrors {@link Yaml.stringify}
+* 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.
@@ -333,7 +344,7 @@ var Yaml = class Yaml {
 		return yield* stringifyOrFail(value, options);
 	});
 	/**
-	* Synchronous single-document parse, returning a {@link Result} instead of
+	* Synchronous single-document parse, returning a `Result` instead of
 	* an `Effect`. A pure escape hatch for config-time callers that cannot
 	* `await` an Effect (a `vitest.config.ts` is the motivating case): it runs
 	* the same engine as {@link Yaml.parse} inline.
@@ -362,7 +373,7 @@ var Yaml = class Yaml {
 		return parseSyncImpl(text, options);
 	}
 	/**
-	* Synchronous stringify, returning a {@link Result} instead of an `Effect`.
+	* Synchronous stringify, returning a `Result` instead of an `Effect`.
 	* The pure counterpart to {@link Yaml.stringify} for config-time callers
 	* that cannot `await`.
 	*

package/YamlDocument.js

@@ -91,6 +91,17 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
 	* — both surface through the typed error channel rather than as an
 	* unhandled stack-overflow defect.
+	*
+	* @remarks
+	* `YamlStringifyOptions.lineWidth` is not honored here: column-based
+	* scalar folding exists only on the value path, through the entry points
+	* that accept stringify options ({@link Yaml.stringify} and
+	* {@link Yaml.stringifySync}). The
+	* document/node path threads `lineWidth` into its render context but
+	* never reads it, so long scalars are emitted unfolded regardless of the
+	* option. Callers that need folding should render the plain value
+	* instead — `Yaml.stringify(doc.toValue(), options)` — at the cost of
+	* the document-level framing and styles this path preserves.
 	*/
 	stringify(options) {
 		return Effect.try({

package/index.d.ts

@@ -149,6 +149,15 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
    * Column at which to fold long scalars. Default `0` (and any value `<= 0`)
    * never wraps; a positive value folds plain, double-quoted and block-folded
    * (`>`) scalars at approximately that column, never block-literal (`|`).
+   *
+   * Takes effect only through {@link Yaml.stringify} and
+   * {@link Yaml.stringifySync} — the two entry points that accept these
+   * options on the value path. The schema factories ({@link Yaml.fromString},
+   * {@link Yaml.schema}, {@link Yaml.YamlFromString}) encode with default
+   * stringify options (`lineWidth` `0`), so their output never folds. The
+   * document/node path — `YamlDocument#stringify` and the `YamlFormat`
+   * helpers built on it — threads the field into its render context but
+   * never reads it, so it is inert there.
    */
   readonly lineWidth: Schema.optionalKey<Schema.Number>;
   readonly defaultScalarStyle: Schema.optionalKey<Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>>;
@@ -170,7 +179,9 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * no-fold behavior; a positive value folds long plain, double-quoted and
  * block-folded (`>`) scalars at approximately that column, inserting only
  * semantically transparent line breaks. Block-literal (`|`) content is never
- * folded — literal blocks preserve their bytes by definition.
+ * folded — literal blocks preserve their bytes by definition. Folding is a
+ * value-path feature only: `YamlDocument#stringify` and the `YamlFormat`
+ * helpers accept these options but do not fold (see `lineWidth`).
  *
  * `indentSequences` controls the presentation of block sequences nested under
  * a mapping key: `false` (the default) emits them at the key's column — the
@@ -284,7 +295,7 @@ declare class Yaml {
    */
   static readonly stringify: (value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlStringifyError, never>;
   /**
-   * Synchronous single-document parse, returning a {@link Result} instead of
+   * Synchronous single-document parse, returning a `Result` instead of
    * an `Effect`. A pure escape hatch for config-time callers that cannot
    * `await` an Effect (a `vitest.config.ts` is the motivating case): it runs
    * the same engine as {@link Yaml.parse} inline.
@@ -311,7 +322,7 @@ declare class Yaml {
    */
   static parseSync(text: string, options?: YamlParseOptions): Result.Result<unknown, YamlParseError>;
   /**
-   * Synchronous stringify, returning a {@link Result} instead of an `Effect`.
+   * Synchronous stringify, returning a `Result` instead of an `Effect`.
    * The pure counterpart to {@link Yaml.stringify} for config-time callers
    * that cannot `await`.
    *
@@ -720,6 +731,17 @@ declare class YamlDocument extends YamlDocument_base {
    * deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
    * — both surface through the typed error channel rather than as an
    * unhandled stack-overflow defect.
+   *
+   * @remarks
+   * `YamlStringifyOptions.lineWidth` is not honored here: column-based
+   * scalar folding exists only on the value path, through the entry points
+   * that accept stringify options ({@link Yaml.stringify} and
+   * {@link Yaml.stringifySync}). The
+   * document/node path threads `lineWidth` into its render context but
+   * never reads it, so long scalars are emitted unfolded regardless of the
+   * option. Callers that need folding should render the plain value
+   * instead — `Yaml.stringify(doc.toValue(), options)` — at the cost of
+   * the document-level framing and styles this path preserves.
    */
   stringify(options?: YamlStringifyOptions): Effect.Effect<string, YamlStringifyError>;
   /**

package/package.json

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