Skip to content

Latest commit

 

History

History
163 lines (121 loc) · 5.49 KB

README.md

File metadata and controls

163 lines (121 loc) · 5.49 KB
Raw

@thi.ng/csv

npm version npm downloads Mastodon Follow

Note

This is one of 199 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

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

  • Simple CSV row parsing w/o object mapping (parseCSVSimple())
  • 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.53 KB

Dependencies

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

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 - 2024 Karsten Schmidt // Apache License 2.0