# csv-walker

> A tiny CSV parser for browsers and Node.js.

Latest version **0.2.1** (published 2026-08-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install csv-walker
pnpm add csv-walker
yarn add csv-walker
bun add csv-walker
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.1 |
| Published | 2026-08-11 |
| First published | 2026-08-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 18.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jesse G. Donat |
| Maintainers | donatj |
| Keywords | csv, generator, parser, stream, tsv |

## Links

- npm: https://www.npmjs.com/package/csv-walker
- Repository: https://github.com/donatj/csv-walker
- Homepage: https://github.com/donatj/csv-walker#readme
- Issues: https://github.com/donatj/csv-walker/issues
- npm.io page: https://npm.io/package/csv-walker

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 0.2.1 (latest) — 2026-08-11
- 0.2.0 — 2026-08-11
- 0.1.0 — 2026-08-11

## README

# csv-walker

[![Node.js CI](https://github.com/donatj/csv-walker/actions/workflows/ci.yml/badge.svg)](https://github.com/donatj/csv-walker/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/donatj/csv-walker/badge.svg?branch=dev)](https://coveralls.io/github/donatj/csv-walker?branch=dev)

Small CSV parser for browsers and Node.js.

It has no runtime dependencies. It reads strings, files, and streams. It yields
rows and columns as it reads them.

## Install

```sh
npm install csv-walker
```

## Strings

Strings use synchronous generators. Each row yields column strings.

```ts
import { parse } from "csv-walker";

for (const row of parse("name,age\nAda,36\nGrace,85")) {
	console.log([...row]);
}

// ["name", "age"]
// ["Ada", "36"]
// ["Grace", "85"]
```

## Node files and streams

Files and streams use async generators. Use `for await...of` for rows and
columns.

```ts
import { createReadStream } from "node:fs";
import { parse } from "csv-walker";

for await (const row of parse(createReadStream("people.csv"))) {
	const person = [];

	for await (const column of row) {
		person.push(column);
	}

	console.log(person);
}
```

## Browser files

Pass a browser `File` to `parse()`.

```ts
input.addEventListener("change", async () => {
	const [file] = input.files;

	for await (const row of parse(file)) {
		for await (const column of row) {
			console.log(column);
		}
	}
});
```

See [`examples/browser.html`](examples/browser.html) for a complete file-picker
example. Build first. Serve the project from a local web server. Browser modules
usually do not load from `file://` URLs.

## CSV controls

Controls use a Go-style option pattern. The defaults match PHP `fgetcsv`.

```ts
import { enclosure, escape, parse, separator } from "csv-walker";

for (const row of parse(input, separator(";"), enclosure("'"), escape(""))) {
	console.log([...row]);
}
```

| Option             | Default   | Use                                                           |
| ------------------ | --------- | ------------------------------------------------------------- |
| `separator(value)` | `","`     | Set the field separator.                                      |
| `enclosure(value)` | `"\""`    | Set the quoted-field character.                               |
| `escape(value)`    | `"\\"`    | Keep a following enclosure literal. Pass `""` to turn it off. |
| `encoding(value)`  | `"utf-8"` | Set the encoding for byte input.                              |

Separators and enclosures take one character. Escapes take one character or an
empty string. Doubled enclosures work. `"said ""hello"""` becomes
`said "hello"`.

With the default escape, a backslash before the enclosure stays in the value.
It also keeps that enclosure from closing the field. Use `escape("")` for RFC
4180 CSV.

## Text encoding

Byte input uses UTF-8 by default. Use `encoding()` for legacy files.

```ts
import { createReadStream } from "node:fs";
import { encoding, parse } from "csv-walker";

const rows = parse(createReadStream("legacy.csv"), encoding("windows-1252"));
```

This affects files, blobs, streams, and byte chunks. It does not affect strings.
The encoding name is passed to `TextDecoder`, so labels such as `"windows-1252"`
and `"cp1252"` work where the platform supports them.

## Streaming

`csv-walker` does not collect the whole input. It does not collect a whole row.
It holds the current column and moves forward as you read it.

Rows share one input cursor. Requesting the next row drops unread columns from
the current row.

Source streams are consumed. If you stop parsing early, do not assume a stream
can be reused. Manage cancellation or destruction at the call site when that
matters.

```ts
for (const row of parse("id,name,role\n1,Ada,Engineer\n2,Grace,Admiral")) {
	console.log(row.next().value);
}

// id
// 1
// 2
```

## Collect values

`allValues()` reads a column generator or a whole row generator into memory.
Async inputs resolve to the same concrete arrays. Avoid it for large data sets.
Iterate instead.

```ts
import { allValues, parse } from "csv-walker";

const rows = allValues(parse("name,age\nAda,36"));
// [["name", "age"], ["Ada", "36"]]

for (const row of parse("name,age")) {
	const columns = allValues(row);
	// ["name", "age"]
}
```

| Input                                | Return value          |
| ------------------------------------ | --------------------- |
| One `Row`                            | `string[]`            |
| One `AsyncRow`                       | `Promise<string[]>`   |
| A synchronous parser (`Rows`)        | `string[][]`          |
| An asynchronous parser (`AsyncRows`) | `Promise<string[][]>` |

## Supported CSV

- Quoted fields. They may contain commas or newlines.
- Doubled enclosures such as `""`.
- Optional PHP-style escapes.
- Unix, Windows, and classic Mac line endings.
- Byte input in any `TextDecoder`-supported encoding; UTF-8 is the default.
  Characters may cross chunk boundaries.

## Examples

- [`examples/node.mjs`](examples/node.mjs): read a file with Node.
  Run `node examples/node.mjs examples/example.csv` after building.
- [`examples/browser.html`](examples/browser.html): read a selected browser
  file.

## Development

```sh
npm test
```

## License

[MIT](LICENSE.md)

---
_Source: https://npm.io/package/csv-walker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._