yaml-effect

yaml-effect

A pure Effect-based YAML 1.2 parser, stringifier, and toolkit for TypeScript. Zero runtime dependencies beyond Effect — no wrappers, no ports, just a clean-room YAML 1.2 implementation designed for the Effect ecosystem.

Features

• Parse and stringify YAML 1.2 with typed errors via Effect
• Bidirectional Effect Schema integration for validated YAML-to-domain roundtrips
• Non-destructive formatting, path-based modification, and semantic equality
• Stream-based lexer, CST parser, and visitor APIs for low-level processing
• Pipeline-friendly dual-style APIs (direct and pipe)

Why does this module exist?

If you just need to parse YAML into a JavaScript object, use yaml. It is depended upon by 13,000+ packages, is battle-tested, and covers the full YAML 1.2 specification.

This library is for Effect-based programs that need deeper introspection and manipulation of YAML documents: typed parse errors you can catchTag, Schema pipelines that validate YAML strings into domain types, AST and CST access, non-destructive formatting and path-based modification, semantic equality comparisons, and SAX-style visitor streams that are composable in Effect pipelines.

Spec Compliance

yaml-effect passes 100% of the official yaml-test-suite (1226 of 1226 assertions). Every assertion in the suite is exercised, with no skipped tests and no expected failures, across all four assertion families:

• Parse-success and parse-rejection (correct accept/reject behavior)
• JSON equivalence of parsed values
• Canonical-output byte-equality against libyaml's reference emitter
• Stringify roundtrip (parse(stringify(parse(x))) === parse(x))

This reflects YAML 1.2 spec compliance as exercised by the yaml-test-suite. It is not a formal certification, and "spec-correct" should not be read as "production hardened" — see the maturity note below.

Status and Maturity

yaml-effect is pre-1.0. While the library is spec-correct against the yaml-test-suite, a 1.0.0 release is intentionally being deferred. Expect the following before stabilization:

• Expanded test coverage. The regression corpus will grow beyond the official yaml-test-suite — additional parser fuzzing, real-world fixtures (CI configs, lockfiles, k8s manifests), and adversarial inputs.
• Performance work. The parser, composer, and stringifier have not been micro-benchmarked or hot-path optimized. Internal data structures and algorithms may change for throughput and memory.
• API surface evolution. Likely additions include incremental and streaming parse APIs, deeper Effect Schema integration, and more ergonomic format and modify helpers.
• Breaking changes between minor versions. Until 1.0.0 ships, breaking changes may land between 0.x and 0.y, not just at major version boundaries. Pin to an exact version (or a tight range) and review CHANGELOG.md before upgrading.

Installation

npm install yaml-effect effect

Peer dependency: effect (>= 3.x) must be installed alongside yaml-effect.

Quick Start

import { Effect } from "effect";
import { parse, stringify } from "yaml-effect";

const program = Effect.gen(function* () {
  const value = yield* parse("name: Alice\nage: 30");
  console.log(value); // { name: "Alice", age: 30 }

  const yaml = yield* stringify({ greeting: "hello", count: 42 });
  console.log(yaml); // "greeting: hello\ncount: 42\n"
});

Effect.runSync(program);

Documentation

For API reference, configuration options, and advanced usage, see docs.

License

MIT