Skip to main content
@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. 
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. 
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. 
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. 
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.