[!NOTE] This is one of 211 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.

Features

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

Planned features

• [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

yarn add @thi.ng/csv

ESM import:

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

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/csv"></script>

JSDelivr documentation

For Node.js REPL:

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.

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:

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

License

© 2014 - 2025 Karsten Schmidt // Apache License 2.0