csv-pipe

A small, fast, zero-dependency CSV encoder and parser for TypeScript and JavaScript. It converts between arrays of objects and RFC 4180-compliant CSV, with typed streaming in both directions, and runs in Node, browsers, Deno, Bun, and edge runtimes.

Documentation · Guide · API · Benchmarks · Conformance

Install

npm install csv-pipe

Usage

Encode an array of objects into CSV:

import { stringify } from 'csv-pipe';

stringify([
  { name: 'Alex Johnson', email: 'alex@example.com', age: 29 },
  { name: 'Carlos Herrera', email: 'carlos@example.com', age: 24 }
]);
// name,email,age
// Alex Johnson,alex@example.com,29
// Carlos Herrera,carlos@example.com,24

And parse it back into typed records:

import { parse } from 'csv-pipe';

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

parse<User>('name,email,age\nAlex Johnson,alex@example.com,29');
// [{ name: 'Alex Johnson', email: 'alex@example.com', age: '29' }]

The header comes from the record keys, quoting and escaping are correct out of the box, and both directions stream and run in every runtime.

Column names are checked against your data, so a typo cannot reach production:

import { stringify } from 'csv-pipe';

type User = { name: string; email: string; age: number };
const users: User[] = [
  { name: 'Alex Johnson', email: 'alex@example.com', age: 29 }
];

stringify(users, { columns: ['name', 'email'] }); // ok
stringify(users, { columns: ['emial'] }); // compile error: 'emial' is not a key of User

Why csv-pipe

• Typed columns. The columns list is typed to keyof T, so renaming a field turns every stale reference into a compile error.
• Encodes and parses. stringify and parse are mirror images, both typed and streaming, so encoding then parsing round-trips your rows, with dynamic typing to recover numbers and booleans.
• Runs where your code runs. The core imports no fs and no DOM, and streaming returns a Web ReadableStream. One import for Node, the browser, Deno, Bun, and edge.
• Flat memory. Parsing streams one record at a time, and encoding does too once the columns are declared, so a file or an HTTP body of any size stays at flat memory.
• Safe by a flag. sanitizeFormulas neutralizes spreadsheet formula injection, so you never hand-sanitize cells.
• Fast and small. The fastest common parser by a wide margin, and the fastest or on-par encoder, across every benchmark, at about 2 kB per direction with zero dependencies.

Documentation

The full documentation is at martsinlabs.github.io/csv-pipe:

• Getting started, Why csv-pipe, Comparison, and Migration
• Encoding: columns, formatting, streaming, and options
• Parsing: overview, columns, typing and validation, streaming and files, and options
• TypeScript, error handling, and security
• Benchmarks, Conformance, and the API reference

Contributing

Contributions are welcome. See CONTRIBUTING for setup and conventions, CODE_OF_CONDUCT for community standards, and SECURITY for reporting vulnerabilities.

License

MIT © Martsin Labs