CSV

@talosjs/csv is a small, streaming CSV reader built on top of Bun. It parses CSV files line by line into typed records, handles quoted fields and custom separators, lets you skip rows by pattern, and can convert a file directly to JSON or YAML without loading everything into memory.

Installation

Add the package with Bun.

bun add @talosjs/csv

Usage

Create a Csv instance with a file path and iterate rows with the async generator load. The first row is treated as the header and each subsequent row becomes an object keyed by those headers. You can pass a type parameter for typed rows.

import { Csv } from "@talosjs/csv";

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

const csv = new Csv<User>("./users.csv");

for await (const user of csv.load()) {
  console.log(user.email);
}

Pass a custom separator as the second constructor argument (,, ;, :, |, or \t).

const csv = new Csv<User>("./users.tsv", "\t");

Skip rows whose fields match a regular expression with the ignore option. Each key maps to a pattern, and matching rows are excluded from iteration.

// Skip internal accounts and empty emails.
for await (const user of csv.load({
  ignore: {
    email: /@internal\.test$|^$/,
  },
})) {
  console.log(user.name);
}

Convert a file straight to JSON or YAML. Both stream through the same parser and accept the same ignore filter.

const csv = new Csv<User>("./users.csv");

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

await csv.toYaml({
  path: "./users.yaml",
  ignore: { email: /^$/ },
});

Missing files and read errors throw a CsvException you can catch and inspect.

import { Csv, CsvException } from "@talosjs/csv";

try {
  for await (const row of new Csv("./missing.csv").load()) {
    // ...
  }
} catch (error) {
  if (error instanceof CsvException) {
    console.error(error.message); // "CSV file not found: ./missing.csv"
  }
}

What it’s good for

This is for files that are too large to buffer whole, where you want to walk them row by row and get back typed records keyed off the header. Quoted fields and escaped quotes are handled, and the separator isn’t fixed to a comma: semicolon, tab, pipe, and colon all work. Along the way you can drop rows by pattern, or skip iteration entirely and convert the file to JSON or YAML in one call. For a tiny, well-formed CSV string you already hold in memory, a quick split does the job. This package targets file-based, streamed reading and needs the Bun runtime.

Getting Started

AI

Framework

Command Line

Installation

Usage

What it’s good for

​Installation

​Usage

​What it’s good for

Installation

Usage

What it’s good for