@effected/yaml 0.3.0 → 0.4.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

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

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

package/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/index.d.ts

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

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.3.0",
+	"version": "0.4.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"
     }
   ]
 }