yaml

A small, fully-typed TypeScript library for building YAML documents programmatically, paired with a Semantic Versioning (SemVer) toolkit. Source is shipped directly — no build step, no runtime dependencies.

• Build documents with composable Yaml / Block classes.
• Automatic, round-trip-safe scalar quoting (YAML 1.1 reserved words, numerics, unsafe leading chars).
• Multiline strings emitted as | literal or > folded block scalars with correct chomping/indentation indicators.
• SemVer parse / compare / sort / bump / format utilities.

Install

bun install

Requires Bun and TypeScript 5+ (peer dependency).

Quick start

import {Yaml, bump} from "yamlsmith";

const doc = new Yaml();
doc.set("name", "my-app");
doc.set("version", bump("1.0.0", "patch")); // "1.0.1"
doc.set("tags", ["api", "v2"]);
doc.set("draft", false);

const meta = doc.section("meta"); // nested mapping
meta.set("host", "localhost");
meta.set("port", 8080);

console.log(doc.toString());

Produces:

name: my-app
version: 1.0.1
tags:
  - api
  - v2
draft: false
meta:
  host: localhost
  port: 8080

API

Everything is exported from the package root.

Yaml — a document

A Yaml is an ordered collection of Blocks and nested Yaml documents. The root has no key; a nested one is a mapping under its key.

| Method | Description | |---|---| | new Yaml(key?) | Root document (key omitted) or nested mapping. | | .set(key, value, style?) | Add a key/value pair. Returns this for chaining. | | .add(entry) | Add a pre-built Block or nested Yaml. Returns this. | | .section(key) | Create and return a nested Yaml mapping under key. | | .getKey() | The key this document nests under, or undefined for the root. | | .toYml(depth?) | Serialize to a YAML fragment (no trailing newline). | | .toYaml(explicit?) | Serialize a full document with trailing newline; pass true for the --- start marker. | | .toString() | Alias for .toYaml(). |

Block — a key/value pair

new Block(key, value, style?)

• value may be a scalar (string | number | boolean), a Char, or an array of those.
• Omit style to auto-detect ('literal' for multiline, 'folded' for long single lines, 'default' otherwise). Pass 'literal' or 'folded' to force a block scalar; pass 'default' to force a plain/quoted scalar.
• Unrepresentable block scalars (e.g. containing control characters) fall back to a quoted scalar.

Scalar helpers (tools.ts)

| Export | Purpose | |---|---| | scalar(v) | Render a primitive as a YAML scalar (true/false, .nan/.inf/-.inf, or quoted string). | | quote(s) | Double-quote a string only when a plain scalar would round-trip as the wrong value/type; otherwise return it as-is. | | detectStyle(text) | Pick 'literal' | 'folded' | 'default' for a string value. | | canBlock(s) / canFold(s) | Whether text can be a block scalar / a folded one. | | wrapLine(line, width) | Wrap at single spaces only. | | foldedBody(text, width) | Encode text as a folded block body, or null if ambiguous. |

SemVer toolkit (version.ts)

import {bump, compare, eq, gt, lt, sort, max, parseVersion, tryParse, format, isSemVer}
from "yamlsmith";

| Export | Description | |---|---| | parseVersion(v) | Parse to {major, minor, patch, prerelease?, build?}; throws TypeError if invalid. | | tryParse(v) | Like parseVersion but returns null instead of throwing. | | format(p) | Format a ParsedVersion back into a SemVer string. | | isSemVer(v) | Type guard: is the string valid SemVer? | | compare(a, b) | -1 | 0 | 1 (build metadata ignored for precedence). | | eq / lt / gt | Boolean comparisons built on compare. | | sort(vs) | Return a new sorted array (original untouched). | | max(vs) | The largest version, or undefined for an empty array. | | bump(v, type) | Bump 'major' | 'minor' | 'patch'; returns undefined for an unknown type. Bumping 'patch' on a prerelease drops the prerelease (1.2.3-beta.1 → 1.2.3). |

Char (char.ts)

A branded single-character type:

isChar(s)   // type guard: true when [...s].length === 1 (one code point)
char(s)     // assert s is a single char, throws TypeError otherwise

Development

bun test              # run the test suite
bunx tsc --noEmit     # typecheck

Project layout

index.ts     barrel re-exports
yml.ts       Yaml document class
block.ts     Block key/value class
tools.ts     scalar helpers + block-scalar folding
utils.ts     constants + low-level character checks
version.ts   SemVer toolkit
char.ts      Char branded type
*.test.ts    bun:test suites

This project was created using bun init in bun v1.3.14.