Skip to main content
@ooneex/yml reads YAML files lazily through an async generator instead of loading the whole file into memory. It handles both multi-document files (--- separators) and top-level array files (- items), supports per-field ignore filters, and can export the parsed stream straight to JSON or CSV. It is built on Bun’s native YAML support, so it runs in the Bun runtime.

​
Installation

Add the package with Bun. 
bun add @ooneex/yml

​
Usage

Create a Yaml instance pointing at a file, then iterate its load() generator. Each yielded value is one document (or one array item) from the file. 
import { Yaml } from "@ooneex/yml";

type User = { id: number; name: string; role: string };

const yaml = new Yaml<User>("./data/users.yaml");

for await (const user of yaml.load()) {
  console.log(user.id, user.name);
}
Pass an ignore map to skip items whose field matches a RegExp. Matched items are dropped from the stream. 
// Skip any user whose role contains "guest" or whose name starts with "_"
for await (const user of yaml.load({ ignore: { role: /guest/i, name: /^_/ } })) {
  handle(user);
}
Stream the file directly to a JSON array file with toJson, or to a CSV with toCsv (you choose the columns and separator). Both reuse the same lazy reader, so they never hold the full dataset in memory. 
import { Yaml } from "@ooneex/yml";

type User = { id: number; name: string; role: string };

const yaml = new Yaml<User>("./data/users.yaml");

await yaml.toJson({ path: "./out/users.json" });

await yaml.toCsv({
  path: "./out/users.csv",
  headers: ["id", "name", "role"],
  separator: ",",
  ignore: { role: /guest/i },
});
A missing file, an unreadable stream, or invalid YAML throws a YamlException carrying a key (FILE_NOT_FOUND, READ_FAILED, or PARSE_FAILED) and the offending path. 
import { Yaml, YamlException } from "@ooneex/yml";

try {
  for await (const item of new Yaml("./missing.yaml").load()) {
    process(item);
  }
} catch (error) {
  if (error instanceof YamlException) {
    console.error(error.message); // e.g. "YAML file not found: ./missing.yaml"
  }
}

​
When to use it

  • You need to process large YAML datasets (logs, seed data, exports) without loading the entire file into memory.
  • Your file is a stream of documents separated by ---, or a top-level list of - items, and you want each entry one at a time.
  • You want to convert YAML to JSON or CSV as a streamed pipeline, optionally filtering out rows by a field pattern.
  • You need typed iteration with a small, Bun-native dependency footprint.
  • You don’t need it for small config files you load once — Bun’s YAML.parse (or a plain import) is simpler when the whole file fits comfortably in memory.