@effected/yaml 0.3.1 → 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

@@ -527,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/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

@@ -237,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.
@@ -404,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
@@ -453,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;
 }
@@ -1466,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.1",
+	"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"
     }
   ]
 }