> ## 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.

# JSON

> Stream large JSON files record-by-record with an async generator, and convert them to YAML or CSV.

`@ooneex/json` reads a JSON file as a stream and yields each top-level object through an async generator, so you can process large arrays without loading the whole file into memory. The `Json` class also lets you skip records by pattern and write the results straight out to YAML or CSV.

## Installation

Install the package with Bun.

```bash theme={null}
bun add @ooneex/json
```

## Usage

Construct a `Json` instance with a file path, optionally typing the records, then iterate with `for await`. Each top-level object (or array element) is parsed and yielded one at a time.

```typescript theme={null}
import { Json } from "@ooneex/json";

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

const json = new Json<User>("./users.json");

for await (const user of json.load()) {
  console.log(user.id, user.name);
}
```

### Ignoring records

Pass an `ignore` map of field-to-`RegExp`. Any record whose field matches its pattern is skipped during iteration.

```typescript theme={null}
import { Json } from "@ooneex/json";

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

const json = new Json<User>("./users.json");

// Skip records whose email is a test/example address
for await (const user of json.load({ ignore: { email: /@example\.com$/ } })) {
  console.log(user.email);
}
```

### Converting to YAML or CSV

`toYaml` and `toCsv` consume the same stream and write to an output path. `toCsv` requires the `headers` to emit and a `separator`; both accept the same `ignore` filter.

```typescript theme={null}
import { Json } from "@ooneex/json";

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

const json = new Json<User>("./users.json");

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

await json.toCsv({
  path: "./users.csv",
  headers: ["id", "name", "email"],
  separator: ",",
  ignore: { email: /@example\.com$/ },
});
```

You can read the source path back at any time with `json.getPath()`.

## When to use it

* Processing large JSON arrays that won't fit comfortably in memory — `load()` streams one record at a time.
* Filtering out unwanted records on the fly with the `ignore` regex map.
* Exporting JSON data to YAML or CSV without a separate serialization library.
* Building ETL-style pipelines where you transform each record as it streams in.

You don't need it for small config files or API payloads — a plain `JSON.parse()` is simpler when the whole document already fits in memory.