!@thi.ng/csv

!npm downloads

> [!NOTE]
> This is one of 214 standalone projects, maintained as part
> of the @thi.ng/umbrella monorepo
> and anti-framework.
>
> 🚀 Please help me to work full-time on these projects by sponsoring me on
> GitHub. Thank you! ❤️

- About
- Features
- Status
- Planned features
- Installation
- Dependencies
- Usage examples
- API
- Authors
- License

About

Customizable, transducer-based CSV parser/object mapper and transformer.

Partially ported and extended from the Clojure versions of the
ws-ldn-1
and
resonate-2014
workshop repos.

$3

The parser supports customizable delimiters, quoted and unquoted cells, line
breaks within quoted cells. Being transducer based, memory usage is kept at a
minimum by only processing single lines of (pre-split) text. For CSV records
spanning multiple lines (due to line breaks), new results are only
emitted/processed downstream once a _logical_ CSV row is complete.

Also, being transducer based means the parser can be easily integrated into more
complex data preparation, cleaning or conversion workflows. See
@thi.ng/transducers
for more details/ideas.

Status

STABLE - used in production

Search or submit any issues for this package

$3

- [x] Simple CSV row parsing w/o object mapping (parseCSVSimple())
- [x] CSV output from structured data
- [ ] CSVW support (#257)
- [ ] Integration with thi.ng/egf

Installation

``bash
yarn add @thi.ng/csv
`

ESM import:

`ts
import * as csv from "@thi.ng/csv";
`

Browser ESM import:

`html

`

JSDelivr documentation

For Node.js REPL:

`js
const csv = await import("@thi.ng/csv");
`

Package sizes (brotli'd, pre-treeshake): ESM: 1.73 KB

Dependencies

- @thi.ng/api
- @thi.ng/checks
- @thi.ng/errors
- @thi.ng/strings
- @thi.ng/transducers

Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)

Usage examples

One project in this repo's
/examples
directory is using this package:

| Screenshot | Description | Live demo | Source |
|:-------------------------------------------------------------------------------------------------------------------------|:-----------------------------------|:--------------------------------------------------------|:-------------------------------------------------------------------------------------|
| | Piechart visualization of CSV data | Demo | Source |

API

Generated API docs

Also see extensive doc strings for parseCSV() and CSVOpts. See
parseCSVSimple() and parseCSVFromString() for alternatives and syntax sugar
forms.

`ts
import { parseCSV, upper, float } from "@thi.ng/csv";

[...parseCSV(
{
all: false,
cols: {
"country": { tx: upper },
"latitude": { alias: "lat", tx: float() },
"longitude": { alias: "lon", tx: float() },
}
},
[
"country","country group","name (en)","latitude","longitude",
"at","eu","Austria","47.6965545","13.34598005",
"be","eu","Belgium","50.501045","4.47667405",
"bg","eu","Bulgaria","42.72567375","25.4823218",
]
)]

// [
// { country: 'AT', lat: 47.6965545, lon: 13.34598005 },
// { country: 'BE', lat: 50.501045, lon: 4.47667405 },
// { country: 'BG', lat: 42.72567375, lon: 25.4823218 }
// ]
`

Authors

- Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

`bibtex
@misc{thing-csv,
title = "@thi.ng/csv",
author = "Karsten Schmidt",
note = "https://thi.ng/csv",
year = 2014
}
``

License

© 2014 - 2026 Karsten Schmidt // Apache License 2.0