@effected/yaml 0.2.0 → 0.3.0

package/Yaml.js

@@ -4,7 +4,7 @@ import { composeAllDocuments, composeFirstDocument } from "./internal/composer/d
 import { isFatalCode } from "./internal/diagnostics.js";
 import { StringifyDepthExceeded, StringifyFailure, stringifyValue } from "./internal/stringifier.js";
 import { YamlDiagnostic } from "./YamlDiagnostic.js";
-import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { Effect, Option, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 //#region src/Yaml.ts
 /**
@@ -34,11 +34,18 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 }) {};
 /**
 * Options controlling stringify behavior. All fields are omissible; absent
-* fields resolve to `indent` `2`, `lineWidth` `80`, `defaultScalarStyle`
+* fields resolve to `indent` `2`, `lineWidth` `0`, `defaultScalarStyle`
 * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
 * `indentSequences` `false`, `finalNewline` `true` and `forceDefaultStyles`
 * `false`.
 *
+* `lineWidth` controls column-based scalar folding. The default `0` (and any
+* value `<= 0`) never wraps, emitting byte-identical output to the historic
+* 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.
+*
 * `indentSequences` controls the presentation of block sequences nested under
 * a mapping key: `false` (the default) emits them at the key's column — the
 * kit's byte-compatible legacy form — while `true` indents them one level,
@@ -64,6 +71,11 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 */
 var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	indent: Schema.optionalKey(Schema.Number),
+	/**
+	* 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 (`|`).
+	*/
 	lineWidth: Schema.optionalKey(Schema.Number),
 	defaultScalarStyle: Schema.optionalKey(ScalarStyle),
 	defaultCollectionStyle: Schema.optionalKey(CollectionStyle),
@@ -123,6 +135,89 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 };
 const toDiagnostics = (text, records) => records.map((r) => YamlDiagnostic.fromRaw(r, text));
 /**
+* Build the fatal {@link YamlParseError} for an alias-expansion "billion
+* laughs" blow-up. The offending expansion has no source span, so the
+* diagnostic carries zero offsets.
+*/
+const aliasCountExceededError = (message, text) => new YamlParseError({
+	diagnostics: [YamlDiagnostic.make({
+		code: "AliasCountExceeded",
+		message,
+		offset: 0,
+		length: 0,
+		line: 0,
+		character: 0
+	})],
+	input: text
+});
+/**
+* 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.
+*/
+const stringifyDefectToError = (defect, value) => {
+	if (defect instanceof StringifyFailure) return new YamlStringifyError({
+		diagnostics: [YamlDiagnostic.make({
+			code: "CircularReference",
+			message: defect.reason,
+			offset: 0,
+			length: 0,
+			line: 0,
+			character: 0
+		})],
+		value
+	});
+	if (defect instanceof StringifyDepthExceeded) return new YamlStringifyError({
+		diagnostics: [YamlDiagnostic.make({
+			code: "NestingDepthExceeded",
+			message: defect.message,
+			offset: 0,
+			length: 0,
+			line: 0,
+			character: 0
+		})],
+		value
+	});
+};
+/**
+* Synchronous single-document parse returning a {@link 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
+* a `Failure` carrying a typed {@link YamlParseError} — never a throw.
+*/
+const parseSyncImpl = (text, options) => {
+	const doc = composeFirstDocument(text, toParseInput(options));
+	const failures = failureRecords(doc, options?.uniqueKeys ?? true);
+	if (failures.length > 0) return Result.fail(new YamlParseError({
+		diagnostics: toDiagnostics(text, failures),
+		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;
+	}
+};
+/**
+* Synchronous stringify returning a {@link 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.
+*/
+const stringifySyncImpl = (value, options) => {
+	try {
+		return Result.succeed(stringifyValue(value, toStringifyInput(options)));
+	} catch (defect) {
+		const error = stringifyDefectToError(defect, value);
+		if (error !== void 0) return Result.fail(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
 * `uniqueKeys` is in force (the v3 `parse` contract). Order preserved:
@@ -142,45 +237,15 @@ const failureRecords = (doc, uniqueKeys) => {
 const extractDocumentValue = (contents, anchors, maxAliasCount, text) => Effect.try({
 	try: () => nodeToJsValue(contents, anchors, maxAliasCount),
 	catch: (defect) => {
-		if (defect instanceof AliasExpansionBudgetExceeded) return new YamlParseError({
-			diagnostics: [YamlDiagnostic.make({
-				code: "AliasCountExceeded",
-				message: defect.message,
-				offset: 0,
-				length: 0,
-				line: 0,
-				character: 0
-			})],
-			input: text
-		});
+		if (defect instanceof AliasExpansionBudgetExceeded) return aliasCountExceededError(defect.message, text);
 		throw defect;
 	}
 });
 const stringifyOrFail = (value, options) => Effect.try({
 	try: () => stringifyValue(value, 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
-		});
-		if (defect instanceof StringifyDepthExceeded) return new YamlStringifyError({
-			diagnostics: [YamlDiagnostic.make({
-				code: "NestingDepthExceeded",
-				message: defect.message,
-				offset: 0,
-				length: 0,
-				line: 0,
-				character: 0
-			})],
-			value
-		});
+		const error = stringifyDefectToError(defect, value);
+		if (error !== void 0) return error;
 		throw defect;
 	}
 });
@@ -268,6 +333,63 @@ var Yaml = class Yaml {
 		return yield* stringifyOrFail(value, options);
 	});
 	/**
+	* Synchronous single-document parse, returning a {@link 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.
+	*
+	* Preserves the package contract — malformed and adversarial input fails
+	* typed, never as a defect. Fatal diagnostics, duplicate keys and a
+	* "billion laughs" alias-expansion blow-up all yield a `Failure` carrying a
+	* {@link YamlParseError}; the method never throws.
+	*
+	* @example
+	* ```ts
+	* import { Yaml } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = Yaml.parseSync("name: Alice\nage: 30");
+	* if (Result.isSuccess(result)) {
+	*   result.success; // { name: "Alice", age: 30 }
+	* } else {
+	*   result.failure; // YamlParseError
+	* }
+	* ```
+	*
+	* @public
+	*/
+	static parseSync(text, options) {
+		return parseSyncImpl(text, options);
+	}
+	/**
+	* Synchronous stringify, returning a {@link Result} instead of an `Effect`.
+	* 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.
+	*
+	* @example
+	* ```ts
+	* import { Yaml } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = Yaml.stringifySync({ name: "Alice" });
+	* if (Result.isFailure(result)) {
+	*   result.failure; // YamlStringifyError
+	* } else {
+	*   result.success; // "name: Alice\n"
+	* }
+	* ```
+	*
+	* @public
+	*/
+	static stringifySync(value, options) {
+		return stringifySyncImpl(value, options);
+	}
+	/**
 	* Strip comments from YAML text. Without `replaceCh`, comment characters
 	* are removed (line breaks are kept, so line numbers stay stable); with a
 	* `replaceCh` (e.g. `" "`), each comment character is replaced instead,

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Data, Effect, Option, Schema, Stream } from "effect";
+import { Data, Effect, Option, Result, Schema, Stream } from "effect";
 //#region src/YamlDiagnostic.d.ts
 /**
  * Error codes emitted by the lexer stage.
@@ -145,6 +145,11 @@ declare const YamlParseOptions_base: Schema.Class<YamlParseOptions, Schema.Struc
 declare class YamlParseOptions extends YamlParseOptions_base {}
 declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Schema.Struct<{
   readonly indent: Schema.optionalKey<Schema.Number>;
+  /**
+   * 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 (`|`).
+   */
   readonly lineWidth: Schema.optionalKey<Schema.Number>;
   readonly defaultScalarStyle: Schema.optionalKey<Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>>;
   readonly defaultCollectionStyle: Schema.optionalKey<Schema.Literals<readonly ["block", "flow"]>>;
@@ -155,11 +160,18 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
 }>, {}>;
 /**
  * Options controlling stringify behavior. All fields are omissible; absent
- * fields resolve to `indent` `2`, `lineWidth` `80`, `defaultScalarStyle`
+ * fields resolve to `indent` `2`, `lineWidth` `0`, `defaultScalarStyle`
  * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
  * `indentSequences` `false`, `finalNewline` `true` and `forceDefaultStyles`
  * `false`.
  *
+ * `lineWidth` controls column-based scalar folding. The default `0` (and any
+ * value `<= 0`) never wraps, emitting byte-identical output to the historic
+ * 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.
+ *
  * `indentSequences` controls the presentation of block sequences nested under
  * a mapping key: `false` (the default) emits them at the key's column — the
  * kit's byte-compatible legacy form — while `true` indents them one level,
@@ -271,6 +283,59 @@ declare class Yaml {
    * rather than as an unhandled stack-overflow defect.
    */
   static readonly stringify: (value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlStringifyError, never>;
+  /**
+   * Synchronous single-document parse, returning a {@link 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.
+   *
+   * Preserves the package contract — malformed and adversarial input fails
+   * typed, never as a defect. Fatal diagnostics, duplicate keys and a
+   * "billion laughs" alias-expansion blow-up all yield a `Failure` carrying a
+   * {@link YamlParseError}; the method never throws.
+   *
+   * @example
+   * ```ts
+   * import { Yaml } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const result = Yaml.parseSync("name: Alice\nage: 30");
+   * if (Result.isSuccess(result)) {
+   *   result.success; // { name: "Alice", age: 30 }
+   * } else {
+   *   result.failure; // YamlParseError
+   * }
+   * ```
+   *
+   * @public
+   */
+  static parseSync(text: string, options?: YamlParseOptions): Result.Result<unknown, YamlParseError>;
+  /**
+   * Synchronous stringify, returning a {@link Result} instead of an `Effect`.
+   * 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.
+   *
+   * @example
+   * ```ts
+   * import { Yaml } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * const result = Yaml.stringifySync({ name: "Alice" });
+   * if (Result.isFailure(result)) {
+   *   result.failure; // YamlStringifyError
+   * } else {
+   *   result.success; // "name: Alice\n"
+   * }
+   * ```
+   *
+   * @public
+   */
+  static stringifySync(value: unknown, options?: YamlStringifyOptions): Result.Result<string, YamlStringifyError>;
   /**
    * Strip comments from YAML text. Without `replaceCh`, comment characters
    * are removed (line breaks are kept, so line numbers stay stable); with a

package/internal/fold.js

@@ -1,5 +1,90 @@
 //#region src/internal/fold.ts
 /**
+* Column-based line folding for a single logical scalar line (YAML 1.2 flow
+* folding, §7.3 / §8.2.1). Breaks the content at "safe" single-space
+* boundaries — a space whose neighbours are both non-space — so each inserted
+* line break is a *semantically transparent* fold: on read, a lone break
+* between non-empty lines at the same indent folds back to a single space, and
+* the leading indentation of continuation lines is absorbed as separation
+* whitespace. The original space at the break point is consumed, replaced by
+* the break, so no content whitespace is added or lost.
+*
+* Continuation lines are prefixed with `indent`. `indentAtStart` is the column
+* the first line begins at (its content is already `indentAtStart` columns in),
+* used only to budget the first line; it is approximate because the caller's
+* exact column (after a `key: ` prefix, say) is not known here.
+*
+* Only breaks where a break is safe. When no safe break point exists before the
+* width limit, the line overflows unwrapped rather than corrupting the value —
+* width folding is a best-effort presentation concern, never a correctness one.
+* A non-positive `lineWidth` (the default) returns the text unchanged.
+*/
+function foldScalarLine(text, indent, lineWidth, indentAtStart) {
+	if (lineWidth <= 0) return text;
+	const contentWidth = Math.max(1, lineWidth - indent.length);
+	let end = Math.max(1, lineWidth - indentAtStart);
+	const folds = [];
+	let split;
+	let prev;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === " " && prev !== void 0 && prev !== " ") {
+			const next = text[i + 1];
+			if (next !== void 0 && next !== " ") split = i;
+		}
+		if (i >= end && split !== void 0) {
+			folds.push(split);
+			end = split + contentWidth;
+			split = void 0;
+		}
+		prev = ch;
+	}
+	if (folds.length === 0) return text;
+	let result = text.slice(0, folds[0]);
+	for (let f = 0; f < folds.length; f++) {
+		const fold = folds[f];
+		const sliceEnd = folds[f + 1] ?? text.length;
+		result += `\n${indent}${text.slice(fold + 1, sliceEnd)}`;
+	}
+	return result;
+}
+/**
+* Apply {@link foldScalarLine} to an already-rendered scalar according to its
+* style, inferred from the leading character:
+*
+* - `|` block-literal — returned unchanged; literal blocks preserve bytes by
+*   definition and must never be folded.
+* - `>` block-folded — each base-indent body content line is folded; blank
+*   lines and more-indented lines (which the reader treats as literal breaks)
+*   are left untouched.
+* - `"` double-quoted — the inner content is folded; breaking only at content
+*   spaces means no `\`-escaped continuations are needed.
+* - `'` single-quoted — returned unchanged (out of scope for width folding).
+* - otherwise plain — folded directly.
+*
+* `indent` is one indentation level (the continuation prefix); `lineWidth` is
+* the target column. A non-positive `lineWidth` returns the text unchanged.
+*/
+function foldRenderedScalar(rendered, indent, lineWidth) {
+	if (lineWidth <= 0 || rendered.length === 0) return rendered;
+	const first = rendered[0];
+	if (first === "|" || first === "'") return rendered;
+	if (first === ">") {
+		const lines = rendered.split("\n");
+		const out = [lines[0]];
+		for (let i = 1; i < lines.length; i++) {
+			const line = lines[i];
+			if (line.length > indent.length && line.startsWith(indent) && line[indent.length] !== " " && line[indent.length] !== "	") {
+				const content = line.slice(indent.length);
+				out.push(indent + foldScalarLine(content, indent, lineWidth, indent.length));
+			} else out.push(line);
+		}
+		return out.join("\n");
+	}
+	if (first === "\"") return `"${foldScalarLine(rendered.slice(1, -1), indent, lineWidth, indent.length + 1)}"`;
+	return foldScalarLine(rendered, indent, lineWidth, indent.length);
+}
+/**
 * C0 control characters (except TAB) that must be escaped in double-quoted scalars.
 */
 function isControlChar(code) {
@@ -150,4 +235,4 @@ function renderBlockFolded(s, indent) {
 }
 
 //#endregion
-export { hasInteriorTrailingWhitespace, hasNewlineSpacesTab, isControlChar, renderBlockFolded, renderBlockLiteral, renderSingleQuotedMultiline };
+export { foldRenderedScalar, foldScalarLine, hasInteriorTrailingWhitespace, hasNewlineSpacesTab, isControlChar, renderBlockFolded, renderBlockLiteral, renderSingleQuotedMultiline };

package/internal/stringifier.js

@@ -1,5 +1,5 @@
 import { YamlAlias, YamlMap, YamlPair, YamlScalar, YamlSeq } from "../YamlNode.js";
-import { hasInteriorTrailingWhitespace, hasNewlineSpacesTab, isControlChar, renderBlockFolded, renderBlockLiteral, renderSingleQuotedMultiline } from "./fold.js";
+import { foldRenderedScalar, hasInteriorTrailingWhitespace, hasNewlineSpacesTab, isControlChar, renderBlockFolded, renderBlockLiteral, renderSingleQuotedMultiline } from "./fold.js";
 
 //#region src/internal/stringifier.ts
 /**
@@ -252,7 +252,7 @@ function detectCircular(value, seen) {
 function createContext(options) {
 	return {
 		indent: options?.indent ?? 2,
-		lineWidth: options?.lineWidth ?? 80,
+		lineWidth: options?.lineWidth ?? 0,
 		defaultScalarStyle: options?.defaultScalarStyle ?? "plain",
 		defaultCollectionStyle: options?.defaultCollectionStyle ?? "block",
 		sortKeys: options?.sortKeys ?? false,
@@ -268,13 +268,17 @@ function createContext(options) {
 * responsible for prepending the appropriate indentation prefix to each line.
 * This avoids double-indentation when embedding nested collections.
 */
-function stringifyLines(value, ctx, depth) {
+function stringifyLines(value, ctx, depth, allowFold = true) {
 	if (depth > 256) throw new StringifyDepthExceeded();
 	if (value === null || value === void 0) return ["null"];
 	if (typeof value === "boolean") return [value ? "true" : "false"];
 	if (typeof value === "number") return [renderNumber(value)];
 	if (typeof value === "bigint") return [value.toString()];
-	if (typeof value === "string") return renderString(value, ctx.defaultScalarStyle, " ".repeat(ctx.indent), false, ctx.forceDefaultStyles).split("\n");
+	if (typeof value === "string") {
+		const indentStr = " ".repeat(ctx.indent);
+		const rendered = renderString(value, ctx.defaultScalarStyle, indentStr, false, ctx.forceDefaultStyles);
+		return (allowFold && ctx.lineWidth > 0 ? foldRenderedScalar(rendered, indentStr, ctx.lineWidth) : rendered).split("\n");
+	}
 	if (Array.isArray(value)) {
 		detectCircular(value, ctx.seen);
 		ctx.seen.add(value);
@@ -300,7 +304,7 @@ function stringifyLines(value, ctx, depth) {
 */
 function stringifyArrayLines(arr, ctx, depth) {
 	if (arr.length === 0) return ["[]"];
-	if (ctx.defaultCollectionStyle === "flow") return [`[${arr.map((item) => stringifyLines(item, ctx, depth + 1).join(" ")).join(", ")}]`];
+	if (ctx.defaultCollectionStyle === "flow") return [`[${arr.map((item) => stringifyLines(item, ctx, depth + 1, false).join(" ")).join(", ")}]`];
 	const pad = " ".repeat(ctx.indent);
 	const lines = [];
 	for (const item of arr) {
@@ -308,7 +312,7 @@ function stringifyArrayLines(arr, ctx, depth) {
 		if (itemLines.length === 1) lines.push(`- ${itemLines[0]}`);
 		else {
 			const first = itemLines[0];
-			if (first.startsWith("|") || first.startsWith(">")) {
+			if (first.startsWith("|") || first.startsWith(">") || typeof item === "string") {
 				lines.push(`- ${first}`);
 				for (let i = 1; i < itemLines.length; i++) lines.push(itemLines[i]);
 			} else {
@@ -338,7 +342,7 @@ function stringifyObjectLines(obj, ctx, depth) {
 	if (keys.length === 0) return ["{}"];
 	if (ctx.sortKeys) keys.sort();
 	if (ctx.defaultCollectionStyle === "flow") return [`{${keys.map((k) => {
-		return `${renderString(k, "plain", "")}: ${stringifyLines(obj[k], ctx, depth + 1).join(" ")}`;
+		return `${renderString(k, "plain", "")}: ${stringifyLines(obj[k], ctx, depth + 1, false).join(" ")}`;
 	}).join(", ")}}`];
 	const renderKey = (k) => k.includes("\n") ? renderDoubleQuoted(k, ctx.forceDefaultStyles) : renderString(k, "plain", "");
 	const pad = " ".repeat(ctx.indent);
@@ -350,7 +354,7 @@ function stringifyObjectLines(obj, ctx, depth) {
 		if (valLines.length === 1 && !isBlockCollection(val, ctx)) lines.push(`${keyStr}: ${valLines[0]}`);
 		else {
 			const first = valLines[0];
-			if (first.startsWith("|") || first.startsWith(">")) {
+			if (first.startsWith("|") || first.startsWith(">") || typeof val === "string") {
 				lines.push(`${keyStr}: ${first}`);
 				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
 			} else if (Array.isArray(val) && val.length > 0) {

package/package.json

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