Yaml

@talosjs/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 @talosjs/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 "@talosjs/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 "@talosjs/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 "@talosjs/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 it fits

This is for large YAML datasets (logs, seed data, exports) that you’d rather not load whole. Whether the file is a stream of documents separated by --- or a top-level list of - items, you get one entry at a time, typed, with a small Bun-native dependency footprint. From there you can run it as a streamed pipeline into JSON or CSV, filtering rows by a field pattern on the way. For a small config file you load once, Bun’s YAML.parse (or a plain import) is simpler. The streaming only matters when the file is too big to sit comfortably in memory.

Getting Started

AI

Framework

Command Line

Installation

Usage

When it fits

​Installation

​Usage

​When it fits

Installation

Usage

When it fits