@effected/yaml 0.3.1 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@effected%2Fyaml?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/yaml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
-[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
 Zero-dependency YAML 1.2 parsing, editing and formatting expressed as Effect schemas and pure functions. Parse a single document or a multi-document stream into plain values or an offset-preserving AST, resolve anchors and aliases, strip comments, compute byte-minimal edits, format, modify by path, walk a document as a `Stream` and decode straight into a validated domain schema.
 

package/Yaml.js

@@ -1,4 +1,4 @@
-import { AliasExpansionBudgetExceeded, CollectionStyle, ScalarStyle, nodeToJsValue } from "./YamlNode.js";
+import { AliasExpansionBudgetExceeded, CollectionStyle, QuoteStyle, ScalarStyle, nodeToJsValue } from "./YamlNode.js";
 import { buildAnchorMap } from "./internal/composer/anchors.js";
 import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
 import { isFatalCode } from "./internal/diagnostics.js";
@@ -36,8 +36,8 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * Options controlling stringify behavior. All fields are omissible; absent
 * fields resolve to `indent` `2`, `lineWidth` `0`, `defaultScalarStyle`
 * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
-* `indentSequences` `false`, `finalNewline` `true` and `forceDefaultStyles`
-* `false`.
+* `indentSequences` `false`, `quoteStyle` `"single"`, `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
@@ -54,6 +54,18 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * matching the `yaml` npm package's default output. Top-level sequences stay
 * at column zero in both modes.
 *
+* `quoteStyle` selects the quote character used when a `plain`-styled scalar
+* (the `defaultScalarStyle` default) turns out to require quoting: `"single"`
+* (the default) emits `'@parcel/watcher'` — the kit's byte-compatible legacy
+* form — while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
+* package's `singleQuote: false` output. It is a fallback selector only:
+* scalars that need no quoting stay plain, and an explicit
+* `defaultScalarStyle` of `"single-quoted"` or `"double-quoted"` still wins.
+* On that plain fallback path, values carrying a tab, a carriage return or
+* any other C0 control character are always emitted double-quoted whichever
+* `quoteStyle` is set, since only double quotes can escape them into a form
+* that round-trips exactly.
+*
 * Construct with the validated `YamlStringifyOptions.make({ ... })` static —
 * the kit convention (never `new`). Call sites that take a
 * `YamlStringifyOptions` also accept a structurally-matching plain literal.
@@ -79,7 +91,7 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	* (`>`) 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
+	* {@link Yaml.stringifyResult} — 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
@@ -92,6 +104,17 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	defaultCollectionStyle: Schema.optionalKey(CollectionStyle),
 	sortKeys: Schema.optionalKey(Schema.Boolean),
 	indentSequences: Schema.optionalKey(Schema.Boolean),
+	/**
+	* Quote style used when a `plain`-styled scalar requires quoting. Default
+	* `"single"` — the released byte-compatible behavior. `"double"` renders
+	* the same scalars double-quoted instead, matching the `yaml` npm
+	* package's `singleQuote: false` output.
+	*
+	* Affects only the plain fallback: scalars that need no quoting stay
+	* plain, and an explicit `defaultScalarStyle` of `"single-quoted"` or
+	* `"double-quoted"` is unaffected.
+	*/
+	quoteStyle: Schema.optionalKey(QuoteStyle),
 	finalNewline: Schema.optionalKey(Schema.Boolean),
 	forceDefaultStyles: Schema.optionalKey(Schema.Boolean)
 }) {};
@@ -141,6 +164,7 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	defaultCollectionStyle: options.defaultCollectionStyle,
 	sortKeys: options.sortKeys,
 	indentSequences: options.indentSequences,
+	quoteStyle: options.quoteStyle,
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };
@@ -198,7 +222,7 @@ const stringifyDefectToError = (defect, value) => {
 * 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 parseResultImpl = (text, options) => {
 	const doc = composeFirstDocument(text, toParseInput(options));
 	const failures = failureRecords(doc, options?.uniqueKeys ?? true);
 	if (failures.length > 0) return Result.fail(new YamlParseError({
@@ -219,7 +243,7 @@ const parseSyncImpl = (text, options) => {
 * recursion budget yields a `Failure` carrying a typed {@link YamlStringifyError},
 * never a thrown defect.
 */
-const stringifySyncImpl = (value, options) => {
+const stringifyResultImpl = (value, options) => {
 	try {
 		return Result.succeed(stringifyValue(value, toStringifyInput(options)));
 	} catch (defect) {
@@ -296,17 +320,11 @@ var Yaml = class Yaml {
 	* resolved size grows exponentially relative to `maxAliasCount`) also
 	* fails through {@link YamlParseError} with an `AliasCountExceeded`
 	* diagnostic, never as an unhandled defect.
+	*
+	* Defined in terms of {@link Yaml.parseResult} — synchronous callers can
+	* use that variant directly.
 	*/
-	static parse = Effect.fn("Yaml.parse")(function* (text, options) {
-		const doc = composeFirstDocument(text, toParseInput(options));
-		const failures = failureRecords(doc, options?.uniqueKeys ?? true);
-		if (failures.length > 0) return yield* new YamlParseError({
-			diagnostics: toDiagnostics(text, failures),
-			input: text
-		});
-		const anchors = /* @__PURE__ */ new Map();
-		return yield* extractDocumentValue(doc.contents, anchors, options?.maxAliasCount ?? 100, text);
-	});
+	static parse = Effect.fn("Yaml.parse")((text, options) => Effect.fromResult(Yaml.parseResult(text, options)));
 	/**
 	* Parse a multi-document YAML stream into an array of plain JavaScript
 	* values (one per document, in order). Any fatal diagnostic in any
@@ -339,6 +357,15 @@ var Yaml = class Yaml {
 	* 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.
+	*
+	* @remarks
+	* A `"<<"` object key is emitted **quoted** (`'<<': …`). This is the
+	* opposite of the document path ({@link YamlFormat.format} and
+	* `YamlDocument#stringify`), which leaves a parsed plain `<<` key unquoted
+	* so it keeps its merge-key meaning, and the asymmetry is deliberate: a
+	* `"<<"` key on a plain JavaScript object is an ordinary string key that
+	* never carried merge semantics, so emitting it plain would silently turn
+	* ordinary data into a merge directive.
 	*/
 	static stringify = Effect.fn("Yaml.stringify")(function* (value, options) {
 		return yield* stringifyOrFail(value, options);
@@ -346,8 +373,14 @@ var Yaml = class Yaml {
 	/**
 	* 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.
+	* `await` an Effect (a `vitest.config.ts` is the motivating case).
+	*
+	* @remarks
+	* This is the package's single parse path. {@link Yaml.parse} is defined in
+	* terms of it (`Effect.fromResult` behind the named span), so the two
+	* variants cannot diverge. Reach for the `Effect` variant inside Effect
+	* code — it carries the `Yaml.parse` tracing span — and for this one at
+	* synchronous boundaries.
 	*
 	* Preserves the package contract — malformed and adversarial input fails
 	* typed, never as a defect. Fatal diagnostics, duplicate keys and a
@@ -359,7 +392,7 @@ var Yaml = class Yaml {
 	* import { Yaml } from "@effected/yaml";
 	* import { Result } from "effect";
 	*
-	* const result = Yaml.parseSync("name: Alice\nage: 30");
+	* const result = Yaml.parseResult("name: Alice\nage: 30");
 	* if (Result.isSuccess(result)) {
 	*   result.success; // { name: "Alice", age: 30 }
 	* } else {
@@ -369,8 +402,8 @@ var Yaml = class Yaml {
 	*
 	* @public
 	*/
-	static parseSync(text, options) {
-		return parseSyncImpl(text, options);
+	static parseResult(text, options) {
+		return parseResultImpl(text, options);
 	}
 	/**
 	* Synchronous stringify, returning a `Result` instead of an `Effect`.
@@ -387,7 +420,7 @@ var Yaml = class Yaml {
 	* import { Yaml } from "@effected/yaml";
 	* import { Result } from "effect";
 	*
-	* const result = Yaml.stringifySync({ name: "Alice" });
+	* const result = Yaml.stringifyResult({ name: "Alice" });
 	* if (Result.isFailure(result)) {
 	*   result.failure; // YamlStringifyError
 	* } else {
@@ -397,8 +430,8 @@ var Yaml = class Yaml {
 	*
 	* @public
 	*/
-	static stringifySync(value, options) {
-		return stringifySyncImpl(value, options);
+	static stringifyResult(value, options) {
+		return stringifyResultImpl(value, options);
 	}
 	/**
 	* Strip comments from YAML text. Without `replaceCh`, comment characters
@@ -527,6 +560,51 @@ var Yaml = class Yaml {
 	static schema(target, options) {
 		return Yaml.fromString(options).pipe(Schema.decodeTo(target));
 	}
+	/**
+	* Bind a target schema to the YAML codec once, yielding the composed
+	* schema plus pre-derived `decode`/`encode` directions — the
+	* {@link Yaml.schema} composition without the generic `Schema` machinery
+	* at every use site. Binds the plain single-document form only: default
+	* {@link YamlParseOptions} on decode, default stringify options on encode;
+	* for multi-document streams compose over {@link Yaml.allFromString}
+	* directly.
+	*
+	* Both directions fail with `Schema.SchemaError`, exactly as
+	* `Schema.decodeEffect`/`Schema.encodeEffect` over {@link Yaml.schema}
+	* would; the target's decoding/encoding service requirements flow through.
+	*
+	* @remarks
+	* Schema-producing: each call composes a fresh schema and derives both
+	* directions from it. Bind the result to a `const` — that single binding is
+	* the point.
+	*
+	* @example
+	* ```ts
+	* import { Yaml } from "@effected/yaml";
+	* import { Effect, Schema } from "effect";
+	*
+	* const Config = Schema.Struct({ port: Schema.Number });
+	* const config = Yaml.bind(Config);
+	*
+	* const program = Effect.gen(function* () {
+	*   const value = yield* config.decode("port: 3000");
+	*   const text = yield* config.encode(value);
+	*   return [value, text] as const;
+	* });
+	* ```
+	*
+	* @param target - The domain schema decoded values must satisfy.
+	* @returns A {@link YamlBoundCodec} carrying the composed schema and its
+	*   two pre-bound directions.
+	*/
+	static bind(target) {
+		const schema = Yaml.schema(target);
+		return {
+			schema,
+			decode: Schema.decodeEffect(schema),
+			encode: Schema.encodeEffect(schema)
+		};
+	}
 };
 /**
 * Parse for `equals`/`equalsValue`: any recorded error — fatal or not — or a

package/YamlDocument.js

@@ -96,7 +96,7 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* `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
+	* {@link Yaml.stringifyResult}). 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

package/YamlEdit.js

@@ -31,10 +31,16 @@ var YamlEdit = class extends Schema.Class("YamlEdit")({
 	/**
 	* Apply `edits` to `text`, producing a new string. Edits are applied in
 	* reverse-offset order so earlier offsets stay valid; the input `edits`
-	* array is not mutated. Pure and total.
+	* array is not mutated. Overlapping edits are a programmer error and throw
+	* as a defect — `YamlFormat` never produces them.
 	*/
 	static applyAll(text, edits) {
 		const sorted = [...edits].sort((a, b) => b.offset - a.offset);
+		for (let i = 0; i + 1 < sorted.length; i++) {
+			const upper = sorted[i];
+			const lower = sorted[i + 1];
+			if (lower.offset + lower.length > upper.offset) throw new Error(`YamlEdit.applyAll received overlapping edits at offsets ${lower.offset} and ${upper.offset} — overlapping edits are a programmer error`);
+		}
 		let result = text;
 		for (const edit of sorted) result = result.substring(0, edit.offset) + edit.content + result.substring(edit.offset + edit.length);
 		return result;

package/YamlFormat.js

@@ -11,7 +11,8 @@ import { Effect, Schema } from "effect";
 //#region src/YamlFormat.ts
 /**
 * Options controlling formatting behavior: every {@link YamlStringifyOptions}
-* field (derived, not hand-duplicated — including `indentSequences`) plus
+* field (derived, not hand-duplicated — including `indentSequences` and
+* `quoteStyle`) plus
 * `preserveComments` (default `true`) and `range` (restrict edits to a
 * region; see the module-level remarks on the `range` parameter vs. this
 * field).
@@ -78,6 +79,7 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	defaultCollectionStyle: options.defaultCollectionStyle,
 	sortKeys: options.sortKeys,
 	indentSequences: options.indentSequences,
+	quoteStyle: options.quoteStyle,
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };
@@ -251,6 +253,14 @@ var YamlFormat = class YamlFormat {
 	* `options?.range` when both are given; either accepts a plain
 	* `{ offset, length }` object as well as a {@link YamlRange} instance, so
 	* callers do not need `YamlRange.make(...)` for the common case.
+	*
+	* A plain `<<` mapping key is preserved unquoted, keeping its merge-key
+	* meaning (`tag:yaml.org,2002:merge`) — quoting it to `'<<'` would produce
+	* an ordinary string key that merges nothing, changing what the document
+	* means with no error raised. A key the author quoted explicitly keeps its
+	* quotes, since that is a literal string key they wrote deliberately. Note
+	* that {@link Yaml.stringify} is deliberately the other way round for a
+	* `"<<"` key on a plain JavaScript object.
 	*/
 	static format(text, range, options) {
 		const formatted = formatDocument(text, options);

package/YamlNode.js

@@ -20,6 +20,16 @@ const ScalarStyle = Schema.Literals([
 */
 const CollectionStyle = Schema.Literals(["block", "flow"]);
 /**
+* 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
+* quoting. Referenced by the `quoteStyle` field of `YamlStringifyOptions`;
+* unlike `ScalarStyle` it is a stringify-option vocabulary, never a property
+* of a composed node.
+*
+* @public
+*/
+const QuoteStyle = Schema.Literals(["single", "double"]);
+/**
 * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
 * Referenced by the {@link YamlScalar} `chomp` field schema.
 *
@@ -393,4 +403,4 @@ function nodeToValue(node, anchors, budget, counting = false) {
 }
 
 //#endregion
-export { AliasExpansionBudgetExceeded, CollectionStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq, aliasExpansionLimit, nodeToJsValue };
+export { AliasExpansionBudgetExceeded, CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq, aliasExpansionLimit, nodeToJsValue };

package/index.d.ts

@@ -151,7 +151,7 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
    * (`>`) 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
+   * {@link Yaml.stringifyResult} — 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
@@ -164,6 +164,17 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
   readonly defaultCollectionStyle: Schema.optionalKey<Schema.Literals<readonly ["block", "flow"]>>;
   readonly sortKeys: Schema.optionalKey<Schema.Boolean>;
   readonly indentSequences: Schema.optionalKey<Schema.Boolean>;
+  /**
+   * Quote style used when a `plain`-styled scalar requires quoting. Default
+   * `"single"` — the released byte-compatible behavior. `"double"` renders
+   * the same scalars double-quoted instead, matching the `yaml` npm
+   * package's `singleQuote: false` output.
+   *
+   * Affects only the plain fallback: scalars that need no quoting stay
+   * plain, and an explicit `defaultScalarStyle` of `"single-quoted"` or
+   * `"double-quoted"` is unaffected.
+   */
+  readonly quoteStyle: Schema.optionalKey<Schema.Literals<readonly ["single", "double"]>>;
   readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
   readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
@@ -171,8 +182,8 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * Options controlling stringify behavior. All fields are omissible; absent
  * fields resolve to `indent` `2`, `lineWidth` `0`, `defaultScalarStyle`
  * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
- * `indentSequences` `false`, `finalNewline` `true` and `forceDefaultStyles`
- * `false`.
+ * `indentSequences` `false`, `quoteStyle` `"single"`, `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
@@ -189,6 +200,18 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * matching the `yaml` npm package's default output. Top-level sequences stay
  * at column zero in both modes.
  *
+ * `quoteStyle` selects the quote character used when a `plain`-styled scalar
+ * (the `defaultScalarStyle` default) turns out to require quoting: `"single"`
+ * (the default) emits `'@parcel/watcher'` — the kit's byte-compatible legacy
+ * form — while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
+ * package's `singleQuote: false` output. It is a fallback selector only:
+ * scalars that need no quoting stay plain, and an explicit
+ * `defaultScalarStyle` of `"single-quoted"` or `"double-quoted"` still wins.
+ * On that plain fallback path, values carrying a tab, a carriage return or
+ * any other C0 control character are always emitted double-quoted whichever
+ * `quoteStyle` is set, since only double quotes can escape them into a form
+ * that round-trips exactly.
+ *
  * Construct with the validated `YamlStringifyOptions.make({ ... })` static —
  * the kit convention (never `new`). Call sites that take a
  * `YamlStringifyOptions` also accept a structurally-matching plain literal.
@@ -237,6 +260,22 @@ declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.T
 declare class YamlStringifyError extends YamlStringifyError_base {
   get message(): string;
 }
+/**
+ * A domain codec pre-bound to its two directions, returned by
+ * {@link Yaml.bind}: the composed `schema` (what {@link Yaml.schema} returns)
+ * plus `decode` and `encode` functions derived from it once, so callers need
+ * no generic `Schema` machinery at the use site.
+ *
+ * @public
+ */
+interface YamlBoundCodec<T, RD = never, RE = never> {
+  /** The composed codec decoding a YAML `string` straight into `T`. */
+  readonly schema: Schema.Codec<T, string, RD, RE>;
+  /** Decode a single-document YAML string into a validated `T`. */
+  readonly decode: (text: string) => Effect.Effect<T, Schema.SchemaError, RD>;
+  /** Encode a `T` back to YAML text with default stringify options. */
+  readonly encode: (value: T) => Effect.Effect<string, Schema.SchemaError, RE>;
+}
 /**
  * Static entry points for YAML parsing, stringification, comment stripping,
  * semantic equality and the schema factories. Not instantiable.
@@ -273,6 +312,9 @@ declare class Yaml {
    * resolved size grows exponentially relative to `maxAliasCount`) also
    * fails through {@link YamlParseError} with an `AliasCountExceeded`
    * diagnostic, never as an unhandled defect.
+   *
+   * Defined in terms of {@link Yaml.parseResult} — synchronous callers can
+   * use that variant directly.
    */
   static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<unknown, YamlParseError, never>;
   /**
@@ -292,13 +334,28 @@ declare class Yaml {
    * 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.
+   *
+   * @remarks
+   * A `"<<"` object key is emitted **quoted** (`'<<': …`). This is the
+   * opposite of the document path ({@link YamlFormat.format} and
+   * `YamlDocument#stringify`), which leaves a parsed plain `<<` key unquoted
+   * so it keeps its merge-key meaning, and the asymmetry is deliberate: a
+   * `"<<"` key on a plain JavaScript object is an ordinary string key that
+   * never carried merge semantics, so emitting it plain would silently turn
+   * ordinary data into a merge directive.
    */
   static readonly stringify: (value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlStringifyError, never>;
   /**
    * 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.
+   * `await` an Effect (a `vitest.config.ts` is the motivating case).
+   *
+   * @remarks
+   * This is the package's single parse path. {@link Yaml.parse} is defined in
+   * terms of it (`Effect.fromResult` behind the named span), so the two
+   * variants cannot diverge. Reach for the `Effect` variant inside Effect
+   * code — it carries the `Yaml.parse` tracing span — and for this one at
+   * synchronous boundaries.
    *
    * Preserves the package contract — malformed and adversarial input fails
    * typed, never as a defect. Fatal diagnostics, duplicate keys and a
@@ -310,7 +367,7 @@ declare class Yaml {
    * import { Yaml } from "@effected/yaml";
    * import { Result } from "effect";
    *
-   * const result = Yaml.parseSync("name: Alice\nage: 30");
+   * const result = Yaml.parseResult("name: Alice\nage: 30");
    * if (Result.isSuccess(result)) {
    *   result.success; // { name: "Alice", age: 30 }
    * } else {
@@ -320,7 +377,7 @@ declare class Yaml {
    *
    * @public
    */
-  static parseSync(text: string, options?: YamlParseOptions): Result.Result<unknown, YamlParseError>;
+  static parseResult(text: string, options?: YamlParseOptions): Result.Result<unknown, YamlParseError>;
   /**
    * Synchronous stringify, returning a `Result` instead of an `Effect`.
    * The pure counterpart to {@link Yaml.stringify} for config-time callers
@@ -336,7 +393,7 @@ declare class Yaml {
    * import { Yaml } from "@effected/yaml";
    * import { Result } from "effect";
    *
-   * const result = Yaml.stringifySync({ name: "Alice" });
+   * const result = Yaml.stringifyResult({ name: "Alice" });
    * if (Result.isFailure(result)) {
    *   result.failure; // YamlStringifyError
    * } else {
@@ -346,7 +403,7 @@ declare class Yaml {
    *
    * @public
    */
-  static stringifySync(value: unknown, options?: YamlStringifyOptions): Result.Result<string, YamlStringifyError>;
+  static stringifyResult(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
@@ -404,6 +461,44 @@ declare class Yaml {
    * {@link Yaml.fromString}).
    */
   static schema<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>, options?: YamlParseOptions): Schema.Codec<T, string, RD, RE>;
+  /**
+   * Bind a target schema to the YAML codec once, yielding the composed
+   * schema plus pre-derived `decode`/`encode` directions — the
+   * {@link Yaml.schema} composition without the generic `Schema` machinery
+   * at every use site. Binds the plain single-document form only: default
+   * {@link YamlParseOptions} on decode, default stringify options on encode;
+   * for multi-document streams compose over {@link Yaml.allFromString}
+   * directly.
+   *
+   * Both directions fail with `Schema.SchemaError`, exactly as
+   * `Schema.decodeEffect`/`Schema.encodeEffect` over {@link Yaml.schema}
+   * would; the target's decoding/encoding service requirements flow through.
+   *
+   * @remarks
+   * Schema-producing: each call composes a fresh schema and derives both
+   * directions from it. Bind the result to a `const` — that single binding is
+   * the point.
+   *
+   * @example
+   * ```ts
+   * import { Yaml } from "@effected/yaml";
+   * import { Effect, Schema } from "effect";
+   *
+   * const Config = Schema.Struct({ port: Schema.Number });
+   * const config = Yaml.bind(Config);
+   *
+   * const program = Effect.gen(function* () {
+   *   const value = yield* config.decode("port: 3000");
+   *   const text = yield* config.encode(value);
+   *   return [value, text] as const;
+   * });
+   * ```
+   *
+   * @param target - The domain schema decoded values must satisfy.
+   * @returns A {@link YamlBoundCodec} carrying the composed schema and its
+   *   two pre-bound directions.
+   */
+  static bind<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>): YamlBoundCodec<T, RD, RE>;
 }
 //#endregion
 //#region src/YamlEdit.d.ts
@@ -453,7 +548,8 @@ 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`
-   * array is not mutated. Pure and total.
+   * array is not mutated. Overlapping edits are a programmer error and throw
+   * as a defect — `YamlFormat` never produces them.
    */
   static applyAll(text: string, edits: ReadonlyArray<YamlEdit>): string;
 }
@@ -483,6 +579,22 @@ declare const CollectionStyle: Schema.Literals<readonly ["block", "flow"]>;
  * @public
  */
 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
+ * quoting. Referenced by the `quoteStyle` field of `YamlStringifyOptions`;
+ * unlike `ScalarStyle` it is a stringify-option vocabulary, never a property
+ * of a composed node.
+ *
+ * @public
+ */
+declare const QuoteStyle: Schema.Literals<readonly ["single", "double"]>;
+/**
+ * The union of all fallback quote style string literals.
+ *
+ * @public
+ */
+type QuoteStyle = typeof QuoteStyle.Type;
 /**
  * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
  * Referenced by the {@link YamlScalar} `chomp` field schema.
@@ -736,7 +848,7 @@ declare class YamlDocument extends YamlDocument_base {
    * `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
+   * {@link Yaml.stringifyResult}). 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
@@ -771,6 +883,7 @@ declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Sc
   readonly defaultCollectionStyle: Schema.optionalKey<Schema.Literals<readonly ["block", "flow"]>>;
   readonly sortKeys: Schema.optionalKey<Schema.Boolean>;
   readonly indentSequences: Schema.optionalKey<Schema.Boolean>;
+  readonly quoteStyle: Schema.optionalKey<Schema.Literals<readonly ["single", "double"]>>;
   readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
   readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
   readonly preserveComments: Schema.optionalKey<Schema.Boolean>;
@@ -778,7 +891,8 @@ declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Sc
 }>, {}>;
 /**
  * Options controlling formatting behavior: every {@link YamlStringifyOptions}
- * field (derived, not hand-duplicated — including `indentSequences`) plus
+ * field (derived, not hand-duplicated — including `indentSequences` and
+ * `quoteStyle`) plus
  * `preserveComments` (default `true`) and `range` (restrict edits to a
  * region; see the module-level remarks on the `range` parameter vs. this
  * field).
@@ -843,6 +957,14 @@ declare class YamlFormat {
    * `options?.range` when both are given; either accepts a plain
    * `{ offset, length }` object as well as a {@link YamlRange} instance, so
    * callers do not need `YamlRange.make(...)` for the common case.
+   *
+   * A plain `<<` mapping key is preserved unquoted, keeping its merge-key
+   * meaning (`tag:yaml.org,2002:merge`) — quoting it to `'<<'` would produce
+   * an ordinary string key that merges nothing, changing what the document
+   * means with no error raised. A key the author quoted explicitly keeps its
+   * quotes, since that is a literal string key they wrote deliberately. Note
+   * that {@link Yaml.stringify} is deliberately the other way round for a
+   * `"<<"` key on a plain JavaScript object.
    */
   static format(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): ReadonlyArray<YamlEdit>;
   /**
@@ -1466,5 +1588,5 @@ declare class YamlVisitor {
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }
 //#endregion
-export { CollectionStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, YamlScalar, type YamlSegment, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };
+export { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, type YamlBoundCodec, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, YamlScalar, type YamlSegment, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,4 @@
-import { CollectionStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
+import { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
 import { YamlComposerErrorCode, YamlDiagnostic, YamlErrorCode, YamlLexErrorCode, YamlModifyErrorCode, YamlParseErrorCode, YamlStringifyErrorCode } from "./YamlDiagnostic.js";
 import { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions } from "./Yaml.js";
 import { YamlDirective, YamlDocument } from "./YamlDocument.js";
@@ -6,4 +6,4 @@ import { YamlEdit, YamlRange } from "./YamlEdit.js";
 import { YamlFormat, YamlFormattingOptions, YamlModificationError } from "./YamlFormat.js";
 import { YamlVisitor, YamlVisitorEvent } from "./YamlVisitor.js";
 
-export { CollectionStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, YamlRange, YamlScalar, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };
+export { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, YamlRange, YamlScalar, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };

package/internal/stringifier.js

@@ -107,7 +107,10 @@ function requiresQuoting(s, ignoreType = false) {
 	if (s.includes(" #") || s.includes("	#")) return true;
 	const last = s[s.length - 1];
 	if (last === " " || last === "	") return true;
-	for (let i = 0; i < s.length; i++) if (isControlChar(s.charCodeAt(i))) return true;
+	for (let i = 0; i < s.length; i++) {
+		const code = s.charCodeAt(i);
+		if (code === 9 || code === 13 || isControlChar(code)) return true;
+	}
 	return false;
 }
 /**
@@ -164,11 +167,13 @@ function renderSingleQuoted(s) {
 *
 * Multi-line strings are routed to block styles regardless of the requested
 * style (except double-quoted). For single-line strings, plain style delegates
-* to {@link requiresQuoting} and falls back to double-quoted when the value
-* would be ambiguous. Block literal and block folded styles are always
-* accepted for single-line strings even though the output is unusual.
+* to {@link requiresQuoting} and falls back to `quoteStyle` (single-quoted by
+* default, double-quoted when the caller asked for it) — or to double-quoted
+* regardless when the value needs YAML escapes single quotes cannot express.
+* Block literal and block folded styles are always accepted for single-line
+* strings even though the output is unusual.
 */
-function renderString(s, style, indent, ignoreType = false, canonical = false, explicitChomp, parentPosition) {
+function renderString(s, style, indent, ignoreType = false, canonical = false, explicitChomp, parentPosition, quoteStyle = "single") {
 	if (s.includes("\n")) {
 		let hasControl = false;
 		for (let i = 0; i < s.length; i++) {
@@ -202,7 +207,7 @@ function renderString(s, style, indent, ignoreType = false, canonical = false, e
 			if (requiresQuoting(s, ignoreType)) {
 				if (s.includes("	") || s.includes("\r")) return renderDoubleQuoted(s, canonical);
 				for (let i = 0; i < s.length; i++) if (isControlChar(s.charCodeAt(i))) return renderDoubleQuoted(s, canonical);
-				return renderSingleQuoted(s);
+				return quoteStyle === "double" ? renderDoubleQuoted(s, canonical) : renderSingleQuoted(s);
 			}
 			return s;
 		case "single-quoted": return renderSingleQuoted(s);
@@ -257,6 +262,7 @@ function createContext(options) {
 		defaultCollectionStyle: options?.defaultCollectionStyle ?? "block",
 		sortKeys: options?.sortKeys ?? false,
 		indentSequences: options?.indentSequences ?? false,
+		quoteStyle: options?.quoteStyle ?? "single",
 		forceDefaultStyles: options?.forceDefaultStyles ?? false,
 		seen: /* @__PURE__ */ new Set()
 	};
@@ -276,7 +282,7 @@ function stringifyLines(value, ctx, depth, allowFold = true) {
 	if (typeof value === "bigint") return [value.toString()];
 	if (typeof value === "string") {
 		const indentStr = " ".repeat(ctx.indent);
-		const rendered = renderString(value, ctx.defaultScalarStyle, indentStr, false, ctx.forceDefaultStyles);
+		const rendered = renderString(value, ctx.defaultScalarStyle, indentStr, false, ctx.forceDefaultStyles, void 0, void 0, ctx.quoteStyle);
 		return (allowFold && ctx.lineWidth > 0 ? foldRenderedScalar(rendered, indentStr, ctx.lineWidth) : rendered).split("\n");
 	}
 	if (Array.isArray(value)) {
@@ -341,10 +347,11 @@ function stringifyObjectLines(obj, ctx, depth) {
 	const keys = Object.keys(obj);
 	if (keys.length === 0) return ["{}"];
 	if (ctx.sortKeys) keys.sort();
+	const renderPlainKey = (k) => renderString(k, "plain", "", false, false, void 0, void 0, ctx.quoteStyle);
 	if (ctx.defaultCollectionStyle === "flow") return [`{${keys.map((k) => {
-		return `${renderString(k, "plain", "")}: ${stringifyLines(obj[k], ctx, depth + 1, false).join(" ")}`;
+		return `${renderPlainKey(k)}: ${stringifyLines(obj[k], ctx, depth + 1, false).join(" ")}`;
 	}).join(", ")}}`];
-	const renderKey = (k) => k.includes("\n") ? renderDoubleQuoted(k, ctx.forceDefaultStyles) : renderString(k, "plain", "");
+	const renderKey = (k) => k.includes("\n") ? renderDoubleQuoted(k, ctx.forceDefaultStyles) : renderPlainKey(k);
 	const pad = " ".repeat(ctx.indent);
 	const lines = [];
 	for (const k of keys) {
@@ -531,12 +538,45 @@ function stringifyScalarNodeLines(node, ctx) {
 	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).split("\n");
+	else if (typeof val === "string") lines = renderString(val, style, " ".repeat(ctx.indent), !!node.tag, ctx.forceDefaultStyles, node.chomp, ctx.parentPosition, ctx.quoteStyle).split("\n");
 	else lines = [renderDoubleQuoted(String(val))];
 	if (node.tag) lines[0] = `${node.tag} ${lines[0]}`;
 	if (node.anchor) lines[0] = `&${node.anchor} ${lines[0]}`;
 	return lines;
 }
+/** The YAML merge key. */
+const MERGE_KEY = "<<";
+/**
+* True when a mapping key must be emitted plain because quoting it would
+* change what the document means.
+*
+* The merge key is the only scalar in this position where the plain and
+* quoted forms resolve to different YAML types: a plain `<<` key resolves to
+* `tag:yaml.org,2002:merge` and splices the aliased mapping into its parent,
+* while `'<<'` is an ordinary string key that merges nothing. The difference
+* is silent — the document still parses and still round-trips — so re-emitting
+* a merge key quoted is a semantic rewrite of the kind the fidelity obligation
+* forbids.
+*
+* Deliberately narrow. It fires only on a plain-styled scalar carrying no tag
+* and no anchor, so an author's explicitly quoted `'<<'` (a literal string key
+* they meant) and any tagged key keep the form they were written in. A key
+* with no style at all counts as plain: an unstyled `<<` built by hand can
+* only have been meant as a merge key, and preserving that meaning outranks
+* normalizing its presentation.
+*/
+function isPlainMergeKey(node) {
+	return node instanceof YamlScalar && node.value === MERGE_KEY && (node.style ?? "plain") === "plain" && node.tag === void 0 && node.anchor === void 0;
+}
+/**
+* Renders a mapping key, honoring the keys that must stay plain before
+* falling back to ordinary node rendering. Both the flow and the block
+* mapping branches route through here so the two cannot disagree.
+*/
+function stringifyMappingKeyLines(node, ctx, depth) {
+	if (isPlainMergeKey(node)) return [MERGE_KEY];
+	return stringifyNodeLines(node, ctx, depth);
+}
 /**
 * Stringifies a YamlMap node into lines, using the node's collection style.
 */
@@ -556,7 +596,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 	}
 	if (style === "flow") {
 		let line = `{${items.map((pair) => {
-			return `${pair.key ? stringifyNodeLines(pair.key, ctx, depth + 1).join(" ") : "null"}: ${pair.value ? stringifyNodeLines(pair.value, ctx, depth + 1).join(" ") : "null"}`;
+			return `${pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null"}: ${pair.value ? stringifyNodeLines(pair.value, ctx, depth + 1).join(" ") : "null"}`;
 		}).join(", ")}}`;
 		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
 		if (flowPrefix) line = `${flowPrefix} ${line}`;
@@ -603,7 +643,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 		}
 		let resolvedKeyStr;
 		if (ctx.forceDefaultStyles && node.style === "flow" && node.sourceMultiline !== true && pair.key instanceof YamlScalar && (pair.key.style === "single-quoted" || pair.key.style === "double-quoted") && typeof pair.key.value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(pair.key.value)) resolvedKeyStr = pair.key.value;
-		else resolvedKeyStr = pair.key ? stringifyNodeLines(pair.key, ctx, depth + 1).join(" ") : "null";
+		else resolvedKeyStr = pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null";
 		const keyStr = resolvedKeyStr;
 		const keyIsAnchoredOrTaggedEmpty = pair.key instanceof YamlScalar && pair.key.length === 0 && (pair.key.value === null || pair.key.value === void 0 || pair.key.value === "") && (pair.key.anchor !== void 0 || pair.key.tag !== void 0);
 		const sep = pair.key instanceof YamlAlias || keyIsAnchoredOrTaggedEmpty ? " :" : ":";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing and formatting as Effect schemas.",
 	"keywords": [
@@ -34,12 +34,13 @@
 	"exports": {
 		".": {
 			"types": "./index.d.ts",
-			"import": "./index.js"
+			"import": "./index.js",
+			"default": "./index.js"
 		},
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-beta.98"
+		"effect": "4.0.0-beta.99"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.10"
+      "packageVersion": "7.58.11"
     }
   ]
 }