@effected/yaml 0.4.0 → 0.5.0

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

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/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.
@@ -289,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>;
   /**
@@ -308,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
@@ -326,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 {
@@ -336,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
@@ -352,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 {
@@ -362,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
@@ -538,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.
@@ -791,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
@@ -826,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>;
@@ -833,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).
@@ -898,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>;
   /**
@@ -1521,5 +1588,5 @@ declare class YamlVisitor {
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }
 //#endregion
-export { CollectionStyle, 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 };
+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.4.0",
+	"version": "0.5.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing and formatting as Effect schemas.",
 	"keywords": [