> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Yaml

> Stream large YAML files item by item using Bun's built-in parser, with optional filtering and JSON/CSV export.

`@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.

```bash theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
// 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.

```typescript theme={null}
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.

```typescript theme={null}
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.